Claude Code Subagents: Build a Custom Code Reviewer

What Claude Code subagents are

Claude Code subagents are specialised assistants that the main Claude session can hand work to. Each one has its own system prompt, its own tool permissions and, importantly, its own context window. When a subagent finishes, only its summary comes back to the main conversation, so a long read-through of your codebase does not fill up your main context.

That makes them a good fit for jobs that are self-contained and output-heavy: reviewing a diff, searching a codebase, running tests, or checking documentation.

Where subagents live

A subagent is just a markdown file with a small block of settings at the top. Claude Code looks in two places:

• .claude/agents/ in your project, which you can commit so the whole team shares the same agents.
• ~/.claude/agents/ in your home directory, for personal agents available in every project.

You can create one interactively with the /agents command, or write the file yourself, which is easier to review and keep in git.

Build a read-only code reviewer

Create .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for bugs, security problems and readability. Use proactively after any significant code change.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When invoked:

1. Run `git diff` to see what changed.
2. Read the changed files and the code around them.
3. Report findings in three groups: must fix, should fix, and nitpicks.
4. For each finding, give the file, the line, what is wrong and a concrete fix.

Be specific and brief. Do not edit any files. If everything looks fine, say so plainly.

What each field does

• name is the identifier, lowercase with hyphens.
• description is how Claude decides when to delegate. Write it as a trigger: what the agent does and when to use it. Wording such as ‘use proactively’ encourages automatic delegation.
• tools limits what the agent can do. The reviewer above has no Edit or Write tool, so it physically cannot change your code. If you omit the field, the agent inherits every tool the main session has.
• model picks the model for this agent, for example sonnet, opus or haiku, or inherit to use the main session’s model. A cheaper, faster model is often enough for review and search work.

Using the agent

Two ways to run it. Claude can delegate automatically when your request matches the description, or you can ask directly:

Use the code-reviewer subagent to check my latest changes

Run /agents to see which agents Claude Code has loaded, and to confirm yours was picked up. If you add the file while a session is open, restart the session or use /agents to refresh.

Tips for good subagents

• Give each agent one job. A reviewer, a test runner and a docs checker work better as three agents than one ‘do everything’ agent.
• Grant the minimum tools. Read-only agents are safer to run on autopilot.
• Put the output format in the prompt. The main session only sees the summary, so tell the agent exactly what to report.
• Keep project agents in git so changes to them go through review like any other code.

Chain agents together

Once the reviewer works, add a second agent for tests. A test-runner agent with Read, Edit, Write and Bash can write and run tests, then report only the failures. Ask Claude to implement a change, have the test-runner agent cover it, then have the code-reviewer check the result. Each agent works in its own context window, so the main conversation stays short.

Remember that subagents cannot start further subagents, so the main session stays in charge of the sequence.

Once a reviewer is working, the natural next step is to chain agents together, for example a test writer followed by a reviewer, which is the pattern covered in the post on the subagent-driven development skill.