Claude Code agent teams: setup and when to use them
Enable Claude Code agent teams, start one, choose in-process or tmux display, size the team, and when subagents or a single session are the better choice.
Ask one Claude Code session to review a large pull request for security, performance, and test coverage, and it works through them one at a time. An agent team can split the job: three teammates take one angle each, challenge each other's findings, and the lead puts the result together.
Agent teams are powerful and expensive, and they're the wrong tool for most tasks. This guide covers setup, a first team, and when to use one, from Anthropic's agent teams documentation, checked on 16 November 2026.
What an agent team is
An agent team is several Claude Code instances working together. One session is the lead: it assigns tasks and combines results. Teammates work independently, each in its own context window, and message each other directly. You can message any teammate yourself, too.
| Subagents | Agent team | |
|---|---|---|
| Context | Own window; results return to the caller | Own window; fully independent |
| Communication | Return a result to the caller | Teammates message each other |
| Coordination | The main agent manages the work | Shared task list; teammates claim work |
| Token use | Moderate | Significantly higher |
| Status | Standard | Experimental, off by default |
For subagents, see Claude Code subagents: 5 examples.
When to use one
Anthropic's documentation lists the strongest uses:
- Research and review: teammates investigate 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.
- Cross-layer changes: frontend, backend, and tests, each owned by a different teammate.
And when not to: for sequential tasks, edits to the same files, or work with many dependencies, a single session or subagents are more effective. Teams add coordination overhead.
Enable agent teams
Set the environment variable, in your shell or in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Two things change once it's on. Claude may form a team on its own when it names a subagent. And teams only spawn in interactive sessions: with -p or the Agent SDK, named subagents run as ordinary subagents.
Start your first team
Describe the task and the teammates in plain language. Anthropic's example:
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 fills a shared task list, spawns the teammates, and combines their findings. If it uses subagents instead, ask again and request an agent team explicitly.
In the lead's terminal, teammates appear in the agent panel: arrow keys select one, Enter opens its transcript so you can message it, and Escape interrupts it.
Display modes
- In-process (default): all teammates in your main terminal. Works anywhere.
- Split panes: each teammate in its own pane, so you see everyone at once. Needs tmux or iTerm2 with the
it2CLI. Anthropic notes tmux has limitations on some systems and suggeststmux -CCin iTerm2.
Best practices
From the documentation:
- Give teammates context in the spawn prompt. They load CLAUDE.md, MCP servers, and skills, but not the lead's conversation.
- Start with 3 to 5 teammates. Three focused teammates often beat five scattered ones.
- Size tasks for a clear deliverable, such as a function, a test file, or a review. About 5 or 6 tasks per teammate lets the lead rebalance.
- Tell the lead to wait if it starts doing teammates' work itself.
- Start with research and review, which have clear boundaries and no code-merge risk.
- Give each teammate its own files. Two teammates editing one file overwrite each other.
- Check in. A team left unattended too long wastes effort.
Limitations
Agent teams are experimental. Current limits include:
/resumeand/rewinddon't restore in-process teammates.- Task status can lag, blocking dependent tasks.
- One team per session; no nested teams; the lead can't change.
- No per-teammate permission modes at spawn.
- Token usage scales with the number of active teammates.
The coordination problem teams don't solve
A team coordinates the work inside one session. It doesn't know what other sessions, other engineers, or last week's planning meeting decided. Five teammates can agree with each other perfectly and still build against a rule the product team replaced yesterday, because none of them was told.
Where Lockstep fits
Lockstep keeps the team's approved decisions in one record that every Claude Code session is briefed on at start. Decisions are captured from PRDs, Slack, and pull requests and become binding when their owner approves them. Teammates load the project's configured MCP servers, so if Lockstep is connected, they can look up the same decisions while they work.
Session briefings work with Claude Code today. See how it works.
Sources checked 16 November 2026
Related reading
For parallel sessions without a team, see Claude Code worktrees. For the wider trade-offs, see two AI agents, one codebase. For script-driven orchestration at larger scale, see Claude Code workflows. For a side-by-side comparison, see Claude Code subagents vs agent teams.
Frequently asked questions
- How do I enable Claude Code agent teams?
- Set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, in your shell or in the env block of settings.json. Agent teams are experimental and disabled by default, and they only spawn in interactive sessions, not with -p.
- What is the difference between agent teams and subagents?
- Subagents work inside one session and report results back to the main agent, which manages all the work. In an agent team, teammates share a task list, claim work, and message each other directly, and you can talk to any teammate yourself.
- How many teammates should an agent team have?
- Anthropic suggests starting with 3 to 5 teammates for most workflows, with about 5 or 6 tasks per teammate. Token costs scale with the number of teammates, coordination overhead grows, and beyond a point more teammates don't speed the work up.
- Do I need tmux for agent teams?
- No. The default in-process mode runs all teammates in your main terminal, and you switch between them in the agent panel. Split-pane mode, where each teammate gets its own pane, needs tmux or iTerm2.
- Do teammates see the lead's conversation?
- No. Teammates load project context such as CLAUDE.md, MCP servers, and skills, but not the lead's conversation history. Put task-specific details in the prompt you use to spawn each teammate.
Keep reading