Claude Code agent teams let one Claude Code session act as a team lead that spawns several teammates, each a full Claude Code instance with its own context window, to work on a task in parallel. Teammates pick work from a shared task list, message each other directly, and report back to the lead, which combines the results. The feature is experimental and off until you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
Anthropic documents it on the agent teams page, which opens with a warning that teams "are experimental and disabled by default" and have known limits around resuming sessions, task coordination and shutdown. Everything below is from that page and related Claude Code docs, checked on 24 October 2026.
What are Claude Code agent teams?
A team has four parts:
| Part | Role |
|---|---|
| Team lead | Your main Claude Code session; spawns teammates and coordinates |
| Teammates | Separate Claude Code instances that each work on assigned tasks |
| Task list | Shared work items that teammates claim and complete |
| Mailbox | The messaging system agents use to talk to each other |
Each teammate loads the same project context a normal session does, including CLAUDE.md, MCP servers and skills, plus the spawn prompt from the lead. The lead's conversation history does not carry over, so the spawn prompt has to contain the task details.
Tasks have three states: pending, in progress and completed. A task can depend on others, and a blocked task can't be claimed until its dependencies finish. Claude Code unblocks dependent tasks automatically, and uses file locking so two teammates can't claim the same task at once.
How are agent teams different from subagents?
Both split work across separate context windows, but they coordinate differently. The docs put it this way: "Subagents report results back to the main agent. In agent teams, teammates share a task list, claim work, and communicate directly with each other."
| Subagents | Agent teams | |
|---|---|---|
| Context | Own window; results return to the caller | Own window; fully independent |
| Communication | Return a result to the caller | Teammates message each other directly |
| Coordination | Main agent manages all work | Self-coordination plus a shared task list |
| Best for | Focused tasks where only the result matters | Work that needs discussion and collaboration |
| Token cost | Lower | Higher: each teammate is a separate instance |
The docs advise checking whether a lighter option does the job before reaching for a team. For a focused job like "find every caller of this function," a subagent is cheaper and simpler; see the Claude Code subagents guide. For running several sessions yourself on separate branches without automated coordination, git worktrees are the manual route, covered in the Claude Code worktrees guide.
How do you enable and start an agent team?
Set the variable in your shell or in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Then describe the task and the teammates you want. The docs use this example, which works because the three roles don't need to wait on each other:
I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.
Two things to know before you turn it on:
- Teams can form without you asking. While agent teams are enabled, a subagent that Claude names when it spawns it launches as a teammate instead. Claude sometimes names subagents on its own, so ordinary delegation can become a team. Setting the variable to
0insettings.jsonstops this, and Claude Code picks up the saved change without a restart. - Interactive sessions only. In non-interactive mode with
-p, including Agent SDK sessions, Claude doesn't spawn teammates; a named subagent runs as an ordinary subagent. The headless mode guide covers those runs.
If Claude uses subagents when you wanted a team, ask again and explicitly request an agent team.
How do you control and talk to teammates?
Teammates appear in an agent panel below the prompt input. Use the up and down arrows to select one, Enter to open its transcript and message it directly, and Escape to clear the selection. Press x on a selected teammate to stop it and Ctrl+T to toggle the task list.
Display modes
There are two ways to see a team:
- In-process (the default): every teammate runs inside your main terminal. Works anywhere.
- Split panes: each teammate gets its own pane, so you see everyone at once. Needs tmux, or iTerm2 with the
it2CLI.
Set teammateMode in ~/.claude/settings.json to "in-process", "auto", "tmux" or "iterm2", or pass claude --teammate-mode auto for one session. auto uses split panes when you are already inside tmux or in iTerm2 with it2, and falls back to in-process otherwise. Split panes are not supported in VS Code's integrated terminal, Windows Terminal or Ghostty.
Models and roles
You can name the model in your prompt, for example "Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate." Otherwise Claude Code uses the model from a subagent definition you referenced, then CLAUDE_CODE_SUBAGENT_MODEL, then the lead's model. Teammates inherit the lead's effort level by default. The Claude Code models guide explains aliases and effort.
To reuse a role, point at an existing subagent definition: "Spawn a teammate using the security-reviewer agent type to audit the auth module." The teammate gets that definition's tools and model, and its body as instructions: appended to the default system prompt for an in-process teammate, or used in place of it for a split-pane teammate. Its skills field is not applied.
Plans, permissions and shutdown
Put the lead in plan mode before spawning, and the new teammate works read-only until its plan is ready. Note the docs' caveat: unless you changed that teammate's permission mode, Claude Code approves the plan as soon as it arrives, without the lead reviewing it. Edits and commands still go through permission prompts.
Teammates start with the lead's permission mode (except dontAsk), and their permission prompts appear in the lead session. Pre-approve common commands in your permission settings to cut down on interruptions.
To end a teammate, ask by name: "Ask the researcher teammate to shut down." It can approve and exit or decline with a reason. The team config is removed when the session ends; the task list under ~/.claude/tasks/ stays on disk.
When are agent teams worth the extra tokens?
The docs say teams "use significantly more tokens than a single session," because token use scales with the number of active teammates. They name four strong use cases:
- Research and review: several teammates look at different aspects and challenge each other's findings.
- New modules or features: each teammate owns a separate piece.
- Debugging with competing hypotheses: teammates test different theories in parallel and try to disprove each other.
- Cross-layer changes: frontend, backend and tests each owned by a different teammate.
For sequential tasks, edits to the same file, or work with many dependencies, a single session or subagents work better. A parallel code review prompt from the docs:
Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
What are the best practices and limits?
From the docs' best practices section:
- Start with 3 to 5 teammates. "Three focused teammates often outperform five scattered ones." Aim for 5 to 6 tasks per teammate.
- Give enough context in the spawn prompt, since teammates don't see the lead's history.
- Avoid file conflicts. Two teammates editing one file leads to overwrites, so split work by file.
- Start with research and review before parallel implementation.
- Tell the lead to wait if it starts doing tasks itself: "Wait for your teammates to complete their tasks before proceeding."
Use hooks for quality gates. TeammateIdle, TaskCreated and TaskCompleted hooks can exit with code 2 to send feedback and keep a teammate working or block a task change.
Current limitations include: /resume and /rewind don't restore in-process teammates; task status can lag; one team per session; no nested teams, since only the lead manages the team; and the lead can't be transferred.
Save the team prompts that work
A good team prompt, with clear roles, file ownership and a "disprove each other" instruction, takes a few tries to get right. Kipt keeps prompts like that as Markdown in a private GitHub repo you own, with {{name}} blanks such as {{pr_number}} or {{module}}, so you can find the review-team prompt again with Cmd+K and fill in the details.