Agent Teams coordinate multiple Claude Code instances working together on complex tasks. Unlike subagents (which are delegated subtasks returning results), teammates work independently with their own context and communicate directly through a shared mailbox system.

Note: Agent Teams is experimental and requires Claude Code v2.1.32+. Enable it before use.

Subagents vs Agent Teams

Aspect	Subagents	Agent Teams
Delegation model	Parent delegates subtask, waits for result	Team lead assigns work, teammates execute independently
Context	Fresh context per subtask, results distilled back	Each teammate maintains its own persistent context
Coordination	Sequential or parallel, managed by parent	Shared task list with automatic dependency management
Communication	Return values only	Inter-agent messaging via mailbox
Session resumption	Supported	Not supported with in-process teammates
Best for	Focused, well-defined subtasks	Large multi-file projects requiring parallel work

Enabling Agent Teams

Set the environment variable or add it to your settings.json:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Or in settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Starting a team

Once enabled, ask Claude to work with teammates in your prompt:

User: Build the authentication module. Use a team — one teammate for the API endpoints,
      one for the database schema, and one for the test suite.

Claude will create the team, assign tasks, and coordinate the work automatically.

Display modes

Control how teammate activity is displayed:

Mode	Flag	Description
Auto	`--teammate-mode auto`	Automatically chooses the best display mode for your terminal
In-process	`--teammate-mode in-process`	Shows teammate output inline in the current terminal (default)
Split-panes	`--teammate-mode tmux`	Opens each teammate in a separate tmux or iTerm2 pane

claude --teammate-mode tmux

You can also set the display mode in settings.json:

{
  "teammateMode": "tmux"
}

Note: Split-pane mode requires tmux or iTerm2. It is not available in VS Code terminal, Windows Terminal, or Ghostty.

Navigation

Use Shift+Down to navigate between teammates in split-pane mode.

Team Configuration

Team configurations are stored at ~/.claude/teams/{team-name}/config.json.

Architecture

graph TB
    Lead["Team Lead<br/>(Coordinator)"]
    TaskList["Shared Task List<br/>(Dependencies)"]
    Mailbox["Mailbox<br/>(Messages)"]
    T1["Teammate 1<br/>(Own Context)"]
    T2["Teammate 2<br/>(Own Context)"]
    T3["Teammate 3<br/>(Own Context)"]

    Lead -->|assigns tasks| TaskList
    Lead -->|sends messages| Mailbox
    TaskList -->|picks up work| T1
    TaskList -->|picks up work| T2
    TaskList -->|picks up work| T3
    T1 -->|reads/writes| Mailbox
    T2 -->|reads/writes| Mailbox
    T3 -->|reads/writes| Mailbox
    T1 -->|updates status| TaskList
    T2 -->|updates status| TaskList
    T3 -->|updates status| TaskList

    style Lead fill:#e1f5fe,stroke:#333,color:#333
    style TaskList fill:#fff9c4,stroke:#333,color:#333
    style Mailbox fill:#f3e5f5,stroke:#333,color:#333
    style T1 fill:#e8f5e9,stroke:#333,color:#333
    style T2 fill:#e8f5e9,stroke:#333,color:#333
    style T3 fill:#e8f5e9,stroke:#333,color:#333

Key components:

Team Lead: The main Claude Code session that creates the team, assigns tasks, and coordinates
Shared Task List: A synchronized list of tasks with automatic dependency tracking
Mailbox: An inter-agent messaging system for teammates to communicate status and coordinate
Teammates: Independent Claude Code instances, each with their own context window

Task assignment and messaging

The team lead breaks work into tasks and assigns them to teammates. The shared task list handles:

Automatic dependency management — tasks wait for their dependencies to complete
Status tracking — teammates update task status as they work
Inter-agent messaging — teammates send messages via the mailbox for coordination (e.g., "Database schema is ready, you can start writing queries")

Plan approval workflow

For complex tasks, the team lead creates an execution plan before teammates begin work. The user reviews and approves the plan, ensuring the team's approach aligns with expectations before any code changes are made.

Hook events for teams

Agent Teams introduce two additional hook events:

Event	Fires When	Use Case
`TeammateIdle`	A teammate finishes its current task and has no pending work	Trigger notifications, assign follow-up tasks
`TaskCompleted`	A task in the shared task list is marked complete	Run validation, update dashboards, chain dependent work

Best practices

Team size: Keep teams at 3-5 teammates for optimal coordination
Task sizing: Break work into tasks that take 5-15 minutes each — small enough to parallelize, large enough to be meaningful
Avoid file conflicts: Assign different files or directories to different teammates to prevent merge conflicts
Start simple: Use in-process mode for your first team; switch to split-panes once comfortable
Clear task descriptions: Provide specific, actionable task descriptions so teammates can work independently

Limitations

Experimental: Feature behavior may change in future releases
No session resumption: In-process teammates cannot be resumed after a session ends
One team per session: Cannot create nested teams or multiple teams in a single session
Fixed leadership: The team lead role cannot be transferred to a teammate
Split-pane restrictions: tmux/iTerm2 required; not available in VS Code terminal, Windows Terminal, or Ghostty
No cross-session teams: Teammates exist only within the current session

Warning: Agent Teams is experimental. Test with non-critical work first and monitor teammate coordination for unexpected behavior.

Introduction