What are agent teams?
Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinates work, and synthesizes results, while teammates work independently in their own context windows and message each other directly.
Agent teams require Claude Code 2.1.32 or later (where they first shipped as a research preview). Check your version with
claude --version. This guide follows the official docs as of October 2026 (v2.1.314); cleanup, the default display mode, and panel navigation have changed since the early releases. Agent teams are experimental and disabled by default, with known limitations around session resumption, task coordination, and shutdown behavior.
Unlike subagents, which work within a single session and return a result to the caller, you can also talk to any teammate directly without going through the lead.
Official docs: Orchestrate teams of Claude Code sessions — code.claude.com/docs/en/agent-teams
Compare with subagents
| Subagents | Agent teams | |
|---|---|---|
| Context | Own context window; results return to the caller | Own context window; fully independent |
| Communication | Return a result to the caller | Teammates message each other directly |
| Coordination | Main agent manages all work | Self-coordination through messages, plus a shared task list |
| Best for | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
| Token cost | Lower — results summarized back to main context | Higher — each teammate is a separate Claude instance |
Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.
Enable agent teams
Set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1, either in your shell environment or through ~/.claude/settings.json.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Enabling agent teams also changes ordinary delegation. While agent teams are enabled, a subagent that Claude names launches as a teammate, so teams can form even when you didn’t ask for one. Spawning teammates also requires an interactive session: in non-interactive mode with -p, including Agent SDK sessions, Claude doesn’t spawn teammates, and a named subagent runs as an ordinary subagent.
Start your first team
After enabling agent teams, describe the task and the teammates you want in natural language. There’s no team setup step: since 2.1.178, every session has one implicit team, and Claude spawns teammates directly. This example works well because the three roles are independent and can explore the problem without waiting 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.
Claude may sometimes use subagents instead of creating a team. Subagents appear in the same agent panel as teammates, so the panel alone doesn’t confirm a team formed. If that happens, ask again and explicitly request an agent team.
The lead’s terminal lists teammates in the agent panel below the prompt input. Use the up and down arrows to select a teammate, then press Enter to open its transcript and message it directly.
The team’s shared directories are cleaned up automatically when the session ends, so there’s no separate cleanup step.
Display modes — in-process vs split panes
Agent teams support two display modes:
- In-process — all teammates run inside your main terminal. Use the up and down arrow keys in the agent panel to select a teammate, then press Enter to view it and type to message it directly. Works in any terminal, no extra setup required.
- Split panes — each teammate gets its own pane. You can see everyone’s output at once and click into a pane to interact directly. Requires tmux or iTerm2.
The default is "in-process". The other values:
"auto"— split panes when you’re already running inside a tmux session, or when your terminal is iTerm2 with theit2CLI installed (or tmux available), falling back to in-process otherwise."tmux"— enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal."iterm2"— uses iTerm2 native split panes explicitly through theit2CLI (added in 2.1.186). Shows an error with the install command ifit2is missing.
To override the default, set teammateMode in ~/.claude/settings.json:
{
"teammateMode": "auto"
}
To set the mode for a single session, pass it as a flag. The --teammate-mode flag is experimental and doesn’t appear in claude --help.
claude --teammate-mode auto
Split-pane mode requires either tmux or iTerm2 with the it2 CLI. Split panes are not supported in VS Code’s integrated terminal, Windows Terminal, or Ghostty.
iTerm2 + tmux setup (the simplest combination)
Split panes require either tmux on its own or iTerm2 with the it2 CLI — not both. The official docs suggest tmux -CC in iTerm2 as the entrypoint into tmux, and that path doesn’t need the it2 CLI or the iTerm2 Python API at all. tmux has known limitations on certain operating systems and traditionally works best on macOS.
1. Install tmux
brew install tmux
Verify it’s on your PATH:
which tmux
2. Set teammateMode
With the default "in-process", teammates don’t open in split panes even inside tmux. Set "teammateMode" to "auto" or "tmux" in ~/.claude/settings.json:
{
"teammateMode": "tmux"
}
3. Launch iTerm2 with tmux -CC
Open a fresh iTerm2 window and start a tmux control-mode session:
tmux -CC
iTerm2 renders the tmux session as native windows and tabs. Run Claude Code from inside this session.
4. Verify with a team
Create an agent team and confirm each teammate opens in its own iTerm2 pane. If split panes don’t open, check your teammateMode value and run which tmux to confirm tmux is on your PATH.

