Claude Swarm — Multi-Agent Orchestration#

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

Quick Start#

bash

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

# 2. Create tasks JSON
cat > /tmp/tasks.json << '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#

RoleModelEffortUsearchitectopushighDesign, planning, complex decisionsbuildersonnethighFeature implementation (parallel)reviewersonnetmediumAuto-review on completionintegratoropushighCross-branch merge + conflict resolution

Configure in config/duty-table.json.

Scripts#

ScriptPurposespawn-batch.shSpawn N parallel agents + integration watcherspawn-agent.shSpawn single agent in worktree + tmuxendorse-task.shEndorse task (required before spawn)check-agents.shShow status of all running agentscleanup.shRemove worktrees, branches, tmux sessionsnotify.shSend webhook/Telegram notificationnotify-on-complete.shAuto-watcher: notify + review on completionintegration-watcher.shAuto: merge all branches when batch completes

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 <task-id>
• 30-second cooldown between endorsement and spawn

3. Spawning#

Each agent runs in:

• Isolated git worktree ( <project>-worktrees/<task-id>/)
• tmux session ( claude-<task-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