Claude Code Subagents: When to Split the Work (and When Not To)

A long Claude Code session slowly fills up with things you'll never need again: three hundred lines of test output, the contents of fifteen files it read while looking for one function, a log file it skimmed for an error. All of it stays in the conversation, gets sent with every later message, and crowds out the things that matter.

Subagents are the fix for that specific problem. A subagent is a separate Claude instance with its own, fresh context window. The main session hands it a task, the subagent does the noisy work, and only a short summary comes back.

This guide covers how they work, how to write one, and — just as important — when not to bother.

Details reflect Claude Code as of September 2026. See Anthropic's subagents documentation for the full set of options.

What a subagent actually is

When Claude delegates to a subagent, the subagent starts with:

Its own system prompt — the instructions in the subagent's definition.
The task Claude wrote for it — a delegation message, not your whole conversation.
Your project's CLAUDE.md, a git status snapshot, and any skills it's configured to preload.

It does not get the main conversation's history. It works through the task — reading files, running commands — and returns a summary. Everything it read and ran stays in its context, not yours.

That isolation is the whole point, and also the main trade-off. The subagent is efficient because it doesn't carry your conversation. It can also miss things because it doesn't carry your conversation.

The built-in subagents

Claude Code ships with a few, and uses them on its own:

Subagent	Can edit files?	Used for
Explore	No — read-only	Searching and understanding a codebase
Plan	No — read-only	Gathering context while in plan mode
General-purpose	Yes	Multi-step research or changes

When you ask "where do we handle password resets?", Claude will often send Explore to search, and you see a summary rather than every file it opened.

Writing your own

A custom subagent is a Markdown file with a short header. Put project subagents in .claude/agents/ (commit them so your team shares them) and personal ones in ~/.claude/agents/.

.claude/agents/test-runner.md:

---
name: test-runner
description: Runs the test suite and reports failures. Use after code changes, or when asked to check whether tests pass.
tools: Bash, Read, Grep, Glob
model: haiku
---

Run the project's tests with `npm test`. If everything passes, say so in one line.

If anything fails, report for each failure: the test name, the file and line,
the assertion that failed, and the most likely cause in one sentence.
Do not paste full output. Do not modify any files.

The fields that matter most:

description — how Claude decides when to use it. Write it as "Use when…", like the example. A vague description means the subagent never gets picked, or gets picked for the wrong things.
tools — what it's allowed to do. Leave it out and it inherits everything. Restricting tools is how you make a reviewer that can't edit, or a researcher that can't run commands.
model — which model it runs on. A mechanical job like running tests doesn't need your most capable (and most expensive) model; haiku or sonnet is often plenty.

There are more options — a turn limit, a permission mode, scoped hooks and MCP servers, even running in its own git worktree — but those three do most of the work. The /agents command shows what's configured.

To make sure a particular subagent runs, name it: "Use the test-runner agent to check the auth changes," or @-mention it.

Where subagents earn their keep

The docs are clear about the pattern: delegate work that produces a lot of output and a small answer.

Running tests. Hundreds of lines of output; the answer is "two failures, here's why." This is the best use case there is.

Searching an unfamiliar codebase. Reading twenty files to find how authentication flows. The main session needs the map, not the twenty files.

Reading logs. A 10,000-line log boiled down to the three errors that matter.

Fetching documentation. Pulling a library's docs and extracting the one API you need.

Focused review. A security-review subagent with read-only tools, a checklist in its prompt, and no ability to "helpfully" fix what it finds. The constraint makes it a better reviewer.

Parallel independent research. Two or three subagents looking into separate questions at once, each returning a summary.

In each case the main conversation stays small, which keeps it focused and makes every later message cheaper.

Where they don't help

Tasks that need the conversation. If the last hour established that you're avoiding a particular library and the database schema is changing next week, a subagent doesn't know that. It'll cheerfully suggest the library. Work that depends on nuance you've built up belongs in the main session.

Back-and-forth work. Anything where you'll refine the result through several rounds. Each round through a subagent loses the thread.

Small, quick changes. Delegation has overhead: the subagent has to rediscover context the main session already has. For a two-line fix, it's slower and costs more.

Coordinated edits across files. Two subagents editing related code in parallel, each unaware of the other, is a reliable way to get conflicting changes.

The cost picture

Subagents are sometimes described as a way to save money. It's more precise to say they move tokens around. The subagent still reads the files and still processes the test output — it's just done in a separate context that's thrown away afterwards, instead of being carried by every later message in your main session.

That's a real saving in long sessions, because it's the repeated carrying of old context that makes long sessions expensive. It's not a saving for short ones. And running several subagents in parallel multiplies usage by roughly the number running. Our guide to keeping Claude Code costs down covers the wider picture.

One thing checkpoints won't undo

A practical detail worth knowing: Claude Code's checkpoints — the /rewind feature — track edits made in your own session. Edits made by most subagents aren't restored by rewinding; you'd revert them with git. That's one more reason to commit before handing a subagent anything that writes files. (More on this in Claude Code Checkpoints.)

A starting set

For most projects, two custom subagents cover the common cases:

A test runner — like the example above: runs tests, reports failures concisely, can't edit.
A reviewer — read-only tools, your project's review checklist in the prompt, told to report findings rather than fix them.

Commit both to .claude/agents/. Add others only when you notice yourself repeatedly doing a noisy task in the main session.

The short version

A subagent is a fresh context window that returns a summary.
Use one when a job produces lots of output and a small answer.
Keep work that depends on the conversation in the main session.
Restrict tools to make subagents safer and more focused, and pick a cheaper model for mechanical jobs.

Used that way, subagents keep your main session sharp for the part of the work that needs judgement — which is the part you actually want Claude's full attention on.

EasySpawn runs Claude Code in a persistent cloud workspace with the resources for parallel work — subagents, test runs, and dev servers side by side — reachable from any device. See how it works or join the waitlist.