Claude Code subagents vs agent teams: the difference, and when to use each

Short answer: a subagent is a helper inside your Claude Code session. Claude hands it a side task (search the code, run the tests, review a change), it works in its own context and reports back a summary. Subagents are on by default and cost relatively little. An agent team is several full Claude Code sessions: a lead plus teammates that share a task list and message each other directly, so they can split a project, debate and check each other's work. Agent teams are experimental, off until you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, and use far more tokens. Use subagents when only the result matters; use a team when the workers need to talk to each other.

Everything here is from Anthropic's Claude Code documentation, checked on November 11, 2026. (I build Morphy, which shows Claude's subagents in its chats and runs teams across different AIs; that's near the end.)

Subagents vs agent teams at a glance

	Subagents	Agent teams
What they are	Helpers inside one session	Separate Claude Code sessions: a lead and teammates
Who coordinates	Your main conversation	The lead, plus a shared task list teammates claim from
How they talk	Each reports its result back to Claude	Teammates message each other directly, and you can message any of them
Context	Their own; only a summary comes back	Their own; each is fully independent
Turned on	By default	Experimental: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
Best for	Focused tasks where only the result matters	Work that needs discussion: reviews, competing theories, features split by layer
Token cost	Lower: results are summarized	Higher: each teammate is a separate Claude; about 7 times a normal session when teammates plan
Nesting	Up to three layers of subagents	Teammates can't start teammates
Own worktree	Yes, with `isolation: worktree`	No: give each teammate different files
How many	Up to 20 running at once (changeable)	No hard limit; Anthropic suggests 3 to 5

Subagents: helpers that report back

Claude already uses subagents without being asked. The built-in ones:

Explore: read-only, for searching and understanding a codebase. It skips your CLAUDE.md to stay fast and cheap.
Plan: read-only research while you're in plan mode.
General-purpose: for multi-step tasks that need to both read and change things.

The point is your context: test output, logs and search results stay in the subagent's window, and only its summary comes back to your conversation. Subagents Claude starts from your main conversation run in the background by default, so you can keep working; /tasks shows them.

Make your own

A subagent is a Markdown file with frontmatter, in .claude/agents/ (this project, shareable through git) or ~/.claude/agents/ (all your projects). Only name and description are required:

---
name: code-reviewer
description: Reviews code for readability, bugs and best practices. Use after writing or changing code.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer. For each issue, explain the problem,
show the code, and suggest a fix.

Or ask Claude to write it ("create a read-only code-reviewer subagent in ~/.claude/agents/ that uses Sonnet"). Since version 2.1.198, /agents no longer opens a wizard: it reminds you to ask Claude or edit those folders.

Other useful fields: model (haiku for cheap, routine work), effort, permissionMode, isolation: worktree (its own copy of the repository), skills, mcpServers, hooks, memory and maxTurns.

Use one

Let Claude decide: it delegates when a task matches a subagent's description. "Use proactively" in the description encourages it.
Ask by name: "use the code-reviewer subagent to look at my changes".
@-mention it: type @ and pick code-reviewer (agent), so that one runs for sure.
A whole session as one: claude --agent code-reviewer.
A subagent that knows your conversation: /subtask starts a fork, which inherits everything so far instead of starting fresh.

Agent teams: sessions that work together

An agent team is one lead session and several teammates, each a complete Claude Code session with its own context. They share a task list (pending, in progress, done, with dependencies) and a mailbox, so teammates claim work, hand results to each other and argue. The lead assigns tasks and pulls the results together.

Turn them on

Add this to ~/.claude/settings.json (or set the variable in your shell):

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Then describe the team in plain words:

Spawn three teammates to review PR #142: one on security,
one on performance, one on test coverage. Have them report findings.

Teams only form in an interactive session: with claude -p or the Agent SDK, Claude starts ordinary subagents instead.

Work with the team

