What an agent team costs in Claude Code

Claude Code is Anthropic's coding tool. One session of it is one conversation between you and an AI model that reads files, runs commands and edits code. The text the model reads on each request is its context window, and every piece of that text is a token you pay for. An agent team is several of those sessions running at once on one task, and this page is about what that multiplies.

It is part of the guide to the cost of agents and unattended runs in Claude Code. The earlier pages covered a subagent, which is a helper that works inside one session and returns a summary. A teammate costs more than a subagent in every way Anthropic's documentation describes, and the documentation, read on 4 October 2026, says so in its own comparison table: token cost is "Lower" for subagents, because results are summarised back to the main context, and "Higher" for agent teams, because "each teammate is a separate Claude instance" [2].

What an agent team is

Anthropic's description: "Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other. You can also talk to any teammate directly without going through the lead." [2]

A team has four parts [2]. The team lead is the main session that starts teammates and coordinates work. The teammates are separate Claude Code instances that each work on assigned tasks. The task list is a shared list of work items that teammates claim and complete. The mailbox is the messaging system between agents, a JSON file per agent under ~/.claude/teams/.

Agent teams are experimental and disabled by default. To enable them, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your shell environment or in the env block of settings.json. Without that variable, "no team is set up at session start, no team directories are written, and Claude does not spawn or propose teammates" [2]. Spawn is Anthropic's verb for starting an agent.

