Claude Code agent teams: how they work and when to use them

What agent teams are

An agent team has four parts:

• Team lead: your main Claude Code session. It creates the team, assigns work and combines the results.
• Teammates: separate Claude Code instances, each with its own context window. They load your CLAUDE.md, MCP servers and skills, but not the lead's conversation history.
• Shared task list: tasks are pending, in progress or completed, and can depend on other tasks. Teammates claim unblocked tasks, and the lead can also assign them.
• Mailbox: teammates message each other and the lead directly, and you can message any teammate yourself.

How to enable agent teams

Set the environment variable in your shell, or in settings.json:

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

Then, in an interactive session, ask for a team in plain language, for example:

Spawn three teammates to review this PR: one focused on security,
one on performance, one on test coverage. Have them share findings
and challenge each other before reporting back.

Teams need an interactive session. Claude doesn't spawn teammates in non-interactive -p mode.

Display modes

• In-process (default): all teammates run in your terminal. Use the agent panel to select a teammate and message it, and Ctrl+T to toggle the task list.
• Split panes: each teammate gets its own pane via tmux or iTerm2. Configure with teammateMode in settings.

Agent teams vs subagents

When agent teams are worth it

• Research and review: several lenses on the same code or question, debated before a conclusion.
• Debugging with competing hypotheses: teammates each try to prove their theory and challenge the others.
• New modules or features where each teammate owns separate files.
• Cross-layer work: front end, back end and tests in parallel.

Avoid teams for sequential tasks, edits to the same files (teammates can overwrite each other), or work with lots of dependencies. A single session or subagents is cheaper and more reliable there.

Best practices from production use

1. Start with 3–5 teammates. Token cost grows linearly with team size and returns diminish quickly.
2. Give each teammate real context in its spawn prompt: goal, files, constraints and the definition of done.
3. Size tasks as self-contained units with a clear deliverable, around 5–6 tasks per teammate.
4. Split by file ownership to avoid edit conflicts.
5. Pre-approve safe, common operations so permission prompts don't stall the team (teammates inherit the lead's permission mode, so be deliberate).
6. Use quality-gate hooks such as TaskCompleted and TeammateIdle to enforce tests or checks before work is accepted.
7. Steer, don't abandon. Check in on the lead periodically rather than letting a team run unattended for hours.

Known limitations

• One team per session, and teammates can't spawn their own teammates.
• The lead is fixed for the session's lifetime.
• /resume and /rewind don't restore in-process teammates.
• Task status can lag, and shutdown can be slow.
• Split panes need tmux or iTerm2.