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.

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

Capability	Description
Parallel agent sessions	Run multiple AI agents simultaneously, each in its own git worktree branch
SQLite messaging	Agents communicate via a durable, threaded mailbox with urgency levels
State machine lifecycle	Each agent follows a well-defined state machine (Initializing → Running → Stopped) with automatic error recovery and backoff
TUI dashboard	Real-time terminal UI showing agent status, logs, and events
Git worktree isolation	Each agent works on an isolated branch; changes are merged back on stop
Configurable permissions	Fine-grained allow/ask/deny rules per tool, per agent
MCP integration	Connect external tool servers via the Model Context Protocol
WASM sandboxed tools	Run untrusted tool code in a WebAssembly sandbox with resource limits
Hooks system	Execute custom scripts on lifecycle events (session start, tool calls, etc.)
Beads issue tracking	Built-in integration with the `bd` CLI for task management across agents
Workflow pipelines	Define multi-stage workflows with gates and approvals
Iteration engine	Run 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