Introduction

Swarm is a multi-agent orchestration framework for AI coding agents. It coordinates multiple AI agents working in parallel on a shared codebase, where each agent runs in an isolated git worktree, communicates through a SQLite-backed mailbox, and is managed by a supervisor that handles merging results back to the main branch.

Swarm's primary interface is an interactive REPL — you run swarm in your project directory and interact through conversational prompts and slash commands like /connect, /send, and /stop.

Who Is This For?

Swarm is built for developers who want to:

  • Parallelize large coding tasks across multiple AI agents, each with a distinct role (backend, frontend, reviewer, etc.)
  • Maintain isolation between agents so they don't interfere with each other's work
  • Coordinate agent work through messaging, shared issue tracking, and supervised merging
  • Monitor progress in real time through a terminal UI

Key Capabilities

CapabilityDescription
Parallel agent sessionsRun multiple AI agents simultaneously, each in its own git worktree branch
SQLite messagingAgents communicate via a durable, threaded mailbox with urgency levels
State machine lifecycleEach agent follows a well-defined state machine (Initializing → Running → Stopped) with automatic error recovery and backoff
TUI dashboardReal-time terminal UI showing agent status, logs, and events
Git worktree isolationEach agent works on an isolated branch; changes are merged back on stop
Configurable permissionsFine-grained allow/ask/deny rules per tool, per agent
MCP integrationConnect external tool servers via the Model Context Protocol
WASM sandboxed toolsRun untrusted tool code in a WebAssembly sandbox with resource limits
Hooks systemExecute custom scripts on lifecycle events (session start, tool calls, etc.)
Beads issue trackingBuilt-in integration with the bd CLI for task management across agents
Workflow pipelinesDefine multi-stage workflows with gates and approvals
Iteration engineRun repeated task-solving loops with configurable progress detection

Architecture at a Glance

┌─────────────────────────────────────────────────────┐
│                   Orchestrator                       │
│  (session management, periodic tasks, shutdown)      │
├──────────┬──────────┬──────────┬────────────────────┤
│ Agent 1  │ Agent 2  │ Agent N  │    Supervisor       │
│ worktree │ worktree │ worktree │    worktree         │
│ branch   │ branch   │ branch   │    branch           │
├──────────┴──────────┴──────────┴────────────────────┤
│              SQLite Mailbox + Router                 │
│         (message delivery, urgent interrupts)        │
├─────────────────────────────────────────────────────┤
│   AgentBackend (Anthropic API / pluggable providers) │
└─────────────────────────────────────────────────────┘

The orchestrator creates a session that tracks the base commit, agent list, and process ID. Each agent runs through a state machine loop: build prompt → spawn backend session → run → handle results → repeat. Agents communicate by sending messages through the SQLite mailbox, and a router polls for urgent messages to trigger interrupts.

When you stop a session, the supervisor merges (or squashes/discards) each agent's branch back into the base branch.

When to Use Swarm

Swarm is a good fit when:

  • Your task can be decomposed into independent or loosely-coupled subtasks (e.g., "backend builds API endpoints while frontend builds the UI")
  • You want automated coordination between agents rather than manual copy-paste between chat windows
  • You need durability — agent work persists in git branches even if the process crashes
  • You want observability into what each agent is doing via the TUI

Swarm may not be the right tool if:

  • Your task is small enough for a single agent session
  • You need agents to share the same working directory in real time (swarm uses branch isolation)

What's Next