claude-swarm

A multi-agent Claude Code workstation you can drop into any project. Two developer agents, a tester, and a final reviewer collaborate on a plan you hand them — coordinated by a small, AI-free dispatcher so the whole thing runs comfortably on a single Claude Max subscription.

You write a plan. You drop it in. Four Claude Code agents pick it apart into tasks and build it: the two devs implement and cross-review each other's work, the tester gates every task with real tests, and a reviewer does one end-to-end pass at the very end. You watch it happen in a terminal dashboard.

How it works (the short version)

The key idea is roles are not processes. There are four agent roles, but they don't all run at once burning your usage. Instead:

• A tiny dispatcher (plain Python, no AI) runs continuously. It watches for your plan, splits it into tasks, assigns them, and decides when to wake an agent. It costs nothing to keep running.
• Agents are summoned to do one task, then they exit. Each is a headless claude -p call. No idle agents sitting around spending your quota.
• At most 3 agents run at once, launched a bit apart, to stay clear of Claude's burst limits.
• Devs and the tester run on Sonnet (the plentiful pool); Opus is reserved for the reviewer's single end-of-project pass.

The full design — state machine, crash recovery, the shared-state files — is in docs/ARCHITECTURE.md.

            you drop a plan ─► dispatcher splits it into tasks
                                      │
   ┌──────────────► dev_1 / dev_2 implement (round-robin, own git worktrees)
   │                        │
   │                the other dev cross-reviews (advisory)
   │                        │
   │                   tester runs tests ──► PASS ─► done
   │                        │
   └──── FAIL: back to the same dev (after 3 fails → "stuck", you step in)

   when every task passes ─► reviewer does one final end-to-end review

Requirements

• An active Claude Max subscription (this is what powers the agents). Authenticate with claude login — do not set an ANTHROPIC_API_KEY, or you'll be billed at paid API rates instead of using your plan.
• Node.js 18+ and Python 3.10+
• Claude Code (claude), git, tmux (for the dashboard), and pdftotext (only if you hand it .pdf plans)

macOS and Linux are supported.

Install

Global (use it in any project):

npm install -g @remi236/claude-swarm
claude-swarm setup        # builds the Python engine, checks your dependencies

Or without installing, via npx:

npx @remi236/claude-swarm setup
npx @remi236/claude-swarm init

Per-project (pin it to one repo):

npm install --save-dev @remi236/claude-swarm
npx claude-swarm setup

Quick start

cd ~/code/my-project          # any git repo you want the agents to work on
claude-swarm init             # sets up a swarm, starts the dispatcher + dashboard
claude-swarm plan ./plan.md   # hand it your plan (.md, .pdf, or .json)
claude-swarm attach           # watch the four agents work (Ctrl-b then d to detach)
# ... when it's finished ...
claude-swarm release          # stop everything, archive the run, clean up

Your project's code is never thrown away: the agents work on git worktrees branched from your repo, and their finished work lands on task/* branches you can review and merge yourself.

Commands

| Command | What it does | |---|---| | claude-swarm setup | One-time: builds the Python virtualenv and checks dependencies. | | claude-swarm init [--name N] [--no-start] | Set up a swarm in the current repo and start it. --no-start scaffolds only. | | claude-swarm plan <file> | Drop a plan (.md / .pdf / .json) for the agents to work through. | | claude-swarm run | Run the dispatcher in the foreground until done/blocked (great for CI / batch). | | claude-swarm attach | Attach to the 4-pane tmux dashboard (dev_1, dev_2, tester, reviewer). | | claude-swarm status | Print the task queue and overall project status. | | claude-swarm release | Stop everything, remove worktrees, archive the run. Leaves your code intact. |

Writing a plan

A plan is just a list of tasks. The simplest form is Markdown — each ## heading becomes one task:

## Add a config loader
Read settings from config.yaml and expose load_config().

## Add a CLI entry point
Parse arguments with argparse and wire up the loader.

You can also hand it a .pdf (text is extracted automatically) or a .json file shaped like [{ "title": "...", "description": "..." }, ...].

When a task gets stuck

If the tester fails a task 3 times, it's marked stuck and the project pauses rather than looping forever. Run claude-swarm status to find it, read the notes the tester left in .claude-swarm/project_knowledge/test_results/, fix or reword the task, and the pipeline continues. A different note ("repeated crashes") means an environment problem (network, a missing tool) rather than a coding one.

Where things live

Everything the swarm creates is tucked under .claude-swarm/ in your project (and it's added to your .gitignore automatically, so it never pollutes your repo):

.claude-swarm/
├── project_knowledge/
│   ├── plans/active.md        # your plan
│   ├── state/task_queue.json  # the live task list
│   ├── logs/                  # one log per agent + the dispatcher
│   ├── reviews/               # cross-reviews
│   ├── test_results/          # tester reports
│   └── final_review.md        # the reviewer's end report
├── worktrees/{dev_1,dev_2}/   # git worktrees the devs build in
└── archive/                   # past runs (after `release`)

Troubleshooting

• "claude: command not found" — install Claude Code and run claude login.
• Agents do nothing / billing surprises — make sure ANTHROPIC_API_KEY is unset (echo $ANTHROPIC_API_KEY should be empty). When set, Claude Code uses paid API credits instead of your Max plan.
• No dashboard — tmux isn't installed. Everything still runs; use claude-swarm status to follow progress, or claude-swarm run to watch in the foreground.
• Rate-limit errors — you may have hit your Max weekly cap, or too many agents started at once. The dispatcher already staggers launches; if it persists, wait for your usage window to reset.

Two ways to deploy

1. Any project (this CLI). What this README describes — npm install -g, then claude-swarm inside any repo.
2. Dedicated always-on VPS. For a 24/7 box (e.g. an Oracle Cloud Free Tier ARM VM), run bootstrap.sh to provision the machine, then use the standalone commands in orchestrator/bin/. Same engine underneath.

Develop / publish your own copy

Push to GitHub:

git init
git add .
git commit -m "feat: claude-swarm multi-agent workstation"
git branch -M main
git remote add origin https://github.com/remi236/claude-swarm.git
git push -u origin main

Publish to npm. The package is scoped to your account and publishConfig already marks it public, so a plain publish works:

npm login
npm publish

Bump the version before each new release (npm version patch / minor / major) — npm never lets you republish a version that already exists.

License

MIT © Salmon