Code Review

There are two things called code review in Claude Code, and this page covers both:

1. Code Review, the managed service. Once switched on for your organisation, it reviews GitHub pull requests on Anthropic's infrastructure and posts inline comments where it finds real bugs.
2. /code-review, the command. Runs in your own session against your diff, a branch, a path or a PR. Available on any plan.

Note: The managed service is a research preview for Team and Enterprise. It is unavailable with Zero Data Retention or the HIPAA configuration, and is not covered by Anthropic's BAA. Everyone else can still use /code-review locally.

If you would rather run Claude in your own CI, see GitHub Actions or GitLab CI/CD. Self-hosted GitHub is covered in GitHub Enterprise Server.

How managed reviews work

When a review fires, several agents examine the diff and the code around it in parallel, each hunting a different class of problem. A verification step then tests every candidate against how the code actually behaves, discarding false positives. What survives is deduplicated, ranked by severity and posted as inline comments, with a summary in the review body. If nothing is found, the check run says so and Claude may leave a short confirming comment.

Reviews take about 20 minutes on average, and cost scales with PR size and complexity. By default the focus is correctness: things that would break in production, not formatting or test coverage.

Reviews never approve or block. Your existing review process stays exactly as it is.

Severity markers

Each finding has a collapsed Why this was flagged section explaining the reasoning and how it was verified.

Reacting to findings

Every comment arrives with 👍 and 👎 already attached, so rating is one click. Anthropic gathers the counts after merge to tune the reviewer; reactions change nothing on the PR.

Replying to a comment does not get a response. To act on a finding, fix the code and push; on push-triggered PRs the next review resolves the thread once fixed. To dismiss a finding without changing code, resolve the thread. For a fresh review without pushing, comment @claude review at the top level.

The check run

Each review also fills in a Claude Code Review check run next to your CI. Its Details page has a table of every finding by severity, file and line, and the findings appear as annotations in Files changed (red for Important, yellow for nits, grey for pre-existing). These are written independently of the inline comments, so they survive even if GitHub rejects a comment on a line that has moved.

The check always concludes neutral, so branch protection is never blocked by it. If you want to gate merges, parse the machine-readable line at the end of the Details text. It is an HTML comment beginning bughunter-severity: followed by JSON counts. A small script for a workflow step:

#!/usr/bin/env bash
set -euo pipefail
repo="$GITHUB_REPOSITORY"
sha="$1"

run_id=$(gh api "repos/$repo/commits/$sha/check-runs" \
  --jq '.check_runs[] | select(.name == "Claude Code Review") | .id' | head -n1)