See and talk to teammates: they're listed in the panel under the prompt. Arrow keys select one, Enter opens it so you can message it directly (Esc there interrupts it), x stops it, Ctrl+T shows the task list.
Split panes: set "teammateMode": "auto" (or "tmux") in settings to give each teammate its own pane. That needs tmux, or iTerm2 with its it2 tool, and doesn't work in VS Code's terminal, Windows Terminal or Ghostty. The default, in-process mode, works in any terminal, Windows included.
Pick models: say it in the prompt ("use Sonnet for each teammate"). Anthropic recommends Sonnet for teammates to keep costs down.
Reuse your subagents as teammates: "spawn a teammate using the security-reviewer agent type".
Plan first: put the lead in plan mode before you ask, and teammates plan before they implement.
Quality gates: the TeammateIdle, TaskCreated and TaskCompleted hooks can keep a teammate working or block a task until it passes your checks.
Finish: "ask the researcher teammate to shut down". Shut teammates down when they're done: each keeps using tokens until it exits.

What doesn't work yet

Anthropic lists these limits: /resume and /rewind don't bring back in-process teammates; a session has one team, and the lead stays the lead; teammates can't start teammates of their own; task status sometimes lags, which blocks the tasks that depend on it; and shutting down can be slow.

One surprise: while agent teams are on, a subagent Claude gives a name to starts as a teammate, so teams can form when you didn't ask for one. If that happens, set the variable back to 0; it applies from the next subagent, without a restart.

What they cost

Both draw from the same plan as the rest of your Claude Code use. A subagent sends its own requests, but only its summary goes back into your conversation. A team costs roughly in proportion to its size, because every teammate is its own Claude with its own context, and Anthropic puts teammates in plan mode at about seven times a normal session. Keep teams small, spawn prompts short, and use Sonnet for teammates. More in how to stop hitting Claude Code's usage limits.

The other ways to run agents in parallel

Subagents and teams are two of Claude Code's options:

Agent view (claude agents): you hand off independent tasks as background sessions and check back.
Dynamic workflows: a script runs dozens of subagents and has them check each other, for audits and big migrations. Ultracode turns them on for every task.
Worktrees: several sessions you run yourself, each on its own copy of the files. See Claude Code worktrees.
/batch: splits one large change into 5 to 30 subagents, each in its own worktree.

All of them, side by side: how to run multiple Claude Code agents at once.

Which should you use?

A side task that would flood your conversation (tests, logs, a codebase search): a subagent.
The same kind of helper again and again (a reviewer, a test runner): a custom subagent in .claude/agents/.
Parallel research where only the answers matter: several subagents.
Reviewers or investigators who should challenge each other: an agent team.
A feature split across frontend, backend and tests: an agent team, one teammate per layer, each on its own files.
Sequential work, or edits to the same files: neither. One session does it better.
New to teams: Anthropic suggests starting with research and review, which needs no code changes.

In Morphy

In a Morphy chat on Claude, each subagent gets a line of its own while it works: which agent, what it's doing, how many steps and for how long. Click it to see the prompt Claude gave it, every step, and its report. See Chats.

For a team, Morphy's flows (on Pro, in beta) put chats in a frame joined by arrows, and the chats can be on different AIs: a Team of chats sharing a task list, a Review from three sides, or a Council of four AIs whose answers a fifth chat turns into one decision. See Flows and the flow templates.

Questions

What's the difference between subagents and agent teams in Claude Code? Subagents work for one session and report back to it. Agent teams are separate Claude Code sessions, led by one of them, that share a task list and message each other.

How do I enable agent teams in Claude Code? Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in the env of your settings.json, or in your shell, then ask Claude for teammates.

Are agent teams better than subagents? Only when the workers need to talk to each other. For focused tasks, subagents do the job for fewer tokens, and Anthropic suggests checking whether they're enough before you set up a team.

Do agent teams work on Windows? Yes, in the default in-process mode, in any terminal. Split panes need tmux or iTerm2, and don't work in Windows Terminal.

Can teammates use different models? Yes: name the model per teammate in your prompt, or in the subagent definition you spawn them from.

Subagents or skills? A skill is instructions Claude follows in your main conversation; a subagent is a separate worker with its own context. A subagent can preload skills with its skills field. More in SKILL.md explained.

References

Anthropic: create custom subagents, agent teams, run agents in parallel, costs
Morphy: Chats, Flows