# 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 `. ## 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. ```markdown --- 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, Glob` makes 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: haiku` is 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. **Question:** Why give a review subagent only Read, Grep and Glob? - Those are the fastest tools - The harness enforces it, so it cannot edit even by mistake - Subagents cannot use any other tools - It makes the summary shorter **Answer:** The harness enforces it, so it cannot edit even by mistake. A tool limit in frontmatter is enforced by the harness. Writing 'do not edit' in the prompt would only ask the model to behave. ## 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. > **Subagents can have subagents** By default they nest three layers deep, and 20 can run at the same time. There is no cap on the total number in a session, so a loose prompt can start far more work than you intended. ## 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 ` spawns a forked background subagent, and `Ctrl+B` sends a running task to the background. `/tasks` manages them. > **Silent typos** Misspelled frontmatter fields are ignored without a message, and a file with no `name` is treated as documentation and skipped. If a subagent behaves as though a setting is missing, run `claude --debug` and search the output for "does not recognize or apply". **Question:** When is a subagent the wrong choice? - Reading hundreds of lines of logs for one cause - A three-line edit you could just make - Searching a large codebase for call sites - Reviewing a diff with limited tools **Answer:** A three-line edit you could just make. Delegating has a cost: a fresh context and a summary back. For a tiny edit that cost is larger than the work.