Claude Swarm — Multi-Agent Orchestration

Parallel Claude Code agents: plan → endorse → spawn → monitor → review → integrate → ship.

Quick Start

# 1. Write task prompts
cat > /tmp/prompt-task1.md \x3C\x3C 'EOF'
Implement feature X...
EOF

# 2. Create tasks JSON
cat > /tmp/tasks.json \x3C\x3C 'EOF'
[
  {"id": "feat-x", "description": "/tmp/prompt-task1.md", "role": "builder"},
  {"id": "feat-y", "description": "/tmp/prompt-task2.md", "role": "builder"}
]
EOF

# 3. Spawn batch (auto-endorses + auto-integration)
bash scripts/spawn-batch.sh "/path/to/project" "batch-1" "Description" /tmp/tasks.json

Roles & Models

Configure in config/duty-table.json.

Scripts

Workflow Detail

1. Planning (human + architect)

Break work into parallel tasks. Each task needs: ID, prompt, role.

2. Endorsement Gate

Every task requires endorsement before spawning — safety gate to prevent runaway agents.

• spawn-batch.sh auto-endorses all tasks in batch
• Manual: bash scripts/endorse-task.sh \x3Ctask-id>
• 30-second cooldown between endorsement and spawn

3. Spawning

Each agent runs in:

• Isolated git worktree (\x3Cproject>-worktrees/\x3Ctask-id>/)
• tmux session (claude-\x3Ctask-id>)
• Non-interactive mode (claude --print --permission-mode bypassPermissions)
• Auto-retry with model fallback (opus → sonnet → haiku) on rate limits

4. Auto-Review

When an agent completes, notify-on-complete.sh:

1. Detects completion (polls tmux every 60s)
2. Sends notification
3. Spawns a reviewer (sonnet) that checks the diff
4. If issues found: fixes and commits (up to 3 rounds)
5. Pushes final state

5. Integration

When all agents in a batch complete, integration-watcher.sh:

1. Collects all branches
2. Merges sequentially into main
3. Uses opus to resolve any conflicts
4. Runs integration review (opus, up to 3 rounds)
5. Pushes to main (if auto-merge enabled)

Setup

1. Copy this skill's scripts/ and config/ to your workspace
2. Copy config/swarm.conf.example → config/swarm.conf and configure
3. Ensure installed: bash 4+, tmux, git, gh, jq, claude (Claude Code CLI)

Notifications

Set SWARM_NOTIFY in swarm.conf:

• webhook — POST to SWARM_WEBHOOK_URL (Slack/Discord/custom)
• telegram — Send via SWARM_TELEGRAM_BOT_TOKEN + SWARM_TELEGRAM_CHAT_ID
• none — Log only (default)

Hard Rules

1. Always endorse before spawning — no exceptions
2. Use spawn-batch.sh for 2+ tasks — starts integration watcher
3. Never run bare claude --print in background — use spawn-agent.sh
4. Let the watcher handle reviews — don't add review logic to prompts