Subagents: Spend Tokens Without Spending Your Context
Anthropic's own data says the tokens an agent spends predict most of its performance — but in one session, every token lands in the same window as your plan. Subagents break that link. Here's the three-line file, the defaults that changed, and when to skip them.
- #claude-code
- #subagents
- #context
- #delegation
The stat that made subagents click for me is buried in Anthropic's research-system postmortem: in their browsing evaluations, token usage by itself explained 80% of the variance in performance. Spending more tokens on a problem is, most of the time, how an agent gets better at it. The catch: in a single session, every one of those tokens piles into the same context window that holds your instructions, your plan, and your diffs — until the useful stuff drowns.
A subagent is the mechanism that breaks that coupling. It lets Claude spend tokens on a problem somewhere else and pay you back with a summary. That's the right mental model: not a smaller Claude, but a second context window you rent per task.
What you're actually buying
A subagent runs with its own context window, its own system prompt, and its own tool permissions. It never sees your conversation — it receives its instructions plus basics like the working directory, nothing more. Two things follow:
- The mess stays out. Test output, log greps, dependency research — thousands of tokens burn in the subagent's window, and only the conclusion returns to yours.
- Zero inherited assumptions. A reviewer subagent reads the work cold, so it can't carry over the reasoning that produced the bug. Blankness is the feature.
The trigger I use: if a side task will flood the main conversation with output I'll never reference again, it goes to a subagent.
A custom subagent is one Markdown file
Drop this in .claude/agents/ (project-scoped, goes in git) or ~/.claude/agents/ (all your projects):
---
name: log-triage
description: Digs through test output and logs to isolate the failing case. Use proactively when tests fail.
tools: Read, Grep, Glob, Bash
model: haiku
---
You investigate failures. Report back only: the failing test, the exact
error, and the most likely file to fix. No log dumps.
Only name and description are required — Claude decides when to delegate by reading the description, and "use proactively" genuinely nudges it. tools is an allowlist (this one can't write files). model defaults to inheriting your session's model; pointing grunt work at haiku is the cheapest optimization available in Claude Code. Both directories are watched, so edits apply within seconds, no restart. Type @ and mention the agent when you want to force the delegation instead of leaving it to Claude.
The defaults moved recently
Two changes worth knowing. Since v2.1.198, subagents run in the background by default — Claude keeps working on your task while they grind, and their result arrives as a notification. And subagents can spawn subagents of their own, up to three layers below your conversation — a reviewer that dispatches one verifier per finding, with none of the intermediate output ever touching your window.
When it's the wrong tool
You buy the clean context with latency: a subagent starts blank and has to gather its own context from scratch. Quick targeted edits, work that needs back-and-forth with you, and phases that genuinely share context belong in the main conversation. And watch the return path — five subagents each sending back a detailed report re-pollute the exact window you were protecting. Ask for summaries, always.
The EM angle
A .claude/agents/ folder in version control is your team's delegation policy as code. How we review, how we triage failures, what a research agent is allowed to touch — the next hire clones the repo and inherits all of it, tool limits included.
Today: create one file — a read-only log-triage or code-reviewer in .claude/agents/ with tools: Read, Grep, Glob — and route the next noisy task through it. Then check how much smaller your main context stays.
Sources
Keep reading
More guides like this one.
Split Your Agents by Context, Not by Job Title
Most multi-agent setups fail because people split the work the way they would split it across a team — planner, coder, tester. Anthropic's own guidance calls that the anti-pattern. Here is the split that works, and the bill you are signing up for.
Skill, Workflow, or Agent? One Question Decides
Most devs reach for an agent when a 20-line workflow would be cheaper, faster, and deterministic. Here's the three-tier ladder with Anthropic's own definitions — and the single question that tells you which one to build.
Anthropic's Playbook for Running Human-Agent Teams
Anthropic published how its own teams actually work with Claude agents — and the four lessons are management skills, not prompting tricks. Here's the playbook, plus how I'd apply it as an EM without a fleet of agents.