Code Reviewer subagent

The code-reviewer subagent is a short Markdown file from Claude Code's documentation. Drop it in .claude/agents/ and Claude gets a specialist that reads your latest git diff, checks it against a review list and reports findings in three priority groups, all inside its own context window. The docs call it read-only, but it keeps the Bash tool, so read the safety section. We checked the docs on 31 October 2026.

Quick facts

This is not a package or a plugin. It is about 30 lines of text you can read in a minute. The value is in how it is built, and what you change for your team.

The file, in full

This is the example from Claude Code's docs.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

How the file works, line by line

The frontmatter

The description does the routing. Claude's docs say "Claude uses each subagent's description to decide when to delegate tasks". The words "Proactively" and "Use immediately after writing or modifying code" invite automatic delegation. If you do not want a review after every small edit, change the description to something like "Use when the user asks for a review". The docs also warn that descriptions cost context. When the combined descriptions of all your custom subagents go past 15,000 tokens, Claude Code warns at startup.

The body

The body is the system prompt. A subagent gets only that prompt plus basic environment details such as the working directory. It does not get Claude Code's own system prompt. So the prompt has to carry everything the agent needs to know.

It has three parts:

1. A workflow. Run git diff, focus on modified files, start reviewing. That anchors the review to recent changes, not the whole repository, which keeps it fast and cheap.
2. A checklist. Eight items covering readability, naming, duplication, error handling, secrets, input validation, tests and performance. They are generic on purpose.
3. An output format. Critical, Warnings, Suggestions, with examples of fixes. A fixed format makes results easy to scan, and the main conversation receives a summary it can act on.

Claude Code docs also list three reasons to use a subagent: it preserves context by keeping exploration out of your main thread, it enforces constraints through limited tools, and it can route work to cheaper models. A reviewer fits the first two well.

Install it

Claude Code, by hand

Create the file in your project:

mkdir -p .claude/agents
$EDITOR .claude/agents/code-reviewer.md

Paste the file above. Check .claude/agents/ into version control so your team shares and improves it. For all projects, use ~/.claude/agents/code-reviewer.md instead. Claude Code watches both folders and picks up an added or edited file within a few seconds. Three cases need a restart: the first agent file in a brand-new agents directory, edits in a folder added with --add-dir, and sessions started with --disable-slash-commands.

Claude Code, by asking

The docs say you can ask Claude to write a subagent for you. The /agents command lists the ones you have. If a file does not load, run claude --debug and look in the log for the reason. Claude Code skips a file with no name, or with a name but no description, and it writes the reason only to the debug log. You can also run claude plugin validate .claude/agents to find frontmatter that does not parse.

Claude Code, one session only

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

This is from the same docs page. It is not saved to disk, which suits testing and scripts.

Calling it

You can let Claude delegate automatically, or ask: "Use the code-reviewer subagent to look at my last commit". See subagents for the full picture of invoking, foreground and background runs.

Codex

Not the same file. Codex custom agents are TOML files in ~/.codex/agents/ or .codex/agents/, and each needs name, description and developer_instructions. Codex's own docs include a reviewer example. Our adaptation of this page's checklist, in .codex/agents/reviewer.toml:

name = "reviewer"
description = "Code reviewer for recent changes. Use after code is written or modified."
model_reasoning_effort = "medium"
developer_instructions = """
Review the recent git diff like an owner. Do not edit files.
Check readability, naming, duplication, error handling, secrets, input validation,
test coverage and performance. Report Critical, Warnings and Suggestions,
with a concrete fix for each.
"""

The Codex docs say custom agents inherit the parent's permissions, provider and MCP servers, and that settings like sandbox_mode in the agent file do not override the parent. So the "do not edit" rule here lives in the instructions, not in a tool allowlist. To limit the agent's tools, Codex lets you set feature keys such as features.shell_tool to false.

OpenCode

OpenCode takes Markdown files in ~/.config/opencode/agents/ or .opencode/agents/, or a JSON agent block in opencode.json. The file name becomes the agent name. Our adaptation, in .opencode/agents/code-reviewer.md:

---
description: Reviews recent changes for quality, security and maintainability
mode: subagent
permission:
  edit: deny
---
You are a senior code reviewer. Run git diff, focus on modified files, and report
Critical issues, Warnings and Suggestions, with a specific fix for each.

This follows OpenCode's agents page, whose own example denies edit for a reviewer. OpenCode's permission block is closer to real enforcement than a prompt line, because it controls the tool itself. [VERIFY: whether bash: deny blocks git diff and whether a bash allow rule for git diff * is the right fix, on opencode.ai/docs/permissions].

Antigravity

Antigravity CLI describes subagents as concurrent background agent sessions you monitor with /agents. We found no documented file format for custom subagents on the pages we read.. Gemini CLI is now Code Assist enterprise only.

Cursor

