I Measured What a Claude Code Subagent Costs, and on Small Files It Lost

Subagents are sold as a context saver, but a measured test shows they cost more on small reads; the skill is judging how much a search will read before you delegate it.

Rick Hightower

Cover image for “I Measured What a Claude Code Subagent Costs, and on Small Files It Lost” by Rick Hightower

A tested experiment with the Explore subagent and /context: the same question asked two ways, the numbers each one added, and the rule for when delegation actually pays.

You were told to delegate every search to a subagent to save context, and you never checked whether it actually saved anything.

In this article: Day 9 of a day-by-day guide to Claude Code. Start here: hand a search to the Explore subagent, read its answer, and measure with /context what the delegation cost your main conversation. Going deeper: what a subagent gets and what comes back, the built-in subagents, custom subagents, and when delegation pays.

Tested on Claude Code 2.1.326.

Yesterday you ran the tests on a loop, watched it catch a break, and canceled it.

Start here

At the end of today, you can hand a search to the Explore subagent, read its answer, and measure with /context what the delegation cost your main conversation.

Starting fresh or fell behind? Run git switch -C main claude-code/day-08. This replaces your main with the end of Day 8; to keep your own work, run git branch my-backup first.

On Day 6 you saw that every file Claude reads stays in the context window. A subagent is a helper that Claude starts for one task. It has its own context window. It reads files and runs searches there, and when it finishes, only its answer comes back to your conversation. Explore is a subagent that Claude Code includes. It can read and search, but it cannot edit files.

Today you ask the same question two ways, through Explore and directly, and compare what each one adds to your context window.

Check the starting state

Open a terminal in Ticket Triage:

cd ~/code/ticket-triage
git status
npm test

Git prints nothing to commit, working tree clean. The tests show ℹ fail 0 and the pass count from yesterday, such as ℹ pass 18.

Read the window first

Start Claude Code with claude and run /context. Write down the Messages line. On the tested run, it was Messages: 10 tokens, an empty conversation.

Ask Explore

Type this prompt:

Use the Explore agent to find every keyword that classify() and priority() check, and list each one with its file and line number.

Naming the agent in the prompt is how you ask for it. Claude can also choose Explore by itself for a broad search, but naming it makes today's test certain. On the tested run, the screen showed:

⏺ Explore(Find classify/priority keywords)
  ⎿  Backgrounded agent (↓ to manage · ctrl+o to expand)

⏺ The Explore agent is now searching for every keyword classify() and
  priority() check. I'll send you the full list with file and line numbers
  when it finishes.

✻ Waiting for 1 background agent to finish

Explore runs in the background. Claude starts it, says so, and waits. You can keep typing while it works. When Explore finishes, Claude's answer appears with a line such as Agent "Find classify/priority keywords" finished · 19s. In some tested runs, a line › Message from @Explore came first.

Sequence of one Explore delegation: you name the Explore agent, the main conversation starts it in the background, Explore reads the two source files into its own context window, and only its final answer of 12 keywords returns, while its tool calls stay with the helper.

On the tested run, the answer listed 12 keywords: nine in classify(), such as "broken" at src/classify.js:4 and "refund" at src/classify.js:5, and three in priority() at src/priority.js:4. Check two of them in your editor. The lines in your files can differ a little, because Claude wrote your files.

Manual mode: no prompts. Explore only reads.

Measure the cost

Run /context again and read the Messages line. On the tested run, it was Messages: 10.6k tokens. Compare the Messages line, not the total at the top. The total also counts the system prompt and the tool descriptions, which change a little between sessions. Messages is the part that your prompts and Claude's work added.

Now ask the same question with no subagent, in a fresh session. Type /exit, start claude again, and run /context. Messages is back to about 10 tokens. Then type:

Without using any subagent, find every keyword that classify() and priority() check, and list each one with its file and line number.

Claude reads the two files itself and gives the same list. Run /context once more. On the tested run, Messages was 7.5k tokens.

Manual mode: no prompt on the latest tested run, because Claude read the files with its Read tool. An earlier run read them with one shell command that combined ls, grep, and cat, and showed one Do you want to proceed?. If that prompt appears, read the command, then choose 1. Yes.

Flow of the two-session measurement: session one starts at 10 tokens and reaches 10.6k after the Explore prompt; after /exit, session two starts at about 10 tokens and reaches 7.5k after the direct prompt; comparing the Messages lines shows that Explore cost more on two tiny files.

Read the result

On Ticket Triage, Explore cost more, not less: 10.6k against 7.5k on the tested run, 9.4k against 7.6k in a session in Manual mode, and the same result in three earlier pairs. The two files are tiny. Explore's answer and the messages that start and report the helper weigh more than the files themselves.

