Agent Teams

Coordinate multiple Claude Code sessions working on the same codebase simultaneously.

Enable

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude  # starts as team lead

The first session becomes the team lead. Subsequent sessions in the same repo join as teammates.

Architecture

Team Lead (coordinates, delegates, reviews)
  ├── Teammate 1 (owns task A, messages lead + peers)
  ├── Teammate 2 (owns task B, messages lead + peers)
  └── Teammate 3 (owns task C, messages lead + peers)
      │
      └── Shared: task list + mailbox + file locks

Key difference from subagents: Teammates are full Claude Code sessions. They have their own context window, can use all tools, and message each other directly, not just report back to a parent.

Team Sizing

Team Size	Best For
2	One builds, one reviews
3-5	Parallel features across layers (API, UI, tests)
> 5	Coordination overhead outweighs parallelism

3-5 teammates is the productive range. Beyond that, the lead spends more time coordinating than the team saves.

Task granularity: Aim for 5-6 tasks per teammate. Fewer means underutilization; more means excessive context switching.

Display Modes

In-process navigation:

• Shift+Down, cycle through teammates (wraps around)
• See each teammate's current task and output

Split-pane (recommended for >2 teammates):

• tmux: tmux split-window -h per teammate
• iTerm2: Cmd+D for vertical split
• Each pane runs its own claude session

Task Management

Tasks flow through states:

pending → in-progress → completed
              │
              └── blocked (waiting on dependency)

Task Decomposition

Break work into units that:

• Touch non-overlapping files
• Can be verified independently
• Have clear done criteria