Multi-Agent Orchestration

Your refactoring task touches 40 files across 6 modules. One Claude session grinds through them sequentially — 90 minutes of waiting. With multi-agent orchestration, 4 parallel workers finish in 25 minutes.

Multi-agent orchestration lets you run multiple Claude Code instances working together as a team, each with its own context window, claiming tasks from a shared list and messaging each other directly. One session acts as team lead, coordinating work, spawning teammates, and synthesizing results. This is the highest-leverage pattern for parallelizing complex work across an entire codebase.

Subagents vs Teams

The key distinction is hierarchy. Subagents report back to a single parent. Agent teams are peers that coordinate through a shared task list and direct messaging.

Use subagents when a focused job needs to run, produce a result, and return. Use agent teams when multiple agents need to negotiate, share context mid-flight, and claim work independently from a common backlog.

Team Lead Pattern

The team lead is the main Claude Code session. It creates the team, spawns teammates with role-specific prompts, defines the shared task list, and synthesizes results at the end. The lead is fixed for the lifetime of the team and cannot be transferred.

The lifecycle follows a clear sequence:

1. Setup — You describe the task and team structure in natural language
2. Spawn — Claude creates teammates with specific role prompts
3. Planning — Lead creates a shared task list with dependencies
4. Execution — Teammates claim and work on tasks independently
5. Communication — Teammates message each other to share findings and resolve conflicts
6. Synthesis — Lead collects results and produces final output
7. Cleanup — You tell the lead to clean up when done (always via lead, never teammates)

Teammates do NOT inherit the lead’s conversation history. They get CLAUDE.md, MCP servers, and skills, but not the conversation context. Always include the full role description, owned files, expected output format, and constraints directly in the spawn prompt.

Shared Task List

The shared task list is the coordination backbone. Each task has a state that progresses through a fixed lifecycle:

pending  -->  in progress  -->  completed

Tasks can declare dependencies on other tasks. A pending task with unresolved dependencies cannot be claimed. When a teammate finishes its current work, it scans the list for the next available pending task, claims it, and begins.

Task claiming uses file locking to prevent race conditions. If two teammates try to claim the same task at the same instant, only one succeeds. The other re-scans and picks a different task.

Team configuration lives at ~/.claude/teams/{team-name}/config.json and task data at ~/.claude/tasks/{team-name}/. These persist on disk so the lead can track state across the full session.

Mailbox System

The mailbox system enables direct inter-agent messaging. Teammates can send messages to each other, not just back to the lead. This avoids routing every coordination request through a bottleneck.

A typical exchange looks like this:

[frontend-dev -> backend-dev]
  "I need the /auth endpoint to return a user_id field in the response body."

[backend-dev -> frontend-dev]
  "Done. The response now includes { user_id, token, expires_at }."

The mailbox pattern is what separates agent teams from subagents. Instead of a hub-and-spoke model where the lead relays everything, teammates form a peer network. This is critical for workflows like cross-layer feature development, where the frontend and backend agents need to negotiate API contracts without waiting for the lead to relay messages.

File Locking

Two teammates editing the same file will cause merge conflicts and wasted work. The agent teams system uses file locking during task claiming to prevent race conditions, but the more important defense is task design.

Structure tasks around directory boundaries so each teammate owns different files:

• Frontend teammate: src/components/, src/styles/
• Backend teammate: src/api/, src/middleware/
• Test teammate: tests/, test-fixtures/

The ideal team size is 3-5 teammates with 5-6 tasks per teammate. More teammates means linear token cost scaling and more coordination overhead. Fewer teammates means less parallelism.

Teammate Modes

How teammates are displayed in your terminal depends on the --teammate-mode flag.

In-process mode is the most portable option. Split pane mode gives better visibility but does not work in VS Code terminal, Windows Terminal, or Ghostty. If the terminal crashes while using in-process mode, teammates are lost. Split pane mode (tmux) is more resilient because each pane is an independent tmux process.

Git Worktrees for Manual Parallelism

For simpler parallel work without the experimental agent teams feature, use native git worktree support:

Each worktree is a separate checkout with its own working directory. Claude sessions in different worktrees cannot conflict on file writes because they operate on separate directory trees. Key constraints: each worktree must use a unique branch name, worktrees share the same .git directory (so git operations like rebasing can still conflict), and the CLAUDECODE environment variable prevents nesting Claude inside Claude.

Quality Gates with Hooks

Two hook events are designed specifically for agent team orchestration:

• TeammateIdle — Fires when a teammate finishes its current task and has nothing left to claim. Your hook can exit 0 to allow idling, or exit 2 to send feedback and keep the teammate working (e.g., “You haven’t run the tests yet”).
• TaskCompleted — Fires when a teammate marks a task complete. Your hook can exit 0 to accept, or exit 2 to reject and send the teammate back to work (e.g., “Tests are failing, fix them first”).

{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/check-idle-teammate.sh"
          }
        ]
      }
    ],
    "TaskCompleted": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/verify-task-done.sh"
          }
        ]
      }
    ]
  }
}

These hooks let you enforce quality standards automatically — no teammate can declare victory until tests pass, linting is clean, or whatever bar you set.

Worktree Isolation

The --worktree flag creates a real git worktree for isolated development. Experimentally confirmed:

• Creates a worktree at .claude/worktrees/<name>/ on branch worktree-<name>
• Uses git worktree add under the hood — standard git tooling works (git worktree list, git worktree remove)
• Files created in a worktree do not appear on the main branch — full git-level isolation
• Worktrees persist after the Claude session exits — they are NOT auto-cleaned
• Multiple worktrees can coexist, each on its own branch

# Create an isolated worktree for feature work
claude --worktree feature-auth

# List all worktrees (including Claude-created ones)
git worktree list

# Clean up when done
git worktree remove .claude/worktrees/feature-auth

Tmux Integration

The --tmux flag (interactive mode only) creates a tmux session for the worktree, enabling side-by-side terminal panes. Use --tmux=classic for traditional tmux behavior vs iTerm2 native panes. Not available in headless (-p) mode.

# Worktree + tmux for parallel interactive work
claude --worktree feature-api --tmux