Claude Code Subagents: What They Do and When to Use Them

Short answer: a subagent is a separate context that Claude Code delegates work to, with its own system prompt, its own tool permissions and optionally its own model. Anthropic’s documentation lists five reasons to use them: preserving context by keeping exploration and implementation out of your main conversation, enforcing constraints by limiting which tools a subagent can use, reusing configurations across projects, specialising behaviour with focused system prompts, and controlling costs by routing tasks to faster, cheaper models. The first and the last are the ones that change your day-to-day experience most.

The Context Problem They Solve

Every message in a Claude Code session carries the whole conversation with it. Read forty files while hunting for something, and those forty files stay in context for the rest of the session, competing with the work you actually care about.

That produces two visible symptoms. Long sessions get slower and more expensive, because the cost driver is the context window rather than the number of messages. And quality degrades, because the signal you need is buried under exploration output that was only relevant for five minutes.

A subagent fixes this structurally. The delegated work happens in its own context and only the result comes back. Twelve files read during a search cost you one summary in the main conversation rather than twelve files of noise.

This is why the built-in exploration agents exist and why they are the ones you will use most, often without noticing.

The Built-In Subagents

Anthropic documents several types that ship with Claude Code, and knowing what each is constrained to explains a lot of otherwise puzzling behaviour.

Two details in that table are worth pausing on.

The Explore agent is capped at Opus on the Claude API, which Anthropic explains is so that Explore never runs on a more expensive model than the one you already chose for the session. That is a deliberate cost guard, and it means searching your codebase does not quietly cost frontier-model rates.

Explore and Plan are both read-only, with Write and Edit denied. That is what makes delegation safe: you can send an agent to investigate without any possibility that it starts editing while it is in there.

Writing Your Own

A custom subagent is a Markdown file with frontmatter. The structure is small enough to memorise.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---
You are a code improvement specialist. For each issue you find, explain the problem, show the current code, and provide an improved version.

Four fields do all the work. name is how it is invoked. description is what Claude reads when deciding whether to delegate, which makes it the most important line in the file. tools restricts what it may do. model picks the tier.

The description deserves more care than people give it. Claude uses it to decide when this agent applies, so a vague description produces an agent that never gets used or gets used for the wrong things. Include the trigger condition explicitly, as in the example above with “Use after writing or modifying code”.

The fastest way to create one is to ask Claude Code to write it. Describe what you want, where it should live and what it should be allowed to do, then review the generated file before using it.

Where subagent definitions live

Anthropic documents five locations with a defined precedence order, and knowing it prevents a common confusion where an agent behaves differently from the file you are looking at.

1. Managed settings, deployed centrally, organisation-wide. Highest priority.
2. The --agents CLI flag, which takes JSON and applies to the current session.
3. .claude/agents/, scoped to the current project.
4. ~/.claude/agents/, available across all your projects.
5. A plugin’s agents/ directory, wherever that plugin is enabled. Lowest priority.

The practical rule: project-level definitions override your personal ones, and anything your organisation deploys through managed settings overrides both.

The --agents flag is underused and useful for one-off work. You pass a JSON object defining agents inline when launching Claude Code, which is convenient for a task where you want a specialist configuration once without leaving a file behind.

What to Know Before You Build a Fleet of Them

Delegation costs a round trip. A subagent has to be spawned, given context, and its result returned. For a task the main conversation would finish in two steps, that overhead is a loss. Delegation pays off when the work would otherwise dump a lot of material into your main context.

The subagent cannot see your conversation. It starts fresh with whatever you pass it. A brief that assumes shared context produces an agent working on the wrong problem, and this is the single most common failure.

Tool restrictions are the point, not a limitation. A read-only reviewer that cannot edit is more useful than an unrestricted one, because you can run it without checking what it touched.

Cheaper models are often correct. Anthropic lists routing tasks to faster, cheaper models like Haiku as one of the five reasons to use subagents. At $1 per million input tokens against $5 for Opus 5, a mechanical task delegated to Haiku is a real saving with no quality cost.

