Table of Contents
When you want several AIs to divide up work in Claude Code, there are two similar-but-different mechanisms — subagents and Agent Teams. The names are confusing, but their roles and modes of coordination are fundamentally different. This article sorts out what each is, the decisive difference, which to use, and how — based on the official docs.
Three crucial points up front. (1) Subagents are a built-in feature — the main agent delegates a focused side-task to a "fresh-context helper" and gets back only a summary (hierarchical, ephemeral). (2) Agent Teams are an experimental, opt-in feature, disabled by default. They work only once you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — multiple independent sessions coordinate as peers via a shared task list (peer-to-peer, persistent). (3) "Nested 5 levels deep" is a subagents feature; Agent Teams cannot nest (they're flat) — don't conflate the two.
Hierarchy, or peers?
— delegate and get a summary, or coordinate as equals
Subagents: the main agent hands a task to a helper and gets the result. Agent Teams: equal peers coordinate via a shared task list.
Teams are an off-by-default experimental feature — CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is required.
1. What subagents are
Subagents are specialized agents that handle specific kinds of work within a single session. Per the official docs, "each subagent runs in its own context window, with a custom system prompt and specific tool permissions." The main agent delegates automatically based on each subagent's description, and the subagent works independently and returns only a summary to the main conversation.
The key is that "each subagent runs in a fresh, separate context" — it does not see your conversation history or files you've already read. So you can have it do heavy lookups "outside" and receive only the conclusion, without flooding your main context with logs or test output. Manage them with /agents (Running / Library tabs). Define them in .claude/agents/<name>.md with YAML frontmatter (name / description / tools / model). Built-ins include Explore (Haiku, read-only), Plan, and general-purpose. Subagents can nest, up to 5 levels deep (at depth 5 the Agent tool isn't passed, so they can't spawn further). For the bigger picture, see What is a multi-agent system.
2. What Agent Teams are (experimental, flag-gated)
Agent Teams let you coordinate multiple Claude Code sessions as a "team." One is the team lead (coordinates, assigns, synthesizes); the others are teammates — each its own independent session and context — that communicate directly with each other via a shared task list and a mailbox. Unlike subagents, you can talk to individual teammates directly.
Important: Agent Teams is an experimental feature, disabled by default
The official docs state plainly that "agent teams are experimental and disabled by default." To use them, set the env var CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (or via settings.json's env). Without it, no team is created at startup and Claude won't propose or spawn teammates.
Note that the v2.1.178 change only "removed the TeamCreate/TeamDelete setup step, so with the flag set every session has one implicit team" — it did not "enable teams by default." The flag is still required.
3. The decisive difference
Side by side, the two have completely different ways of coordinating.
| Subagents | Agent Teams | |
|---|---|---|
| Coordination | Hierarchical (main delegates, aggregates results) | Peer-to-peer (self-coordinate via a shared task list) |
| Communication | Report back to the caller only (never talk to each other) | Teammates message each other directly via the mailbox |
| Persistence | Ephemeral (return a summary after the task) | Persistent independent sessions (steer them directly) |
| Context | Own fresh context; summary returns to main | Fully independent (nothing summarized back automatically) |
| Token cost | Relatively low | High (each teammate is a separate Claude instance) |
| Status | Built-in, always available | Experimental, flag-gated, off by default |
| Nesting | Subagents nest up to 5 levels | No nesting (teammates can't spawn teammates) |
In one line: Subagents = "the main agent hands a focused task to a fresh-context helper and gets back the conclusion (hierarchical, ephemeral, summary-only)." Agent Teams = "multiple persistent sessions coordinate via a shared task list and messaging, and you can steer each one (peer, independent)." A common mistake: "5-level nesting" is a subagents feature, while Teams are flat (no nesting).
4. Which one should you use
Pick by purpose and you won't agonize. Most day-to-day work is fine with subagents (or a single session).
Choose by purpose
· the work is self-contained and only the result matters
· you want tool limits or a cheaper model
· workers don't need to talk
· parallel exploration pays (parallel review / competing-hypothesis debug / multi-module)
· you want to steer each worker
(accept higher cost + the flag)
· you need frequent back-and-forth
· it touches the same files
· it's a quick local change
Default to "when in doubt, a single session or subagents."
Reach for Agent Teams only for parallel work that truly needs peer coordination.
5. Usage cheat sheet
A quick reference for commands and config.
# --- Subagents (built-in) ---
/agents # manager (Running / Library)
.claude/agents/<name>.md # project definition (name/description/tools/model)
~/.claude/agents/<name>.md # user definition (all projects)
claude --agent code-reviewer # run the whole session as a specific subagent
@agent-<name> # @-mention to invoke explicitly
# --- Agent Teams (experimental, flag-gated) ---
# Enable via env (or settings.json env); OFF by default
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
# Then describe in plain language, e.g.: "Spawn three teammates to review PR #142:
# one for security, one for performance, one for test coverage."
# Display via teammateMode (default in-process; split panes need tmux/iTerm2)In a subagent definition file, you can restrict tools with tools or route to a lighter model like haiku with model. For building and designing agents, see How to build a multi-agent system and How to build an AI agent.
6. Agent Teams caveats
Agent Teams are powerful but come with experimental-stage limits and cost. Know these before adopting them.
(1) One team per session, no nesting — teammates can't spawn teammates, and the lead is fixed. (2) High token usage (each teammate is a separate Claude instance); the recommendation is 3-5 teammates. (3) Teammates are not isolated in worktrees, so if they touch the same files they overwrite each other — partition the files manually. (4) As an experimental feature, there are limits like /resume and /rewind not restoring in-process teammates. (5) Split-pane display needs tmux or iTerm2 (some terminals like VS Code's aren't supported). In short, use it only when the payoff of parallel coordination outweighs the cost and effort.
Summary
Claude Code's subagents and Agent Teams both "divide work across AIs," but their coordination models differ. Subagents are built-in — the main agent delegates a focused task to a fresh-context helper and gets back only a summary (hierarchical, ephemeral, don't talk to each other, nest up to 5 levels). Agent Teams are an experimental opt-in, off by default (needs CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) — multiple independent sessions coordinate as peers via a shared task list and messaging (persistent, steer each one, no nesting).
How to choose: "want only the result / don't want to pollute context → subagents," "parallel work where workers must share and coordinate → Agent Teams," "sequential / same files / quick fix → a single session." A common confusion: "5-level nesting" is a subagents feature; Teams are flat. And note that v2.1.178 streamlined team startup — it did not "enable by default." Teams are costly and experimental, so limit them to cases where coordination pays off. Related: What is a multi-agent system, how to build one, AI observability.
FAQ
Q. How do subagents and Agent Teams differ?
A. Their coordination is fundamentally different. Subagents are hierarchical — the main agent delegates a focused task to a fresh-context helper and gets back only a summary (helpers don't talk to each other; ephemeral). Agent Teams are peer-to-peer — multiple independent sessions coordinate via a shared task list and a mailbox, and you can steer each one (persistent). Subagents are built-in; Agent Teams are experimental and require a flag.
Q. Can I use Agent Teams right away?
A. No — they're disabled by default. You must set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in env (or settings.json's env). v2.1.178 only streamlined startup (it "removed the TeamCreate setup step, so with the flag set every session has one implicit team") — it did not "enable teams by default." The flag is still required.
Q. Which one does "nests up to 5 levels" refer to?
A. Subagents. A subagent can spawn its own subagents, up to 5 levels deep (at depth 5 it can't go further). Agent Teams cannot nest — teammates can't spawn teammates, and only the lead manages the team. Don't conflate the two.
Q. I can't tell which to use.
A. Most of the time a single session or subagents is enough. If you want only the result and don't want heavy output flooding your main context, use subagents. If workers must share findings, cross-check, and self-coordinate in parallel work (parallel review, competing-hypothesis debugging, multi-module development) and you want to steer each, use Agent Teams. For sequential work, frequent back-and-forth, or touching the same files, a single session fits.
Q. What should I watch out for with Agent Teams?
A. High token usage (each teammate is a separate instance; 3-5 recommended), one team per session with no nesting, teammates not isolated in worktrees so they conflict on the same files (partition manually), experimental limits on /resume and /rewind, and split panes needing tmux/iTerm2. Use it only for parallel work where coordination outweighs the cost.
