Use a Claude subagent when the work splits into pieces and each result only needs to come back to your main session. Use Claude agent teams when several agents need to share findings and challenge each other before you get an answer. Two things can change that choice: whether the agents need to talk to each other, and whether you can accept the extra token cost. If they don’t need to talk, a subagent is usually enough.
What they share
Both let Claude Code work on parts of a task in parallel, and both run each agent in its own context window (Subagents docs, Agent teams docs). Each one keeps its exploration out of your main conversation, so the main session sees only what matters.
Where they differ
Where results go. A subagent returns its result to the main conversation. Teammates in an agent team message each other directly (Agent teams docs).
Who coordinates. With subagents, the main session hands out tasks and collects the results. With a team, the agents coordinate among themselves through messages and a shared task list (Agent teams docs).
Cost. Each teammate is a separate Claude instance, so agent teams use significantly more tokens (Agent teams docs). The docs put it this way: subagents suit focused tasks where only the result matters, and teams suit complex work that needs discussion and collaboration (Agent teams docs, Subagents docs).
Which to choose
Looking up how a library works, or running one check. A subagent is enough. It does the job and the result comes back. Nobody else needs to see it first.
One PR reviewed for security, performance, and tests. This depends on the reviewers. If each angle stands on its own, subagents can handle it: each reviewer reports, and you read the three reports. A team is worth considering only if the reviewers need to check each other’s findings. For example, the security reviewer might need to question a change the performance reviewer suggested. The official docs use this kind of split as an example (Agent teams docs).
Several hypotheses that try to disprove each other. This is the typical agent teams case. Each agent argues for one explanation and attacks the others, which only works if they can talk directly. The official docs include this as a debate-style example (Agent teams docs).
Combining them. The two don’t have to be exclusive. A team member can use its own subagents, but the docs say teammates cannot spawn their own teammates (Agent teams docs). Keep the team to the part of the work that needs discussion, and use subagents for the rest.
Things to know before turning teams on
- Agent teams are experimental and disabled by default (Agent teams docs).
- To turn them on, set
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1insettings.jsonor in your environment. - With the variable on, a subagent that Claude names can launch as a teammate, even if you didn’t ask for a team. Set the variable to
0to turn this off. - Print mode (
-p) does not spawn teammates. /resumeand/rewinddo not restore in-process teammates. After resuming, tell the lead to spawn new ones.- A session has one team.
- The docs suggest starting with 3 to 5 teammates.
How to choose
This is a suggested rule of thumb, not an official rule. Ask three questions:
- Can the work split into parts that do not depend on each other?
- Does the result need another agent to review it and revise it before it is final?
- Is the token cost acceptable?
Consider a team only if all three answers are yes. Otherwise, start with subagents.
Closing
If each piece of work only needs to return a result, use a subagent. If the agents need to question each other’s findings and you can accept the extra tokens, consider agent teams. For details, see the official docs for subagents and agent teams.