Claude Code Subagents: When They Earn Their Keep

Every time you spawn a Claude Code subagent, it forgets your entire project. No conversation history, no CLAUDE.md, no coding standards, nothing you and Claude worked out over the last three hours. Just a fresh, empty window and one prompt the parent handed it. People got angry about this online, and the loudest of them called subagents “incredibly unreliable.”

They were looking at the feature and calling it a bug. That amnesia is the entire reason subagents exist. This piece walks through what they actually are, why context erasure is the win, the one pattern worth your money, the one that is mostly theater, and the cheapest trick to keep them from eating your budget.

What are Claude Code subagents?

A subagent is a fresh Claude session that your main session can spawn, hand a single prompt to, and get one summary back from. It runs with a different context window, a different system prompt, a different tool list, and optionally a different model. The parent does not watch the work happen. It only receives what the child reports at the end.

If you have ever used fork and exec in a shell, you already know the shape. The parent launches a subprocess, the child does its thing in its own memory, prints a result, and exits. There is no shared brain, no threads, no microservice. Just: here is a prompt, go cook, come back with a sentence.

Parent session

• CLAUDE.md
• coding-standards.md
• 3 hrs of conversation
• architecture notes

Loaded · ~200k window

one prompt ↓ OPAQUE ↑ one summary

Child subagent

> _ fresh, empty window

Forked · dies on return

Why context isolation is the real win

Most tutorials sell you on parallelism: run ten agents at once, ship faster. That is the sizzle. The steak is context isolation, and Anthropic’s own documentation leads with it. Your main session has a context window of around 200,000 tokens, and quality starts slipping once it passes roughly two-thirds full. What fills that window matters as much as how big it is.

So picture telling Claude to “run the test suite,” and the failing tests dump 40,000 tokens of stack traces straight into your conversation. That is not test output anymore. That is your main agent slowly losing the plot. Hand the job to a subagent instead and the noise stays in the child’s window. The parent gets back something like “23 tests failed, all in auth, here are the names.” Roughly 200 tokens instead of 40,000.

Inside the subagent

TypeError: cannot read 'id' of undefined at auth/login.ts:47 at runMicrotasks (node:internal) AssertionError: expected 200, got 500 at test/auth.spec.ts:112 FAIL src/auth/session.test.ts Expected token to be defined …

~40,000 tokens of noise

→ only the summary crosses back

Back to the parent

23 tests failed all in auth/ → here are the names

~200 tokens

That is why isolation beats throughput as the headline benefit. Parallelism is a nice side effect when work happens to be independent, but the durable reason to reach for a subagent is to keep junk out of the session that holds your actual reasoning.

How do you create a subagent?

You write a small Markdown file. The YAML frontmatter on top carries the config; the body becomes the subagent’s system prompt. Only name and description are required. Drop the file in .claude/agents/ for one project, or ~/.claude/agents/ to make it available everywhere, then Claude reads each description at startup and decides when to delegate.

---
name: explore
description: Read-only codebase exploration. Use proactively to map files.
model: haiku
tools: [Read, Grep, Glob]
---

You are a focused exploration agent.
Return only what is relevant to the question. Be concise.

That description field is doing more work than it looks. Claude routes to a subagent by matching the task against the verbs in its description, so “Use proactively to run tests” delegates more reliably than a vague label. You can also force a specific subagent with an @-mention, or hand the whole session over to one with claude --agent <name>.

Why are Claude Code subagents so expensive?

Because each one is a full Claude conversation built from scratch. New system prompt, new tool schemas, new everything. Before a subagent does a single useful thing, it has already burned somewhere between 15,000 and 25,000 tokens just turning the lights on. Spawn three at once and you pay that three times over, before any code is written.

This is the part the parallelism pitch quietly skips. Anthropic’s multi-agent research system beat a single-agent setup by 90.2% on an internal eval, but it spent about 15 times the tokens of a normal chat to get there. Everyday Claude Code sessions that lean on subagents land around 4 to 7 times the token cost. One Max-plan user documented burning 59% of a weekly budget in two days of parallel fan-out.

Tokens to start 15–25k

burned per subagent just loading a fresh system prompt and tool schemas, before a single line of work is done

Token multiplier 4–7×

typical overhead of a subagent-heavy Claude Code session versus running the same work in one agent

Budget in 2 days 59%

of one Max user’s weekly quota gone in 48 hours of parallel subagents, per a documented Claude Code issue

The summary string gets billed twice, too: once as the subagent’s output, then again as the parent reads it back in. Spawning a subagent does not reuse the parent’s prompt cache the way you might assume, which is exactly why the next section exists.

The cheapest trick: route subagents to Haiku

The fix is one line of YAML. Keep your main session on Opus or Sonnet, where the planning and the hard judgment calls happen. Then pin the grunt-work subagents, the test-runner, the file-explorer, the doc-reader, to Haiku with model: haiku. Haiku is roughly three times cheaper per token, and on the kind of search-and-execute work you delegate, it barely gives anything up.

