Claude Code Swarm Orchestration Master multi-agent orchestration using Claude Code's TeammateTool and Task system. Primitives 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 How They Connect 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
owner: teammate1"] Task2 ["#2 in_progress: Implement
owner: teammate2"] Task3 ["#3 pending: Test
blocked by #2"] end T1 --> Task1 T2 --> Task2 Task2 -.-> |unblocks| Task3 Lifecycle 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] Message Flow 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 Table of Contents Core Architecture Two Ways to Spawn Agents Built-in Agent Types Plugin Agent Types TeammateTool Operations Task System Integration Message Formats Orchestration Patterns Environment Variables Spawn Backends Error Handling Complete Workflows Core Architecture How Swarms Work A swarm consists of: Leader (you) - Creates team, spawns workers, coordinates work Teammates (spawned agents) - Execute tasks, report back Task List - Shared work queue with dependencies Inboxes - JSON files for inter-agent messaging File Structure ~/.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 Team Config Structure { "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" } ] } Two Ways to Spawn Agents Method 1: Task Tool (Subagents) 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: Runs synchronously (blocks until complete) or async with run_in_background: true Returns result directly to you No team membership required Best for: searches, analysis, focused research Method 2: Task Tool + team_name + name (Teammates) Use 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: Joins team, appears in config.json Communicates via inbox messages Can claim tasks from shared task list Persists until shutdown Best for: parallel work, ongoing collaboration, pipeline stages Key Difference 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 Built-in Agent Types These are always available without plugins: Bash Task ( { subagent_type : "Bash" , description : "Run git commands" , prompt : "Check git status and show recent commits" } ) Tools: Bash only Model: Inherits from parent Best for: Git operations, command execution, system tasks Explore Task ( { subagent_type : "Explore" , description : "Find API endpoints" , prompt : "Find all API endpoints in this codebase. Be very thorough." , model : "haiku" // Fast and cheap } ) Tools: All read-only tools (no Edit, Write, NotebookEdit, Task) Model: Haiku (optimized for speed) Best for: Codebase exploration, file searches, code understanding Thoroughness levels: "quick", "medium", "very thorough" Plan Task ( { subagent_type : "Plan" , description : "Design auth system" , prompt : "Create an implementation plan for adding OAuth2 authentication" } ) Tools: All read-only tools Model: Inherits from parent Best for: Architecture planning, implementation strategies general-purpose Task ( { subagent_type : "general-purpose" , description : "Research and implement" , prompt : "Research React Query best practices and implement caching for the user API" } ) Tools: All tools (*) Model: Inherits from parent Best for: Multi-step tasks, research + action combinations claude-code-guide Task ( { subagent_type : "claude-code-guide" , description : "Help with Claude Code" , prompt : "How do I configure MCP servers?" } ) Tools: Read-only + WebFetch + WebSearch Best for: Questions about Claude Code, Agent SDK, Anthropic API statusline-setup Task ( { subagent_type : "statusline-setup" , description : "Configure status line" , prompt : "Set up a status line showing git branch and node version" } ) Tools: Read, Edit only Model: Sonnet Best for: Configuring Claude Code status line Plugin Agent Types From the compound-engineering plugin (examples): Review Agents // Security review Task ( { subagent_type : "compound-engineering:review:security-sentinel" , description : "Security audit" , prompt : "Audit this PR for security vulnerabilities" } ) // Performance review Task ( { subagent_type : "compound-engineering:review:performance-oracle" , description : "Performance check" , prompt : "Analyze this code for performance bottlenecks" } ) // Rails code review Task ( { subagent_type : "compound-engineering:review:kieran-rails-reviewer" , description : "Rails review" , prompt : "Review this Rails code for best practices" } ) // Architecture review Task ( { subagent_type : "compound-engineering:review:architecture-strategist" , description : "Architecture review" , prompt : "Review the system architecture of the authentication module" } ) // Code simplicity Task ( { subagent_type : "compound-engineering:review:code-simplicity-reviewer" , description : "Simplicity check" , prompt : "Check if this implementation can be simplified" } ) All review agents from compound-engineering: agent-native-reviewer - Ensures features work for agents too architecture-strategist - Architectural compliance code-simplicity-reviewer - YAGNI and minimalism data-integrity-guardian - Database and data safety data-migration-expert - Migration validation deployment-verification-agent - Pre-deploy checklists dhh-rails-reviewer - DHH/37signals Rails style julik-frontend-races-reviewer - JavaScript race conditions kieran-python-reviewer - Python best practices kieran-rails-reviewer - Rails best practices kieran-typescript-reviewer - TypeScript best practices pattern-recognition-specialist - Design patterns and anti-patterns performance-oracle - Performance analysis security-sentinel - Security vulnerabilities Research Agents // Best practices research Task ( { subagent_type : "compound-engineering: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-engineering:research:framework-docs-researcher" , description : "Research Active Storage" , prompt : "Gather comprehensive documentation about Active Storage file uploads" } ) // Git history analysis Task ( { subagent_type : "compound-engineering: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 practices framework-docs-researcher - Framework documentation git-history-analyzer - Code archaeology learnings-researcher - Search docs/solutions/ repo-research-analyst - Repository patterns Design Agents Task ( { subagent_type : "compound-engineering:design:figma-design-sync" , description : "Sync with Figma" , prompt : "Compare implementation with Figma design at [URL]" } ) Workflow Agents Task ( { subagent_type : "compound-engineering:workflow:bug-reproduction-validator" , description : "Validate bug" , prompt : "Reproduce and validate this reported bug: [description]" } ) TeammateTool Operations 1. spawnTeam - Create a Team Teammate ( { operation : "spawnTeam" , team_name : "feature-auth" , description : "Implementing OAuth2 authentication" } ) Creates: ~/.claude/teams/feature-auth/config.json ~/.claude/tasks/feature-auth/ directory You become the team leader 2. discoverTeams - List Available Teams Teammate ( { operation : "discoverTeams" } ) Returns: List of teams you can join (not already a member of) 3. requestJoin - Request to Join Team Teammate ( { operation : "requestJoin" , team_name : "feature-auth" , proposed_name : "helper" , capabilities : "I can help with code review and testing" } ) 4. approveJoin - Accept Join Request (Leader Only) 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" } ) 5. rejectJoin - Decline Join Request (Leader Only) Teammate ( { operation : "rejectJoin" , target_agent_id : "helper" , request_id : "join-123" , reason : "Team is at capacity" } ) 6. write - Message One Teammate 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. 7. broadcast - Message ALL Teammates 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: Critical issues requiring immediate attention Major announcements affecting everyone When NOT to broadcast: Responding to one teammate Normal back-and-forth Information relevant to only some teammates 8. requestShutdown - Ask Teammate to Exit (Leader Only) Teammate ( { operation : "requestShutdown" , target_agent_id : "security-reviewer" , reason : "All tasks complete, wrapping up" } ) 9. approveShutdown - Accept Shutdown (Teammate Only) 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. 10. rejectShutdown - Decline Shutdown (Teammate Only) Teammate ( { operation : "rejectShutdown" , request_id : "shutdown-123" , reason : "Still working on task #3, need 5 more minutes" } ) 11. approvePlan - Approve Teammate's Plan (Leader Only) 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" } ) 12. rejectPlan - Reject Plan with Feedback (Leader Only) Teammate ( { operation : "rejectPlan" , target_agent_id : "architect" , request_id : "plan-456" , feedback : "Please add error handling for the API calls and consider rate limiting" } ) 13. cleanup - Remove Team Resources Teammate ( { operation : "cleanup" } ) Removes: ~/.claude/teams/{team-name}/ directory ~/.claude/tasks/{team-name}/ directory IMPORTANT: Will fail if teammates are still active. Use requestShutdown first. Task System Integration TaskCreate - Create Work Items 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 - See All Tasks 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 - Get Task Details TaskGet ( { taskId : "2" } ) Returns full task with description, status, blockedBy, etc. TaskUpdate - Update Task Status // 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" ] } ) Task Dependencies 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. Task File Structure ~/.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 } Message Formats Regular Message { "from" : "team-lead" , "text" : "Please prioritize the auth module" , "timestamp" : "2026-01-25T23:38:32.588Z" , "read" : false } Structured Messages (JSON in text field) Shutdown Request { "type" : "shutdown_request" , "requestId" : "shutdown-abc123@worker-1" , "from" : "team-lead" , "reason" : "All tasks complete" , "timestamp" : "2026-01-25T23:38:32.588Z" } Shutdown Approved { "type" : "shutdown_approved" , "requestId" : "shutdown-abc123@worker-1" , "from" : "worker-1" , "paneId" : "%5" , "backendType" : "in-process" , "timestamp" : "2026-01-25T23:39:00.000Z" } Idle Notification (auto-sent when teammate stops) { "type" : "idle_notification" , "from" : "worker-1" , "timestamp" : "2026-01-25T23:40:00.000Z" , "completedTaskId" : "2" , "completedStatus" : "completed" } Task Completed { "type" : "task_completed" , "from" : "worker-1" , "taskId" : "2" , "taskSubject" : "Review authentication module" , "timestamp" : "2026-01-25T23:40:00.000Z" } Plan Approval Request { "type" : "plan_approval_request" , "from" : "architect" , "requestId" : "plan-xyz789" , "planContent" : "# Implementation Plan\n\n1. ..." , "timestamp" : "2026-01-25T23:41:00.000Z" } Join Request { "type" : "join_request" , "proposedName" : "helper" , "requestId" : "join-abc123" , "capabilities" : "Code review and testing" , "timestamp" : "2026-01-25T23:42:00.000Z" } Permission Request (for sandbox/tool permissions) { "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 } Orchestration Patterns Pattern 1: Parallel Specialists (Leader Pattern) 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-engineering: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-engineering: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-engineering: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" } ) Pattern 2: Pipeline (Sequential Dependencies) 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-engineering: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 Pattern 3: Swarm (Self-Organizing) 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 Pattern 4: Research + Implementation Research first, then implement: // 1. Research phase (synchronous, returns results) const research = await Task ( { subagent_type : "compound-engineering: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. } ) Pattern 5: Plan Approval Workflow 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" } ) Pattern 6: Coordinated Multi-File Refactoring // 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 } ) Environment Variables 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." } ) Spawn Backends 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 Comparison 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 Auto-Detection Logic 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 iTerm2 which tmux → tmux available which it2 → it2 CLI installed in-process (Default for non-tmux) Teammates run as async tasks within the same Node.js process. How it works: No new process spawned Teammates share the same Node.js event loop Communication via in-memory queues (fast) You don't see teammate output directly When it's used: Not running inside tmux session Non-interactive mode (CI, scripts) Explicitly set via CLAUDE_CODE_SPAWN_BACKEND=in-process Characteristics: ┌─────────────────────────────────────────┐ │ Node.js Process │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Leader │ │Worker 1 │ │Worker 2 │ │ │ │ (main) │ │ (async) │ │ (async) │ │ │ └─────────┘ └─────────┘ └─────────┘ │ └─────────────────────────────────────────┘ Pros: Fastest startup (no process spawn) Lowest overhead Works everywhere Cons: Can't see teammate output in real-time All die if leader dies Harder to debug // 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 tmux Teammates run as separate Claude instances in tmux panes/windows. How it works: Each teammate gets its own tmux pane Separate process per teammate You can switch panes to see teammate output Communication via inbox files When it's used: Running inside a tmux session ( $TMUX is set) tmux available and not in iTerm2 Explicitly set via CLAUDE_CODE_SPAWN_BACKEND=tmux Layout modes: Inside tmux (native): Splits your current window ┌─────────────────┬─────────────────┐ │ │ Worker 1 │ │ Leader ├─────────────────┤ │ (your pane) │ Worker 2 │ │ ├─────────────────┤ │ │ Worker 3 │ └─────────────────┴─────────────────┘ Outside tmux (external session): Creates a new tmux session called claude-swarm

