Claude Code Agent Teams vs Subagents: Context, Cost, and Review Trade-offs

A common assumption is that agent teams are where you graduate once a project outgrows subagents. Project size is not what decides it; the real question is whether your workers need to talk to each other. Stay with subagents when you only need a result back and the workers never have to. Move to agent teams when the work splits into parallel tracks whose owners claim tasks from a shared list, message each other by name, and settle dependencies among themselves. The move carries conditions: the feature is experimental and disabled by default, token spend scales linearly with teammate count, and review turns into something you consolidate.

What changes when teammates replace subagents?

Claude Code’s documentation draws the line in one sentence: subagents report results back to the main agent, while teammates share a task list, claim work, and communicate directly with each other. Everything else follows from that. A subagent is a worker you dispatch inside the session you are already running. A teammate is a separate Claude Code session that keeps its own context window for the whole job and can message a named peer without asking you to relay the finding.

Who owns the work when a task moves to a team

Responsibility lands in three places. The lead is the main session you type into: it creates the team, spawns teammates, coordinates them, and synthesizes the final result. Each teammate is a separate Claude Code instance with its own context window. The shared task list is where ownership becomes legible, because agents that have the Task tools can see task status and claim available work. Team configuration sits at ~/.claude/teams/{name}/config.json and the shared list at ~/.claude/tasks/{name}/, so you can open both and see what has been claimed and what is still sitting there.

Several structural rules shape how you plan around a team. A session has exactly one team, scoped to that session, and you cannot create additional named teams or share one across sessions. Teammates cannot spawn their own teammates, so only the lead manages the team. Leadership is fixed for the session’s lifetime, with no path to promote a teammate or transfer the role. Claude also decides whether to spawn teammates based on the task, which is why the docs tell you to check that the work was complex enough to warrant a team when no teammates appear. The feature also comes with known limitations around session resumption, task coordination, and shutdown behavior.

Subagent ownership stays flat. One caller hands out work and every result returns to it, so accountability sits in a single place. The natural fit the docs describe is a side task that would otherwise flood your main conversation with search results, logs, or file contents you will never reference again.

Sideways messages instead of one return path

Communication is the difference you notice first. Subagents return a result to the caller, and the only peer messaging available is between subagents that Claude named when it spawned them. Teammates message each other directly, and each message carries one recipient. There is no broadcast, so reaching four peers takes four messages. That is how a teammate passes a discovered constraint straight to the peer who owns the affected file, without routing it through the lead and hoping it survives the summary.

Teammates start cold in one specific way: they do not inherit the lead’s conversation history, so each one begins with its spawn prompt plus whatever the project configuration gives it. Prompt detail therefore changes team output more than it changes subagent output. The docs make that point with a sample reviewer prompt that names the module path, the vulnerability classes to check, the auth mechanism in use, and the severity format for the report.

Model choice follows a fixed order. The model named in the spawn prompt wins. For a teammate spawned from a subagent definition, the definition’s model applies, where inherit selects the lead’s model. CLAUDE_CODE_SUBAGENT_MODEL applies when it is set to anything other than inherit. A blocked family alias behaves differently on different providers: the Anthropic API and Claude Platform on AWS can pick the newest permitted version of that family, while a blocked value that cannot be substituted falls back to the lead’s model. If you want cheap teammates for mechanical work and an expensive one for planning, that order is the lever.

How does a bounded parallel task work in practice?

Take a breaking change to a payments API. The backend endpoint changes shape, the checkout components consume the new shape, and the test suite covers both. Backend has to land first, frontend cannot start until it does, and the test track can begin scaffolding against the frozen contract while backend is still being written. That is three owners, one real dependency, and no need for a fourth teammate to referee.

The agent-teams page lists this shape as cross-layer coordination, where changes that span frontend, backend, and tests are owned by a different teammate each. One practitioner guide describes the same case with the ordering written into the shared task list: backend first, frontend after, tests in parallel once the API contract is defined, and the lead synthesizing the merged diff at the end.

Where the dependency order lives

The task list owns the ordering. When a teammate finishes a task others depend on, blocked tasks unblock automatically, and claiming uses file locking so two teammates cannot grab the same item at the same moment. That mechanism is what makes the three-track example safe to run without a person watching every handoff.

File ownership is still yours. Partition files cleanly, the way the payments example separates src/payments/, components/checkout/, and tests/payments/, because a team does not hand its teammates separate checkouts on its own. The docs keep file conflict avoidance in the best practices list for the same reason.

Task size decides whether the split pays. Too small, and coordination overhead exceeds the benefit. Too large, and a teammate works for a long stretch without a check-in, which raises the risk of wasted effort. A self-contained unit that produces a clear deliverable, a function, a test file, or a review, sits in the middle. The same guidance says to wait for teammates to finish before you proceed, because the lead’s synthesis is only as good as the state it reads.

Team size has a ceiling you feel before you can measure it. One practitioner guide offers a blunt test: if you cannot name at least three genuinely independent parallel workstreams, a single session or subagents will likely outperform a team at lower cost. The docs point the same way from the other side, warning that added teammates bring more communication and coordination, and that past a certain point they do not speed up the work proportionally.

What does the token math say about cost?

A team of one lead plus three teammates runs four independent token streams. Each teammate has its own context window and consumes tokens independently, so total spend scales with how many teammates you spawn. Coordination messages land on top of that baseline, because each message is a turn inside someone’s window.

Counting the token streams

