Claude Code subagents vs agent teams: which to use
Claude Code subagents vs agent teams: how each coordinates work, context and token cost, how to enable teams, their limits, and which fits your task.
You ask Claude Code to review a large pull request for security, performance, and test coverage. With subagents, three helpers each review one angle and report back, and Claude writes one summary. With an agent team, three teammates review in parallel, and the security reviewer can tell the performance reviewer that the cache they're worried about also leaks tokens. Same task, different coordination.
This guide compares the two from Anthropic's agent teams documentation, checked on 16 November 2026.
The short answer
| Subagents | Agent teams | |
|---|---|---|
| What they are | Helpers inside one session | Separate Claude Code sessions with a lead |
| Context | Own window; result returns to the caller | Own window; fully independent |
| Communication | Report back to the main agent | Teammates message each other directly |
| Coordination | The main agent manages everything | Shared task list and self-coordination |
| Best for | Focused tasks where only the result matters | Work that needs discussion and challenge |
| Token cost | Lower | Higher; scales with teammates |
| Status | Built in | Experimental, off by default |
Anthropic's summary: use subagents for quick, focused workers that report back; use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.
Subagents
A subagent is a worker Claude spawns inside your session. It gets a task, works in its own context window, and returns a result. The main conversation sees only the summary, so a subagent that reads 40 log files doesn't fill your context with them.
Good fits:
- Running tests or reading logs and reporting what failed
- Researching one question while you keep working
- Reviewing a diff from one angle
- Any task where you want the answer, not the process
Define reusable ones in .claude/agents/, with their own tools, model, and instructions.
Agent teams
An agent team is several Claude Code instances. One session is the lead: it breaks work into tasks, assigns them, and combines results. Teammates each work in their own context, claim tasks from a shared list, and message each other. You can also talk to any teammate directly.
Anthropic 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 one teammate
Enabling them
Agent teams are experimental and off by default:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
They need an interactive session; claude -p and Agent SDK sessions don't spawn teammates. With teams on, a subagent Claude names can launch as a teammate, so a team can form even when you didn't ask for one.
Limits to know
/resumeand/rewinddon't restore in-process teammates- Task status can lag, blocking dependent tasks
- One team per session, no nested teams, and the lead can't change
- Split-pane display needs tmux or iTerm2
Cost
Agent teams use significantly more tokens than a single session, because each teammate is a full instance with its own context. Anthropic's docs suggest starting with 3 to 5 teammates and 5 to 6 tasks per teammate. For routine work, a single session is cheaper. Subagents are the lighter option: their output is summarized back, and you can give them a smaller model.
Which to use
| Task | Use |
|---|---|
| Run tests and report failures | Subagent |
| Look something up while you work | Subagent |
| Review a PR from three angles, one summary | Subagents |
| Review where reviewers should debate findings | Agent team |
| Build frontend, backend, and tests in parallel | Agent team |
| Debug with several competing theories | Agent team |
| Sequential steps, or edits to the same file | Neither: one session |
| Audit or migrate hundreds of files | A workflow |
If you're unsure, start with subagents. Move to a team only when workers clearly need to talk to each other.
The shared brief problem
Whether it's three subagents or five teammates, each starts with its own fresh context. If the team decided last week that the new endpoint must stay backward compatible, every one of them needs to know, and the lead's summary of the task may not mention it. Anthropic's best practices for teams include giving teammates enough context up front; that's the same problem at a larger scale.
Where Lockstep fits
Lockstep briefs Claude Code sessions on the team's approved decisions that apply to the work, captured from PRDs, Slack, and pull requests. Put the decisions that matter for a team task in the lead's prompt, using lockstep brief to print them, so the lead can pass them to every teammate.
See how it works.
Sources checked 16 November 2026
Related reading
For when to use skills, hooks, and CLAUDE.md as well, see CLAUDE.md vs skills vs hooks vs subagents. For parallel sessions you run yourself, see Claude Code worktrees.
Frequently asked questions
- What is the difference between subagents and agent teams in Claude Code?
- Subagents run inside your session, each with its own context, and return a result to the main agent, which manages all the work. Agent teams are separate Claude Code instances: a lead assigns tasks from a shared list, and teammates message each other directly and coordinate on their own.
- Which uses more tokens, subagents or agent teams?
- Agent teams. Each teammate is a separate Claude instance with its own context, so usage scales with the number of active teammates. Subagents cost less because their results are summarized back into the main conversation.
- How do I enable agent teams in Claude Code?
- Set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, in your shell or under env in settings.json. Agent teams are experimental and disabled by default, and need an interactive session; claude -p and Agent SDK sessions don't spawn teammates.
- How many teammates should an agent team have?
- Anthropic's docs suggest starting with 3 to 5 for most work, with about 5 to 6 tasks per teammate. Costs grow linearly with teammates, coordination overhead rises, and returns diminish. Three focused teammates often beat five scattered ones.
- When should I use neither?
- For sequential tasks, edits to the same file, or work with many dependencies, a single session is usually best. For large fan-out work across many files, a dynamic workflow may fit better than either.
Keep reading