Claude Code agent teams vs Claude Code subagents
Subagents are helpers inside one Claude Code session: each works in its own context and returns a result to the caller. Agent teams are several full Claude Code sessions with a lead, a shared task list and direct messaging between teammates. Teams are experimental, off by default and cost more tokens; subagents are the standard, cheaper option.
Facts side by side
| Fact | Claude Code agent teams | Claude Code subagents |
|---|---|---|
| Status (source) | Experimental and disabled by default; enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. | Standard feature; built-in subagents (such as Explore and Plan) are used automatically. |
| Unit of work (source) | Separate Claude Code instances (teammates) coordinated by a lead session. | Helper agents inside a single session, each with its own context window. |
| Communication (source) | Teammates message each other directly; the user can message any teammate. | A subagent returns its result to the caller; named subagents can also message each other. |
| Coordination (source) | Self-coordination through messages plus a shared task list with dependencies and file-locked claiming. | The main agent manages all work. |
| Token cost (source) | Higher: each teammate is a separate Claude instance; usage scales with the number of active teammates. | Lower: results are summarized back to the main context. |
| Nesting (source) | No nested teams; only the lead manages the team, one team per session. | By default a subagent can spawn subagents up to three layers below the main conversation (configurable). |
| Concurrency limit (source) | No hard limit on teammates; the docs suggest starting with 3 to 5. | By default 20 subagents running at once in a session (configurable). |
| Non-interactive mode (`-p`, Agent SDK) (source) | Teammates are not spawned. | Subagents work; a named subagent runs as an ordinary subagent. |
| Reusable role definitions (source) | Can reference a subagent definition as a teammate role (tools and model apply; skills do not). | Markdown files in .claude/agents/ or ~/.claude/agents/, or passed with --agents. |
Choose Claude Code agent teams if
- Workers need to share findings, challenge each other and coordinate on their own, for example debugging with competing hypotheses.
- The work splits into independent pieces owned by different teammates, such as separate modules or frontend, backend and tests.
- You accept the documented limitations: no
/resumefor in-process teammates, one team per session, higher token use.
Choose Claude Code subagents if
- You need focused workers where only the result matters, such as searching a codebase or verifying a change.
- The task is sequential, touches the same files, or has many dependencies between steps.
- You run non-interactively (
-por the Agent SDK), where teammates are not spawned.
Migration notes
Moving from subagents to a team: set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, then ask Claude for teammates in natural language. Existing subagent definitions can be reused as teammate roles by naming the agent type; the definition's tools and model apply, its skills field does not, and mcpServers applies only to split-pane teammates. Teammates do not inherit the lead's conversation history, so put task details in the spawn prompt, and give each teammate its own files to avoid overwrites. Be aware of a side effect stated in the docs: while agent teams are enabled, a subagent that Claude names launches as a teammate, so teams can form without being requested. Moving back: set the variable to 0; no new session is needed, and the next named subagent launches as a subagent again.
FAQ
When should I use agent teams instead of subagents?
The official docs say: use subagents for quick, focused workers that report back, and agent teams when teammates need to share findings, challenge each other and coordinate on their own.
Do agent teams cost more than subagents?
Yes. The docs state agent teams use significantly more tokens than a single session because each teammate has its own context window.
Can I use my existing subagent definitions in a team?
Yes. A teammate can be spawned from a subagent definition by naming the agent type. Its tools and model apply; its skills field does not.
Why did Claude spawn a teammate when I asked for a subagent?
With agent teams enabled, a subagent that Claude names is launched as a teammate. Setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 0 restores subagent behavior.
Are agent teams available outside the terminal split-pane mode?
Yes. The default in-process mode works in any terminal. Split panes need tmux or iTerm2 and are not supported in VS Code's integrated terminal, Windows Terminal or Ghostty.