Skip to content
Mia Automation
NLEN Sign in Put Mia to workGet started

Claude Code Subagents: When They Help, and When They Only Cost More

A Claude Code subagent is a helper with its own context window: it does a side task, such as searching or running tests, and hands back only a summary. The usual pitch is that this keeps your main conversation clean. In our pilot of nine sessions the effect was small. On a 40-file search the main conversation ended at 21,278 tokens with a subagent instead of 23,079. On a noisy test run it grew, from about 18,500 to about 21,000. Each subagent session cost 1.6 to 2.4 times as much. A reviewer subagent caught two planted bugs, but took the author's view when the author briefed it.

Claude in practiceUpdated 7 min read

Tested by us on 11 November 2026.

What a subagent is

Anthropic's docs describe subagents as specialized assistants that each run in their own context window, with their own instructions, tool access and permissions. The main conversation hands off a task and gets the result back as one message. Everything the subagent read along the way stays with the subagent. Claude Code ships with three built-in ones: Explore for read-only searching, Plan for research in plan mode, and a general-purpose agent that can also make changes.

Animated bar chart: without a subagent the main conversation grows to 23,079 tokens; with the Explore subagent reading the files in its own context and returning a summary, it ends at 21,278 tokens
Our 40-module search: the subagent kept the file reads out of the main conversation, but the main agent had already filtered them well.

What we measured

We ran two tasks in fresh Claude Code 2.1.321 sessions on Ubuntu, once with subagents turned off and once with a subagent asked for by name. For each run we read the session log and took the size of the main conversation at its last turn, in tokens (chunks of about three quarters of a word). The test suite printed about 70 KB of debug output with two failing tests among 302. The search covered 40 Python modules, five of which added money as floats. With one or two runs per variant, treat the numbers as a pilot, not as averages.

November 11, 2026. Cost is what Claude Code reported at API rates. Ratios: tests 1.9 to 2.4 times, search 1.6 times. Six sessions here, three more in the review test below.
TaskVariantMain context at the endCostResult
Run tests, fix failuresMain conversation, run 1 and 218,537 and 18,525$0.045 and $0.046Both fixed, all tests pass
Run tests, fix failurestest-runner subagent, run 1 and 220,907 and 21,023$0.107 and $0.087Both fixed, all tests pass
Find rounding bugs in 40 modulesMain conversation23,079$0.071Five correct, but it first said six and then corrected itself
Find rounding bugs in 40 modulesExplore subagent21,278$0.115Five correct, with file and line numbers

Why so little saving? Without subagents, Claude Code didn't pour the full test log into its context. It piped the output through grep and tail and read only the failures. On the search it filtered the files with shell commands before reading. The subagent then adds its own instructions and a summary on top. The extra cost has a second cause: the docs say that with a Claude subscription or Console account, the built-in Explore agent runs on the Opus model, whatever your main model is.

Two final answers side by side. Left, the main conversation opens with Six modules and later says That is five modules, not six. Right, the Explore subagent lists five modules with file and line numbers (opens at full size)
Both answers to the 40-module search. The main conversation miscounted before correcting itself (highlighted); the subagent's list was clean.

When a subagent is worth it

Use a subagentStay in the main conversation
Review, as long as you pass the original request and the diff, not the author's summaryShort tasks where output can be filtered with grep or tail
Several independent searches you want to run at the same timeWork that needs back-and-forth with you
Long sessions where every saved page of context adds up over hoursOne-off questions where speed matters more than a tidy context
A task that should run on a cheaper or stronger model than the main oneAnything where cost per task matters and quality is already fine