. We have not confirmed that it reads Claude Code's .claude/agents/ files.

Make it safer: the Bash question

The docs describe this example as "a read-only subagent that reviews code without modifying it". The reason given is that it excludes Edit and Write. That is true as far as it goes. But Bash is in the allowlist, and a shell can write files, run git commit, delete things and call the network. The subagent also inherits your permission rules, so what it can do with Bash depends on what you allow. In the docs, a subagent inherits the parent's permission rules.

So "read-only" here is a convention, not a guarantee. Options, in rising strictness:

The docs say disallowedTools is applied first, then tools, and that a specifier such as Bash(git push *) in disallowedTools still removes the whole Bash tool. Do not rely on that for fine-grained blocking. Use permission rules or hooks for that. [VERIFY: how permission rules with Bash(git diff *) patterns apply inside a subagent, on code.claude.com/docs/en/permissions].

What to change for your team

The example is generic. A reviewer earns its keep when it knows your rules. Ideas that follow from the file's structure:

1. Name your standards. Replace "Good test coverage" with the thing you check, such as "new public functions have a test in tests/".
2. Add a stack section. For a WordPress plugin: nonces, capability checks, escaping on output. For a Laravel app: mass assignment and policy checks. The body can be as long as you need.
3. Choose a model. model: sonnet or haiku makes reviews cheaper. inherit follows the main model, which may be your most expensive.
4. Set a turn limit. maxTurns stops a runaway review and returns partial output, which the docs say you can resume. Partial marking needs Claude Code v2.1.246 or later, per the docs.
5. Preload skills. The skills field injects full skill content at startup, so the reviewer can load your team's checklist as a skill. See skills.
6. Give it memory. The memory field (user, project or local) lets it learn across sessions, for example which false positives you dismissed.
7. Isolate it. isolation: worktree runs the agent in a temporary git worktree, so even a stray write does not touch your checkout.
8. Color it. color helps you spot it in the task list.

What it costs

The file is free. The subagent sends its own requests, and they count toward the same usage limits as your main conversation, per the docs. A review of a small diff is cheap. A review of a large diff, with Grep and Read calls across many files, is not. Routing it to a smaller model with the model field is the main lever. Keep diffs small, and ask for review per commit, not per day.

Example requests

A good pattern from the docs' own wording: the reviewer reports, the main conversation fixes. That keeps the reviewer's context clean and avoids a reviewer marking its own homework.

Security notes

• Review is advice. The model can miss a bug or flag a non-issue. Do not treat a clean review as sign-off.
• Secrets. The checklist says to look for exposed secrets, which means the agent reads files that may contain them. Anything it reads goes to the model provider.
• Bash scope. See above. Restrict it if the repo is sensitive.
• Prompt injection. Code comments, commit messages and pull request text can address the agent. A diff from an untrusted contributor can carry instructions. Run the reviewer without write tools on untrusted changes.
• Shared files. A project subagent in .claude/agents/ is code your team runs. Review changes to it like changes to a CI script.
• Description routing. A malicious or sloppy description could pull the agent into unrelated work. Keep descriptions specific.

Limits and known issues

• The generic checklist finds generic problems.
• It reviews what git diff shows. A diff of staged and committed changes can differ, so name the range you want.
• Subagents cannot ask you questions mid-run, since the docs remove AskUserQuestion from subagents.
• Subagents run in their own context, so the main thread sees only a summary.
• Field names are case sensitive. A misspelled field is ignored without an error. claude --debug shows unknown fields.

Alternatives

Our take

It is a good example because it is small and honest about its shape: a clear description, a short tool list, a workflow, a checklist and a format. Copy it, then spend your time on the checklist, since that is where your standards live.

Two cautions. The "read-only" label oversells it while Bash is on the list, so decide how much that matters for your repo. And the proactive description can trigger reviews you did not want, which spend tokens. Start with a manual trigger, and switch to proactive once you like the output.

This is our reading of the documentation, not a hands-on test.

A short setup checklist

1. Create .claude/agents/code-reviewer.md with the example.
2. Rewrite the checklist for your stack.
3. Decide how to limit Bash, or drop it.
4. Pick a model, sonnet for cost or inherit for consistency.
5. Make the description say when to run.
6. Check the file into version control.
7. Run it on a small commit and read the output.
8. Check claude --debug if it does not load.

See also the Claude Code cheat sheet.

Frequently asked questions

What is the code-reviewer subagent?

A Markdown file that gives Claude Code a review specialist working in its own context window.

Where do I put the file?

In .claude/agents/ for a project or ~/.claude/agents/ for all projects.

Is it really read-only?

It lacks Edit and Write, but Bash can still change things, so restrict it if that matters.

How does Claude decide to use it?

From the description field. The example invites automatic use after code changes.

Does it work in Codex or OpenCode?

Not as the same file. Both have their own formats, shown above.