AI Code Review with Claude Code: What It Catches and Misses

Claude Code's review looks for correctness bugs in a diff: logic errors, broken edge cases, security vulnerabilities and regressions, read against the rest of your codebase. By default, the managed reviewer doesn't flag formatting preferences or missing test coverage. It never approves or blocks a pull request, and it doesn't know whether the change was the right thing to build. Use it as a second reviewer that runs before a person looks, and tune it with a REVIEW.md file so it flags what your team cares about.

This guide covers the four ways to run it, what each one is for, and the settings that decide whether you get useful findings or noise.

Four ways to run AI code review in Claude Code

Local review with /code-review

/code-review

It reviews your branch's commits ahead of its upstream plus any uncommitted changes. You can also pass a target: a file path, a PR number, a branch name, or a ref range such as main...my-feature. It runs as a background subagent with its own context window, so it doesn't fill your conversation, and the findings arrive there when it finishes. /review is an alias for it.

Flags:

• --fix applies the findings to your working tree after the review.
• --comment posts findings as inline comments on a GitHub pull request, or as a single note on a GitLab merge request.
• --max-findings <n> (or all, or default) replaces the usual limit on how many findings it reports. It needs Claude Code v2.1.288 or later.

You can also pass an effort level. At low it reports only the findings it's most confident in, so you see fewer false positives; from medium through max it covers more ground. If you don't give a level, it reuses the last one you typed. One catch: /rewind doesn't undo the edits a background review makes with --fix, so revert them with git.

Deeper review with ultrareview

/code-review ultra
/code-review ultra 1234
/code-review ultra develop

These review your current branch against the default branch, then pull request #1234 on github.com, then your branch against develop. Ultrareview is a research preview. It runs a larger group of reviewer agents in a cloud sandbox, and every finding it reports is independently reproduced and verified. A review typically takes 15 to 25 minutes.

Pro and Max accounts get three free runs, a one-time allotment that doesn't refresh. After that a review typically costs $5 to $25 in usage credits, depending on the size of the change, and the launch dialog shows an estimate first. A branch review can include up to 500 changed files and 8,000 changed lines by default. Those limits can change, and the refusal message names the ones in effect.

For scripts and CI, use the subcommand. It waits for the review to finish (up to 45 minutes by default) and prints the findings to stdout; --json prints the raw findings payload:

claude ultrareview 1234 --json

Don't use claude -p '/code-review ultra' for this: it launches the cloud review and exits without the findings. Ultrareview needs a claude.ai sign-in and isn't available on Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, or to organizations with Zero Data Retention or the HIPAA configuration. Where it isn't available, /code-review ultra runs a local review instead.

Managed Code Review on every pull request

Code Review is a research preview for Team and Enterprise plans, with the same Zero Data Retention and HIPAA exclusions. An Owner opens claude.ai/admin-settings/claude-code, installs the Claude GitHub App, selects repositories and picks a trigger for each:

• Once after PR creation: one review when the PR is opened or marked ready for review.
• After every push: a review on each push. It catches new issues as the PR changes and auto-resolves threads when you fix flagged issues, but it runs the most reviews and costs the most.
• Manual: reviews run only when someone comments @claude review (a single review) or @claude review always (a review, plus reviews on later pushes).

Several agents analyze the diff and surrounding code in parallel, each looking for a different class of issue. A verification step then checks candidates against how the code actually behaves, to filter out false positives. Findings arrive as inline comments tagged Important (fix before merging), Nit (minor, not blocking) or Pre-existing (a real bug this PR didn't introduce). Anthropic's docs put the average at $15–25 per review, scaling with PR size and complexity, and about 20 minutes per review. Code Review is billed through usage credits, not your plan's included usage.

Your own workflow with claude-code-action

To run review on your own runners and control the prompt, use the GitHub Action. The quickest route is /install-github-app inside Claude Code, selecting the review workflow. The manual version runs the code-review plugin when a PR is opened, updated, reopened or marked ready for review:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Keep both --comment and the claude_args line. Without --comment, Claude posts nothing and the findings appear only in the workflow log. The action starts the inline-comment tool only when --allowedTools in claude_args names it. To use a Claude subscription instead of an API key, use claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}. For more on running Claude non-interactively, see our guide to Claude Code headless mode in CI.

What AI code review catches

By default, managed Code Review focuses on correctness: "bugs that would break production, not formatting preferences or missing test coverage." That covers:

• Logic errors and broken edge cases. The docs' examples: a token refresh that races with logout and leaves stale sessions active, and a parser that silently returns 0 on malformed input.
• Security vulnerabilities.
• Subtle regressions, found by reading the change in the context of the full codebase, not only the diff.
• Pre-existing bugs that the PR didn't introduce, tagged separately.
• Rule violations and stale docs. Code Review reads your CLAUDE.md files, flags newly introduced violations as nits, and flags changes that make a CLAUDE.md statement outdated.

