Claude Code Subagents: What They Are and How to Use Them

What a subagent actually is

When Claude Code hits a job that would flood the main conversation with output, it hands that job to a subagent: a separate Claude instance with its own fresh context window, model, and a restricted set of tools. It does the work and returns a short result. The ten-thousand-line log file it just read never enters your context — only the three lines that mattered do.

Be precise about what isolation means. A subagent does not inherit your conversation history or the files Claude has already read — it starts fresh. Its opening context is a deliberately small bundle: its own system prompt (the config instructions, not the full Claude Code system prompt), the delegation message that launched it, your CLAUDE.md project memory, a git status snapshot, and any skills you attached. Only its final summary crosses back; the raw results and fetched pages stay behind.

That one-way valve keeps the main conversation small, which keeps it faster and cheaper, because every message in Claude Code re-sends the full conversation. A turn is priced on the whole transcript, not just your latest instruction, so a context bloated with log output costs more on every subsequent turn — the same logic behind prompt caching and context hygiene. One exception: a fork inherits the full conversation instead of starting clean, where a named subagent starts clean.

When to reach for a subagent

Subagents earn their place when an operation is verbose, repetitive, or exploratory — work whose output you do not need in full, only its conclusion.

The pattern: delegate the high-volume step, keep the decision in the main session. If you find yourself scrolling past tool output you will never read, that work belonged in a subagent — and if you need the full output in front of you to decide, keep it in the main thread.

How to configure one

A subagent is a small Markdown file: YAML frontmatter on top, a system prompt in the body. Only name and description are required; the description is what Claude Code matches to decide when to invoke it, so make it specific. Two optional fields, tools and model, are where the real control lives.

---
name: test-runner
description: Runs the test suite and returns only failing cases. Use proactively after code changes.
model: haiku
tools: Bash, Read
---
Run the project's tests. Report only failing cases and the first
error line for each. Do not print passing output.

The fields that matter:

Where you put the file decides who gets it. A file in .claude/agents/ belongs to the project and travels in version control, so the whole team inherits it; one in ~/.claude/agents/ is personal and follows you across projects. When names collide the more specific scope wins, and organisation-managed settings override both — the hook a platform team uses to standardise across a fleet.

Claude Code invokes a subagent automatically, when your request matches its description closely enough — which is why a tight, task-specific description beats a clever name — or explicitly, when you name or @-mention it. Run /agents to view and edit them, or claude --agent <name> to run a whole session as one.

Setting model explicitly is not housekeeping — it is the cost control. A test-runner left on Opus costs roughly 40x a Haiku one for the same output and does the job no better. Claude Code resolves it in order — a per-invocation override, the frontmatter model, the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then your session’s model — so an unset model means the subagent runs on whatever you are running. For which model fits which task, see Opus vs Sonnet vs Haiku: a cost-vs-capability routing guide.

Four subagent patterns worth copying

Most useful subagents fall into four shapes, each with a clear right model:

• Test runner (Haiku). Runs the suite, returns only the failing cases and first error line each. Needs Bash and Read — high volume, zero reasoning, the textbook Haiku job.
• Code reviewer (Sonnet). Reads a diff and flags quality, security and correctness issues. Give it Read, Glob and Grep but not write access — it cannot change code while it reviews.
• Doc fetcher (Haiku or Sonnet). Pulls documentation or API references and returns the two paragraphs that answer the question. The full pages are noise; keeping them out of the main thread is the value.
• Migration worker (Sonnet). Applies a mechanical change across many files — a dependency bump, an import rewrite, a framework upgrade. You want the summary of what changed and what broke, not every hunk.

---
name: code-reviewer
description: Reviews a diff for quality, security and correctness. Use after code changes.
model: sonnet
tools: Read, Glob, Grep
---
You are a code reviewer. Flag concrete, actionable issues only —
security, correctness, and maintainability. Cite file and line.
Do not restate what the code does. Do not edit anything.

The shape repeats: a narrow toolset, an explicit model, and a prompt that says what not to return as much as what to return.

Subagents, skills and MCP — which is which

Subagents are one of three ways to extend Claude Code, and they are easy to confuse. A subagent is a separate context that does work and reports back; a skill is a packaged instruction set that loads into the current context on demand; an MCP server is an external tool or data source Claude calls.

The rule: reach for a subagent when the problem is volume or isolation, a skill when it is repeatable know-how, MCP when it is access to a system. They stack — a migration subagent can load a skill and call an MCP server inside its own context. For the governance angle, see tool vs skill vs subagent governance and Claude Skills.

Foreground, background, and agent teams

A subagent can run in the foreground — you wait for it — or in the background while you keep working. Either way, one with no model set inherits your session’s model — the quiet route by which an Opus session turns every subagent into an Opus subagent. Set it on the ones that do not need one.

