/agent-swarm-orchestation

name: orchestrating-swarms
description: Master multi-agent orchestration using Claude Code's TeammateTool and Task system. Use when coordinating multiple agents, running parallel code reviews, creating pipeline workflows with dependencies, building self-organizing task queues, or any task benefiting from divide-and-conquer patterns.

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: "spawnTe