counts=$(gh api "repos/$repo/check-runs/$run_id" \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson')

echo "Claude Code Review: $counts"
important=$(jq '.normal' <<<"$counts")
[ "$important" -eq 0 ] || { echo "Important findings present"; exit 1; }

The JSON looks like {"normal": 1, "nit": 3, "pre_existing": 0}. normal is the Important count.

Setting it up

An Owner does this once for the organisation.

1. Open the Code Review section of the Claude Code admin settings on claude.ai. You need the Owner or Primary Owner role in Claude and rights to install GitHub Apps in the GitHub organisation.
2. Click Setup to start the GitHub App flow.
3. Install the Claude GitHub App: choose the GitHub organisation, the repositories it can see, and approve permissions. Reviews use read access to contents and write access to pull requests and checks; the full permission set is shared with other Claude features such as GitHub Actions.
4. Select which repositories get reviews. Missing ones usually mean the app was not given access.
5. Set Review Behavior for each repository:

Whatever you pick, PRs from forks are only reviewed on request.

The repository table shows average cost per review, and row actions let you pause or remove a repository.

To test, open a PR. With an automatic trigger a Claude Code Review check appears within minutes; in Manual mode, comment @claude review. No check? Confirm the repo is listed in admin settings and the app can see it.

Requesting a review by comment

These work in any mode. The rules:

• top-level PR comment, not an inline diff comment;
• the command starts the comment, with once or always on the same line;
• you have write, maintain or admin on the repository;
• the PR is open.

Manual requests run on draft PRs too. If a review is already running, the request queues behind it.

Note: Before a July 2026 change, plain @claude review also subscribed the PR to push reviews. Use @claude review always for that now.

Private org membership trap. GitHub hides organisation membership by default, and then does not tell Claude you are a member. Claude may react with 👀 but will not start, unless you were added to the repo directly as a collaborator. Make your membership public, or ask an admin to add you as a collaborator.

Fork pull requests

Forks are never reviewed automatically, in any mode. Comment @claude review (you need write access to the base repository). @claude review always works but does not subscribe. Clicking Re-run on the check or pushing new commits does nothing for forks; post a new comment each time.

Tuning what gets flagged

Two files in the repository steer reviews:

• CLAUDE.md: your general project instructions. Code Review treats newly introduced violations as nits, and also flags when a change makes a CLAUDE.md statement out of date. Nested CLAUDE.md files apply to their own subtrees. See memory.
• REVIEW.md at the repository root: review-only instructions. The finding and verification agents receive it directly, and the ranking and reporting agents consult it, so rules here bite harder than the same rules buried in a long CLAUDE.md.

What to put in REVIEW.md

It is freeform Markdown. The levers that matter most in practice:

• Severity calibration. Say what counts as Important in this repo, and what is Nit at most. You can also promote, e.g. treat CLAUDE.md violations as Important.
• Nit caps. Limit inline nits and summarise the rest as a count.
• Skip rules. Paths, branches and categories to stay silent on: generated code, lockfiles, vendored code, bot branches, anything CI already enforces. Or raise the bar instead of skipping.
• Always-check rules. House rules for every PR.
• Evidence requirements. Demand a file:line citation before certain claims are posted.
• Re-review behaviour. E.g. after the first pass, only report Important findings.
• Summary format. A one-line tally at the top, or "no blocking issues" when that is the case.

Here is the one I use on a React Native app:

# Review rules for the mobile app

## Severity
Important means: crashes, data loss, auth or payment flow regressions, or anything
that would fail App Store review. Accessibility regressions on checkout screens are
Important. Everything else, including naming and refactors, is Nit at most.

## Limits
Post no more than three Nits. Summarise the remainder as "and N minor points".
After the first review of a PR, only post Important findings.

## Ignore
- `ios/Pods/`, `android/app/build/`, `*.lock`
- Anything under `src/generated/`
- Branches starting with `renovate/`

## Always check
- New screens register an analytics screen-view event
- Network calls go through `apiClient`, never raw `fetch`
- No secrets or API keys in `app.config.ts`

## Summary
Start the review body with "Blocking: N, Nits: M".

Keep it short. Every extra paragraph dilutes the rules that matter; put general context in CLAUDE.md.

Usage and pricing

The analytics dashboard for Code Review on claude.ai shows:

Dashboard figures are estimates; your Anthropic invoice is authoritative.

Reviews are billed on tokens, averaging US$15 to US$25 each depending on PR size, codebase complexity and how much verification is needed. They are billed through usage credits, separate from plan usage, and appear on your Anthropic bill even if the rest of your Claude Code traffic goes through Bedrock or Agent Platform.

How triggers affect cost: once-per-PR runs once; every-push multiplies by pushes; Manual costs only what is requested. @claude review always on a once-per-PR or Manual repo adds a review per push from then on. Forks never accrue per-push cost.

Set a monthly cap for the Claude Code Review service in the usage section of admin settings.

Troubleshooting

Runs are best-effort and never block a PR. Some interrupted runs retry automatically.

Failed or timed out. The check title reads Code review failed or Code review timed out, still neutral. Unless the summary says a retry is already queued, comment @claude review, or (non-fork PRs only) click Re-run on the check. Neither subscribes the PR.

Skipped with a budget message. Either the monthly cap is reached (resumes next period, or when an admin raises it) or usage credits are exhausted (resumes when topped up). Both are fixed in the usage section of admin settings.

Check says issues were found, but no inline comments. Look at the check's Details table, the Files changed annotations, and the review body: findings on lines that changed during the review go under Additional findings.

Reviewing locally with /code-review

/code-review reviews a diff in your session, no GitHub App required. It reports correctness bugs and, depending on model and effort, reuse, simplification and efficiency cleanups. /review is an alias (before v2.1.223 it was a separate read-only PR review).

/code-review

With no target it reviews your branch's commits ahead of upstream plus uncommitted changes. Or pass a target: a path, PR number, branch, or range like main...feature/export-csv.

Flags:

For GitLab, pass the MR URL or !123. Bare numbers or branch names are treated as MRs only when origin is on gitlab.com.

The review runs as a background subagent with its own context, and findings land in your conversation when done. Ask Claude to fix them, or they are already applied or posted if you used --fix or --comment.

In a terminal and in -p runs, findings come back as text. Host apps that ask for a structured list (such as the desktop app) get them through the ReportFindings tool, rendered with location, summary and category tags such as correctness (v2.1.218+). Later fixes mark entries as fixed, skipped or no change needed.

Things to know

• It follows CLAUDE.md but not REVIEW.md.
• Background --fix edits sit outside your checkpoints, so /rewind will not undo them; use git. Foreground reviews are rewindable.
• It runs in the foreground if a previous review is still going, in -p or Agent SDK runs, or with CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.

Effort levels

Add low, medium, high, xhigh or max. low shows only the most confident findings; higher levels widen coverage. With no level typed, it reuses the last level you typed (even from a previous session) and says so, e.g. Reusing high effort, the level you typed last time. Levels passed in -p runs do not update the remembered value, and ultra neither uses nor changes it. With no history, it uses the session's effort.

After the level and flags, the rest of the line is the target, even if it looks like another command (/code-review /fix-issue 12 treats /fix-issue 12 as text). With ultra, a single word is a base branch or PR, and longer text becomes a note.

Letting Claude run it

Claude can start /code-review itself when you ask in plain language, and a scheduled task can use it as its prompt (scheduled tasks never launch ultra). To keep it manual-only:

{
  "skillOverrides": {
    "code-review": "user-invocable-only"
  }
}

in a settings file such as ~/.claude/settings.json.

Going deeper with ultra

/code-review ultra (optionally with --fix) sends the change to ultrareview, a verified multi-agent review in a cloud sandbox, and applies findings when they return. It reviews your branch against the default branch plus local changes, following cloud upload rules for credential-like files. Pass a branch to change the base. It needs a claude.ai login and is unavailable on Bedrock, Agent Platform, Foundry, ZDR or HIPAA, where it falls back to a local review. For scripts, use claude ultrareview.

Note: Before v2.1.147 this command was called /simplify and fixed by default. Today /simplify is a separate cleanup-only pass that does not hunt bugs. Scripts that used /simplify to find bugs should switch to /code-review --fix.

Related

• Ultrareview
• GitHub Actions
• Security guidance plugin
• Memory and CLAUDE.md
• Analytics