Setup context is the part people underestimate, because it repeats per stream. One write-up walks through a lead plus three teammates at 10k tokens of initialization context each and arrives at 40k where a single session would have spent 10k. Treat that as arithmetic on assumed numbers, not a measured bill, and keep the condition the same source attaches: a subagent with a fresh context window repeats setup context too. What differs is where the window goes afterwards. A subagent’s result is summarized back into the main context, while a teammate keeps its own window for the whole run, which is why the docs list token cost as lower for subagents and higher for teams.

Parallelism changes the shape of the spend. Running tracks at once can cut wall-clock time, but the bill goes up, because you pay for the same work plus the coordination wrapped around it. That is the trade in one sentence: seconds bought with tokens. Take it when a release window is tight, and decline it when the task would have finished comfortably in one session anyway.

What a 0% platform fee leaves in the estimate

MixRoute’s pricing page lists a 0% platform fee on tokens across its model line, which keeps the arithmetic readable once the model rates are known: no percentage is added on top of the upstream rate for each stream. A four-teammate run then estimates as the sum of what each teammate’s model actually costs, multiplied by the tokens that teammate consumes. Mix a planning model with cheaper execution models and the estimate follows those choices, with no blanket multiplier on top.

When Claude Code is configured to send its calls through MixRoute, agent-team spend follows the upstream provider rate with no gateway markup added, so you can size a run from model rates and expected token counts before enabling the feature. Comparing two team sizes comes down to the cost of the extra stream plus the messages around it.

Before you spawn the fourth teammate, compare the per-token rate behind each model your team would run, because that rate is what the extra stream costs.

How does review responsibility shift between the two patterns?

With subagents, review is one reading task: a summary comes back to the caller and you judge it there. With a team, review becomes a coordination task. Teammates can read and challenge each other’s work directly, several review tracks can run at once, and the lead merges the findings into a single result. You still approve the outcome, but what you read is a synthesis of opinions about work you did not watch happen. The file boundaries you drew are what make that synthesis readable.

One summary versus parallel review slices

The parallel review case in the docs is short and specific: spawn three teammates to review one pull request, one on security implications, one on performance impact, one on test coverage, and let each report findings. In a team the merge is explicit, and the lead turns three reports into one prioritized list. The same pattern covers competing-hypothesis debugging, where several teammates test different theories at once and the ones that lose can be stopped early.

What you gain is depth and speed. What you pay for is visibility. One practitioner write-up puts it bluntly: the top-level session stream is a condensed view, so finding out what a called agent actually did can mean inspecting that worker’s own history. If you need to know why a reviewer flagged a line, the answer sits in the reviewer’s window, not in the lead’s summary.

Independent critique is where separation pays for itself. A reviewer that never saw the first agent’s reasoning cannot be anchored by it, so some teams deliberately keep the evaluator on the final output, or hand it the artifact itself.

What stays on your side of the line

Four things do. Task status can lag, because teammates sometimes fail to mark tasks complete, and that blocks whatever depended on them; when a task looks stuck, check whether the work is done, then either update the status or nudge the lead. File conflicts remain possible, since a team does not isolate its workers on its own. Permissions are set at spawn, so the pre-approval decision happens before the team starts, and per-teammate permission modes are not available at spawn time. Review looks at the final state: many internal trajectories can end in the same successful-looking output, so the outcome is what you can actually check.

Two reviewers can work in a subagent setup as well, but you build the comparison yourself: two summaries arrive at the same caller and you reconcile them. The team version moves that reconciliation into the lead, and with it moves the question from which summary to trust to how to verify a merged result.

When does a single agent still make sense?

More often than the tooling suggests. One agent with good tools, disciplined context handling, and a subagent or two for heavy search work covers a larger share of coding tasks than most people expect, and it keeps the bill predictable. The coordination layer starts earning its keep at a specific point, not at a vague sense that the project has grown.

The boundary conditions for staying with one agent

Four conditions mark that point, and one practitioner guide lists them plainly: the work is too large to fit in a single context window even with subagent delegation; different parts need genuinely different tool access and behavioral constraints, not just different instructions; parts can run in parallel and wall-clock time matters; or output quality depends on independent critique that has not seen the first agent’s reasoning. None of the four is about capability. They are about how the work is shaped, and if you cannot point to one of them, the single-agent path is still open.

Specialization alone rarely settles it, because subagents already cover that ground with isolated contexts, task-specific instructions, and results that return to the caller. A practical version for subagents reads: use them when you only need the final summary, when the work is self-contained enough to return a clean result, when you want to restrict tools or route to a cheaper model, and when you need parallel research paths that do not depend on each other.

Sequential handoffs are the clearest case for staying simple. If one agent has to hand the same artifact to the next in order, a pipeline is more predictable than a team, and the docs’ description of subagents, focused tasks where only the result matters, fits that shape exactly. A single session also holds cost predictability, which matters when a task has a deadline but no wall-clock pressure.

Choosing the pattern for the task in front of you

Two facts about the work decide it. Does any worker need to read or challenge another worker’s finding before the task finishes? Does the work split into at least three tracks that can proceed on their own once the dependencies are written down? Two yes answers point to agent teams. Any other combination points to subagents or to a single session.

If the single-agent habits come first for you, our guide to the vibe coding workflow, where one session sets the pace before you split it, covers how to keep that session productive as a task grows.

Claude Code talks to a gateway in the Anthropic Messages format, and MixRoute exposes an Anthropic-compatible Messages endpoint next to its OpenAI-compatible one, so changing which Claude model a teammate runs is a configuration change.