Swarm CLAUDE.md

CLAUDE.md

Guidance for AI coding assistants (Claude Code, Cursor, etc.) working in this repository. This file is the canonical, in-repo briefing — read it before making changes.

What is Swarm?

Swarm is a Swift 6.2 framework for building agents and multi-agent workflows on Apple platforms (iOS 26+, macOS 26+, tvOS 26+) and Linux. It is built around:

• Agents — Agent struct with @ToolBuilder trailing closures, an AgentRuntime protocol, and pluggable inference providers.
• Workflows — fluent composition (.step, .parallel, .route, .repeatUntil) compiled to a DAG with checkpoint/resume.
• Tools — the @Tool macro generates JSON schemas from Swift structs at compile time; FunctionTool covers ad-hoc closures.
• Memory — conversation, sliding-window, summary, vector, and persistent backends.
• Guardrails / Resilience / Observability — first-class concerns, not bolt-ons.
• Providers — Built-in Apple Foundation Models; custom backends inject InferenceProvider. No Conduit / cloud façade ships with Swarm.
• MCP — Model Context Protocol client and server support.

The package uses Swift 6.2 with StrictConcurrency enabled across all targets. All public types must be Sendable — the compiler enforces it.

Repository Layout

Swarm/
├── Package.swift                  # SPM manifest (Swift 6.2, products)
├── README.md                      # User-facing overview
├── Sources/
│   ├── Swarm/                     # Main library (156 .swift files)
│   │   ├── Agents/                # Agent struct, workspace integration
│   │   ├── Core/                  # AgentRuntime, Conversation, Environment,
│   │   │                          #   PromptEnvelope, RuntimeMetadata, …
│   │   ├── Workflow/              # Workflow + durable engine + checkpointing
│   │   ├── Tools/                 # Tool protocol, ToolCollection, ParallelExecutor,
│   │   │                          #   built-ins, web tools, schema bridging
│   │   ├── Memory/                # Conversation, sliding window, summary, vector,
│   │   │                          #   SwiftData, ContextCore, hybrid backends
│   │   ├── Providers/             # Foundation Models, multi-provider, sessions
│   │   ├── Guardrails/            # Input/Output/Tool guardrail specs + runner
│   │   ├── Resilience/            # Retry, circuit breaker, fallback, rate limit
│   │   ├── Observability/         # AgentTracer, SwiftLog/OSLog tracers, metrics
│   │   ├── MCP/                   # MCPClient, MCPServerConnection, stdio/HTTP transports, ToolBridge
│   │   ├── Workspace/             # AgentWorkspace (AGENTS.md, .swarm/ skills)
│   │   ├── Macros/                # Public macro declarations
│   │   ├── Integration/           # Membrane and Wax integrations
│   │   └── Internal/GraphRuntime/ # Compiled DAG runtime (internal)
│   ├── HiveCore/                  # In-tree durable graph (Integrations only)
│   ├── MembraneCore/              # In-tree Membrane core (Integrations only)
│   ├── Membrane/                  # In-tree Membrane session (Integrations only)
│   ├── MembraneContextCore/       # In-tree Membrane↔ContextCore (Integrations)
│   ├── ContextCoreTypes/          # In-tree ContextCore types (Integrations)
│   ├── ContextCoreShaders/        # In-tree Metal shaders (Integrations)
│   ├── ContextCoreEngine/         # In-tree ContextCore engine (Integrations)
│   ├── ContextCore/               # In-tree ContextCore façade (Integrations)
│   ├── SwarmMacros/               # Compiler plugin (@Tool, @Parameter,
│   │                              #   @Traceable, #Prompt, builders)
│   ├── SwarmMembrane/             # Deprecated hollow re-export (remove in 0.7.0)
│   ├── SwarmMCP/                  # MCP server adapter product
│   ├── SwarmCapabilityShowcase/        # Executable: deterministic showcase CLI
│   ├── SwarmCapabilityShowcaseSupport/ # Library backing the showcase
│   ├── SwarmDemo/                 # (opt-in) demo executable
│   └── SwarmMCPServerDemo/        # (opt-in) MCP server demo
├── Tests/
│   ├── SwarmTests/                # Main test target (mirrors Sources/Swarm)
│   │   └── Mocks/                 # MockAgentRuntime, MockInferenceProvider, …
│   ├── HiveSwarmTests/            # Hive integration tests
│   ├── SwarmMacrosTests/          # Macro expansion tests
│   └── SwarmCapabilityShowcaseTests/
├── Examples/CodeReviewer/         # Standalone example SPM project
├── docs/
│   ├── guide/                     # Getting started, agent workspace, showcase
│   ├── reference/                 # API catalog, front-facing-api, audits
│   └── release/                   # release-checklist.md
└── .github/workflows/             # swift.yml, claude.yml, claude-code-review.yml,
                                   #   docs.yml