Agent teams vs subagents: which one to choose in Claude Code

Updated on 2026-11-03

Claude Code can run several agents in two ways: with subagents, or with agent teams. This guide helps you choose. Agent teams are experimental and off by default: until you enable them, Claude creates no team. For the team that coordinates subagents, read the Chief of Staff guide. For files you can copy, read the subagent examples guide. Back to the home page.

In short

Start with subagents. A subagent does one focused task and reports its result: it is the right choice when only that result matters.

Move to agent teams when teammates need to share findings, challenge each other and coordinate on their own: a review from several angles, or a debugging session with competing hypotheses. This choice uses significantly more tokens, and agent teams remain experimental.

Subagents

A subagent is an agent that the main session starts for one precise task. It starts with its own context window, works alone, then returns a result to the caller. The main session receives that result, not every file read that led to it.

A named subagent can also message other agents. But as long as agent teams are not enabled, it remains an ordinary agent that reports to its caller. The format of an agent file is described in the official subagent documentation.

Agent teams

An agent team is a group of several Claude Code instances. The session that leads it is the team lead: it coordinates, assigns tasks and merges results. Each teammate works in its own context window, fully independently, and can message the others directly.

The shared task list shows each task’s state (pending, in progress, done) and its dependencies. A teammate claims a task before starting it, using a file lock.
The mailbox carries messages between agents.
A teammate loads the same project context as a normal session: CLAUDE.md, MCP servers and skills. It receives the lead’s launch prompt, but not the lead’s history.

To start a team, describe the task and the teammates you want, in natural language. Example from the documentation:

Spawn three teammates to explore this from different angles: one on UX, one on technical architecture, one playing devil's advocate.

You can also start a teammate from an existing subagent definition, for example security-reviewer: its tools and model apply, not its skills. The details are in the official agent teams documentation.

Experimental status

Agent teams are experimental and off by default. Without the activation described below, Claude neither starts nor offers teammates.

Comparing on five criteria

The official documentation compares the two on five criteria:

Context: each subagent has its own window, and its results return to the caller. Each teammate has its own window, fully independent.
Communication: subagents return a result to the caller. Teammates message each other directly.
Coordination: with subagents, the main agent handles everything. With agent teams, teammates coordinate among themselves, through messages and a shared task list.
Best for: focused tasks where only the result matters, for subagents; complex work that needs discussion and collaboration, for agent teams.
Token cost: lower with subagents, because their summarized results enter the main context. Higher with agent teams, because each teammate is an instance of Claude.

The documentation sums it up this way: subagents for quick, focused workers that report back; agent teams when teammates need to share findings, challenge each other and coordinate on their own.

When to choose each

Agent teams are worth their cost in the cases the documentation lists:

Research and review: several angles in parallel, with teammates who can contradict each other.
Independent modules or features: one teammate per piece.
Debugging with competing hypotheses: each teammate follows one lead, and the others challenge it.
Coordination across layers: frontend, backend and tests, each within its own scope.

The documentation also warns that agent teams add coordination overhead and use significantly more tokens than a single session. For sequential tasks, edits to the same file or many dependencies, a single session or subagents work better.

Enabling agent teams

Agent teams are off by default. To enable them for one session, set the variable in the environment:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

To enable them for a project, add the variable under the env key of .claude/settings.json. That file may hold other settings: add only this key.

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

Side effect on subagents

Once agent teams are enabled, a subagent that Claude names can start as a teammate, unless it is a fork or the call sets isolation. Claude sometimes names subagents on its own, so a team can form without you asking for one. To go back to subagents only, set the variable to 0.

In non-interactive mode, with the -p option or in the Agent SDK, Claude does not start teammates: a named subagent then remains an ordinary subagent. Agent teams therefore need an interactive session.

Best practices and limits

These points come from the documentation on best practices and limits.

Start with 3 to 5 teammates. Token cost grows with each one, and the documentation notes that three focused teammates often outperform five scattered ones.
Aim for 5 to 6 tasks per teammate. Give enough context in the launch prompt: a teammate does not inherit the lead’s history.
Avoid having two teammates edit the same file. Start with research or review rather than parallel implementation.
One team per session. No nested teams: a teammate cannot start teammates, and the lead does not change.
/resume and /rewind do not restore in-process teammates, the default mode. Do not count on them to resume a team.
Task status can lag behind. The split-pane mode requires tmux or iTerm2; the default in-process mode works in any terminal.

With Swarmbuilder

Swarmbuilder does not set up an agent team. It generates subagents in .claude/agents/ and a Chief of Staff, started with claude --agent chief-of-staff. That is the subagent model described above, and it works without enabling agent teams.

The generated definitions can also serve as teammate types if you enable agent teams. Be careful then: the subagents that the Chief names can start as teammates, as described in the activation section.

For the Chief’s structure, read the Chief of Staff guide. For complete files to copy, read the subagent examples guide. Back to the home page.