Your terminal stays as-is

Workers run in separate tmux session

View workers:

tmux attach -t claude-swarm Pros: See teammate output in real-time Teammates survive leader exit Can attach/detach sessions Works in CI/headless environments Cons: Slower startup (process spawn) Requires tmux installed More resource usage

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 iterm2 (macOS only) Teammates run as split panes within your iTerm2 window. How it works: Uses iTerm2's Python API via it2 CLI Splits your current window into panes Each teammate visible side-by-side Communication via inbox files When it's used: Running in iTerm2 ( $TERM_PROGRAM === "iTerm.app" ) it2 CLI is installed and working Python API enabled in iTerm2 preferences Layout: ┌─────────────────┬─────────────────┐ │ │ Worker 1 │ │ Leader ├─────────────────┤ │ (your pane) │ Worker 2 │ │ ├─────────────────┤ │ │ Worker 3 │ └─────────────────┴─────────────────┘ Pros: Visual debugging - see all teammates Native macOS experience No tmux needed Automatic pane management Cons: macOS + iTerm2 only Requires setup (it2 CLI + Python API) Panes die with window 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: Install it2 now (guided setup) Use tmux instead Cancel Forcing a Backend

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 Backend in Team Config 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" } ] } Troubleshooting Backends 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 Checking Current Backend

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 Handling Common Errors 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 Graceful Shutdown Sequence 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" } ) Handling Crashed Teammates Teammates have a 5-minute heartbeat timeout. If a teammate crashes: They'll be automatically marked as inactive after timeout Their tasks remain in the task list Another teammate can claim their tasks Cleanup will work after timeout expires Debugging

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 Complete Workflows Workflow 1: Full Code Review with Parallel Specialists // === 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-engineering: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-engineering: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-engineering: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" } ) Workflow 2: Research → Plan → Implement → Test Pipeline // === 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-engineering: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-engineering: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 Workflow 3: Self-Organizing Code Review Swarm // === 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 Best Practices 1. Always Cleanup Don't leave orphaned teams. Always call cleanup when done. 2. Use Meaningful Names // Good name : "security-reviewer" name : "oauth-implementer" name : "test-writer" // Bad name : "worker-1" name : "agent-2" 3. Write Clear Prompts 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" 4. Use Task Dependencies 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..." 5. Check Inboxes for Results Workers send results to your inbox. Check it: cat ~/.claude/teams/ { team } /inboxes/team-lead.json | jq '.' 6. Handle Worker Failures Workers have 5-minute heartbeat timeout Tasks of crashed workers can be reclaimed Build retry logic into worker prompts 7. Prefer write Over broadcast broadcast sends N messages for N teammates. Use write for targeted communication. 8. Match Agent Type to Task Explore for searching/reading Plan for architecture design general-purpose for implementation Specialized reviewers for specific review types Quick Reference Spawn Subagent (No Team) Task ( { subagent_type : "Explore" , description : "Find files" , prompt : "..." } ) Spawn Teammate (With Team) Teammate ( { operation : "spawnTeam" , team_name : "my-team" } ) Task ( { team_name : "my-team" , name : "worker" , subagent_type : "general-purpose" , prompt : "..." , run_in_background : true } ) Message Teammate Teammate ( { operation : "write" , target_agent_id : "worker-1" , value : "..." } ) Create Task Pipeline TaskCreate ( { subject : "Step 1" , description : "..." } ) TaskCreate ( { subject : "Step 2" , description : "..." } ) TaskUpdate ( { taskId : "2" , addBlockedBy : [ "1" ] } ) Shutdown Team 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