Delegate to a custom subagent

01The goal

Write a subagent restricted to the tools its task needs — read and search, nothing else — and delegate a review to it.

02The idea

A subagent is a separate Claude that your session hands a task to. It works in its own context window, from its own instructions, with only the tools you gave it, and returns a summary. Everything it read, searched and considered stays out of your conversation: the forty files a reviewer opens cost your window nothing.

A project subagent is a Markdown file in .claude/agents/: frontmatter with a name and a description — both required; Claude Code silently skips a file missing either — an optional tools list, then the instructions it works from. Claude reads the description to decide when to delegate; you can also name the subagent in your request outright. Without a tools line, the subagent inherits every tool available; with one, it gets exactly what you listed.

When to delegate, in one breath: when the output is what you need rather than the process, and when restricted tools are the point. Keep work in the main conversation when it needs back-and-forth, or when it is a quick, targeted change — spinning up a subagent to rename a variable is ceremony, not safety. This is our delivery board’s oldest rule at session scale: delegate with a purpose, and the reviewer role is the purpose that pays for itself daily.

03The walkthrough

1. 01Write .claude/agents/code-reviewer.md. The frontmatter: name: code-reviewer, tools: Read, Grep, Glob — it can read and search files and nothing else; no edits, no commands. The body: the instructions — review uncommitted changes, report findings grouped by severity, name the file and line for each, and change nothing.
2. 02Start claude — a fresh session, because Claude Code watches only the agent folders that existed when the session started. If you created .claude/agents/ mid-session, restart.
3. 03Make a small change in a source file, then ask: "Use the code-reviewer agent to review my uncommitted changes."
4. 04The transcript shows a row — code-reviewer(Review uncommitted changes) — while it works. It cannot run git diff, so it works from the task message your session writes for it and the git status snapshot Claude Code includes in its startup context; then its findings come back as one summary. Note what did not come back: every file it opened.

04Your turn

Build the read-only finder: .claude/agents/test-gaps.md, named test-gaps, with a description saying it finds exported functions no test calls, and tools that can read and search but never change anything or run a command. The body: list the functions each source file exports; search the test files for calls to each; report the untested ones grouped by file, one line on what a test for each should check — and say so plainly if everything has a test. Commit it, then ask in a session: "Use the test-gaps agent to list the functions no test calls." Watch the row appear, and the summary land.

Three edges. A subagent listing Bash can still change files through shell commands — a sed edit, a > redirect — so leave Bash out and let your session pass in what a command would have shown. A custom subagent reads your CLAUDE.md files like the main conversation does, but the built-in Explore and Plan subagents skip them — restate a rule in your request when Claude hands them work. And on macOS, Linux and WSL, where Glob and Grep are absent from the main conversation by default, a subagent that names them in its tools list gets them anyway — a small asymmetry worth knowing when you compose the list.