You can turn them off. To block one built-in type, add it to permissions.deny. To stop delegation entirely, deny the Agent tool itself. To remove Explore and Plan specifically, set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1, which requires Claude Code v2.1.198 or later and makes Claude read files directly instead. In non-interactive mode and the Agent SDK, CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 removes all built-in types so only your own remain.

A Decision Framework: Delegate or Not

Run a task through these five questions before writing an agent for it.

1. Will this generate a lot of output I do not need afterwards? Searching, exploring, reading many files, scanning logs. If yes, delegate; this is the strongest case.
2. Should this be prevented from writing? Review, audit, analysis and investigation all benefit from a read-only agent, and the restriction is the value.
3. Is it mechanical enough for a cheaper model? Formatting, mechanical refactors, straightforward lookups. Route to Haiku and keep your main session on the model you actually need.
4. Will I do this more than a few times? A one-off does not justify a definition file. Something you do weekly does, and the reuse compounds.
5. Can I brief it without my conversation history? If the task only makes sense given three hours of context you have built up, delegation will disappoint you. Restructure the brief or keep it in the main thread.

Three or more yes answers means write the agent. Fewer means do it inline.

Common mistakes right now

• Writing a vague description, so Claude never delegates to the agent or delegates the wrong work.
• Giving every custom agent every tool, which discards the main safety benefit.
• Delegating something small, where the round-trip overhead exceeds the saving.
• Assuming the subagent can see the conversation, and briefing it as if it can.
• Building a large library of agents before establishing that any of them get used.

Three agents worth writing first

If you want concrete starting points rather than principles, these three earn their keep in most codebases and take a few minutes each.

A read-only reviewer. Tools limited to Read, Grep and Glob, model set to Sonnet, with a system prompt that says to report problems with the current code and a suggested replacement rather than making changes. Because it cannot edit, you can run it on anything without checking afterwards what it touched.

A test-failure investigator. Give it the ability to run tests and read files, and a prompt telling it to find the root cause and report it rather than to fix anything. The separation matters: an agent that diagnoses and reports lets you decide whether the fix is worth making, while one that diagnoses and fixes commits you to its first theory.

A documentation checker on Haiku. Mechanical work comparing what the docs claim against what the code does. This is exactly the profile for a cheaper model: high volume, low judgement, easily verified output.

Notice that two of the three are read-only and the third is on the cheapest model. That ratio is not accidental. The agents that get used are the ones that are safe to run without supervision or cheap enough to run often.

Where This Fits in a Larger Workflow

Subagents pair naturally with plan mode. Investigate in a read-only agent, bring back a summary, plan against that summary in the main conversation, then execute. The exploration never enters your main context and the plan is built on a clean digest rather than on forty files of raw output.

They also change how long sessions behave. The practical effect of routing exploration away is that a session stays usable for far longer before context pressure degrades it, which for anyone working through a large task is worth more than the token saving.

Building the Judgement Behind the Configuration

The mechanics on this page take twenty minutes to learn. What takes longer is knowing which work to delegate, how to brief an agent so its output is usable, and when a restriction improves a result rather than limiting it.

That is the same judgement that applies to every agentic tool: decomposing a task into pieces that can be done independently, specifying each so the output is checkable, and designing the review step that catches what goes wrong. Learning it in a structured sequence rather than by trial and error produces a method that transfers when the tooling changes, which in this field it reliably does. If you want a structured route in, explore Coursiv AI lessons and check current plan details on the official site.

FAQ

Your Next Step

Take the investigation you run most often, the one where you end up reading a dozen files to answer a recurring question, and write a read-only agent for it with tools: Read, Grep, Glob and a description that names when it should be used. Run it once and compare how your main conversation looks afterwards against a session where you did the same search inline. That single comparison makes the case for delegation better than any explanation of the mechanism.