Subagents: when to split the work

This guide is for people who already run Claude Code every day and notice long sessions getting slow, expensive or confused. You will learn when to hand a job to a subagent and when to keep it in the main conversation, and you will build one custom subagent that runs your tests and reports only the failures.

What you will have at the end

A clear rule of thumb for when a subagent helps and when it only adds overhead.
A working test-runner subagent in your project, checked into git.
The three ways to call a subagent, from a hint to a guarantee.
A short list of frontmatter keys worth knowing, and the ones to leave alone.

Before you start

Claude Code installed and signed in. Run claude --version to see what you have (costs page).
A project with a test command, such as npm test or pytest.
About 15 minutes.

Step 1: understand what a subagent buys you

A subagent is a separate Claude worker with its own context window, its own system prompt, its own tool list and its own permissions (sub-agents docs). It does a job, then hands back a summary. Everything it read along the way stays in its own window.

That is the whole point. The docs put it plainly: use one "when a side task would flood your main conversation with search results, logs, or file contents you won't reference again" (sub-agents docs).

Good fits:

Running a test suite and reporting only what failed.
Searching a large codebase for every caller of a function.
Reading long log files to find one error.
Researching several independent modules in parallel.

Keep the work in the main conversation when the task needs a lot of back and forth, when planning, coding and testing share a lot of context, when the change is small, or when speed matters, because a fresh subagent has to gather context first (sub-agents docs).

One more thing to know: subagents are not free. Each one sends its own requests, and those count toward the same usage limits as your main session (sub-agents docs). They save context, not tokens.

Step 2: meet the built-in ones

You already use subagents without asking. Claude Code ships with built-in ones and picks them automatically (sub-agents docs):

Explore: read-only, for finding files and searching code. Claude asks it to work at a thoroughness level of quick, medium or very thorough.
Plan: read-only research used during plan mode, so the main conversation stays read-only while it gathers context.
General-purpose: for multi-step tasks that need both exploring and changing code.

Explore and Plan start without your CLAUDE.md files and the git status snapshot, which keeps research fast and cheap (sub-agents docs). If you want exploration on a cheaper model, you can define your own subagent named Explore with model: haiku, and it overrides the built-in one.

So before you write a custom subagent, ask yourself: would Explore already do this? For pure searching, it usually does.

Step 3: write your first custom subagent

Write a custom subagent when you keep asking for the same kind of worker with the same instructions. A subagent is a Markdown file with YAML frontmatter, and the body becomes its system prompt (sub-agents docs).

Create .claude/agents/test-runner.md in your project:

---
name: test-runner
description: Runs the test suite and reports only failing tests with their error messages. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
---

You run this project's tests and report back briefly.

1. Find the test command in package.json, Makefile or the README.
2. Run it once.
3. Report only the failing tests: file, test name, and the first useful lines of the error.
4. If everything passes, say so in one line.

Never edit files. Never rerun the suite more than twice.

What each line does:

name and description are the only required fields. Claude reads the description to decide when to delegate, so say when to use it. Adding a phrase like "use proactively" encourages Claude to delegate on its own (sub-agents docs).
tools limits what the subagent can do. Leave it out and the subagent inherits every tool available to subagents.
model accepts sonnet, opus, haiku, fable, a full model ID, or inherit (frontmatter reference). Haiku is fine for reading test output.

Field names are case sensitive camelCase, and Claude Code silently ignores a field it does not recognise (frontmatter reference). A typo will not error, it will just do nothing.

Where you save the file decides who gets it. .claude/agents/ is this project, and you can commit it for the team. ~/.claude/agents/ is every project on your machine. When two share a name, the project one wins (scope table).

You can also skip the typing and ask Claude to write the file for you: describe the agent, where to save it, which tools and which model.

Step 4: call it

There are three ways, from loosest to strictest (invoke explicitly):

Name it in plain language. Claude decides whether to delegate.
```
Use the test-runner subagent to fix failing tests
```
@-mention it. Type @ and pick it from the list. This guarantees that subagent runs for this task.
```
@"test-runner (agent)" run the suite after my last change
```
Run the whole session as that agent with the --agent flag or the agent setting.

For most days, the first two are all you need.

Step 5: know the keys worth reaching for

The frontmatter reference lists many fields (frontmatter reference). These are the useful ones for a builder:

disallowedTools: remove tools from the inherited list instead of listing every allowed one.
effort: run this subagent at its own effort level, from low to max, depending on the model.
maxTurns: stop the subagent after a set number of turns.
skills: preload specific skills into the subagent at startup.
isolation: worktree: give the subagent its own temporary git worktree, cleaned up automatically if it changes nothing.
omitClaudeMd: true: start it without your user, project and local CLAUDE.md files, for agents that get everything they need from the prompt.

A note on models. Leave CLAUDE_CODE_SUBAGENT_MODEL unset unless you need it. It is only a default under each subagent's own model field, and paired with CLAUDE_CODE_SUBAGENT_MODEL_FORCE it overrides every subagent at once (run every subagent on one model). Setting the model per agent is easier to reason about.

Current numbers (checked 2026-11-06)

Startup warning when your custom subagent descriptions together pass 15,000 tokens (sub-agents docs).

Default concurrent limit: 20 running subagents per session (concurrent limit).

Default nesting: up to three layers below the main conversation (nesting).

skills preloads the first 32 distinct names in the list (sub-agents docs).

Check it worked

Start a session in your project and type:

Use the test-runner subagent to run the tests

In the transcript you should see a tool call row with the subagent's name and a short task, in the form test-runner(Run the tests) (quickstart). The reply in your main conversation should be a short list of failures, or one line saying everything passed. The full test log stays inside the subagent.

Run /usage afterwards if you want to see how the session's tokens were spent (costs page).

Common problems

Claude does not find the new subagent. If .claude/agents/ or ~/.claude/agents/ did not exist when the session started, restart Claude Code. A running session only watches directories that already existed (write subagent files).

A field seems to have no effect. Check the spelling and the camelCase. Unknown fields are ignored without an error. Running claude --debug and searching the debug log for does not recognize or apply names the unknown fields (frontmatter reference).

Claude never delegates on its own. Make the description say when to use it, and include "use proactively". Or @-mention the agent.

The main context still fills up. Running many subagents that each return long results can still eat context (common patterns). Tell each one to report briefly, as the test runner prompt above does.

Usage climbs faster than expected. Every subagent spends tokens of its own. Pick a smaller model for simple agents (costs page). Also note that subagents get a five-minute prompt cache by default, even on a subscription (prompt caching).

Spend less without getting worse results: where subagents fit in a lean session.
The multi-agent orchestration playbook: a full .claude/ pack with several agents working together.

Sources

Last checked: 2026-11-06