Without tmux: iTerm2 standalone
If you’d rather not install tmux, iTerm2 native split panes work through a separate path. This path is the only one that needs the it2 CLI and the Python API enabled; set teammateMode to "iterm2" or "auto".
-
Enable iTerm2 → Settings → General → Magic → Enable Python API
-
Install the it2 CLI with uv (recommended) or pip:
uv tool install it2If you don’t have uv,
pip install it2works too. it2 requires macOS with iTerm2 3.3.0 or later and Python 3.10+.
For most users, the tmux + tmux -CC route above is simpler, so try it first.
Agent panel shortcuts (in-process)
Useful when you stay inside the main terminal:
| Shortcut | Action |
|---|---|
| Up / Down arrows | Select a teammate |
| Enter | Open the selected teammate’s transcript and message it directly |
| Escape | Clear the selection. While viewing a teammate’s transcript, interrupts that teammate’s current turn |
x | Stop the selected teammate |
| Ctrl+T | Toggle the task list |
Once every agent in the panel is idle, idle rows hide after 30 seconds; the teammate stays running and addressable while hidden. When more than three teammates are idle, the extra rows collapse into a single N idle agents row that Enter expands.
Control your team
Tell the lead what you want in natural language. It handles team coordination, task assignment, and delegation based on your instructions.
Specify teammates and models
Claude decides the number of teammates based on the task, or you can specify exactly what you want:
Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.
Claude Code picks each teammate’s model from the first of these that applies:
- The model your spawn prompt names for that teammate.
- For a teammate spawned from a subagent definition, the definition’s
model, whereinheritselects the lead’s model. CLAUDE_CODE_SUBAGENT_MODEL, when it’s set to anything other thaninherit.- The lead’s current model.
teammateDefaultModel was removed in v2.1.234; Claude Code ignores a leftover value. Name the model in your prompt instead. A teammate’s model and fast mode are fixed when it spawns.
Have teammates plan before implementing
For complex or risky tasks, you can have teammates plan before implementing. A teammate that Claude spawns while the lead is in plan mode works in read-only plan mode until its plan is ready. Switch the lead into plan mode first, then ask for the teammate:
Spawn an architect teammate to refactor the authentication module.
When that teammate finishes planning, it sends a plan approval request to the lead. If you haven’t changed that teammate’s permission mode since it was spawned, Claude Code approves the plan as soon as the request arrives, without the lead reviewing it — so this isn’t a way to gate plans on criteria you write in the prompt. The teammate’s edits and commands still go through the usual permission prompts.
If you put a running in-process teammate in plan mode by pressing Shift+Tab while viewing its session, the lead reviews that run’s plan instead, and approves it or sends it back for revision.
Talk to teammates directly
Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.
- In-process — use the up and down arrow keys in the agent panel to select a teammate, then press Enter to view its session and type to send it a message. Press
xon a selected teammate to stop it. Press Ctrl+T to toggle the task list. - Split panes — click into a teammate’s pane to interact with their session directly. Each teammate has a full view of their own terminal.
While you’re viewing an in-process teammate, plain text and skills go to that teammate, and built-in commands go to the lead’s session. /compact, /clear, and /rewind act on the lead’s conversation, so Claude Code asks you to confirm first; /model and /fast don’t run from this view.
Assign and claim tasks
The shared task list coordinates work across the team. Tasks have three states — pending, in progress, completed — and can depend on other tasks. A task with unfinished dependencies shows as blocked; teammates don’t self-claim a blocked task, but you or the lead can still assign it. When a dependency completes, Claude Code unblocks the dependent tasks automatically.
- Lead assigns — tell the lead which task to give to which teammate
- Self-claim — after finishing a task, a teammate picks up the next unassigned, unblocked task on its own
Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task simultaneously.
Shut down teammates
To gracefully end a teammate’s session, refer to it by name:
Ask the researcher teammate to shut down
The lead sends a shutdown request. The teammate can approve, exiting gracefully, or reject with an explanation.
There’s no separate cleanup step. Version 2.1.178 removed the TeamCreate and TeamDelete tools, and the team’s shared directories are cleaned up automatically when the session ends. See “How agent teams work” below for which directories are removed and which stay on disk.
How agent teams work
An agent team consists of four components:
| Component | Role |
|---|---|
| Team lead | The main Claude Code session that spawns teammates and coordinates work |
| Teammates | Separate Claude Code instances that each work on assigned tasks |
| Task list | Shared list of work items that teammates claim and complete |
| Mailbox | Messaging system for communication between agents |
Teams and tasks are stored locally under a session-derived name (session- followed by the first eight characters of the session ID):
- Team config:
~/.claude/teams/{team-name}/config.json— removed when the session ends. - Task list:
~/.claude/tasks/{team-name}/— stays on disk after the session ends; setcleanupPeriodDaysto change how long it’s kept.
The team config holds runtime state such as session IDs and tmux pane IDs, so don’t edit it by hand or pre-author it — your changes are overwritten on the next state update. To define reusable teammate roles, use subagent definitions instead.
Each teammate has its own context window. When spawned, a teammate loads the same project context as a regular session — CLAUDE.md, MCP servers, and skills — but the lead’s conversation history does not carry over. Include task-specific details in the spawn prompt.
Use subagent definitions for teammates
When spawning a teammate, you can reference a subagent type from the project, user, managed, or plugin subagent scope. This lets you define a role once, such as a security-reviewer or test-runner, and reuse it both as a delegated subagent and as an agent team teammate.
Spawn a teammate using the security-reviewer agent type to audit the auth module.
Which parts of the definition apply depends on the teammate’s display mode:
toolsandmodel— applied in either display mode. For an in-process teammate, Claude Code addsSendMessageand the Task tools to the list.- Body — for an in-process teammate, appended to its default system prompt as additional instructions. For a split-pane teammate, used in place of its default system prompt.
skills— not applied in either display mode. The teammate loads skills from your project and user settings.mcpServers— applied for a split-pane teammate. An in-process teammate ignores the field and loads MCP servers from your project and user settings.
So skills attached only to a subagent definition won’t take effect for teammates, and MCP servers attached only there won’t take effect for in-process teammates.
Use case examples
Run a parallel code review
A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously:
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.
Investigate with competing hypotheses
When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. Making teammates explicitly adversarial forces them to challenge each other’s theories rather than anchor on the first one.
Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.
Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it. With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause.
Enforce quality gates with hooks
Use hooks to enforce rules when teammates finish work or tasks are created or completed. Exiting with code 2 sends feedback and blocks the action.
| Hook | Fires when | Effect of exit code 2 |
|---|---|---|
TeammateIdle | A teammate is about to go idle | Sends feedback and keeps the teammate working |
TaskCreated | A task is being created | Prevents creation, sends feedback |
TaskCompleted | A task is being marked complete | Prevents completion, sends feedback |
Best practices
- Give teammates enough context — teammates load CLAUDE.md, MCP servers, and skills automatically, but they don’t inherit the lead’s conversation history. Include task-specific details (file paths, libraries used, reporting format) in the spawn prompt.
- Start with 3–5 teammates — token cost scales linearly and coordination overhead grows. Keep 5–6 tasks per teammate.
- Size tasks appropriately — too small means coordination overhead exceeds the benefit; too large means teammates work too long without check-ins. Aim for self-contained units like a function, a test file, or a review.
- Avoid file conflicts — two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files.
- Monitor and steer — don’t let a team run unattended for too long. Redirect approaches that aren’t working and synthesize findings as they come in.
- Start with research and review — if you’re new to agent teams, start with PR reviews, library research, or bug investigations. These show the value of parallel exploration without the coordination challenges of parallel implementation.
Known limitations
Agent teams are experimental. Current limitations to be aware of:
- No session resumption with in-process teammates —
/resumeand/rewinddo not restore in-process teammates. After resuming, the lead may attempt to message teammates that no longer exist. Tell the lead to spawn new ones. - Task status can lag — teammates sometimes fail to mark tasks as completed, blocking dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually or tell the lead to nudge the teammate.
- Shutdown can be slow — teammates finish their current request or tool call before shutting down.
- One team per session — a session has exactly one team, scoped to that session. You can’t create additional named teams or share a team across sessions.
- No nested teams — teammates cannot spawn their own teammates. Only the lead can manage the team.
- No background subagents from in-process teammates — an in-process teammate’s own subagents run in the foreground. Claude Code returns an error when a teammate spawns a subagent whose definition sets
background: true. - Lead is fixed — the main session is the lead for its lifetime. You can’t promote a teammate to lead or transfer leadership.
- Permissions set at spawn — teammates start with the lead’s permission mode, except
dontAskmode, which they don’t inherit. You can change individual modes after spawning, but you can’t set per-teammate modes at spawn time. - Split panes require tmux or iTerm2 — the default in-process mode works in any terminal. Split panes are not supported in VS Code’s integrated terminal, Windows Terminal, or Ghostty.
Troubleshooting
Teammates not appearing
-
In in-process mode, teammates appear in the agent panel below the prompt input. Use the up and down arrow keys to select one, then press Enter to view it.
-
A teammate row that disappeared after sitting idle has been hidden, not stopped. Send the teammate a message by name to bring it back.
-
Check that the task is complex enough to warrant a team — Claude decides whether to spawn teammates based on the task.
-
If you explicitly requested split panes, check that
teammateModeisn’t"in-process"and that tmux is on your PATH:which tmux -
If you’re using iTerm2 standalone (without tmux), verify the
it2CLI is installed and the Python API is enabled.
Claude spawns teammates instead of subagents
While agent teams are enabled, a subagent that Claude names launches as a teammate. To make named subagents launch as subagents again, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 0. Claude Code reapplies settings-file env values to the running session when you save, so you don’t need a new session. Project, local, or managed settings that set it to 1 still win over user settings.
Too many permission prompts
Teammate permission requests bubble up to the lead, which can create friction. Pre-approve common operations in your permission settings before spawning teammates.
Teammates stopping on errors
Teammates may stop after encountering errors instead of recovering. Check their output, then either give them additional instructions directly or spawn a replacement teammate.
Orphaned tmux sessions
If a tmux session persists after the Claude Code session ends, it may not have been fully cleaned up. List sessions and end the one created by the team:
tmux ls
tmux kill-session -t <session-name>
Next steps
- Subagents — lighter-weight delegation when teammates don’t need to coordinate with each other
- Plan mode — useful background when having teammates plan before implementing
- Hooks automation — applying
TeammateIdleand other team coordination hooks - Official docs: code.claude.com/docs/en/agent-teams