From compound-workflows
Orchestrate multi-agent swarms — parallel reviews, pipelines, task queues
npx claudepluginhub adamfeldman/compound-workflows --plugin compound-workflowsThis skill uses the workspace's default tool permissions.
> **Beta / Unreviewed:** This skill is beta. The patterns shown do not include disk-persist
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Beta / Unreviewed: This skill is beta. The patterns shown do not include disk-persist for teammate outputs. Do not copy these patterns without adding OUTPUT INSTRUCTIONS per the disk-persist-agents skill. A broader context-lean review is tracked for when swarms go GA.
Master multi-agent orchestration using Claude Code's TeammateTool and Task system.
| Primitive | What It Is | File Location |
|---|---|---|
| Agent | A Claude instance that can use tools. You are an agent. Subagents are agents you spawn. | N/A (process) |
| Team | A named group of agents working together. One leader, multiple teammates. | ~/.claude/teams/{name}/config.json |
| Teammate | An agent that joined a team. Has a name, color, inbox. Spawned via Task with team_name + name. | Listed in team config |
| Leader | The agent that created the team. Receives teammate messages, approves plans/shutdowns. | First member in config |
| Task | A work item with subject, description, status, owner, and dependencies. | ~/.claude/tasks/{team}/N.json |
| Inbox | JSON file where an agent receives messages from teammates. | ~/.claude/teams/{name}/inboxes/{agent}.json |
| Message | A JSON object sent between agents. Can be text or structured (shutdown_request, idle_notification, etc). | Stored in inbox files |
| Backend | How teammates run. Auto-detected: in-process (same Node.js, invisible), tmux (separate panes, visible), iterm2 (split panes in iTerm2). See Spawn Backends. | Auto-detected based on environment |
flowchart TB
subgraph TEAM[TEAM]
Leader[Leader - you]
T1[Teammate 1]
T2[Teammate 2]
Leader <-->|messages via inbox| T1
Leader <-->|messages via inbox| T2
T1 <-.->|can message| T2
end
subgraph TASKS[TASK LIST]
Task1["#1 completed: Research<br/>owner: teammate1"]
Task2["#2 in_progress: Implement<br/>owner: teammate2"]
Task3["#3 pending: Test<br/>blocked by #2"]
end
T1 --> Task1
T2 --> Task2
Task2 -.->|unblocks| Task3
flowchart LR
A[1. Create Team] --> B[2. Create Tasks]
B --> C[3. Spawn Teammates]
C --> D[4. Work]
D --> E[5. Coordinate]
E --> F[6. Shutdown]
F --> G[7. Cleanup]
sequenceDiagram
participant L as Leader
participant T1 as Teammate 1
participant T2 as Teammate 2
participant Tasks as Task List
L->>Tasks: TaskCreate (3 tasks)
L->>T1: spawn with prompt
L->>T2: spawn with prompt
T1->>Tasks: claim task #1
T2->>Tasks: claim task #2
T1->>Tasks: complete #1
T1->>L: send findings (inbox)
Note over Tasks: #3 auto-unblocks
T2->>Tasks: complete #2
T2->>L: send findings (inbox)
L->>T1: requestShutdown
T1->>L: approveShutdown
L->>T2: requestShutdown
T2->>L: approveShutdown
L->>L: cleanup
A swarm consists of:
~/.claude/teams/{team-name}/
├── config.json # Team metadata and member list
└── inboxes/
├── team-lead.json # Leader's inbox
├── worker-1.json # Worker 1's inbox
└── worker-2.json # Worker 2's inbox
~/.claude/tasks/{team-name}/
├── 1.json # Task #1
├── 2.json # Task #2
└── 3.json # Task #3
{
"name": "my-project",
"description": "Working on feature X",
"leadAgentId": "team-lead@my-project",
"createdAt": 1706000000000,
"members": [
{
"agentId": "team-lead@my-project",
"name": "team-lead",
"agentType": "team-lead",
"color": "#4A90D9",
"joinedAt": 1706000000000,
"backendType": "in-process"
},
{
"agentId": "worker-1@my-project",
"name": "worker-1",
"agentType": "Explore",
"model": "haiku",
"prompt": "Analyze the codebase structure...",
"color": "#D94A4A",
"planModeRequired": false,
"joinedAt": 1706000001000,
"tmuxPaneId": "in-process",
"cwd": "/Users/me/project",
"backendType": "in-process"
}
]
}
Use Task for short-lived, focused work that returns a result:
Task({
subagent_type: "Explore",
description: "Find auth files",
prompt: "Find all authentication-related files in this codebase",
model: "haiku" // Optional: haiku, sonnet, opus
})
Characteristics:
run_in_background: trueUse Task with team_name and name to spawn persistent teammates:
// First create a team
Teammate({ operation: "spawnTeam", team_name: "my-project" })
// Then spawn a teammate into that team
Task({
team_name: "my-project", // Required: which team to join
name: "security-reviewer", // Required: teammate's name
subagent_type: "security-sentinel",
prompt: "Review all authentication code for vulnerabilities. Send findings to team-lead via Teammate write.",
run_in_background: true // Teammates usually run in background
})
Characteristics:
config.json| Aspect | Task (subagent) | Task + team_name + name (teammate) |
|---|---|---|
| Lifespan | Until task complete | Until shutdown requested |
| Communication | Return value | Inbox messages |
| Task access | None | Shared task list |
| Team membership | No | Yes |
| Coordination | One-off | Ongoing |
These are always available without plugins:
Task({
subagent_type: "Bash",
description: "Run git commands",
prompt: "Check git status and show recent commits"
})
Task({
subagent_type: "Explore",
description: "Find API endpoints",
prompt: "Find all API endpoints in this codebase. Be very thorough.",
model: "haiku" // Fast and cheap
})
Task({
subagent_type: "Plan",
description: "Design auth system",
prompt: "Create an implementation plan for adding OAuth2 authentication"
})
Task({
subagent_type: "general-purpose",
description: "Research and implement",
prompt: "Research React Query best practices and implement caching for the user API"
})
Task({
subagent_type: "claude-code-guide",
description: "Help with Claude Code",
prompt: "How do I configure MCP servers?"
})
Task({
subagent_type: "statusline-setup",
description: "Configure status line",
prompt: "Set up a status line showing git branch and node version"
})
From the compound-workflows plugin (examples):
// Security review
Task({
subagent_type: "compound:review:security-sentinel",
description: "Security audit",
prompt: "Audit this PR for security vulnerabilities"
})
// Performance review
Task({
subagent_type: "compound:review:performance-oracle",
description: "Performance check",
prompt: "Analyze this code for performance bottlenecks"
})
// Architecture review
Task({
subagent_type: "compound:review:architecture-strategist",
description: "Architecture review",
prompt: "Review the system architecture of the authentication module"
})
// Code simplicity
Task({
subagent_type: "compound:review:code-simplicity-reviewer",
description: "Simplicity check",
prompt: "Check if this implementation can be simplified"
})
All review agents from compound:
agent-native-reviewer - Ensures features work for agents tooarchitecture-strategist - Architectural compliancecode-simplicity-reviewer - YAGNI and minimalismdata-integrity-guardian - Database and data safetydata-migration-expert - Migration validationdeployment-verification-agent - Pre-deploy checklistsfrontend-races-reviewer - JavaScript race conditionspython-reviewer - Python best practicestypescript-reviewer - TypeScript best practicespattern-recognition-specialist - Design patterns and anti-patternsperformance-oracle - Performance analysissecurity-sentinel - Security vulnerabilities// Best practices research
Task({
subagent_type: "compound:research:best-practices-researcher",
description: "Research auth best practices",
prompt: "Research current best practices for JWT authentication in Rails 2024-2026"
})
// Framework documentation
Task({
subagent_type: "compound:research:framework-docs-researcher",
description: "Research Active Storage",
prompt: "Gather comprehensive documentation about Active Storage file uploads"
})
// Git history analysis
Task({
subagent_type: "compound:research:git-history-analyzer",
description: "Analyze auth history",
prompt: "Analyze the git history of the authentication module to understand its evolution"
})
All research agents:
best-practices-researcher - External best practicesframework-docs-researcher - Framework documentationgit-history-analyzer - Code archaeologylearnings-researcher - Search docs/solutions/repo-research-analyst - Repository patternsTask({
subagent_type: "compound:workflow:bug-reproduction-validator",
description: "Validate bug",
prompt: "Reproduce and validate this reported bug: [description]"
})
Teammate({
operation: "spawnTeam",
team_name: "feature-auth",
description: "Implementing OAuth2 authentication"
})
Creates:
~/.claude/teams/feature-auth/config.json~/.claude/tasks/feature-auth/ directoryTeammate({ operation: "discoverTeams" })
Returns: List of teams you can join (not already a member of)
Teammate({
operation: "requestJoin",
team_name: "feature-auth",
proposed_name: "helper",
capabilities: "I can help with code review and testing"
})
When you receive a join_request message:
{"type": "join_request", "proposedName": "helper", "requestId": "join-123", ...}
Approve it:
Teammate({
operation: "approveJoin",
target_agent_id: "helper",
request_id: "join-123"
})
Teammate({
operation: "rejectJoin",
target_agent_id: "helper",
request_id: "join-123",
reason: "Team is at capacity"
})
Teammate({
operation: "write",
target_agent_id: "security-reviewer",
value: "Please prioritize the authentication module. The deadline is tomorrow."
})
Important for teammates: Your text output is NOT visible to the team. You MUST use write to communicate.
Teammate({
operation: "broadcast",
name: "team-lead", // Your name
value: "Status check: Please report your progress"
})
WARNING: Broadcasting is expensive - sends N separate messages for N teammates. Prefer write to specific teammates.
When to broadcast:
When NOT to broadcast:
Teammate({
operation: "requestShutdown",
target_agent_id: "security-reviewer",
reason: "All tasks complete, wrapping up"
})
When you receive a shutdown_request message:
{"type": "shutdown_request", "requestId": "shutdown-123", "from": "team-lead", "reason": "Done"}
MUST call:
Teammate({
operation: "approveShutdown",
request_id: "shutdown-123"
})
This sends confirmation and terminates your process.
Teammate({
operation: "rejectShutdown",
request_id: "shutdown-123",
reason: "Still working on task #3, need 5 more minutes"
})
When teammate with plan_mode_required sends a plan:
{"type": "plan_approval_request", "from": "architect", "requestId": "plan-456", ...}
Approve:
Teammate({
operation: "approvePlan",
target_agent_id: "architect",
request_id: "plan-456"
})
Teammate({
operation: "rejectPlan",
target_agent_id: "architect",
request_id: "plan-456",
feedback: "Please add error handling for the API calls and consider rate limiting"
})
Teammate({ operation: "cleanup" })
Removes:
~/.claude/teams/{team-name}/ directory~/.claude/tasks/{team-name}/ directoryIMPORTANT: Will fail if teammates are still active. Use requestShutdown first.
TaskCreate({
subject: "Review authentication module",
description: "Review all files in app/services/auth/ for security vulnerabilities",
activeForm: "Reviewing auth module..." // Shown in spinner when in_progress
})
TaskList()
Returns:
#1 [completed] Analyze codebase structure
#2 [in_progress] Review authentication module (owner: security-reviewer)
#3 [pending] Generate summary report [blocked by #2]
TaskGet({ taskId: "2" })
Returns full task with description, status, blockedBy, etc.
// Claim a task
TaskUpdate({ taskId: "2", owner: "security-reviewer" })
// Start working
TaskUpdate({ taskId: "2", status: "in_progress" })
// Mark complete
TaskUpdate({ taskId: "2", status: "completed" })
// Set up dependencies
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })
When a blocking task is completed, blocked tasks are automatically unblocked:
// Create pipeline
TaskCreate({ subject: "Step 1: Research" }) // #1
TaskCreate({ subject: "Step 2: Implement" }) // #2
TaskCreate({ subject: "Step 3: Test" }) // #3
TaskCreate({ subject: "Step 4: Deploy" }) // #4
// Set up dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] }) // #2 waits for #1
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] }) // #3 waits for #2
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] }) // #4 waits for #3
// When #1 completes, #2 auto-unblocks
// When #2 completes, #3 auto-unblocks
// etc.
~/.claude/tasks/{team-name}/1.json:
{
"id": "1",
"subject": "Review authentication module",
"description": "Review all files in app/services/auth/...",
"status": "in_progress",
"owner": "security-reviewer",
"activeForm": "Reviewing auth module...",
"blockedBy": [],
"blocks": ["3"],
"createdAt": 1706000000000,
"updatedAt": 1706000001000
}
{
"from": "team-lead",
"text": "Please prioritize the auth module",
"timestamp": "2026-01-25T23:38:32.588Z",
"read": false
}
{
"type": "shutdown_request",
"requestId": "shutdown-abc123@worker-1",
"from": "team-lead",
"reason": "All tasks complete",
"timestamp": "2026-01-25T23:38:32.588Z"
}
{
"type": "shutdown_approved",
"requestId": "shutdown-abc123@worker-1",
"from": "worker-1",
"paneId": "%5",
"backendType": "in-process",
"timestamp": "2026-01-25T23:39:00.000Z"
}
{
"type": "idle_notification",
"from": "worker-1",
"timestamp": "2026-01-25T23:40:00.000Z",
"completedTaskId": "2",
"completedStatus": "completed"
}
{
"type": "task_completed",
"from": "worker-1",
"taskId": "2",
"taskSubject": "Review authentication module",
"timestamp": "2026-01-25T23:40:00.000Z"
}
{
"type": "plan_approval_request",
"from": "architect",
"requestId": "plan-xyz789",
"planContent": "# Implementation Plan\n\n1. ...",
"timestamp": "2026-01-25T23:41:00.000Z"
}
{
"type": "join_request",
"proposedName": "helper",
"requestId": "join-abc123",
"capabilities": "Code review and testing",
"timestamp": "2026-01-25T23:42:00.000Z"
}
{
"type": "permission_request",
"requestId": "perm-123",
"workerId": "worker-1@my-project",
"workerName": "worker-1",
"workerColor": "#4A90D9",
"toolName": "Bash",
"toolUseId": "toolu_abc123",
"description": "Run npm install",
"input": {"command": "npm install"},
"permissionSuggestions": ["Bash(npm *)"],
"createdAt": 1706000000000
}
Multiple specialists review code simultaneously:
// 1. Create team
Teammate({ operation: "spawnTeam", team_name: "code-review" })
// 2. Spawn specialists in parallel (single message, multiple Task calls)
Task({
team_name: "code-review",
name: "security",
subagent_type: "compound:review:security-sentinel",
prompt: "Review the PR for security vulnerabilities. Focus on: SQL injection, XSS, auth bypass. Send findings to team-lead.",
run_in_background: true
})
Task({
team_name: "code-review",
name: "performance",
subagent_type: "compound:review:performance-oracle",
prompt: "Review the PR for performance issues. Focus on: N+1 queries, memory leaks, slow algorithms. Send findings to team-lead.",
run_in_background: true
})
Task({
team_name: "code-review",
name: "simplicity",
subagent_type: "compound:review:code-simplicity-reviewer",
prompt: "Review the PR for unnecessary complexity. Focus on: over-engineering, premature abstraction, YAGNI violations. Send findings to team-lead.",
run_in_background: true
})
// 3. Wait for results (check inbox)
// cat ~/.claude/teams/code-review/inboxes/team-lead.json
// 4. Synthesize findings and cleanup
Teammate({ operation: "requestShutdown", target_agent_id: "security" })
Teammate({ operation: "requestShutdown", target_agent_id: "performance" })
Teammate({ operation: "requestShutdown", target_agent_id: "simplicity" })
// Wait for approvals...
Teammate({ operation: "cleanup" })
Each stage depends on the previous:
// 1. Create team and task pipeline
Teammate({ operation: "spawnTeam", team_name: "feature-pipeline" })
TaskCreate({ subject: "Research", description: "Research best practices for the feature", activeForm: "Researching..." })
TaskCreate({ subject: "Plan", description: "Create implementation plan based on research", activeForm: "Planning..." })
TaskCreate({ subject: "Implement", description: "Implement the feature according to plan", activeForm: "Implementing..." })
TaskCreate({ subject: "Test", description: "Write and run tests for the implementation", activeForm: "Testing..." })
TaskCreate({ subject: "Review", description: "Final code review before merge", activeForm: "Reviewing..." })
// Set up sequential dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })
TaskUpdate({ taskId: "5", addBlockedBy: ["4"] })
// 2. Spawn workers that claim and complete tasks
Task({
team_name: "feature-pipeline",
name: "researcher",
subagent_type: "compound:research:best-practices-researcher",
prompt: "Claim task #1, research best practices, complete it, send findings to team-lead. Then check for more work.",
run_in_background: true
})
Task({
team_name: "feature-pipeline",
name: "implementer",
subagent_type: "general-purpose",
prompt: "Poll TaskList every 30 seconds. When task #3 unblocks, claim it and implement. Then complete and notify team-lead.",
run_in_background: true
})
// Tasks auto-unblock as dependencies complete
Workers grab available tasks from a pool:
// 1. Create team and task pool
Teammate({ operation: "spawnTeam", team_name: "file-review-swarm" })
// Create many independent tasks (no dependencies)
for (const file of ["auth.rb", "user.rb", "api_controller.rb", "payment.rb"]) {
TaskCreate({
subject: `Review ${file}`,
description: `Review ${file} for security and code quality issues`,
activeForm: `Reviewing ${file}...`
})
}
// 2. Spawn worker swarm
Task({
team_name: "file-review-swarm",
name: "worker-1",
subagent_type: "general-purpose",
prompt: `
You are a swarm worker. Your job:
1. Call TaskList to see available tasks
2. Find a task with status 'pending' and no owner
3. Claim it with TaskUpdate (set owner to your name)
4. Do the work
5. Mark it completed with TaskUpdate
6. Send findings to team-lead via Teammate write
7. Repeat until no tasks remain
`,
run_in_background: true
})
Task({
team_name: "file-review-swarm",
name: "worker-2",
subagent_type: "general-purpose",
prompt: `[Same prompt as worker-1]`,
run_in_background: true
})
Task({
team_name: "file-review-swarm",
name: "worker-3",
subagent_type: "general-purpose",
prompt: `[Same prompt as worker-1]`,
run_in_background: true
})
// Workers race to claim tasks, naturally load-balance
Research first, then implement:
// 1. Research phase (synchronous, returns results)
const research = await Task({
subagent_type: "compound:research:best-practices-researcher",
description: "Research caching patterns",
prompt: "Research best practices for implementing caching in Rails APIs. Include: cache invalidation strategies, Redis vs Memcached, cache key design."
})
// 2. Use research to guide implementation
Task({
subagent_type: "general-purpose",
description: "Implement caching",
prompt: `
Implement API caching based on this research:
${research.content}
Focus on the user_controller.rb endpoints.
`
})
Require plan approval before implementation:
// 1. Create team
Teammate({ operation: "spawnTeam", team_name: "careful-work" })
// 2. Spawn architect with plan_mode_required
Task({
team_name: "careful-work",
name: "architect",
subagent_type: "Plan",
prompt: "Design an implementation plan for adding OAuth2 authentication",
mode: "plan", // Requires plan approval
run_in_background: true
})
// 3. Wait for plan approval request
// You'll receive: {"type": "plan_approval_request", "from": "architect", "requestId": "plan-xxx", ...}
// 4. Review and approve/reject
Teammate({
operation: "approvePlan",
target_agent_id: "architect",
request_id: "plan-xxx"
})
// OR
Teammate({
operation: "rejectPlan",
target_agent_id: "architect",
request_id: "plan-xxx",
feedback: "Please add rate limiting considerations"
})
// 1. Create team for coordinated refactoring
Teammate({ operation: "spawnTeam", team_name: "refactor-auth" })
// 2. Create tasks with clear file boundaries
TaskCreate({
subject: "Refactor User model",
description: "Extract authentication methods to AuthenticatableUser concern",
activeForm: "Refactoring User model..."
})
TaskCreate({
subject: "Refactor Session controller",
description: "Update to use new AuthenticatableUser concern",
activeForm: "Refactoring Sessions..."
})
TaskCreate({
subject: "Update specs",
description: "Update all authentication specs for new structure",
activeForm: "Updating specs..."
})
// Dependencies: specs depend on both refactors completing
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })
// 3. Spawn workers for each task
Task({
team_name: "refactor-auth",
name: "model-worker",
subagent_type: "general-purpose",
prompt: "Claim task #1, refactor the User model, complete when done",
run_in_background: true
})
Task({
team_name: "refactor-auth",
name: "controller-worker",
subagent_type: "general-purpose",
prompt: "Claim task #2, refactor the Session controller, complete when done",
run_in_background: true
})
Task({
team_name: "refactor-auth",
name: "spec-worker",
subagent_type: "general-purpose",
prompt: "Wait for task #3 to unblock (when #1 and #2 complete), then update specs",
run_in_background: true
})
Spawned teammates automatically receive these:
CLAUDE_CODE_TEAM_NAME="my-project"
CLAUDE_CODE_AGENT_ID="worker-1@my-project"
CLAUDE_CODE_AGENT_NAME="worker-1"
CLAUDE_CODE_AGENT_TYPE="Explore"
CLAUDE_CODE_AGENT_COLOR="#4A90D9"
CLAUDE_CODE_PLAN_MODE_REQUIRED="false"
CLAUDE_CODE_PARENT_SESSION_ID="session-xyz"
Using in prompts:
Task({
team_name: "my-project",
name: "worker",
subagent_type: "general-purpose",
prompt: "Your name is $CLAUDE_CODE_AGENT_NAME. Use it when sending messages to team-lead."
})
A backend determines how teammate Claude instances actually run. Claude Code supports three backends, and auto-detects the best one based on your environment.
| Backend | How It Works | Visibility | Persistence | Speed |
|---|---|---|---|---|
| in-process | Same Node.js process as leader | Hidden (background) | Dies with leader | Fastest |
| tmux | Separate terminal in tmux session | Visible in tmux | Survives leader exit | Medium |
| iterm2 | Split panes in iTerm2 window | Visible side-by-side | Dies with window | Medium |
Claude Code automatically selects a backend using this decision tree:
flowchart TD
A[Start] --> B{Running inside tmux?}
B -->|Yes| C[Use tmux backend]
B -->|No| D{Running in iTerm2?}
D -->|No| E{tmux available?}
E -->|Yes| F[Use tmux - external session]
E -->|No| G[Use in-process]
D -->|Yes| H{it2 CLI installed?}
H -->|Yes| I[Use iterm2 backend]
H -->|No| J{tmux available?}
J -->|Yes| K[Use tmux - prompt to install it2]
J -->|No| L[Error: Install tmux or it2]
Detection checks:
$TMUX environment variable → inside tmux$TERM_PROGRAM === "iTerm.app" or $ITERM_SESSION_ID → in iTerm2which tmux → tmux availablewhich it2 → it2 CLI installedTeammates run as async tasks within the same Node.js process.
How it works:
When it's used:
CLAUDE_CODE_SPAWN_BACKEND=in-processCharacteristics:
┌─────────────────────────────────────────┐
│ Node.js Process │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Leader │ │Worker 1 │ │Worker 2 │ │
│ │ (main) │ │ (async) │ │ (async) │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────┘
Pros:
Cons:
// in-process is automatic when not in tmux
Task({
team_name: "my-project",
name: "worker",
subagent_type: "general-purpose",
prompt: "...",
run_in_background: true
})
// Force in-process explicitly
// export CLAUDE_CODE_SPAWN_BACKEND=in-process
Teammates run as separate Claude instances in tmux panes/windows.
How it works:
When it's used:
$TMUX is set)CLAUDE_CODE_SPAWN_BACKEND=tmuxLayout modes:
┌─────────────────┬─────────────────┐
│ │ Worker 1 │
│ Leader ├─────────────────┤
│ (your pane) │ Worker 2 │
│ ├─────────────────┤
│ │ Worker 3 │
└─────────────────┴─────────────────┘
claude-swarm# Your terminal stays as-is
# Workers run in separate tmux session
# View workers:
tmux attach -t claude-swarm
Pros:
Cons:
# Start tmux session first
tmux new-session -s claude
# Or force tmux backend
export CLAUDE_CODE_SPAWN_BACKEND=tmux
Useful tmux commands:
# List all panes in current window
tmux list-panes
# Switch to pane by number
tmux select-pane -t 1
# Kill a specific pane
tmux kill-pane -t %5
# View swarm session (if external)
tmux attach -t claude-swarm
# Rebalance pane layout
tmux select-layout tiled
Teammates run as split panes within your iTerm2 window.
How it works:
it2 CLIWhen it's used:
$TERM_PROGRAM === "iTerm.app")it2 CLI is installed and workingLayout:
┌─────────────────┬─────────────────┐
│ │ Worker 1 │
│ Leader ├─────────────────┤
│ (your pane) │ Worker 2 │
│ ├─────────────────┤
│ │ Worker 3 │
└─────────────────┴─────────────────┘
Pros:
Cons:
Setup:
# 1. Install it2 CLI
uv tool install it2
# OR
pipx install it2
# OR
pip install --user it2
# 2. Enable Python API in iTerm2
# iTerm2 → Settings → General → Magic → Enable Python API
# 3. Restart iTerm2
# 4. Verify
it2 --version
it2 session list
If setup fails: Claude Code will prompt you to set up it2 when you first spawn a teammate. You can choose to:
# Force in-process (fastest, no visibility)
export CLAUDE_CODE_SPAWN_BACKEND=in-process
# Force tmux (visible panes, persistent)
export CLAUDE_CODE_SPAWN_BACKEND=tmux
# Auto-detect (default)
unset CLAUDE_CODE_SPAWN_BACKEND
The backend type is recorded per-teammate in config.json:
{
"members": [
{
"name": "worker-1",
"backendType": "in-process",
"tmuxPaneId": "in-process"
},
{
"name": "worker-2",
"backendType": "tmux",
"tmuxPaneId": "%5"
}
]
}
| Issue | Cause | Solution |
|---|---|---|
| "No pane backend available" | Neither tmux nor iTerm2 available | Install tmux: brew install tmux |
| "it2 CLI not installed" | In iTerm2 but missing it2 | Run uv tool install it2 |
| "Python API not enabled" | it2 can't communicate with iTerm2 | Enable in iTerm2 Settings → General → Magic |
| Workers not visible | Using in-process backend | Start inside tmux or iTerm2 |
| Workers dying unexpectedly | Outside tmux, leader exited | Use tmux for persistence |
# See what backend was detected
cat ~/.claude/teams/{team}/config.json | jq '.members[].backendType'
# Check if inside tmux
echo $TMUX
# Check if in iTerm2
echo $TERM_PROGRAM
# Check tmux availability
which tmux
# Check it2 availability
which it2
| Error | Cause | Solution |
|---|---|---|
| "Cannot cleanup with active members" | Teammates still running | requestShutdown all teammates first, wait for approval |
| "Already leading a team" | Team already exists | cleanup first, or use different team name |
| "Agent not found" | Wrong teammate name | Check config.json for actual names |
| "Team does not exist" | No team created | Call spawnTeam first |
| "team_name is required" | Missing team context | Provide team_name parameter |
| "Agent type not found" | Invalid subagent_type | Check available agents with proper prefix |
Always follow this sequence:
// 1. Request shutdown for all teammates
Teammate({ operation: "requestShutdown", target_agent_id: "worker-1" })
Teammate({ operation: "requestShutdown", target_agent_id: "worker-2" })
// 2. Wait for shutdown approvals
// Check for {"type": "shutdown_approved", ...} messages
// 3. Verify no active members
// Read ~/.claude/teams/{team}/config.json
// 4. Only then cleanup
Teammate({ operation: "cleanup" })
Teammates have a 5-minute heartbeat timeout. If a teammate crashes:
# Check team config
cat ~/.claude/teams/{team}/config.json | jq '.members[] | {name, agentType, backendType}'
# Check teammate inboxes
cat ~/.claude/teams/{team}/inboxes/{agent}.json | jq '.'
# List all teams
ls ~/.claude/teams/
# Check task states
cat ~/.claude/tasks/{team}/*.json | jq '{id, subject, status, owner, blockedBy}'
# Watch for new messages
tail -f ~/.claude/teams/{team}/inboxes/team-lead.json
// === STEP 1: Setup ===
Teammate({ operation: "spawnTeam", team_name: "pr-review-123", description: "Reviewing PR #123" })
// === STEP 2: Spawn reviewers in parallel ===
// (Send all these in a single message for parallel execution)
Task({
team_name: "pr-review-123",
name: "security",
subagent_type: "compound:review:security-sentinel",
prompt: `Review PR #123 for security vulnerabilities.
Focus on:
- SQL injection
- XSS vulnerabilities
- Authentication/authorization bypass
- Sensitive data exposure
When done, send your findings to team-lead using:
Teammate({ operation: "write", target_agent_id: "team-lead", value: "Your findings here" })`,
run_in_background: true
})
Task({
team_name: "pr-review-123",
name: "perf",
subagent_type: "compound:review:performance-oracle",
prompt: `Review PR #123 for performance issues.
Focus on:
- N+1 queries
- Missing indexes
- Memory leaks
- Inefficient algorithms
Send findings to team-lead when done.`,
run_in_background: true
})
Task({
team_name: "pr-review-123",
name: "arch",
subagent_type: "compound:review:architecture-strategist",
prompt: `Review PR #123 for architectural concerns.
Focus on:
- Design pattern adherence
- SOLID principles
- Separation of concerns
- Testability
Send findings to team-lead when done.`,
run_in_background: true
})
// === STEP 3: Monitor and collect results ===
// Poll inbox or wait for idle notifications
// cat ~/.claude/teams/pr-review-123/inboxes/team-lead.json
// === STEP 4: Synthesize findings ===
// Combine all reviewer findings into a cohesive report
// === STEP 5: Cleanup ===
Teammate({ operation: "requestShutdown", target_agent_id: "security" })
Teammate({ operation: "requestShutdown", target_agent_id: "perf" })
Teammate({ operation: "requestShutdown", target_agent_id: "arch" })
// Wait for approvals...
Teammate({ operation: "cleanup" })
// === SETUP ===
Teammate({ operation: "spawnTeam", team_name: "feature-oauth" })
// === CREATE PIPELINE ===
TaskCreate({ subject: "Research OAuth providers", description: "Research OAuth2 best practices and compare providers (Google, GitHub, Auth0)", activeForm: "Researching OAuth..." })
TaskCreate({ subject: "Create implementation plan", description: "Design OAuth implementation based on research findings", activeForm: "Planning..." })
TaskCreate({ subject: "Implement OAuth", description: "Implement OAuth2 authentication according to plan", activeForm: "Implementing OAuth..." })
TaskCreate({ subject: "Write tests", description: "Write comprehensive tests for OAuth implementation", activeForm: "Writing tests..." })
TaskCreate({ subject: "Final review", description: "Review complete implementation for security and quality", activeForm: "Final review..." })
// Set dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })
TaskUpdate({ taskId: "5", addBlockedBy: ["4"] })
// === SPAWN SPECIALIZED WORKERS ===
Task({
team_name: "feature-oauth",
name: "researcher",
subagent_type: "compound:research:best-practices-researcher",
prompt: "Claim task #1. Research OAuth2 best practices, compare providers, document findings. Mark task complete and send summary to team-lead.",
run_in_background: true
})
Task({
team_name: "feature-oauth",
name: "planner",
subagent_type: "Plan",
prompt: "Wait for task #2 to unblock. Read research from task #1. Create detailed implementation plan. Mark complete and send plan to team-lead.",
run_in_background: true
})
Task({
team_name: "feature-oauth",
name: "implementer",
subagent_type: "general-purpose",
prompt: "Wait for task #3 to unblock. Read plan from task #2. Implement OAuth2 authentication. Mark complete when done.",
run_in_background: true
})
Task({
team_name: "feature-oauth",
name: "tester",
subagent_type: "general-purpose",
prompt: "Wait for task #4 to unblock. Write comprehensive tests for the OAuth implementation. Run tests. Mark complete with results.",
run_in_background: true
})
Task({
team_name: "feature-oauth",
name: "reviewer",
subagent_type: "compound:review:security-sentinel",
prompt: "Wait for task #5 to unblock. Review the complete OAuth implementation for security. Send final assessment to team-lead.",
run_in_background: true
})
// Pipeline auto-progresses as each stage completes
// === SETUP ===
Teammate({ operation: "spawnTeam", team_name: "codebase-review" })
// === CREATE TASK POOL (all independent, no dependencies) ===
const filesToReview = [
"app/models/user.rb",
"app/models/payment.rb",
"app/controllers/api/v1/users_controller.rb",
"app/controllers/api/v1/payments_controller.rb",
"app/services/payment_processor.rb",
"app/services/notification_service.rb",
"lib/encryption_helper.rb"
]
for (const file of filesToReview) {
TaskCreate({
subject: `Review ${file}`,
description: `Review ${file} for security vulnerabilities, code quality, and performance issues`,
activeForm: `Reviewing ${file}...`
})
}
// === SPAWN WORKER SWARM ===
const swarmPrompt = `
You are a swarm worker. Your job is to continuously process available tasks.
LOOP:
1. Call TaskList() to see available tasks
2. Find a task that is:
- status: 'pending'
- no owner
- not blocked
3. If found:
- Claim it: TaskUpdate({ taskId: "X", owner: "YOUR_NAME" })
- Start it: TaskUpdate({ taskId: "X", status: "in_progress" })
- Do the review work
- Complete it: TaskUpdate({ taskId: "X", status: "completed" })
- Send findings to team-lead via Teammate write
- Go back to step 1
4. If no tasks available:
- Send idle notification to team-lead
- Wait 30 seconds
- Try again (up to 3 times)
- If still no tasks, exit
Replace YOUR_NAME with your actual agent name from $CLAUDE_CODE_AGENT_NAME.
`
// Spawn 3 workers
Task({ team_name: "codebase-review", name: "worker-1", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })
Task({ team_name: "codebase-review", name: "worker-2", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })
Task({ team_name: "codebase-review", name: "worker-3", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })
// Workers self-organize: race to claim tasks, naturally load-balance
// Monitor progress with TaskList() or by reading inbox
Don't leave orphaned teams. Always call cleanup when done.
// Good
name: "security-reviewer"
name: "oauth-implementer"
name: "test-writer"
// Bad
name: "worker-1"
name: "agent-2"
Tell workers exactly what to do:
// Good
prompt: `
1. Review app/models/user.rb for N+1 queries
2. Check all ActiveRecord associations have proper includes
3. Document any issues found
4. Send findings to team-lead via Teammate write
`
// Bad
prompt: "Review the code"
Let the system manage unblocking:
// Good: Auto-unblocking
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
// Bad: Manual polling
"Wait until task #1 is done, check every 30 seconds..."
Workers send results to your inbox. Check it:
cat ~/.claude/teams/{team}/inboxes/team-lead.json | jq '.'
broadcast sends N messages for N teammates. Use write for targeted communication.
Task({ subagent_type: "Explore", description: "Find files", prompt: "..." })
Teammate({ operation: "spawnTeam", team_name: "my-team" })
Task({ team_name: "my-team", name: "worker", subagent_type: "general-purpose", prompt: "...", run_in_background: true })
Teammate({ operation: "write", target_agent_id: "worker-1", value: "..." })
TaskCreate({ subject: "Step 1", description: "..." })
TaskCreate({ subject: "Step 2", description: "..." })
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
Teammate({ operation: "requestShutdown", target_agent_id: "worker-1" })
// Wait for approval...
Teammate({ operation: "cleanup" })
Based on Claude Code v2.1.19 - Tested and verified 2026-01-25