Claude Code Subagents: What They Actually Cost, Where to Keep Them, and When They Stop Working

A Claude Code subagent is a separate session, with its own context, that you hand a task to and that hands you back a summary. It costs more than it looks, and not for the reason you would guess: across 858 runs I measured, 94.4% of the tokens are re-read context and only 0.78% is what the agent writes. Cost follows turns, not answers.

This is the second piece in a series on configuring Claude Code. The first, on hooks, was about what the model cannot do. This one is about who does the work, what it costs you, and when to stop.

A note on scope first, because it is the thing I would go and check. Every number below comes from counting the Claude Code transcripts on one of my machines, from 19 July to 5 September 2026, 24 working days across 12 projects. They are the median of my work, not a constant of the product: use them to understand the shape of the problem, not to estimate your own bill. And since I work across more than one computer, they are not even all of my own usage: they are what sits on this machine.

What does a subagent actually cost?

The useful answer is not a number, it is a shape.

The median subagent moves through 359,969 context tokens. The mean is 1,712,629, which is 4.8 times the median. The 99th percentile is 17.5 million and the worst one I measured reached 61,468,112 tokens, 171 times the median.

When a distribution has a mean five times its median, the mean describes nothing that will happen to you: it describes the tail. Anyone telling you "a subagent costs around X" is quoting their outliers.

The worst one is worth looking at closely, because it teaches something: a documentation-update agent, launched by hand against a large codebase, with no declared scope. 202 model turns, 255 tool calls, 31.6 minutes. It did nothing wrong. It just kept reading.

Why is nearly the whole bill re-read context?

Because on every turn the model receives the entire conversation again. The Claude Code documentation on costs says so plainly: the whole conversation travels with every request, and a one-line question in a session that has been open for hours still draws on the entire conversation.

Across the 1,368,390,396 tokens moved by subagents in the measured period, the breakdown is this:

• context re-read: 94.4%
• fresh input and cache creation: 4.8%
• output: 0.78%

That thin sliver at the end of the bar is everything the subagents wrote. The practical consequence is the first rule I took from this: what hurts is not how much it writes, it is how many turns it takes. Give an agent an exploratory goal and it will take many turns, and every turn pays again for the whole context accumulated so far.

The tool profile confirms it. Across 16,314 tool calls: Bash 5,419, Read 4,049, Grep 1,522, Glob 947, Edit 896, Write 216. Writes are 6.8% of the total. Subagents read, and cost follows reading.

There is a flip side, and it is the reason subagents exist at all: precisely because the verbose output stays in their context and only the summary comes back to you, delegating noisy operations saves money. A subagent pays off when the input is bulky and the return is one page.

What do you pay before the agent has done anything?

This is the number that changed how I work more than any other.

Measured on the first turn of every run: median 37,063 tokens, p10 36,537. Between the tenth percentile and the median there is less than 2% of spread. That is not a variable: it is a flat fee.

Inside it are, and the documentation lists them one by one, the system prompt, the delegation message, the CLAUDE.md files at every level of the hierarchy, a snapshot of the parent session's git status taken at its start, and the preloaded skills.

Read the bold part again, then go and look at your CLAUDE.md. You do not pay for it once: you pay for it multiplied by every agent you launch. The documentation recommends keeping it under 200 lines by moving specialist instructions into skills, which load only when needed. With subagents, that advice is multiplied by the size of your wave.

Hence the operating rule: if the task closes in two minutes in the session you already have open, delegating it means buying a 37,000-token ticket for a one-block journey. It pays off when the agent takes many turns over material that must not enter your session: the long transcript, the laid-out PDF, the ten-thousand-line log.

Why does the same work cost four times more if you just ask for it?

Of the 799 runs whose cost I could reconstruct, 700 ran inside a written workflow and 99 were launched by hand from the session. Same kind of work, same metric.

These are weighted tokens, a cost proxy counting input, cache creation, a tenth of the re-read and output. It is not Anthropic's official counter, and it is stated as an estimate.

3.8 times, and the difference is not the model. It is that writing a workflow forces you to scope the task before launching it: you declare the phases, you tell each agent what it must return, and whatever is not needed stays out. When you ask out loud, the agent decides the scope while working, and it decides it wide.

When is it worth launching fifty instead of one?

When one would not make it.

The clearest example I have is a job on the JSON schema of every article on this blog: parameters to review and correct, one per article, fifty-four articles. I did it by launching one Sonnet agent per article, and it was done in twenty minutes. I am telling you this as direct experience, not as a measurement: it happened on another machine and it is not in the transcripts I analysed.

