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.
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.
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.
| Task | Variant | Main context at the end | Cost | Result |
|---|---|---|---|---|
| Run tests, fix failures | Main conversation, run 1 and 2 | 18,537 and 18,525 | $0.045 and $0.046 | Both fixed, all tests pass |
| Run tests, fix failures | test-runner subagent, run 1 and 2 | 20,907 and 21,023 | $0.107 and $0.087 | Both fixed, all tests pass |
| Find rounding bugs in 40 modules | Main conversation | 23,079 | $0.071 | Five correct, but it first said six and then corrected itself |
| Find rounding bugs in 40 modules | Explore subagent | 21,278 | $0.115 | Five 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.
(opens at full size)When a subagent is worth it
| Use a subagent | Stay in the main conversation |
|---|---|
| Review, as long as you pass the original request and the diff, not the author's summary | Short tasks where output can be filtered with grep or tail |
| Several independent searches you want to run at the same time | Work that needs back-and-forth with you |
| Long sessions where every saved page of context adds up over hours | One-off questions where speed matters more than a tidy context |
| A task that should run on a cheaper or stronger model than the main one | Anything where cost per task matters and quality is already fine |
Create a subagent in three steps
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.Write the frontmatter and instructions
Only
nameanddescriptionare required. The description decides when Claude Code delegates, so say what it does and when to use it. Limittoolsto 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>."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.
textUse 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.
| Review setup | Noticed the missing cent? | Reported it as a problem? |
|---|---|---|
| Reviewer subagent, diff written by us | Yes | Yes, as the most severe bug |
| Main agent reviews its own code | Yes | No, left as specified |
| Reviewer subagent, briefed by the main agent that wrote the code | Yes | No, called it a consequence of the request |
---
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
Explorewithmodel: haikuif 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
- Claude Code: Create custom subagents checked on
More in claude in practice
- CLAUDE.md and Claude Code Memory: A Template We TestedHow Claude Code memory works through CLAUDE.md, with a template we tested: rules that stick, background files that load only when needed, and AGENTS.md.
- Claude Code Permissions: Let It Work Freely Without Breaking AnythingSet up Claude Code permissions so it works without constant prompts but can't delete or leak what matters. Tested settings file, deny rules and a blocking hook.
- Claude Code Agent Teams: Setup, a Real Test, and When They're Worth ItHow to turn on Claude Code agent teams and what a three-teammate review gave us: 24 findings versus 12 from one session, at seven times the cost.
- Claude Code in a Loop: /loop, the Ralph Loop, and When a Long Job Needs Something ElseClaude Code's /loop, the Ralph loop and long-running jobs compared. We ran six tasks as a loop and as one session: same result, four times the cost.
Also useful
- AGENTS.md Explained: One Instruction File for Codex, Claude Code and Other AgentsAGENTS.md is the shared instruction file for coding agents. How Codex reads it, when Claude Code does, and the one-line fix we tested.
- AI for project managers: minutes, status reports and a critical path, each tested three timesMinutes, a status report and a critical path, each run three times. Where AI was right every time, its one invented claim, and a weekly report setup.
- How to Build an MCP Server: A Tested Python and Node ExampleBuild a working MCP server in Python or Node, test it without a model, inspect it, then connect it to an AI app. Full code and the errors we hit.