Agent teams go further: several Claude Code instances in parallel, each with its own context window. They are powerful for genuinely parallel work but the most expensive thing you can do — in plan mode a team burns roughly 7x the tokens of a standard session, because every teammate maintains and re-sends a full context of its own. Keep teams small, keep each task self-contained, and shut them down when the work is done. This is also where governance matters most (tool vs skill vs subagent governance).

Want to see subagent and agent-team spend per developer, not buried in one invoice?

TrueFoundry AI Gateway

What subagents cost

A subagent’s requests draw on your usage just like the main conversation — isolation saves tokens on the main thread, it does not make the subagent free. The saving comes from two places: a cheaper model than your session would use, and verbose output that never gets re-sent on every turn.

The model gap is large: from published API rates, Haiku is an order of magnitude cheaper per token than Sonnet, which is itself a fraction of Opus on output — so the same test-runner job can differ by 40x on one line of config. Prompt caching compounds it: a subagent’s cached system prompt and project memory read at roughly a tenth of fresh-input cost (the prompt-caching cost math). For a fleet, the missing piece is visibility, which a gateway adds (cost tracking for Claude Code).

A worked example

A backend team keeps a main session on Sonnet and adds three subagents: a test-runner and a log-triage on Haiku, and a codebase-explorer on Sonnet. The main session stays lean — it asks the test-runner to run the suite, gets back only the four failures, and fixes them. Spend drops because the noisy work runs on Haiku and the main context never balloons. The configs live in .claude/agents/, committed to the repo, so every engineer inherits them.

The honest limit: subagents keep your context clean but do not govern themselves. Which models they reach, what they spend, and which tools they touch are fleet decisions that live at the gateway, not in a config on a laptop (Claude Code governance with an AI gateway).

Governing and attributing subagent spend

A subagent config is a per-developer setting. Nothing in .claude/agents/ stops an engineer pointing a subagent at Opus or spawning a five-member team. On one laptop that is fine; across a hundred engineers it is an ungoverned, unattributed line item — and because each runs its own context, their token volume is the part of the bill that grows fastest and explains itself least.

Native billing does not resolve this. When Claude Code runs against a raw API key, or on a cloud provider such as Amazon Bedrock, Google Vertex or Microsoft Foundry, spend is billed per token to your cloud account and Anthropic’s dashboards do not cover it — so usage lands in one aggregate with no per-developer breakdown. Attribution has to come from elsewhere: OpenTelemetry instrumentation or an LLM gateway in front of every request.

Routing Claude Code through the TrueFoundry AI Gateway puts one control plane in that path. Every request — main session, subagent, or teammate — resolves to a developer and a key, so spend shows up attributed rather than lumped. You set which models are reachable (Haiku and Sonnet for subagents, Opus for approved cases), apply per-developer and per-team spend limits, and meter usage across providers in one view. The gateway adds only a few milliseconds per call and is OpenTelemetry-compliant, so governance costs no latency (centralising cost control and observability for AI coding IDEs).

Gotchas worth knowing

• An unset model is an inherited model. A subagent with no model runs on your session’s — an expensive surprise on an Opus session. Set it, or pin a default with CLAUDE_CODE_SUBAGENT_MODEL.
• Agent teams are ~7x tokens. Treat them as a deliberate choice for parallel work, not a default.
• Spawn prompts are context. Everything in the prompt loads into the teammate from the start, on top of CLAUDE.md, skills and MCP servers — so keep it tight.
• Give each subagent only the tools it needs. A test-runner does not need write access; least-privilege tools limit both blast radius and context size.
• A vague description never fires — or fires everywhere. Auto-delegation keys off the description, so write it like a routing rule.
• Subagents are not free. Their requests count against your usage; isolation saves the main thread, not the subagent itself.

Related reading

• Tool vs Skill vs Subagent Governance — where each one belongs, and how to govern it
• Cost Tracking Claude Code with the TrueFoundry AI Gateway — attribution for subagents and teams
• Opus vs Sonnet vs Haiku: a Cost-vs-Capability Routing Guide — which model for which subagent
• Claude Code Governance with an AI Gateway — controlling models, tools and spend at fleet scale
• Claude Skills — the other way to give Claude Code focused capability

Conclusion

Claude Code subagents are a simple idea with an outsized effect: hand the noisy work to a second instance, keep the decision in the main thread, and your session stays fast and cheap. The one setting that decides whether they save money or quietly cost it is the model — set it on every subagent, and reserve Opus and teams for work that earns them.

That is the individual-developer story. The fleet story is governance: which models subagents may reach, what they can spend, which tools they can touch — decisions that belong at the gateway, not in a config on each laptop.

Put your coding agents, subagents and all — behind one control and cost plane.

Book a demo