Subagents keep the mess out of your session
A subagent works in its own context window and returns only a summary. That is the whole benefit, and it is also the whole limit, so it pays to know what comes back.
A second context window, on purpose
Suppose you ask Claude to find every place a deprecated function is called. It opens thirty files, reads long search results, and by the end your main session is full of material you will never need again.
A subagent takes that job elsewhere. It has its own context window, its own system prompt, its own tool set and its own permissions. It does the reading in there, and what returns to your session is a summary.
The thirty files stay in the subagent's context and are gone when it finishes. Your session receives the conclusion. This is the same budget problem the context lessons describe, solved by moving the spending to a place that gets thrown away.
What is built in
Claude Code ships with several. Explore is read-only search and skips CLAUDE.md and git status, which makes it light. Plan designs an approach. There is also a general-purpose agent, statusline-setup, claude-code-guide and a catch-all.
Claude chooses among them on its own. You can also force the choice by mentioning @agent-name, or run the whole session as one agent with --agent <name>.
Writing your own
A custom subagent is a markdown file with frontmatter, kept in .claude/agents/ for a project or ~/.claude/agents/ for yourself. Only name and description are required.
---
name: security-reviewer
description: Reviews a diff for security problems. Use after changes to auth, input handling or file access.
tools: Read, Grep, Glob
model: haiku
---
Review the changes for injection, unsafe file access and leaked secrets.
Report only real findings, each with a file and line. Skip style.
Keep the answer under twenty lines.Three choices in that file carry most of the value.
tools: Read, Grep, Globmakes the reviewer unable to edit anything. That limit is enforced by the harness. A sentence in the prompt saying "do not edit" would only be a request.model: haikuis enough for a lookup-style task and costs less. Model choice resolves in this order: the per-call parameter, the frontmatter,CLAUDE_CODE_SUBAGENT_MODEL, then the main model.- The last two lines of the prompt control what comes back. Ask for short summaries, and tell reviewers to skip style, or they will always find something.
Why give a review subagent only Read, Grep and Glob?
What comes back is the cost
The summary is all you get. If the subagent found the answer but wrote a vague report, the detail is gone with its context. This is why you decide what to ask for, such as file paths and line numbers, before it starts.
Treat the report as input, not as a command. Reports are scanned for instruction-like text, which is marked but never removed, so a file the subagent read could try to slip directions into what it hands back.
When one is worth it
Use a subagent when the work is large in tokens and small in conclusion: searching a codebase, reading logs, reviewing a diff. Skip it when you need to see the intermediate steps, or when the task is a three-line edit that costs more to delegate than to do.
For work that edits files, isolation: worktree gives the subagent a temporary git worktree, removed automatically if nothing changed. To run something in the background, /subtask <task> spawns a forked background subagent, and Ctrl+B sends a running task to the background. /tasks manages them.
When is a subagent the wrong choice?
Chapter complete
You've finished chapter 3 of 6 in Extending Claude Code.
MCP gives Claude tools that live outside your machine's built-ins. The setup is one command. The real decisions are which scope to use and whether a plain CLI would have done the job for free.
Next chapter