orchestrating-swarms

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](#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<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

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

1. [Core Architecture](#core-architecture)
2. [Two Ways to Spawn Agents](#two-ways-to-spawn-agents)
3. [Built-in Agent Types](#built-in-agent-types)
4. [Plugin Agent Types](#plugin-agent-types)
5. [TeammateTool Operations](#teammatetool-operations)
6. [Task System Integration](#task-system-integration)
7. [Message Formats](#message-formats)
8. [Orchestration Patterns](#orchestration-patterns)
9. [Environment Variables](#environment-variables)
10. [Spawn Backends](#spawn-backends)
11. [Error Handling](#error-handling)
12. [Complete Workflows](#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