Infographic: on two small files, Explore cost more. The same question asked through Explore and directly, with tested Messages readings of 10.6k and 7.5k tokens, because two ten-line files produce an answer as long as the files.

The same question, asked through Explore, added about 3k more tokens than asking directly, because the answer was as long as the files and the helper's start and report messages came on top.

Scene: a developer at a desk leans toward the monitor, surprised that the helper cost more context than asking directly, with two numbers written on a sticky note.

The scene captures the moment the measurement contradicts the rule of thumb. Two numbers on a sticky note beat a slogan.

A subagent saves context when the reading is much bigger than the answer: a search across dozens of files, long logs, or a whole folder of tests. The helper's context window fills with all of that, and yours gets one page of answer. For a question about two small files, ask directly.

Judge it before you ask. Picture what the search reads. In Ticket Triage it reads two files of about ten lines each, so the answer is about as long as the files. In a real project, a question such as "where do we validate a session token?" can read forty files and several thousand lines, and the answer is still one page. In that case the helper earns its overhead: the forty files fill the helper's window, not yours, and your window stays free for the work that follows the answer.

A second reason to delegate is focus, not size. A helper that only searches does not see the rest of your conversation, so what you discussed before does not shape its answer. A helper is therefore a fair second reader for your own work.

Decision flow before you ask: if the search will read much more than the answer, such as many files, long logs, or a folder of tests, name Explore; for one or two small files, ask directly; and when you want a reader that has not seen your reasoning, delegate for focus.

Check the win

You have two answers with the same keywords, and two Messages readings, one for each way. Your numbers can differ from the tested ones. The check: the first conversation shows an Explore(...) line, both answers list the same keywords, and the Explore reading is higher than the direct one. Neither prompt changed a file, so in a second terminal, git status still prints nothing to commit, working tree clean.

You handed a search to Explore, read its answer, and measured what the delegation cost.

You can stop here. Going deeper explains why this works and where it breaks.

Going deeper

This section is for readers who want the other built-in subagents, custom subagents, and the rules for when delegation pays. It assumes that you finished Start here in Parts 1 to 9.

What a subagent gets, and what comes back

A subagent starts with its own system prompt and the task that Claude wrote for it. It gets the MCP servers and skills of the session. Explore and Plan skip CLAUDE.md and the git status to stay small, so restate any CLAUDE.md rule that matters for the search in your prompt, such as "ignore the vendor/ folder". When the subagent finishes, the main conversation gets its final answer and a short note with its token count and time. It does not get the subagent's tool calls. Press ctrl+o on the agent line to see them.

The docs' context-window walkthrough gives an example of the case where delegation pays: a subagent reads about 6,100 tokens of files and returns a 420-token summary, so the main conversation grows by 420 tokens.

Infographic: delegate when the reading dwarfs the answer. The docs example shows a subagent reading 6,100 tokens and returning 420; name Explore for many files, long logs, or a folder of tests; ask directly for one or two small files.

The docs example reads 6,100 tokens and returns 420. A ratio like this one is what makes delegation pay, and it is the ratio Ticket Triage never had.

The built-in subagents

Table: Subagent, Tools, Model, Use it for. Rows: Explore; Plan; general-purpose.

Each built-in subagent differs in what it may touch, which model runs it, and the job it suits.

  • Explore is read-only, with Write and Edit denied, and has run on the parent conversation's model since v2.1.198. With a Fable parent, it runs on Opus or stays on Fable, based on how you connect. Use it to go and find out.
  • Plan is read-only and runs on the parent conversation's model. It does the research step inside plan mode, and plan mode starts it for you.
  • General-purpose has all tools and runs on the parent conversation's model. Use it for multi-step work that reads and also changes files.

Docs pages: v2.1.198, plan mode.

Claude Code also runs small helpers that you see in transcripts, such as claude-code-guide, which answers questions about Claude Code itself and runs on Haiku.

You can ask Explore for a depth: "Use Explore with very thorough mode to map every place that calls classify()." The levels are quick, medium, and very thorough.

Mind map of the built-in subagents: Explore is read-only on the parent model with quick, medium, and very thorough depths; Plan is read-only and runs inside plan mode; general-purpose has all tools; and small helpers such as claude-code-guide run on Haiku.

Running in the background

On 2.1.326, Explore ran as a background agent in every tested run: Claude started it, said so, and waited for the result while the prompt box stayed free. The ↓ to manage hint opens the list of running agents. A connected browser or phone from Day 7 also shows subagents that run in the background. The docs say that stopping one there stops it on your machine. This guide's test did not try that.

