Claude Code Subagents vs Agent Teams

Subagents and agent teams both let Claude Code split work across several Claude instances, but they are built for different jobs. A subagent is a worker inside your session: Claude hands it a task, it works in its own context window, and it returns a result to whoever called it. An agent team is a set of separate Claude Code sessions: one lead and several teammates that share a task list, claim work from it, and message each other directly, and you can talk to any teammate yourself. Use subagents for focused jobs where only the result matters. Use an agent team when the workers need to share findings, challenge each other and coordinate on their own. Agent teams are experimental and off until you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

The difference in five lines

The agent teams documentation↗ (opens in a new tab) compares the two directly. In short:

• Context. Both get their own context window. A subagent’s result returns to its caller; a teammate is fully independent.
• Communication. A subagent returns a result to the caller, and subagents Claude named when it spawned them can also message each other. Teammates message each other directly.
• Coordination. With subagents, the main agent manages all the work. A team coordinates itself through messages and a shared task list.
• Best for. Subagents: focused tasks where only the result matters. Teams: complex work that needs discussion and collaboration.
• Cost. Subagents are lower, because results are summarised back. Teams are higher, because each teammate is a separate Claude instance.

Subagents, briefly

A subagent is defined in a Markdown file with YAML frontmatter, in .claude/agents/ for a project or ~/.claude/agents/ for you, or used from the built-ins such as Explore and Plan. Claude delegates to it with a message it writes itself; the subagent starts fresh with its own system prompt, your CLAUDE.md files and a git status snapshot, but not your conversation. It does the work and hands back a summary. How definitions and delegation work in detail is covered in Claude Code Task tool vs subagents.

What matters for this comparison is that subagents stay under the main conversation’s control. According to the subagents documentation↗ (opens in a new tab), they work within a single session, can run in the foreground or background, and by default can spawn subagents of their own up to three layers deep. Claude can give one a name and resume it later with SendMessage, but there is no shared task list: the main conversation decides what each one does next.

Agent teams, in detail

An agent team has four parts. The team lead is your main Claude Code session, which spawns teammates and coordinates the work. Teammates are separate Claude Code instances, each with its own context window. The task list is a shared list of work items that teammates claim and complete. The mailbox carries messages between agents.

• Tasks have three states: pending, in progress and completed. A task can depend on others, and a pending task cannot be claimed until its dependencies are completed; Claude Code unblocks it when they are.
• The lead can assign a task to a named teammate, or teammates self-claim: after finishing one, a teammate picks up the next unassigned, unblocked task. Claiming uses file locking, so two teammates cannot take the same task at once.
• Messages are delivered automatically, one teammate to another by name. When a teammate finishes and stops, it notifies the lead with its final answer.
• You can talk to any teammate yourself. In the default in-process mode, select it in the agent panel with the arrow keys and press Enter; Ctrl+T toggles the task list. Split-pane mode gives each teammate its own pane and needs tmux or iTerm2.
• Teammates load the same project context as a normal session — CLAUDE.md, MCP servers and skills — plus the spawn prompt from the lead. The lead’s conversation history does not carry over.

You can also reuse a subagent definition as a teammate: ask for “a teammate using the security-reviewer agent type” and its tool list and model apply. And hooks↗ (opens in a new tab) such as TeammateIdle, TaskCreated and TaskCompleted enforce quality gates: exit with code 2 and a teammate about to go idle keeps working, or a task that breaks your rule is not created or not marked complete, with your feedback sent back.

Turning agent teams on

Set the variable in your shell or in settings.json, then ask for a team in plain language: what the job is and which teammates you want.

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

Two things change once it is on. First, ordinary delegation: while teams are enabled, a subagent that Claude names when it spawns it launches as a teammate instead, and Claude may name subagents on its own, so a team can form when you did not ask for one. Setting the variable back to 0 makes named subagents launch as subagents again. Second, teams need an interactive session: with -p, including Agent SDK sessions, Claude does not spawn teammates and a named subagent runs as an ordinary subagent.

When to use which

Reach for subagents when:

• The job produces a lot of output and you only need the conclusion: a test run, a search, a log.
• You want hard limits on what the worker can touch, through its tool list.
• The work is self-contained and can come back as a summary.
• The pieces do not need to know about each other.

Reach for an agent team when:

• Several angles on one problem should be argued out, such as a review split into security, performance and test coverage.
• The cause of a bug is unclear and you want competing hypotheses tested and challenged against each other.
• A change spans layers, and each teammate can own a separate set of files: front end, back end, tests.
• Workers will discover things mid-task that other workers need to hear about.

Reach for neither when the work is sequential, touches the same files, or has many dependencies between steps. The documentation says a single session or subagents are more effective there, and warns that two teammates editing the same file leads to overwrites.

What agent teams cost, and their limits

Agent teams use significantly more tokens than a single session, and the costs page↗ (opens in a new tab) says usage is roughly proportional to team size. Its advice: keep teams small, keep spawn prompts focused, consider Sonnet for teammates, and shut teammates down when their work is done. The teams documentation suggests three to five teammates for most workflows, with five or six tasks each.

Because the feature is experimental, the documented limitations are worth reading before you rely on it:

• /resume and /rewind do not restore in-process teammates.
• Task status can lag: a teammate may fail to mark a task completed, which blocks the tasks that depend on it.
• One team per session, no nested teams, and the lead stays the lead for the session’s lifetime.
• Teammates start with the lead’s permission mode, and their permission prompts appear in the lead’s session.

Keeping a record of either

Neither leaves you a record you can hand to someone else. A subagent’s result goes to the main conversation and nowhere else. A team’s task list is stored under ~/.claude/tasks/ on the machine that ran it and is never uploaded, and a team belongs to one session.

If the work needs to be visible later, mirror it on a board. Teammates load your MCP servers like any session, so a teammate connected to a fenbs board can comment its result on the task it was given. They connect through your sign-in, so fenbs records them all as “Claude via <you>”; have each one start its comment with its teammate name. The claim-and-report rhythm for several sessions is in running Claude Code tasks in parallel, and the tool-agnostic version in multi-agent workflows.