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, started per task). (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) Only subagents can nest (by default up to 3 layers below the main conversation); 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. To create or edit one, ask Claude or edit the definition file directly (as of v2.1.198, /agents no longer opens the interactive creation wizard). Define them in .claude/agents/<name>.md with YAML frontmatter (name / description / tools / model). Built-ins include Explore (read-only; as of v2.1.198 it inherits the main conversation's model, capped at Opus on the Claude API), Plan, and general-purpose. Subagents can nest, by default up to 3 layers below the main conversation (v2.1.219+; at the depth limit the Agent tool isn't passed, so they can't spawn further. Change the limit with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH; 1 turns nesting off). 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 | Mainly return a result to the caller (named subagents can also message each other) | Teammates message each other directly via the mailbox |
| Persistence | Started per task (return a summary; can be resumed) | 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 | By default up to 3 layers down (limit adjustable) | 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, started per task, 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: 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 # no wizard since v2.1.198 (ask Claude or edit the files below)
.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 how the model is resolved and a hands-on test on different models, see Claude Code: How to Run Subagents on a Different 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, started per task, mainly report to the caller, nest up to 3 layers down by default). 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: 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. One more thing: both of the options compared here run on your own machine. As the cloud-side option that keeps going after you close your machine, Projects — where Claude opens threads of its own and keeps track of them — arrived in September 2026. 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 mainly report to the caller, though named ones can message each other; started per task and resumable). 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 can nest?
A. Subagents. A subagent can spawn its own subagents, by default up to 3 layers below the main conversation (v2.1.219+; change the limit with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, and 1 turns nesting off). Agent Teams cannot nest — teammates can't spawn teammates, and only the lead manages the team. Don't conflate the two.
Q. Are there ways to parallelise other than these two?
A. Yes. The official documentation sorts parallelisation into five approaches: alongside the two in this article there are agent view (dispatch), dynamic workflows, and Projects, which joined them in September 2026. Agent view is the screen you open with claude agents, where you hand off independent tasks and collect the results later (research preview). Subagents mean "Claude delegates inside one conversation" and Agent Teams mean "Claude runs the show", whereas with agent view the one running the show is you. The isolation model and the things to watch for are covered in a dedicated article.
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.