Custom subagents

When you describe the same helper in three prompts, write it down once. A custom subagent is a Markdown file in .claude/agents/ for the project or ~/.claude/agents/ for you, with frontmatter and a system prompt:

---
name: test-reviewer
description: Reviews new tests for Ticket Triage. Use after tests are added.
tools: Read, Grep, Glob
model: inherit
---

You review tests. For each new test, check that its ticket also matches an
older keyword, as CLAUDE.md requires. Report each test that does not.

The tools line limits what the helper can do. model takes sonnet, opus, haiku, or inherit for the parent's model. Claude Code has had no wizard for this since v2.1.198: write the file yourself, or ask Claude to write it. This guide's test did not create a custom subagent.

Infographic: a custom subagent is one Markdown file. It lives in .claude/agents/ or ~/.claude/agents/, its frontmatter holds name, description, tools, and model, its body is the system prompt, and since v2.1.198 there is no wizard.

A custom subagent comes down to where the file lives, the four frontmatter fields, and the system prompt below them. No wizard writes it for you, so the file is the whole interface.

When to delegate

Table: Delegate, Do it yourself. Rows: A search across many files or folders; Reading long logs or test output; A review that should not see your reasoning; Work that can run while you keep going.

Delegation pays in some situations and not in others, and each pair sets work to hand to a subagent against the matching work to keep in the main conversation.

  • A search across many files or folders is worth delegating, while a question about one or two small files is cheaper to ask yourself.
  • Reading long logs or test output belongs with a helper, while a change that needs the whole conversation stays with you.
  • A review that should not see your reasoning suits a subagent, while a step that you want to watch in detail does not.
  • Work that can run while you keep going is a good handoff, while quick lookups are not, because the helper's overhead costs more.

A subagent can start its own subagents, up to three layers below your conversation by default since v2.1.219. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH changes that limit. For several helpers that talk to each other, agent teams are the next step, and Day 22 covers them.

Corrections to the first edition

The first edition's Part 6 was written in May 2026. Checked against Claude Code 2.1.326 on November 16, 2026:

  • Explore runs on the parent conversation's model since v2.1.198, not on Haiku. The first edition's source now has this correction. Its published page does not have it yet.
  • Subagents can start subagents, three layers deep by default since v2.1.219. The first edition said that they cannot.
  • On Ticket Triage, delegating to Explore cost more context than asking directly. The first edition's rule, "delegate reading every time," holds only for large reading.

Timeline of subagent changes: the first edition in May 2026 said Explore ran on Haiku and subagents could not start subagents; v2.1.198 moved Explore to the parent model and removed the wizard; v2.1.219 allowed three layers of subagents; 2.1.326 was tested on November 16, 2026.

Go further: The Claude Code Feature You Skip Every Day (And Why It Quietly Wrecks Your Sessions) is the first edition's subagent chapter, with more on why long sessions degrade when you do not delegate. Read it with the corrections above in mind: the page still says that Explore runs on Haiku and that subagents cannot start subagents.

Do this today

Everyone

  • Ask the keyword question through Explore and directly, with /context after each. Check the win: you have two Messages readings and can say which way cost less, and git status is clean.
  • Habit: before a search, ask how much it will read. Many files: name Explore. One or two files: ask directly. Check: the next time you name Explore, the conversation shows an Explore(...) line.

If you read Going deeper

  • Ask "Use Explore with very thorough mode to list every test name in test/ and the keyword each one uses." Press ctrl+o on the Explore(...) line. Check: you see the tool calls that Explore made, which the main conversation did not keep. Reset: nothing changed. Check that git status --short prints nothing.
  • Create .claude/agents/test-reviewer.md from the example above. Type /exit and start claude again, because a running session does not pick up a new agents folder. Then ask "Use the test-reviewer agent on test/classify.test.js." Check: the conversation shows the agent's name and its report. Reset: run rm -r .claude/agents. Check that git status --short prints nothing.

Measure before you delegate

The slogan was "delegate reading every time." The measurement said otherwise: on two ten-line files, Explore added 10.6k tokens where asking directly added 7.5k. A subagent is not free. It pays for itself only when the reading it absorbs is much larger than the answer it returns.

Keep the habit, not the slogan. Before you hand off a search, picture what it will read. Forty files and a one-page answer is a job for Explore. Two small files is a question you can just ask. And when you are not sure, /context will tell you.


This is Part 9 of "Claude Code, Day-to-Day (second edition)," a day-by-day guide to Claude Code in which each day takes 20 to 40 minutes. Part 9 is Day 9. All 28 days are out now.