- Research and review: multiple teammates can investigate different aspects of a problem simultaneously, then share and challenge each other’s findings
- New modules or features: teammates can each own a separate piece without stepping on each other
- Debugging with competing hypotheses: teammates test different theories in parallel and converge on the answer faster
- Cross-layer coordination: changes that span frontend, backend, and tests, each owned by a different teammate
| Subagents | Agent teams | |
|---|---|---|
| Context | Own context window; results return to the caller | Own context window; fully independent |
| Communication | Report results back to the main agent only | Teammates message each other directly |
| Coordination | Main agent manages all work | Shared task list with self-coordination |
| 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 |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1, either in your shell environment or through settings.json:
After enabling agent teams, tell Claude to create an agent team and describe the task and the team structure you want in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt.
This example works well because the three roles are independent and can explore the problem without waiting on each other:
From there, Claude creates a team with a shared task list, spawns teammates for each perspective, has them explore the problem, synthesizes findings, and attempts to clean up the team when finished.
The lead’s terminal lists all teammates and what they’re working on. Use Shift+Up/Down to select a teammate and message them directly.
If you want each teammate in its own split pane, see Choose a display mode. Tell the lead what you want in natural language. It handles team coordination, task assignment, and delegation based on your instructions. Agent teams support two display modes:
- In-process: all teammates run inside your main terminal. Use Shift+Up/Down to select a teammate and type to message them 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.
tmux has known limitations on certain operating systems and traditionally works best on macOS. Using tmux -CC in iTerm2 is the suggested entrypoint into tmux.
"auto", which uses split panes if you’re already running inside a tmux session, and in-process otherwise. The "tmux" setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal. To override, set teammateMode in your settings.json:
To force in-process mode for a single session, pass it as a flag:
Split-pane mode requires either tmux or iTerm2 with the
it2 CLI. To install manually:
- tmux: install through your system’s package manager. See the tmux wiki for platform-specific instructions.
- iTerm2: install the
it2CLI, then enable the Python API in iTerm2 → Settings → General → Magic → Enable Python API.
For complex or risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves their approach:
When a teammate finishes planning, it sends a plan approval request to the lead. The lead reviews the plan and either approves it or rejects it with feedback. If rejected, the teammate stays in plan mode, revises based on the feedback, and resubmits. Once approved, the teammate exits plan mode and begins implementation.
The lead makes approval decisions autonomously. To influence the lead’s judgment, give it criteria in your prompt, such as “only approve plans that include test coverage” or “reject plans that modify the database schema.” Without delegate mode, the lead sometimes starts implementing tasks itself instead of waiting for teammates. Delegate mode prevents this by restricting the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks.
This is useful when you want the lead to focus entirely on orchestration, such as breaking down work, assigning tasks, and synthesizing results, without touching code directly.
To enable it, start a team first, then press Shift+Tab to cycle into delegate mode. 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 mode: use Shift+Up/Down to select a teammate, then type to send them a message. Press Enter to view a teammate’s session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list.
- Split-pane mode: click into a teammate’s pane to interact with their session directly. Each teammate has a full view of their own terminal.
- 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
The lead sends a shutdown request. The teammate can approve, exiting gracefully, or reject with an explanation. When you’re done, ask the lead to clean up:
This removes the shared team resources. When the lead runs cleanup, it checks for active teammates and fails if any are still running, so shut them down first.
This section covers the architecture and mechanics behind agent teams. If you want to start using them, see Control your agent team above. There are two ways agent teams get started:
- You request a team: give Claude a task that benefits from parallel work and explicitly ask for an agent team. Claude creates one based on your instructions.
- Claude proposes a team: if Claude determines your task would benefit from parallel work, it may suggest creating a team. You confirm before it proceeds.
| Component | Role |
|---|---|
| Team lead | The main Claude Code session that creates the team, 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 |
- Team config:
~/.claude/teams/{team-name}/config.json - Task list:
~/.claude/tasks/{team-name}/
members array with each teammate’s name, agent ID, and agent type. Teammates can read this file to discover other team members. Teammates start with the lead’s permission settings. If the lead runs with --dangerously-skip-permissions, all teammates do too. After spawning, you can change individual teammate modes, but you can’t set per-teammate modes at spawn time. 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. It also receives the spawn prompt from the lead. The lead’s conversation history does not carry over.
How teammates share information:
- Automatic message delivery: when teammates send messages, they’re delivered automatically to recipients. The lead doesn’t need to poll for updates.
- Idle notifications: when a teammate finishes and stops, they automatically notify the lead.
- Shared task list: all agents can see task status and claim available work.
- message: send a message to one specific teammate
- broadcast: send to all teammates simultaneously. Use sparingly, as costs scale with team size.
Each reviewer works from the same PR but applies a different filter. The lead synthesizes findings across all three after they finish. When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. The prompt fights this by making teammates explicitly adversarial: each one’s job is not only to investigate its own theory but to challenge the others’.
The debate structure is the key mechanism here. 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. Teammates load project context automatically, including CLAUDE.md, MCP servers, and skills, but they don’t inherit the lead’s conversation history. See Context and communication for details. Include task-specific details in the spawn prompt:
- Too small: coordination overhead exceeds the benefit
- Too large: teammates work too long without check-ins, increasing risk of wasted effort
- Just right: self-contained units that produce a clear deliverable, such as a function, a test file, or a review
If you’re new to agent teams, start with tasks that have clear boundaries and don’t require writing code: reviewing a PR, researching a library, or investigating a bug. These tasks show the value of parallel exploration without the coordination challenges that come with parallel implementation. Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files. Check in on teammates’ progress, redirect approaches that aren’t working, and synthesize findings as they come in. Letting a team run unattended for too long increases the risk of wasted effort. If teammates aren’t appearing after you ask Claude to create a team:
- In in-process mode, teammates may already be running but not visible. Press Shift+Down to cycle through active teammates.
- Check that the task you gave Claude was complex enough to warrant a team. Claude decides whether to spawn teammates based on the task.
- If you explicitly requested split panes, ensure tmux is installed and available in your PATH:
- For iTerm2, verify the
it2CLI is installed and the Python API is enabled in iTerm2 preferences.
- Give them additional instructions directly
- Spawn a replacement teammate to continue the work
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 a session, the lead may attempt to message teammates that no longer exist. If this happens, tell the lead to spawn new teammates. - Task status can lag: teammates sometimes fail to mark tasks as completed, which blocks 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, which can take time.
- One team per session: a lead can only manage one team at a time. Clean up the current team before starting a new one.
- No nested teams: teammates cannot spawn their own teams or teammates. Only the lead can manage the team.
- Lead is fixed: the session that creates the team is the lead for its lifetime. You can’t promote a teammate to lead or transfer leadership.
- Permissions set at spawn: all teammates start with the lead’s permission mode. You can change individual teammate 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-pane mode isn’t supported in VS Code’s integrated terminal, Windows Terminal, or Ghostty.
- Lightweight delegation: subagents spawn helper agents for research or verification within your session, better for tasks that don’t need inter-agent coordination
- Manual parallel sessions: Git worktrees let you run multiple Claude Code sessions yourself without automated team coordination
- Compare approaches: see the subagent vs agent team comparison for a side-by-side breakdown
