Claude Swarm

Claude-native multi-agent swarm orchestration for parallel coding. Use when spawning multiple Claude Code agents to work in parallel on a project with git wo...

Security Scan

The skill's scripts and instructions align with a Claire/Claude multi-agent orchestration purpose, but several high-privilege behaviors (automatic commits/pushes, auto-merge to main, use of model 'bypassPermissions', and optional webhook/Telegram notifications) are powerful and not fully surfaced in the declared requirements — review before use.

Purpose & Capability

The name/description match the included scripts: spawning agents in tmux, isolated git worktrees, auto-review, merge and push. However the skill assumes existing CLI credentials/tools (claude CLI, git/gh) and repository push rights — these are not declared as required env vars or credentials. Auto-pushing/PR-creation behaviors are consistent with 'ship' goals but grant broad repository privileges.

Instruction Scope

Runtime instructions and scripts read and write the entire project, create and remove git worktrees/branches, run dependency installers (pip/yarn/npm), run the claude CLI with 'bypassPermissions', automatically fix files, commit and push changes, and optionally POST prompts/messages to webhooks/Telegram. They also save prompts to SWARM_DIR/logs (possible leakage of sensitive prompts). These actions go beyond passive orchestration and allow automatic, potentially large-impact code changes and network exfiltration if notification endpoints are misconfigured.

Install Mechanism

No install spec; this is instruction/script-only. All code is included in the package and there are no remote downloads or archive extraction steps in the skill itself.

Credentials

The skill declares no required env vars, but the scripts use/configure SWARM_* variables (SWARM_NOTIFY, SWARM_WEBHOOK_URL, SWARM_TELEGRAM_BOT_TOKEN, SWARM_TELEGRAM_CHAT_ID, SWARM_AUTO_MERGE, etc.) via a swarm.conf file. It also implicitly requires git/gh credentials and a working 'claude' CLI (and whatever credentials that CLI uses). The skill should explicitly list these dependencies/credentials because they are necessary and sensitive.

Persistence & Privilege

always:false (good). The skill spawns background watcher processes, creates logs/state files under its SWARM_DIR, and can autonomously push to remotes and create PRs when started. That autonomously-executing, repo-writing behavior is powerful but consistent with its purpose; users should be aware it can change repository state without additional interactive confirmations unless config flags (like auto-merge) are disabled.

What to consider before installing

This skill does what it says (multi-agent orchestration) but it also has high privileges and network capabilities you must accept before running it. Before installing: 1) Inspect and configure config/swarm.conf; set SWARM_NOTIFY=none until you trust it. 2) Disable SWARM_AUTO_MERGE or set it to false while testing to avoid automatic pushes to main. 3) Run it first in a disposable or test repository (not production) to observe behavior. 4) Review logs/ SWARM_DIR/logs and the saved prompt files for sensitive data; prompts are stored and may be sent to webhooks/Telegram if configured. 5) Ensure you understand the required credentials (git/gh, claude CLI auth, optional webhook/telegram tokens) and grant least privilege (use a throwaway repo account or restricted token). 6) Consider running inside an isolated environment/container to limit network and filesystem impact. The combination of 'bypassPermissions' calls to the model and automatic code changes is powerful — be cautious and test thoroughly.

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 << '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

Role	Model	Effort	Use
architect	opus	high	Design, planning, complex decisions
builder	sonnet	high	Feature implementation (parallel)
reviewer	sonnet	medium	Auto-review on completion
integrator	opus	high	Cross-branch merge + conflict resolution

Configure in config/duty-table.json.

Scripts

Script	Purpose
spawn-batch.sh	Spawn N parallel agents + integration watcher
spawn-agent.sh	Spawn single agent in worktree + tmux
endorse-task.sh	Endorse task (required before spawn)
check-agents.sh	Show status of all running agents
cleanup.sh	Remove worktrees, branches, tmux sessions
notify.sh	Send webhook/Telegram notification
notify-on-complete.sh	Auto-watcher: notify + review on completion
integration-watcher.sh	Auto: 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