But the reason I did it that way was not speed. It was that a single agent would not have reached the end. Fifty-four articles in sequence, inside one context window, means a context that grows until it degrades: the last articles would have been handled worse than the first, and in all likelihood it would have died before finishing. The fan-out was not there to do the same thing faster, it was there to make it possible.

That is the criterion I now use to decide whether to open a wave: does the work split into independent parts that do not need to know about each other? If yes, many small heads beat one big head, and the cost per part drops because each one carries only its own piece. If the parts have to talk to each other, orchestration becomes pure expense.

One technical limit worth knowing, and it needs reading carefully because it is counter-intuitive: when 20 subagents are running in a session, spawning another one fails, and the error explicitly says not to retry. They do not queue. The number is changed with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. If you launch large waves, queueing is on you, or on whatever orchestration tool you are using.

Where do you keep agents: inside the project or above it?

I keep mine above, in a company plugin that every repository loads, and I still think that is right. The criterion is this: the craft goes in the company layer, the object stays in the project.

A brand reviewer, a visual verifier, a security reviewer, a functional analyst are crafts: they exist identically in any project, and a lesson you learn on one client serves the next one. If that agent lives inside a repository's .claude/agents/, the lesson dies there. The test is quick: move it to another repository, and if it loses its object, it is local. An agent that knows the database schema of one particular system stays where it is.

The catalogue today is 17 agents: 13 Sonnet, 4 Opus, no Haiku. Seven declare a high reasoning effort, the rest inherit the session's. Eleven of the seventeen have neither Write nor Edit, and that is deliberate: you take away a reviewer's ability to rewrite what it is judging, or it stops judging and starts fixing.

Now the uncomfortable part, which is also the most useful.

Nine of those seventeen agents have never run, and none has ever been deleted. Worse: across 42 orchestration scripts, exactly one calls a plugin agent by name, and 92% of the runs went to anonymous workers defined on the fly inside the workflow.

So: the catalogue is the right call and I am the one bypassing it. When I write a workflow I define the agent right there, because it is faster, and the carefully written role with its rationale and its toolset sits and watches. That is a discipline problem, not an architecture problem, and the fact that it only shows up when you count is exactly why I counted.

When is something an agent, and when is it a hook or a skill?

Three questions in order, and the first one that answers yes decides.

Can it be checked by machine, and must it always hold? Then it is a hook, and it costs almost nothing. A check that filters before the model cuts context from tens of thousands of tokens to hundreds: the piece on hooks covers where to put one and why you will put your first one in the wrong place.

Is it a procedure you invoke when needed? Then it is a skill, with the advantage of loading only at the moment of use instead of sitting in context permanently.

Does it need judgement that a regular expression cannot give? Only then is it an agent. And there is a second legitimate reason to create one, independent of judgement: context isolation, meaning when you need a container that takes the megabytes and hands you back a page.

On models, the rule I apply has three levels: the expensive model only where being wrong costs money, data or a dispute; the middle model as the default for qualitative judgement; and for mechanical tasks, before picking a model, ask whether it should be a hook instead. And before raising the model, ask how the agent actually fails: if it fails by tiring halfway through, raising the reasoning effort costs a fraction and buys exactly that.

What happens when the limit hits halfway through a fan-out?

What happens is that the agents still queued die without producing anything, and the work has to be paid for again in full, because there is no automatic resume.

In the measured period: 59 subagents out of 858, or 6.9%, killed by the limit before producing a single token. Fifty-five of those fifty-nine on just two projects, which means the problem is not spread out, it concentrates where the waves are large. I counted 166 limit messages, of which 158 session limits, 3 weekly and 5 out-of-credit; 121 landed inside a subagent and 45 in the main thread.

On the count of days I have to widen the scope I declared at the top, or the number does not add up: the walls touched 16 days out of 56, and those 56 are the entire Claude Code archive on this machine, which starts on 12 May 2026. It is a wider window than the subagent one, because I was hitting limits before I started using them too.

All of that happened while I was on a Max 5x plan. I moved to Max 20x in early September 2026, when I started using subagents heavily. I am not telling you the 20x solves it, because I have only been on it for a few days and I do not have the data to claim that. I am telling you two separate things: on the 5x the walls arrived roughly one working day in three and a half, and waves of agents are the fastest way I know of getting there, as the 55 deaths across just two projects suggest.

There is a third route, and I tried it: pay-as-you-go credits. I bought about a hundred euros' worth between May and June 2026, and they evaporated in three hours of agents. They are for breaking through a wall at a moment when you cannot stop, not for changing how you work.

Which subscription do you actually need?