Anthropic clearly designed it this way. It ships Haiku as the subagent tier, and the built-in Explore agent runs on Haiku by default, read-only. Boris Cherny, who built Claude Code, has pushed the same pattern for months: heavy model plans, light model executes. One developer reported shipping four to five times more work inside the same weekly cap just by adding model: haiku in the right places.

Opus / Sonnet Main session · the planner

• Holds the plan and the hard judgment calls
• Decides what to delegate and reads the summaries
• Where the reasoning that actually matters happens

Haiku Subagents · the executor

• Runs tests, explores files, fetches docs
• Roughly 3× cheaper per token than Sonnet
• Ships as the default for the built-in Explore agent

~4 pts On SWE-bench Verified, Haiku 4.5 scores 73.3% against Sonnet 4.5’s 77.2%. On the search-and-execute work you hand a subagent, that four-point gap is a rounding error, and it costs a third as much.

Are persona subagents a scam?

Mostly, yes. Open the popular awesome-claude-code-subagents repo and you will find more than a hundred pre-made personas: senior-engineer, product-manager, frontend-architect, database-admin, whole AI org charts. People download an entire fake company and drop it into .claude/agents/. It feels productive. It mostly is not.

The model has no special memory of being a senior engineer. Telling Claude it is one does not make it reason like one, it just makes it sound like one. A widely-quoted Hacker News comment put it best: this is like launching an entire team of “fake it til you make it” employees. The costs, meanwhile, are real. A dozen role-named agents fight each other for routing, balloon your description-loading overhead, and produce zero quality lift.

Roles Theater

• "senior-engineer", "product-manager", "frontend-architect"
• The model has no memory of being a senior engineer
• It sounds the part; it does not reason any differently
• 12 of them just fight each other for routing

Tasks Real

• A read-only agent with only Read, Grep, Glob
• A test-runner that returns nothing but failures
• Different because the guardrails are different
• Action-verb names auto-delegate more reliably

The rule Make subagents for tasks, not roles.

What actually works is mechanical isolation. A read-only subagent that only has Read, Grep, and Glob is genuinely different from your main agent, because it physically cannot edit anything. A test-runner that returns only failures behaves differently too, because the contract is narrow. The guardrails matter more than the personality. Make subagents for tasks, not roles.

What is “context amnesia”?

It is the second thing nobody warns you about, and it follows directly from how subagents work. They do not inherit your CLAUDE.md anymore. Since Claude Code v2.1.84, a feature flag actively strips it from subagents. Your project rules, your conventions, your house style: the child never sees any of it. It is working blind in your codebase, guessing at your architecture from scratch.

The community named it context amnesia, and it explains a complaint you have probably seen: subagents that return code that “looks like the right answer to a different project.” That is exactly what it is. There is a third tax on top, too. When a subagent goes off the rails, you cannot watch it happen. The parent only sees the final report, so if the child spent twenty minutes solving the wrong problem, you find out at the end, after paying for it.

v2.1.84

CLAUDE.md stripped

Since this version a feature flag actively removes your project rules from subagents, so your conventions and house style never reach the child.

Blind

No project context

With no rules and no parent conversation, the subagent hallucinates your architecture and returns "the right answer to a different project."

Black box

No live visibility

The parent only sees the final report. If a subagent spends twenty minutes solving the wrong problem, you find out at the end, after paying for it.

None of this makes subagents useless. It makes them sharp tools with a specific grip. If a subagent needs your conventions, inline them into its system prompt, preload them as a skill, or pass them in the prompt itself. Do not assume they leak in.

When should you use a Claude Code subagent?

The honest test is simple: is the output loud and the conclusion short? If yes, a subagent earns its keep. If the work is a tight loop where each decision depends on the last, it does not, because that is exactly where amnesia and the token multiplier hurt most. The table below is the decision in one screen.

There is a fourth winning case worth calling out on its own: routing execution to Haiku is close to free money, because you keep your quality where it matters and pay less for the parts that do not need it. Anthropic widened the five-hour limits and removed peak-hour throttling in May 2026, but it left the weekly caps untouched. Run subagents around the clock and you still hit that wall, just later in the week.

The verdict: a context firewall, not an AI workforce

Subagents are a real primitive doing narrow work. They are a context firewall with parallelism as a bonus. They are not an AI workforce, they are not a senior team, and a hundred Markdown files in your config folder is not a strategy. It is a graveyard you will never open.

Use them where it hurts to do without: read-heavy fan-out, model-routed execution, independent verification passes. Skip them everywhere the inner loop lives. Pin the grunt work to Haiku, fork instead of spawn when you fan out, and keep one eye on the meter. Do that and subagents stop being the thing people rage about online and start being the boring, useful tool they actually are.