AI Swarm Orchestration#

Orchestrate parallel AI coding agents with automated review, integration, and notifications.

Setup#

Prerequisites#

• tmux — agent sessions run here
• git — worktrees for parallel branches
• claude CLI (Claude Code) — primary agent
• Telegram bot token + chat ID (optional, for notifications)

Install scripts#

Copy scripts/ to your swarm directory (e.g., ~/workspace/swarm/). Make executable:

bash

chmod +x ~/workspace/swarm/*.sh

Initialize state files#

bash

mkdir -p ~/workspace/swarm/{logs,endorsements}
echo '[]' > ~/workspace/swarm/active-tasks.json
echo '' > ~/workspace/swarm/pending-notifications.txt

Duty table#

Copy references/duty-table-template.json to ~/workspace/swarm/duty-table.json. Configure model assignments.

Core Workflow#

Phase 1: PLAN (present to human, STOP, wait for approval)#

⛔ CRITICAL GATE: Present the plan table to the human. Then STOP. Do NOT write prompts or spawn agents until the human explicitly approves.

The plan message and the spawn action must be in DIFFERENT turns. Never combine them.

text

🐝 Swarm Plan: [batch description]

| # | Task ID | Description | Agent | Model |
|---|---------|-------------|-------|-------|
| 1 | fix-xyz | Fix the freeze bug | claude | sonnet |
| 2 | add-feat | Add feature X | claude | sonnet |

Dependencies: None (all parallel)
Estimated time: ~15-20 min

Proceed? 👍/👎

Wait for human reply. Only after "yes"/"go"/👍 → proceed to Phase 2.

Phase 2: BUILD (write prompts, spawn agents)#

Write task prompts to /tmp/prompt-<task-id>.md, create batch JSON, then spawn:

bash

cat > /tmp/batch-tasks.json << 'EOF'
[
  {"id": "task-1", "description": "/tmp/prompt-task1.md", "agent": "claude", "model": "claude-sonnet-4-6"},
  {"id": "task-2", "description": "/tmp/prompt-task2.md", "agent": "claude", "model": "claude-sonnet-4-6"}
]
EOF

cd ~/workspace/swarm
bash spawn-batch.sh "/path/to/project" "batch-id" "Batch description" /tmp/batch-tasks.json

spawn-batch.sh handles everything automatically:

• Creates git worktrees + feature branches
• Launches agents in tmux sessions
• Starts per-agent completion watchers (auto-review + Telegram notification)
• Starts integration watcher (auto-merge when all done)

For single tasks: bash spawn-agent.sh "/path/to/project" "task-id" "/tmp/prompt.md" "claude" "claude-sonnet-4-6"

Phase 3: SHIP (automatic)#

The scripts handle this automatically:

1. notify-on-complete.sh detects each agent finishing → spawns reviewer → sends Telegram
2. integration-watcher.sh detects ALL agents done → spawns Opus integration agent → merges branches → resolves conflicts → verifies builds → sends Telegram

Prompt Template#

Write clear, self-contained prompts for each agent. Include:

• Project path and stack
• Specific files to modify
• What to do (detailed steps)
• Verification commands ( tsc --noEmit, npm run build, etc.)

Do NOT include openclaw system event in prompts — notify-on-complete.sh handles notifications automatically.

Monitoring#

bash

tmux ls                              # List active agent sessions
bash check-agents.sh                 # Health check all agents
bash pulse-check.sh                  # Detect stuck agents (auto-kills)
cat pending-notifications.txt        # Check pending notifications

Script Reference#

ScriptPurposespawn-batch.shSpawn N agents + auto-integration watcherspawn-agent.shSpawn single agent with completion watcherintegration-watcher.shPoll agents, auto-merge when all donestart-integration.shManual integration watcher startnotify-on-complete.shPer-agent watcher: detect done → review → notifypulse-check.shDetect and kill stuck agentscheck-agents.shQuick status checkendorse-task.shCreate endorsement file for a taskesr-log.shUpdate project ESR docseor-log.shWrite agent end-of-run logfallback-swap.shModel selection with fallbackassess-models.shWeekly model benchmarkdeploy-notify.shCI/CD notification

Hard Rules#

ALWAYS#

• Present plan → STOP → wait for human approval → THEN spawn (separate turns!)
• Use spawn-batch.sh for 2+ tasks, spawn-agent.sh for single tasks
• Let scripts handle tmux, notifications, review, integration — don't bypass

NEVER#

• Spawn agents without human endorsement
• Present plan and spawn in the same message/turn
• Write prompts before receiving endorsement
• Use bare claude --print or background exec (bypasses entire pipeline)
• Spawn agents in the orchestrator's workspace directory

Heartbeat Checks#

Read references/HEARTBEAT.md for periodic checks:

1. Read pending-notifications.txt → send to human → clear
2. Run pulse-check.sh for stuck agents
3. Check tmux ls for completed agents
4. Report brief status if agents are running

Further Reading#

• references/ROLE.md — Full role definition with lessons learned
• references/TOOLS.md — Detailed script usage and prompt patterns