The official prices, verified on 5 September 2026 on Anthropic's page, are in US dollars and exclude applicable taxes: Pro 17 USD a month with the annual discount (20 monthly), Max 5x 100 USD, Max 20x 200 USD. Claude Code is included in every paid plan and shares the plan's limits, with a window that resets every five hours plus a weekly limit.

And here I have to tell you something no guide says, because it is inconvenient: those multipliers cannot be converted into anything. Max 5x gives five times Pro's usage and 20x gives twenty times, but the base is not published, so there is no honest way to translate them into hours, messages, tokens or number of agents. Anyone who writes "with plan X you can launch N agents" is making it up.

What the sources do support is this: Anthropic itself recommends moving from 5x to 20x for people who consistently hit the limits. If you launch waves of agents, you hit them. The rest you have to measure yourself, and the /usage command shows you how recent consumption is attributed to skills, subagents, plugins and MCP servers, over 24 hours or 7 days. With a caveat the documentation states: the figures are approximate, computed from that machine's local session history, so they do not include usage from other devices.

How do you notice that a workflow only pretended to work?

Not by looking at the result, because the result arrives either way.

In my archive there is a review closed with a completed status that had lost nine verifiers out of twenty-two to the limit, and one where all three agents died together after burning 339,196 tokens and 113 tool calls, delivering a log that said "confirmed zero out of zero". Neither presented itself as failed.

After a wave I check three things, and it takes me twenty seconds: the status of every agent (how many started against how many delivered), the match between the number of findings and the number of verdicts, and that every declared phase actually started. If the count does not add up, the result is not wrong: it is incomplete, which is worse, because it looks complete.

One last thing about quality, and treat it as a warning. I had the findings of a review checked by independent agents, three per finding, with a mandate to try to knock them down. On a prose report, 29 of 46 findings fell, 63%. On the same setup applied to code, where the verifier can open the file and count, the rejections were zero out of seventy. The lesson: an adversarial verifier is worth exactly as much as what it can check. Give it a verifiable fact and it saves you from an error; give it an opinion and it hands you back a second opinion dressed as a verdict.

Frequently asked questions

How much does it cost to launch a subagent in Claude Code?

On a measurement across 858 real runs, the median subagent moves through 359,969 context tokens, but the mean is 1,712,629, which is 4.8 times as much, and the worst case measured reached 61,468,112. The mean describes the tail, not the typical case: plan on the median. These are numbers from one specific usage on one machine, not a constant of the product.

Why does a subagent consume so much even when it writes very little?

Because almost all of the consumption is re-reading context. On the same measurement, 94.4% of tokens are cache read, 4.8% are fresh input plus cache creation and only 0.78% is output. Every turn pays again for the whole context accumulated up to that point, so cost follows the number of turns, not the length of the answer.

Is it always worth delegating to a subagent?

No. A subagent starts from roughly 37,000 context tokens before doing anything at all, and it is a fixed cost: system prompt, delegation message, the CLAUDE.md files of the hierarchy, the parent session's git status and the preloaded skills. If the task closes in two minutes in the session you already have open, that ticket does not pay for itself. It pays off when the agent takes many turns over bulky material that must not enter your session.

How many subagents can you run in parallel?

With 20 subagents already running in a session, spawning another one fails with an error that says not to retry: they do not queue by themselves. The number is changed with the CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS variable. But the technical ceiling is not the budget: how many you can afford depends on your plan's window, and no official source publishes that number.

Which Claude subscription do you need for heavy subagent use?

Claude Code is included in every paid plan and shares the plan's limits. Prices verified on 5 September 2026 are Pro 17 US dollars a month with the annual discount, Max 5x 100 dollars and Max 20x 200 dollars, excluding taxes. Anthropic recommends moving from 5x to 20x for those who consistently hit the limits. The multipliers, however, are relative to a base that is not published, so they cannot be converted into hours, messages, tokens or number of agents.

Where to start

If you have never counted what they cost you, start there: /usage gives you the attribution, and your transcripts give you the rest. The measurement needs one precaution, or the numbers come out inflated: the same model turn appears across several records sharing one request identifier, so they must be grouped rather than summed. On my subagent transcripts, summing the records as they come inflates the total by 2.24 times.

Then three rules, in order of how much they have saved me:

1. Look at your CLAUDE.md and cut it. It is the multiplier you pay on every agent.
2. Write the task down before delegating it. The gap between 82,337 and 313,958 tokens is entirely there.
3. Open a wave only when the parts do not need to talk to each other, and afterwards check how many agents actually delivered.

The tools we publish live in the Open Lab.