What it misses, or leaves to you

• It doesn't gate merges. The check run always ends with a neutral conclusion, so branch protection never blocks on it.
• It doesn't hold a conversation. Replying to an inline finding gets no response. Fix the code and push, or resolve the thread to dismiss it.
• Some PRs are skipped. Managed Code Review never reviews fork PRs automatically; someone with write access to the base repository must comment @claude review. The Action workflow skips draft and closed PRs, PRs that already have a comment from Claude, and PRs it judges don't need review, such as automated or trivial ones. On public repositories, GitHub withholds secrets from fork-triggered runs, so the Action reviews only PRs from branches in the same repository.
• Runs can fail. Reviews are best-effort. Code Review retries some interrupted reviews itself; otherwise the check run title says the review failed or timed out, and you rerun it with @claude review or, for non-fork PRs, the Re-run button.
• Big diffs hit limits. Ultrareview refuses diffs over its size limits, so split large changes.
• It can't judge intent. It checks the code for bugs, not whether the feature matches what was asked for or whether the change should exist at all.

Tune what it flags with REVIEW.md

For managed Code Review, the main lever is a REVIEW.md at the repository root. Its contents go directly to the agents that find and verify findings, so rules there land more reliably than the same rules in a long CLAUDE.md. Local /code-review follows CLAUDE.md but doesn't read REVIEW.md.

The docs list these as the patterns with the most impact:

• Redefine Important for your repo. A docs, config or prototype repo might want a much narrower definition.
• Cap nits, for example "report at most five nits, mention the rest as a count in the summary."
• Skip what you don't need reviewed: generated code, lockfiles, vendored dependencies, and anything CI already enforces.
• Add repo-specific checks, such as "new API routes must have an integration test."
• Set a verification bar, for example "behavior claims need a file:line citation in the source, not an inference from naming."
• Converge on re-review: "after the first review, suppress new nits and post Important findings only."

A short example, adapted from the docs:

# Review instructions

## What Important means here
Incorrect logic, unscoped database queries, PII in logs, and
migrations that aren't backward compatible. Style is Nit at most.

## Do not report
- Lint, formatting and type errors (CI enforces these)
- Files under `src/gen/` and any `*.lock` file

## Always check
- Database queries are scoped to the caller's tenant

Keep it short: the docs warn that a long REVIEW.md dilutes the rules that matter most. General project context belongs in CLAUDE.md; see our CLAUDE.md best practices.

Gate merges on findings yourself

To fail CI on Important findings, read the check run's output. Its Details text ends with a machine-readable comment. Find the check run ID first:

gh api repos/OWNER/REPO/commits/COMMIT_SHA/check-runs --jq '.check_runs[] | {id, name}'

Take the id of the Claude Code Review run, then parse the severity counts:

gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

This returns counts such as {"normal": 2, "nit": 1, "pre_existing": 0}, where normal is the number of Important findings. Fail the job when it's above zero, and keep a way for a person to override it.

Keep costs predictable

• Choose the trigger deliberately. "After every push" multiplies cost by the number of pushes; "Once after PR creation" runs one review per PR; "Manual" costs only what someone asks for. In those last two modes, @claude review always adds per-push cost for that PR.
• Cap managed Code Review with a monthly spend cap at claude.ai/admin-settings/usage. The repositories table in admin settings shows average cost per review, and the analytics dashboard breaks spend down by repository.
• Cap the Action: set --max-turns in claude_args, add a workflow timeout, and use GitHub's concurrency controls.
• Match depth to the change: local /code-review while you iterate, ultrareview for substantial changes before merging.

A review setup that works

1. Run /code-review locally before pushing.
2. Run one automatic review per PR, through managed Code Review or the Action, with a focused REVIEW.md.
3. Use ultrareview, or @claude review always, for risky changes such as auth, billing or migrations.
4. Have a person approve every merge, focusing on intent, design and anything tagged pre-existing.

The same approach applies when agents write the code as well as review it: review each piece as it finishes, then review everything going out together before production. That's how Atlas runs its AI engineering team. Every build is reviewed as it finishes and comes back either RELEASABLE or with fix tasks filed to its builder by name, and before a production release everything going out is reviewed together.

Conclusion

Claude Code's reviewers look for correctness problems in the context of the wider codebase. They won't block merges, judge product intent or replace a human approval. Start with one review per PR and a short REVIEW.md that defines Important for your repo, add a merge gate only if you need one, and save ultrareview for changes where a missed bug would cost the most.