Create a subagent in three steps

  1. Make the agents folder

    Project subagents live in .claude/agents/ in your project, so the whole team gets them through git. Personal ones go in ~/.claude/agents/. Each subagent is one Markdown file.

  2. Write the frontmatter and instructions

    Only name and description are required. The description decides when Claude Code delegates, so say what it does and when to use it. Limit tools to what the job needs; a reviewer has no reason to edit files. The text below the frontmatter becomes the subagent's instructions. This is the code reviewer we use, which we tested on a change with two hidden bugs:

    markdown
    ---
    name: code-reviewer
    description: Reviews a diff or recently changed files for correctness only, with a fresh context. Use after every substantial code change, before reporting done.
    tools: Read, Grep, Glob, Bash
    ---
    
    You review code with a fresh context, so you are not biased toward code that was just written.
    You get a diff, a list of changed files or a path.
    
    Scope: correctness only.
    - bugs, edge cases, race conditions, error handling that silently swallows failures
    - security: injection, missing auth checks, secrets in code or logs
    - behavior that differs from what the task asked for
    
    Do not: comment on style, propose redesigns, or write "you could consider" suggestions.
    A reviewer who must find problems will always find some. That is not the goal here.
    
    Report at most 5 findings, most severe first. For each: file:line, one sentence on what is wrong,
    and a concrete failure scenario (which input or situation leads to which wrong behavior).
    No findings? Say so explicitly: "No correctness problems found in <scope>."
  3. Call it by name, then let the description do the work

    Start a new session so Claude Code picks up the file. Then ask for it by name, as in the line below. Once that works, Claude Code also delegates on its own when a task matches the description.

    text
    Use the code-reviewer subagent to review the uncommitted changes (git diff).

We tested this reviewer twice. The first time it got a diff we wrote ourselves, with two planted bugs. One was an installment function whose parts don't add up: splitting 100 into three gave 33.33 three times, 99.99 in total. The other was an average that crashes on an empty list. It reported both, plus an inconsistent rounding mode, and no style remarks.

Then we let the main agent write similar functions itself, from a request for "equal installments rounded to cents", and hand them to the reviewer. This time the reviewer saw the missing cent and called it fine, because it "follows from equal installments". A control run without a subagent, where the main agent reviewed its own code, said the same and left it as specified. The reviewer only knows what the main agent tells it. If you want an independent check, give the reviewer the original request and the diff, not the author's summary.

One run each, Claude Code 2.1.321, November 11, 2026.
Review setupNoticed the missing cent?Reported it as a problem?
Reviewer subagent, diff written by usYesYes, as the most severe bug
Main agent reviews its own codeYesNo, left as specified
Reviewer subagent, briefed by the main agent that wrote the codeYesNo, called it a consequence of the request
markdown
---
name: test-runner
description: Runs the test suite or build and reports only what fails. Use it to check work without filling the main conversation with test output.
tools: Bash, Read, Grep, Glob
---

You run tests. You get a project path and, if known, the test command.
No command given? Work it out from the project files (package.json, Makefile, pyproject.toml, tests/).

1. Run the full suite. Long output is for you, not for the caller.
2. For each failure, extract the core: file, test name, error message, 1-3 relevant lines of the traceback. Group identical causes.
3. Separate real failures from noise such as deprecation warnings.

Report briefly. First line: "PASS: n tests" or "FAIL: n of m failed". Then only the failures with a one-line diagnosis.
Never paste the full log.

Our test-runner subagent, used in the measurement above. It keeps long logs out of the main conversation even when the main agent wouldn't filter them.

Things that tripped us up

  • Subagents start in the background. According to the docs, a subagent Claude spawns from the main conversation runs in the background unless you configure otherwise. In our headless test runs, Claude Code first answered "still running" and only gave the result in a second message.
  • A new file needs a new session. Claude Code reads subagent definitions at startup.
  • Typos in frontmatter fail silently. The docs say unknown fields are ignored, so Tools: with a capital letter does nothing.
  • Explore may cost more than you expect. On a subscription or Console account it runs on Opus. Define your own subagent named Explore with model: haiku if you want cheap searching; we haven't measured that variant.

Questions

Do Claude Code subagents save tokens?

They keep tokens out of your main conversation, but they spend their own. In our pilot the total went up in both tasks: 1.6 to 2.4 times the cost of the same task without a subagent, while the main conversation shrank by 8% at best.

Where do I put subagent files?

In .claude/agents/ in your project for shared ones, or in ~/.claude/agents/ for your own across all projects. Each subagent is a Markdown file with name and description in the frontmatter.

Can a subagent start other subagents?

Yes, up to three levels below the main conversation by default. Leave Agent out of a subagent's tools to stop it from spawning others.

Does Codex have subagents too?

We use the same review instructions in Codex by starting a separate session with only the diff. The instruction text works unchanged; how you start it differs per tool.

Sources