Claude Corner

Review Turned Into Edits? Give Claude Code a Read Only Reviewer Subagent.

By ยท 18 Nov 2026

Two hands hold a magnifying glass over a blank green circuit board on a bright periwinkle table, seen from a low angle, with no face or screen in view.

At a glance

  • One Markdown file in .claude/agents/ gives you a reviewer you can call by name in that project.
  • A tools list of Read, Grep and Glob means the reviewer can look at your code but cannot edit or write files.
  • The review runs in its own context window and hands back a summary, so the main conversation stays on the work.

You ask Claude to look over your changes, and two turns later it is rewriting a function you never asked it to touch. A review and a fix are different jobs, and Claude Code lets you give the review its own worker with its own limits.

Why it matters

Anthropic's subagents docs describe a subagent as a specialized assistant that runs in its own context window, with specific tool access. It returns only a summary, so the files it read stay out of your main conversation. The tools field is an allowlist, and a reviewer limited to Read, Grep and Glob cannot edit or write files. Saved in .claude/agents/ and checked into version control, the same reviewer is there for your team.

How to set up a read only reviewer

We built these steps from Anthropic's docs and have not run them live.

  1. From your project root, create the .claude/agents/ folder if it does not exist yet.
  2. Write reviewer.md with a name, a short description, a tools line of Read, Grep and Glob, and a model. The body below the frontmatter becomes the reviewer's system prompt.
  3. Run claude plugin validate .claude/agents to check that the frontmatter parses before you rely on it.
  4. Start Claude Code, or restart it if the agents folder is new, then type @ and pick the reviewer.
  5. Read the summary it returns, then make the fixes yourself in the main conversation.
# We have not run this script end to end on every platform.
# Run it from your project root. It writes one file.

claude --version

mkdir -p .claude/agents

cat > .claude/agents/reviewer.md <<'MD'
---
name: reviewer
description: Reviews recent code changes for bugs, security and readability.
tools: Read, Grep, Glob
model: sonnet
---

You are a code reviewer. Read the changed files, then list each issue
with the file, the problem and a suggested fix.
MD

# Check that the frontmatter parses.
claude plugin validate .claude/agents

# Then, in Claude Code, send:
# @"reviewer (agent)" look at my recent changes

Gotchas

  • A brand new folder needs a restart. Claude Code watches .claude/agents/ and picks up edits within a few seconds, but only for directories that existed when the session started. A new folder needs a restart.
  • Some broken files are skipped quietly. A file with no name, a name with no description, or YAML that does not parse is skipped without a notice. Misspelled field names are ignored with no error. If you omit tools, the reviewer inherits every tool. On v2.1.296 or later, claude --debug names unrecognized fields.
  • /agents no longer opens a wizard. Current versions print a reminder to ask Claude or edit the agents folders directly. Only v2.1.197 and earlier open the wizard.
  • Reviews still use your plan. Each subagent sends its own requests, and the docs say they count toward the same usage limits as your main conversation.
  • Your body text is the whole system prompt. A subagent's system prompt is only its own body text plus basic environment details, not the Claude Code system prompt, so say what to check and what to return.

For keeping CLAUDE.md out of a focused worker, see our Sep 21 Corner on skipping CLAUDE.md in subagents.

Sources:

Recommended AI prompt

Copy this paragraph into ChatGPT, Claude, Gemini, Grok, or whatever AI you use.

Prompt

Using only Anthropic's Claude Code subagents docs, help me write a reviewer file for my project's .claude/agents folder with a tools list limited to Read, Grep and Glob and a focused system prompt. Give a short checklist for confirming it loaded and calling it by name. Ask which language and review priorities I care about.