DEV Community

Cover image for Claude Code subagents explained: context vs token count
System Design Simple
System Design Simple

Posted on Originally published at systemdesignsimple.com

Claude Code subagents explained: context vs token count

Claude Code subagents let one agent hand reading work to helpers that each run in their own context window and send back a short summary, so the main conversation keeps the task instead of every file it read. Each helper adds requests and overhead; total token use depends on how much repeated context the split avoids. Split reading that is independent; keep quick changes and work that shares context in the main chat.

Why does a coding agent lose track of the task? {#buried}

An agent works in a loop: it calls a tool, the tool's output is added to its context, and the next model call sends that context again. Ask it to fix a login bug and it might read the auth module, the session code, the logs, a search result and some test output. All of that sits in the same context window as your request.

A context window is the fixed amount of text a model can take in on one call. Once it is full of file contents you will not look at again, your original task is a small part of a large prompt. We covered the effect in why a long AI chat forgets your name, and the arithmetic of resending history in why an AI agent re-sends its history.

What is a Claude Code subagent? {#what}

A subagent is a helper that Claude Code starts for a side task. The Claude Code docs put it this way: "Each subagent runs in its own context window" (Claude Code docs). It has its own system prompt, its own tool access and its own permissions, and when it finishes it returns its results to the main conversation.

Claude Code docs paragraph: each subagent runs in its own context window and its requests count toward the same usage limits as the main conversation
The Subagents page of the Claude Code docs. Captured 2026-11-16. Source: code.claude.com.

When a side task would fill your main conversation with search results, logs or file contents, the subagent does that work in its own context and only the summary comes back. A non-fork subagent starts without the parent's conversation history and receives a delegation message describing its task. A fork inherits the parent conversation; its subsequent tool calls stay separate. The simulation below models non-fork helpers starting fresh. Forks inherit existing history and reuse the parent's prompt cache, so their accounting differs (fork docs).

The built-in Explore subagent is an example. It is read-only and searches a codebase, and the docs say Claude delegates to it so exploration results stay out of the main conversation.

Do subagents use more tokens? {#tokens}

The docs say each subagent sends its own requests, which count toward the same usage limits as your main conversation, and that each subagent spends tokens of its own while it runs. Only the main conversation's context gets smaller.

Anthropic has published a number for its own multi-agent research system. In a post published Jun 13, 2025, it reports that in its data agents used about 4x the tokens of chat interactions and that "multi-agent systems use about 15× more tokens than chats" (Anthropic Engineering).

Anthropic Engineering paragraph: agents use about 4x more tokens than chat interactions, and multi-agent systems about 15x more than chats
The paragraph on token use in Anthropic's post "How we built our multi-agent research system", published Jun 13, 2025. Captured 2026-11-16. Source: anthropic.com.

The figure compares Anthropic's multi-agent systems with chats, in its data. The post does not describe a controlled same-task token comparison between one agent and several. Its 15x figure cannot establish the token overhead of Claude Code subagents. The same paragraph adds that domains where all agents need the same context, or with many dependencies between agents, are not a good fit for multi-agent systems today, and that most coding tasks have fewer truly parallel parts than research.

The post also explains why the extra tokens can be worth spending. In Anthropic's analysis of the BrowseComp evaluation, token usage by itself explained 80% of the variance in performance. Spreading work across agents with separate context windows is a way to spend more tokens on a problem than one context can hold.

The orchestrator-worker pattern {#pattern}

Anthropic describes its Research system as an orchestrator-worker pattern: a lead agent plans, delegates parts of the question to subagents running in parallel, and combines what they return. The subagents act as filters, each searching one aspect and passing back a condensed result.

Claude Code subagents fit the same shape, as we read the docs. The main conversation is the orchestrator: it keeps the task and decides what to hand off. Each subagent is a worker with a narrow job, its own context and a summary to return.

Anthropic writes that vague instructions made its subagents repeat each other's searches, and that each subagent needed an objective, an output format, tool guidance and clear task boundaries. We simulated duplicated work between agents in multi-agent orchestration: 15 of 30 jobs duplicated.

When to use subagents, and when not to {#when}

The docs recommend:

Stay in the main conversation when Use a subagent when
The task needs frequent back-and-forth The task produces verbose output you do not need in the main context
Several phases share a lot of context, such as planning, implementation and testing You want to restrict which tools or permissions it gets
You are making a quick, targeted change The work is self-contained and can return a summary
Latency matters: a fresh subagent may need time to gather context

For parallel research, the docs add that it works best when the research paths do not depend on each other, and that many subagents each returning detailed results can still fill the main context.

So for the login bug: reading logs, searching for similar bugs and checking docs are independent and produce a lot of text, which suits subagents. Reading the auth code and the session code depends on the same context, so keep that in one place. Renaming one variable needs no helper at all. If you want two agents to check each other's work instead of splitting it, see one AI writes, another reviews.

A simulation: main context vs total tokens {#simulation}

This script replays an assumed reading workflow and estimates input tokens. It is a simulation, not a measurement of Claude Code or any model. The file in labs/ai-37 (node compare-single-agent-vs-subagent-tokens.mjs), which we ran on 2026-11-16 with Node 22.13.1, replays the shape of a 5-part reading job two ways and adds up estimated input tokens. In the first, one agent reads every file in one context. In the second, five helpers each read their files in a fresh context and return a summary.

The files are synthetic filler. Tokens come from a custom counter that has not been checked against a real tokenizer. Helper summaries are filler of an assumed 300 tokens, and both ways are assumed to give an equally good answer. There is no prompt caching, no compaction and no real model.

Simulated job (estimated tokens) One agent Five helpers
Main AI's largest input prompt, 5 parts x 4 files of about 2,000 tokens 40,477 3,616
Total input, larger job: 5 parts x 4 files of about 2,000 tokens 442,773 152,852
Total input, tiny job: 5 parts x 1 file of about 300 tokens 14,075 32,155

Assume N equal file reads of F tokens, an initial prompt of S tokens, and one final answer call. Ignoring tool-call text and framing, total input is (N + 1)S + FN(N + 1)/2. With 20 reads, the file contribution is 210F; five helpers reading four files each reduce that contribution to 50F, before delegation and summaries. The file term grows with the square of the reads in one context, and splitting cuts it because each helper's history stays short.

Prompt caching and compaction, which the simulation leaves out, would both change these numbers. Caching lowers the price of a repeated prefix but leaves it in the prompt, so it changes billing more than context size. Compaction summarizes older turns, so it changes how much history is kept and resent. The summaries also carry a risk: a fixed-size note may omit something the answer needs, and this simulation assumes equal answer quality.

On the tiny job the helpers used more input in total, because each one pays its own system prompt and brief. Real totals depend on how widely real helpers explore, which a script like this cannot show.

What we saw when we ran it {#we-ran-it}

On 2026-11-16 we ran node labs/ai-37/compare-single-agent-vs-subagent-tokens.mjs and it finished in 71 ms. It printed a table of one agent against 5 helpers, on a job of 5 subtopics with 4 file reads each. The token counts on the screen are estimates from our own counter, next to model call counts (21 for one agent, 31 with helpers). The read counts are not measured; they are part of the job setup and the sweep.

Terminal output of our ai-37 run: node compare-single-agent-vs-subagent-tokens.mjs
Our terminal after the ai-37 run, with the main table and the size sweep below it.

The main AI's largest input prompt fell from 40,477 to 3,616, and total input fell from 442,773 to 152,852. The sweep at the bottom is what surprised us. With 1 read per subtopic of a file estimated at ~300 tokens, the helpers used 32,155 against 14,075 for one agent, about 2.3x as many estimated input tokens. Each helper pays the system prompt again, and on a small job that overhead wins.

Screenshot of the official page: Anthropic Engineering: How we built our multi-agent research system (Jun 13, 2025)
Anthropic Engineering's post on how it built its multi-agent research system.

That post compares Anthropic's multi-agent systems with chats, which is a different comparison from ours and does not measure helper overhead on the same task. In our simulation, helpers used fewer estimated input tokens once each one had a lot to read, assuming a ~300-token summary is enough and both ways give an equally good answer, which the lab does not check. On the tiny job, 5 subtopics with one small file read each, one agent used fewer estimated input tokens in total.

Our take {#our-take}

Subagents keep the main conversation focused on the task and let independent reading run in parallel. The reading still happens somewhere, and every helper pays its own prompt overhead. A good split has independent parts, each with a clear boundary and a short summary to return. For the wider Claude Code toolkit (skills, hooks, worktrees), see how to use Claude like a professional.

This article summarizes the Claude Code Subagents documentation (read 2026-11-16) and Anthropic Engineering's post of Jun 13, 2025. The five-helper login bug is our own illustration. The table of numbers comes from our own simulation script, not from Claude Code, any model or any real workload.

Top comments (0)