Ask Claude Code to run a test suite or search a large codebase and your conversation fills with logs and file contents you will never look at again. Every one of those lines stays in context and costs you for the rest of the session. Subagents are how you keep that noise somewhere else.
What a subagent is
A subagent is a helper that Claude starts to do one task. It gets its own context window, its own system prompt and its own set of tools. Claude writes it a short brief, the subagent does the work, and only its final report comes back to your conversation. The searches, the test output and the files it read stay in its own context.
That design has three consequences:
- A subagent doesn't see your conversation. It starts from the brief Claude writes, plus your CLAUDE.md files and a git status snapshot.
- It can have fewer tools than the main session. A reviewer that can only read files can't edit them by accident.
- It isn't free. Its requests count towards the same usage limits as your main conversation, and every result it returns lands in your context.
The ones you already have
Claude Code ships with built-in subagents and uses them without being asked:
| Subagent | What it does | Tools |
|---|---|---|
| Explore | Searches and reads a codebase | Read-only |
| Plan | Researches the code while you're in plan mode | Read-only |
| general-purpose | Multi-step tasks that need to search and change things | All tools available to subagents |
Claude delegates to Explore when it needs to search or understand code without changing it. Explore and Plan skip your CLAUDE.md files and the git status snapshot to stay fast and cheap.
When to use one
The docs give a short rule.
| Use a subagent when | Stay in the main conversation when |
|---|---|
| The task produces output you don't need to keep | You're going back and forth to refine something |
| You want to limit which tools can run | Planning, building and testing share a lot of context |
| The work is self-contained and can end in a summary | It's a quick, targeted change |
| You need the answer fast |
A subagent starts with no memory of what you've discussed, so it spends time gathering context the main session already has. For a two-line fix, delegating is slower and costs more.
Three prompts that work well:
Use a subagent to run the test suite and report only the failing tests with their error messages
Research the authentication, database and API modules in parallel using separate subagents
Use the code-reviewer subagent to find performance issues, then fix them in the main conversationParallel research only pays off when the parts don't depend on each other. Each subagent's report comes back into your context, so five detailed reports can cost more than the work they saved.
Write your own
A custom subagent is a Markdown file with YAML frontmatter. The body becomes its system prompt. Save this as .claude/agents/test-runner.md in a project, or in ~/.claude/agents/ to use it everywhere:
---
name: test-runner
description: Runs the test suite and reports failures. Use proactively after code changes or when the user asks whether tests pass.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You run tests and report results. You do not edit files.
1. Find the test command in package.json, Makefile or the README.
2. Run it once.
3. Report each failing test with its file, the assertion and the first
lines of the error. Skip passing tests.
4. If everything passes, say so in one line.Only name and description are required. If you leave out tools, the subagent gets every tool available to subagents. If you leave out model, it normally runs on the main conversation's model.
Claude Code watches both agents folders and picks up a new or edited file within a few seconds. The exception is the first agent in a folder that didn't exist when the session started: restart Claude Code for that one.
Since v2.1.198, /agents no longer opens a creation wizard. It prints a reminder to write the file yourself or ask Claude to write it.
Fields worth knowing
| Field | What it does |
|---|---|
tools |
The tools the subagent may use. Omit it to inherit them all |
disallowedTools |
Tools to remove from the inherited or listed set |
model |
sonnet, opus, haiku, a full model ID, or inherit |
permissionMode |
Such as plan for read-only or acceptEdits |
isolation |
worktree runs it in a temporary git worktree, removed if nothing changed |
skills |
Skills whose full text is loaded into the subagent at start |
maxTurns |
Stops the subagent after that many turns |
Field names are camelCase and must match exactly. Claude Code ignores a misspelled field without reporting an error. If a setting seems to do nothing, check the spelling first.
Calling a subagent by name
Claude chooses subagents by matching your request against each description, the same way it picks skills. Write the description as a trigger: what the agent does and when to use it. Phrases like "use proactively" make Claude reach for it without being asked.
You can also choose for it:
- Name it in your prompt: "Use the test-runner subagent to check this."
- Type
@and pick it from the list, which guarantees that subagent runs. - Start the whole session as that agent with
claude --agent test-runner.
By default, subagents Claude starts from your main conversation run in the background, so you can keep working while they run. A permission prompt from a background subagent appears in your main session with the subagent's name on it.
How I use them
I keep 80 agent definitions in ~/.claude/agents/, but my rules tell Claude to delegate only when a trigger condition is met. A trivial rename or single-file edit doesn't get an agent. One I do use is silent-failure-hunter, which looks for swallowed errors after error-handling code changes. Its frontmatter is tools: Read, Grep, Glob, so it can report problems but can't change anything. When a job splits into independent parts, my rules send each part to a parallel agent on Sonnet and keep Opus for the parts that are hard.
If a subagent must follow a rule that isn't in CLAUDE.md, put the rule in your request, because the subagent can't see what you said ten messages ago.
Questions
Can subagents start their own subagents?
Yes. A subagent can spawn its own, up to three layers below the main conversation by default. The CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH environment variable changes the limit, and setting it to 1 turns nesting off.
What's the difference between a subagent and a skill?
A skill is a set of instructions that runs inside your main conversation and sees everything in it. A subagent runs in a separate context and returns only a summary. Use a skill for a repeatable procedure and a subagent for work whose output you don't want in your context.
Does a subagent read my CLAUDE.md?
Custom subagents and general-purpose do, along with a git status snapshot. Explore and Plan don't. Your conversation history and auto memory never reach a subagent, so restate anything it needs in your request.
Sources
- Claude Code docs: Create custom subagents
- Claude Code CLI reference,
claude --helpon v2.1.306