Quick Start

Install, configure, and run your first swarm session in minutes.

Prerequisites

Before you begin, ensure you have:

Requirement	Minimum Version	Check Command
Rust toolchain	Latest stable	`rustc --version`
Git	2.20+	`git --version`
Anthropic API key	—	`echo $ANTHROPIC_API_KEY`

Swarm uses git worktrees, which require git 2.20 or newer. If your version is older, swarm will exit with a VersionTooOld error at startup.

Install

Clone the repository and build:

git clone <repo-url> swarm
cd swarm
cargo build --release

The binary is at target/release/swarm. Add it to your PATH or use cargo install --path swarm.

To enable WASM sandboxed tools (optional):

cargo build --release --features wasm-sandbox

Initialize a Project

Navigate to a git repository and run:

cd /path/to/your-project
swarm init

This creates ~/.swarm/settings.json with a starter configuration for your project. The config is keyed by the absolute, canonicalized path to your project directory.

Tip: You can also pass --path /path/to/project to initialize a different directory.

Configure Agents

Open ~/.swarm/settings.json and define your agents. Here is a minimal two-agent configuration:

{
  "version": 2,
  "/home/user/my-project": {
    "providers": {
      "default": {
        "type": "anthropic",
        "api_key_env": "ANTHROPIC_API_KEY"
      }
    },
    "defaults": {
      "model": "sonnet"
    },
    "agents": [
      {
        "name": "backend",
        "prompt": "You are a backend engineer. Work on server-side code, APIs, and database logic."
      },
      {
        "name": "frontend",
        "prompt": "You are a frontend engineer. Work on UI components, styling, and client-side logic."
      }
    ]
  }
}

Each agent needs:

name — Unique identifier matching [a-z][a-z0-9-]*
prompt — System prompt text, or @path/to/file to load from a file

See Writing Agents for the full configuration guide.

Set Your API Key

Export your Anthropic API key:

export ANTHROPIC_API_KEY="sk-ant-..."

The environment variable name can be customized per provider via the api_key_env field.

Start a Session

swarm start

This launches the orchestrator, which:

Loads and validates your configuration
Checks git prerequisites (clean tree, version)
Creates a session with ID format YYYYMMDD-XXXX
Creates a git worktree per agent at .swarm/worktrees/<name>
Opens the SQLite mailbox at .swarm/messages.db
Spawns all agents in parallel
Opens the TUI dashboard

If your working tree has uncommitted changes, use --stash to auto-stash them:

swarm start --stash

To run without the TUI (log output to terminal instead):

swarm start --no-tui

The TUI Dashboard

The TUI displays a panel for each agent showing:

Agent name and current state (e.g., Running, CoolingDown)
Session sequence number
Live log output

Key Bindings

Key	Action
`Tab` / `Shift+Tab`	Cycle focus between agent panels
`1`–`9`	Jump to agent panel by index
`l`	Toggle log viewer overlay
`e`	Toggle event viewer overlay
`q`	Quit TUI (session keeps running)
`:`	Open input bar for commands

The TUI refreshes at approximately 30 FPS (33ms frame interval).

Send Messages to Agents

From a separate terminal, send a message to a specific agent:

swarm send backend "Add a health check endpoint at GET /health"

Or broadcast to all agents:

swarm broadcast "Please commit your current work"

For messages that should interrupt an agent immediately:

swarm send backend "Stop what you're doing and fix the failing tests" --urgent

Urgent messages trigger the router interrupt — the agent's current session is cancelled and it restarts with the urgent message in its prompt.

Check Status

swarm status

This shows each agent's current state, session sequence, and error counts. Add --json for machine-readable output.

Stop the Session

When you're done, stop the session and merge all agent work:

swarm stop --merge

Stop modes:

Flag	Behavior
`--merge`	Merge each agent's worktree branch into the base branch
`--squash`	Squash-merge each agent's work into a single commit
`--discard`	Discard all agent work and clean up worktrees

If no flag is provided, swarm prompts for your choice.

The stop sequence:

Signals all agents to stop
Waits for graceful shutdown
Applies the chosen merge strategy
Removes worktrees and session artifacts
Cleans up the lockfile

View Logs

To view an agent's logs:

swarm logs backend

Follow logs in real time:

swarm logs backend --follow

View logs from a specific session:

swarm logs backend --session 2

Clean Up

If a session crashed or left stale artifacts:

swarm clean

Use --force to remove artifacts without confirmation.

Next Steps

Writing Agents — Full agent configuration guide
Configuration — How config loading and resolution works
Agent Lifecycle — Understanding agent states
Messaging — How agents communicate
Beads Workflow — Using beads for issue tracking