Two conditions follow. Starting teammates requires an interactive session: in non-interactive mode with the -p flag, which is a run started from a script with no person at the keyboard, including sessions run through the Agent SDK (Anthropic's library for building your own programs on Claude Code), Claude does not start teammates, and a subagent that Claude names runs as an ordinary subagent even with teams enabled [2]. And enabling teams changes ordinary delegation: Claude may name a subagent on its own, and while teams are enabled a named subagent launches as a teammate, "so teams can form even when you didn't ask for one" [2]. Setting the variable to 0 in your user settings.json reverses that, and Claude Code rereads the variable each time Claude starts a subagent, so no restart is needed [2]. Managed settings apply after every other source, so an organisation can enable or disable teams for everyone; the page on settings an administrator can enforce covers that layer.

Anthropic's figure: 7 times a standard session

The cost page gives one number. Anthropic puts agent team usage at 7 times that of standard sessions when teammates run in plan mode, "because each teammate maintains its own context window and runs as a separate Claude instance" [1]. The condition is part of the statement: teammates running in plan mode. Plan mode is the mode in which Claude reads the code and proposes an approach before it edits anything. A teammate started while the lead is in plan mode works in read-only plan mode until its plan is ready, and Claude Code approves that plan in the lead's session as soon as the request arrives, without the lead reviewing it [2].

The figure is Anthropic's statement about its own product. The documentation gives no measurement for teams outside plan mode, so the page states the number with its condition and nothing more. The reason behind it is the same on every page: the cost page says each teammate runs its own context window, so token usage grows in proportion to team size, and the agent teams page says "Token costs scale linearly" [1][2].

What each teammate loads

The multiplication starts before a teammate does any work. "Each teammate has its own context window. When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills." [2] CLAUDE.md is the instruction file you write for Claude. An MCP server is a program that connects Claude Code to an outside tool or data source. A skill is a packaged set of instructions for one task. Everything that loads at the start of your own session, which the page on where Claude Code tokens go lists item by item, loads again for each teammate.

A teammate also receives the spawn prompt from the lead, and "The lead's conversation history does not carry over." [2] If you start the lead with --setting-sources, teammates load from the same restricted list of sources; before Claude Code v2.1.281, teammates shown in split panes (a display mode in which each teammate gets its own terminal pane) loaded every settings source [2].

The table shows what multiplies. The counts are our own arithmetic on Anthropic's statements that each teammate has its own context window and loads CLAUDE.md, MCP servers and skills; the last column quotes Anthropic's guidance on size.

Team	Context windows open	Copies of CLAUDE.md, MCP servers and skills loaded	Anthropic's guidance
Lead only, no team	1	1	"For routine tasks, a single session is more cost-effective" [2]
Lead and 3 teammates	4	4	"If you have 15 independent tasks, 3 teammates is a good starting point" [2]
Lead and 5 teammates	6	6	"Start with 3-5 teammates for most workflows" [2]
Lead and more than 5	1 per teammate, plus the lead	1 per teammate, plus the lead	Anthropic says three teammates with focused tasks often do better than five without focus [2]

Anthropic states that there is no fixed limit on the number of teammates, and lists the practical constraints instead: token costs scale linearly, coordination overhead (the messages and task handling between agents) increases, and "beyond a certain point, additional teammates don't speed up work proportionally" [2].

Anthropic's four cost rules

The cost page gives four rules under the heading "Agent team token costs" [1]. Each one maps to a cost named above.

1. Use Sonnet for teammates. "It balances capability and cost for coordination tasks." [1] You name the model in the spawn prompt, as in Anthropic's example "Use Sonnet for each teammate" [2]. Claude Code picks a teammate's model from the first of these that applies: the model the spawn prompt names, the model of a subagent definition the teammate is spawned from (where inherit selects the lead's model), CLAUDE_CODE_SUBAGENT_MODEL when set to anything other than inherit, and the lead's current model. CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 removes the first two sources and requires Claude Code v2.1.257 or later; before v2.1.251 the environment variable came first [2]. A teammate's model and fast mode are fixed when it starts, and teammates inherit the lead's effort level, the setting for how much the model reasons before it answers, by default [2]. The page on giving a subagent a smaller model covers the same variables for subagents.

2. Keep teams small. Each teammate runs its own context window, so Anthropic describes token usage as growing in proportion to team size [1]. The agent teams page adds the 3 to 5 starting range and the 15-tasks example [2].

3. Keep spawn prompts focused. "Teammates load CLAUDE.md, MCP servers, and skills automatically, but everything in the spawn prompt adds to their context from the start." [1] A spawn prompt is the message the lead gives a teammate when it starts it. Anthropic's example of a good one names the module path, the things to focus on, how the application stores its tokens, and the form of the report it wants [2].

4. Shut down teammates when their work is done. "Each active teammate continues consuming tokens until it exits or the session ends." [1] You end one by asking the lead to ask that teammate, by name, to shut down; the teammate can approve or reject with an explanation [2]. Anthropic lists shutdown as something that "can be slow", because a teammate finishes its current request or tool call first [2]. In in-process mode, the default display in which every teammate runs inside your main terminal, x on a selected teammate stops it [2]. An idle teammate's row hides from the panel after 30 seconds once every agent is idle, and the teammate "stays running and addressable while hidden" [2].

Anthropic adds a fifth caution under its best practices: "Letting a team run unattended for too long increases the risk of wasted effort." [2] The pages on loops and scheduled tasks and timeouts, retries and cleanup for unattended runs cover what runs without a person watching.

The teammates' cache bucket

The prompt cache is a store, kept by the service that runs the model, of request text it has already processed, so unchanged text is billed at a lower rate. Claude Code decides the cache lifetime per request, and in-process teammates fall in the "everything else" bucket with subagents, workflows, forks and compaction (the step that replaces a long history with a summary), which gets a five-minute lifetime by default, including on a Claude subscription, where the main conversation gets one hour within plan usage [3]. The agent teams page says the same and names the setting that extends it to an hour, subagentPromptCacheTtl, adding that the API bills one-hour cache writes at a higher rate [2]. The page on the five-minute and one-hour cache lifetimes owns that setting and its precedence.

When a team is worth it, by Anthropic's own use cases

Anthropic names the tasks "where parallel exploration adds real value" [2]:

• Research and review: teammates investigate different aspects of a problem at the same time, then share and challenge each other's findings.
• New modules or features: each teammate owns a separate piece.
• Debugging with competing hypotheses: teammates test different theories in parallel.
• Cross-layer coordination: changes that span frontend, backend and tests, each owned by a different teammate.

And the tasks where Anthropic says a team is the less effective choice: "For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective." [2] The page also says that "For research, review, and new feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective." [2] Anthropic suggests that a team new to the feature start with tasks that have clear boundaries and need no code written: reviewing a pull request, researching a library, investigating a bug [2].

Three limitations also affect cost [2]. /resume and /rewind do not restore in-process teammates, so a resumed lead may message teammates that no longer exist. A teammate whose turn ends on an API error notifies the lead with the error text, and teammates "may stop after encountering errors instead of recovering", which leaves tokens spent on a task that was not finished. And an in-process teammate's own subagents run in the foreground, because a teammate's background work cannot outlive the lead's process.

Our position

Treat a teammate as a whole session, because that is what Anthropic says it is. Before you start a team, write down the tasks and check that they are independent and each produce one deliverable; Anthropic's example is "a function, a test file, or a review" [2]. Reveneau recommends the four rules in Anthropic's order, with one addition: name every teammate in the spawn instruction so you can shut each one down by name, since the documentation's shutdown instruction works by name. If the tasks depend on each other or touch the same file, use subagents, which the page on when a subagent saves tokens covers, or a workflow, a script that starts many subagents, which the next page covers.

Reveneau is an AI software development consultancy. All of its code is written by AI, and every change must pass an eval suite, a set of automated tests written from the specification, before release, so token use is a running cost of every Reveneau build. Reveneau is independent of Anthropic. The 7 times figure and every other figure on this page are Anthropic's own statements about its own product, read on 4 October 2026.