Claude Code's /code-review is a command that reads the diff you have right now (uncommitted changes and commits ahead of upstream), hunts for correctness bugs, and reports them. It's a bundled skill that ships with Claude Code, so you can run it straight from the terminal without installing any GitHub app. Typing /review runs the same thing.
This article draws on the original text of the official Claude Code documentation (Review locally with /code-review, Find bugs with ultrareview, and Commands) and the CHANGELOG to explain what it does, how to choose between the levels (low to max) and ultra, and how to use --fix and --comment. Every spec described here was checked against the source text as of October 2, 2026 (the description of the levels was rechecked on October 14, 2026, and the GitHub App version of Code Review and the duration of ultra on October 18, 2026). Sections 9 and 10 also cover what happened when I actually ran /code-review high on this site's code, and the downsides I found along the way.
The short version: /code-review at a glance
Source: Claude Code official docs, "Review locally with /code-review" and "Find bugs with ultrareview" (checked October 18, 2026)
WHAT IT DOES
Finds bugs in your diff
Reports correctness bugs. Depending on model and level, it also suggests cleanups.
LEVELS
Pick from low to max
Lower means only high-confidence findings, higher casts a wider net. Leave it out and it reuses the level you typed last.
COST
Normal usage
Low to max comes out of your plan's limits. There's no separate charge.
ULTRA
Deep review in the cloud
3 free runs on Pro, Max, and Ultra. After that, roughly $5–25 per run in usage credits.
Contents
- 1. What is /code-review? A bundled skill that finds bugs in your diff
- 2. Basic usage: choosing what to review
- 3. Choosing a level: low to max
- 4. Using --fix and --comment
- 5. ultra: multi-agent cloud review and pricing
- 6. How it differs from similar features
- 7. When Claude starts it on its own, and how to stop that
- 8. What to use when
- 9. I tried it on this site's code
- 10. Downsides and caveats
- FAQ
1. What is /code-review? A bundled skill that finds bugs in your diff
The Commands reference describes it as follows: "Review the current diff, or a PR number, branch, or path you pass, for correctness bugs." It goes on to say, "Depending on your model and effort level, the review also covers cleanup opportunities," and the /code-review page (Review locally with /code-review) says it "looks for correctness bugs, and depending on the model and effort level, also covers reuse, simplification, and efficiency cleanups." Bug hunting is the main job; cleanup suggestions come along depending on the conditions.
The syntax looks like this:
/code-review [low|medium|high|xhigh|max|ultra] [--fix] [--comment] [--max-findings n|all|default] [pr#|branch|path]
Four properties are worth knowing up front:
- It runs in the background. The review runs as a subagent with its own context window, so it doesn't fill your conversation. The findings arrive in your conversation when it finishes.
- It reads CLAUDE.md, but not REVIEW.md. REVIEW.md is the instruction file for the GitHub App version of Code Review, covered below.
/reviewis an alias. According to the docs, before v2.1.223/reviewwas a separate command that did a single-pass read of a GitHub PR. Today it's the same as/code-review.- Its former name was
/simplify. Per the CHANGELOG,/simplifywas renamed to/code-reviewin v2.1.147, and/simplifylater came back as a separate command that only does cleanups and doesn't look for bugs.
In the terminal and in -p runs, the findings come back as text in the reply. In apps that request a findings list, such as the desktop app, they're shown as a list where each entry has the file location, a one-sentence summary, and a category tag such as correctness. When Claude later fixes them, each entry is marked fixed, skipped, or no change needed.
2. Basic usage: choosing what to review
The most basic form is to type it with no arguments in the session you're working in.
# Review commits ahead of upstream + uncommitted changes
/code-review
# Review at a specific level
/code-review high
# Pass a PR number to review a colleague's pull request
/code-review high 1234
# Pass a branch range
/code-review main...my-feature
With no arguments, the target is, in the docs' words, "your branch's commits ahead of its upstream plus any uncommitted changes." If there's nothing new on the branch or in the working tree, it has nothing to report. To review something else, pass a target:
| What you pass | Example | What gets reviewed |
|---|---|---|
| Nothing | /code-review | Commits ahead of upstream + uncommitted |
| A file path | /code-review src/auth.ts | That file |
| A PR number | /code-review 1234 | That pull request |
| A branch name | /code-review my-feature | That branch |
| A range | /code-review main...my-feature | The given ref range |
Unless you add ultra, whatever is left after the level and flags is treated as the review target. For example, /code-review /fix-issue 123 doesn't load /fix-issue as a second skill; it reads the text /fix-issue 123 as the target.
In these cases it runs in the foreground, inside your conversation, instead of in the background: when you run it again while an earlier review is still in progress, in non-interactive mode with -p or the Agent SDK, and when you set the environment variable CLAUDE_CODE_DISABLE_BACKGROUND_TASKS to 1 (which also turns off every other background feature).
3. Choosing a level: low to max
The level is a trade-off between how widely the review looks and how confident its findings must be. As of October 14, 2026, the docs explain that at low the review reports only the findings it's most confident in, so you see fewer false positives, while medium through max broaden coverage (when I checked on October 2, medium was grouped with low on the high-confidence side). Since v2.1.290, medium also reports cleanup and CLAUDE.md conventions findings on models without tuned review settings, such as Opus 5.5 and Sonnet 5.5 (CHANGELOG).
Levels and the kind of findings you get
Source: official docs, "Review locally with /code-review," Tune effort and arguments (checked October 18, 2026)
low
Only high-confidence findings. Fewer of them, and fewer false positives.
medium / high / xhigh / max
Broader coverage. Because it casts a wider net, you need to sort through the results.
The rule of thumb is how much effort you can spend reading findings. If you want a quick check between tasks, use low; if you also want cleanup and CLAUDE.md convention findings, use medium; if you want to catch more before merging and can afford to throw out false positives yourself, use high or above. That split follows the docs' description. Higher levels using more tokens is the same idea as effort in general, but the official docs don't give any figures for time or usage per level. What effort itself means is explained in our article on Claude Code's effort setting.
Leave out the level and it reuses "the level you typed last"
If you don't type a level, the review uses the last level from low to max that you typed yourself. That includes one typed in an earlier session, in which case you'll see a notice such as Reusing high effort, the level you typed last time. The details:
- The remembered level is updated when you type something like
/code-review highin an interactive session. - A level passed in a non-interactive
-prun isn't remembered. ultraneither uses nor updates the remembered level.- If you've never typed a level, the session's current effort is used.
The docs also note: "Before v2.1.223, a /code-review without a level always used the session's current effort." If you leave it out expecting the old behavior, it may run at a higher (or lower) level than you expect, so if it matters, type the level every time.
4. Using --fix and --comment
--fix: go as far as fixing
Applies the findings to your working tree after the review finishes.
--comment: post to the PR
Posts inline comments on a GitHub PR, or a single note on a GitLab MR.
--fix may not be undone by /rewind
This is the part to watch most closely. According to the docs, edits made by --fix in a background review happen outside your session's checkpoints, so /rewind doesn't undo them. Use git to revert them instead. When the review runs in the foreground (an earlier review still running, -p, and so on), it edits during your own turn, so /rewind restores them as usual.
# Commit your current state before --fix so it's easy to go back
git add -A && git commit -m "wip: before code-review --fix"
/code-review medium --fix
# If you don't like the result, undo it with git
git diff
git restore .
You can also run the review without --fix, read the results, and then ask "fix only #1 and #3." If you're not sure every finding should be applied, that's the safer route. Checkpoints are covered in detail in our article on checkpoints and /rewind.
Where --comment posts
- GitHub pull requests: posts the findings as inline comments on the relevant lines.
- GitLab merge requests: posts them as a single note through
glab, GitLab's CLI (v2.1.257 or later). Ifglabisn't installed, the findings are only printed in the terminal.
On GitLab, pass the MR as a URL or in the !123 form. A bare number or branch name is treated as an MR only when the origin is on gitlab.com; on a self-managed GitLab instance, the docs say to use the URL or !123. Whether posting to GitHub needs authentication such as gh isn't stated in the official docs as of October 2, 2026.
Changing the number of findings: --max-findings
From v2.1.288 (October 2, 2026), --max-findings changes how many findings are reported. Pass a number, as in --max-findings 20, to get up to that many; --max-findings all reports every finding it found, in place of the usual limit. The value you set carries over to later reviews, so pass --max-findings default to go back (official docs: "Review locally with /code-review").
5. ultra: multi-agent cloud review and pricing
/code-review ultra is a deep review that runs several reviewer agents in parallel in a sandbox in Anthropic's cloud, not on your machine. It's a research preview called ultrareview, and on accounts where it's available, /ultrareview is an alias. The official docs list three advantages over a local /code-review:
- Higher signal: every reported finding is independently reproduced and verified, so the results focus on real bugs rather than style suggestions.
- Broader coverage: more agents explore the change in parallel, which surfaces issues a local review can miss.
- No local resources: it runs in the cloud, so you can keep doing other work in your terminal meanwhile.
Pricing and free runs
ultra is billed from usage credits (extra usage), not from the usage included in your plan.
| Plan | Free runs | After the free runs |
|---|---|---|
| Pro | 3 | Billed as usage credits |
| Max | 3 | Billed as usage credits |
| Ultra | 3 | Billed as usage credits |
| Team / Enterprise | None | Billed as usage credits |
- Free runs: the three Pro, Max, and Ultra runs are a one-time allotment per account and don't refresh.
- Cost per run: once the free runs are used up, it's typically $5 to $25 in usage credits, depending on the size of the change. The launch dialog shows an estimate before each run.
- How runs are counted: a run counts once the cloud session starts. Stopping it partway or a failure still uses up one free run. Paid reviews are billed for what actually ran.
- Prerequisite: paid reviews won't launch unless usage credits are enabled. You can check with
/usage-credits. The confirmation for billing to usage credits appears once per conversation.
Whether "$5–25" is expensive or cheap depends on what you compare it with. Compared with /code-review at low to max, which stays inside your plan's limits with no separate charge, ultra is an extra expense. Compared with the GitHub App version of Code Review described below, on the other hand, that one has no fixed price per review. The cost varies with the review level, the size of the change, and the complexity of the surrounding code, and it's billed to the organization as a whole (Code Review costs and usage, checked October 18, 2026). Since it's a different system that runs automatically on each PR, you can't compare the two by the cost of one run alone.
Time, scope, and where it isn't available
- Duration: typically 15 to 25 minutes (the docs say "typically takes 15 to 25 minutes" as checked on October 18, 2026; on October 2 they said 5 to 10 minutes). It runs in the background, and you can check on it or stop it with
/tasks. Stopping it returns no partial results. - Scope: with no arguments, it reviews your current branch against the repository's default branch, plus uncommitted and staged changes. That's a different baseline from the local
/code-review's "ahead of upstream." Pass a branch name, as in/code-review ultra develop, to change the base. - Reviewing a PR: pass a number, as in
/code-review ultra 1234, and nothing is uploaded from your machine; the cloud clones the PR directly. This works only for repositories on github.com. For GitHub Enterprise Server repositories, leave out the number and review your local branch instead (checked October 18, 2026). - Limits: a branch review covers up to 500 changed files and 8,000 changed lines by default (the docs state these values can change).
- Where it isn't available: it requires signing in with a claude.ai account, and isn't available through Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, or to organizations with Zero Data Retention or HIPAA-compliant setups, and when it isn't available,
/code-review ultraruns as a local review. Organizations that use customer-managed encryption keys (CMEK) can't run ultra either.
A branch review bundles the state of your local repository and uploads it to the cloud. Uncommitted changes to files with credential-like names, such as .env and *.tfvars, follow the same rules as uploading to a cloud session. How cloud sessions work in general is covered in our article on cloud sessions.
Posting results to the PR (--post) and running it from scripts
When you review a github.com PR with ultra, you can post the results to the PR as a single comment from your own GitHub account (v2.1.227 or later). It's an ordinary comment, not a review or an approval, and the default is not to post (--no-post). /code-review ultra 1234 --post preselects posting in the launch dialog, but you still get the confirmation before it starts. Posting begins when the review finishes, so you need to keep the session open until it's done.
For CI or scripts, use the claude ultrareview subcommand. It waits for the results and writes them to stdout (with --json, --timeout (default 45 minutes), and --post available). claude -p '/code-review ultra' only launches the review and exits without waiting, so you don't get the results, and when billing to usage credits is required it doesn't even launch.
Starting with v2.1.309, claude ultrareview asks for workspace trust. In a terminal it asks Trust <folder>? [y/N]. In places where it can't ask, such as CI, it stops with Error: Workspace not trusted. In CI, either add --trust-workspace or set CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1 in the environment where it runs (both require v2.1.309 or later). --trust-workspace takes no value, so write the PR number or branch name before it.
# Review PR 1234 with ultra from a script and get the results
claude ultrareview 1234
# Use a base other than the default branch
claude ultrareview origin/main
# In CI or other places that can't answer the trust prompt (v2.1.309 or later)
claude ultrareview 1234 --trust-workspace
Only use this in repositories you trust. Once you trust a repository, git and Claude Code can run programs defined in that repository's git settings and project settings (official explanation).
6. How it differs from similar features
Claude Code has several review features with similar names. The GitHub App feature called "Code Review" is especially easy to mix up, because its name is nearly the same as the /code-review command. The official docs also give the local /code-review its own separate page, "Review locally with /code-review."
| Comparison | /code-review | /code-review ultra | /simplify | /security-review | Code Review (GitHub App) | claude-code-action |
|---|---|---|---|---|---|---|
| Purpose | Correctness bugs | Verified bugs | Cleanups only | Vulnerabilities | PR bugs and regressions | General automation |
| Runs on | Your machine | Cloud | Your machine | Your machine | Anthropic's infrastructure | Your own Actions |
| Target | Diff, PR, branch, path | Diff vs. default branch, PR | Changed code | Diff vs. origin's default branch | PRs | Depends on workflow |
| Fixes | Applies with --fix | Applies with --fix | Applies them | Not stated in docs | No | Depends on workflow |
| Cost | Normal usage | $5–25 after 3 free runs | Not stated in docs | Not stated in docs | Billed to the org by token usage (no flat fee) | API pricing + Actions minutes |
| Who can use it | All plans | claude.ai accounts | No limits stated | No limits stated | Team / Enterprise (enabled by the Owner) | Set up by repo admins |
/simplify: four agents check in parallel for reuse of existing helpers, simplification, efficiency, and whether the change is at the right level of abstraction, then apply the fixes. It doesn't look for correctness bugs. The/code-reviewpage also advises that if you scripted/simplifyfor bug-finding, you should switch to/code-review --fix./security-review: checks the diff between your current branch and origin's default branch for vulnerabilities such as injection, authentication problems, and data exposure. It requires anoriginremote.- Code Review (GitHub App): once an organization Owner enables it, multiple agents on Anthropic's infrastructure examine a PR when it's opened, on every push, or when someone writes
@claude review, and leave line-level comments. It went generally available on October 15, 2026, after its research preview ended (Anthropic's announcement). Only Team and Enterprise can use it, and it isn't available to organizations with Zero Data Retention, HIPAA-compliant setups, or customer-managed encryption keys (CMEK). The review depth has three settings: Quick (lighter and faster, the lowest cost), Standard (the default), and Deep (the most thorough, and the slowest and most expensive). The Owner chooses the organization default and per-repository settings. Pricing is based on token usage rather than a flat fee per review, and it's billed to the organization from usage credits, separately from plan limits. Owners can also set a monthly spending limit for Code Review alone. According to Anthropic, most reviews take 6 to 10 minutes (about 20 minutes during the research preview). Commenting@claude review alwayson a PR makes it review that PR on every push. You can stop this subscription with@claude review stop(offandpausework the same way) (added in v2.1.307 according to the CHANGELOG). You can tune what it flags withREVIEW.md(Code Review and Code Review costs and usage, checked October 18, 2026). - claude-code-action: runs Claude Code in GitHub Actions workflows in your own repository. The review example in the official docs calls the plugin version of the
code-reviewskill (/code-review:code-review --comment) to comment on the PR. The cost is Claude API pricing (or subscription tokens) plus GitHub Actions run time.
Sorting them by "where it runs, who pays, and what it looks at" makes things clearer. To check your own diff locally, use /code-review; to look deeply before merging, use ultra; to run automatically on every team PR, use the GitHub App's Code Review or claude-code-action.
If GitHub emails you saying "Claude is requesting updated permissions," see Claude is requesting updated permissions: Is It Real? Approve or Wait? for how to tell whether it is genuine and whether to approve it.
7. When Claude starts it on its own, and how to stop that
Claude can start /code-review on its own. If you ask it in plain language to review your changes, it may run the skill without you typing the command, and a scheduled task with /code-review as its prompt also runs a review. A scheduled task never launches ultra (the cloud review), though. ultra runs only when you type /code-review ultra yourself.
To stop both Claude and scheduled tasks from starting it, while keeping it available when you type it yourself, add the following to a settings file such as ~/.claude/settings.json:
{
"skillOverrides": {
"code-review": "user-invocable-only"
}
}
Background reviews run as subagents. How subagents handle context and models is explained in our article on subagents and agent teams.
8. What to use when
The comparison table in the official docs says the local /code-review is best for "quick feedback while iterating" and ultra for "pre-merge confidence on substantial changes." Mapped onto an everyday workflow, it looks like this:
Which to use at each stage of work
Source: based on the official docs, "Find bugs with ultrareview," How ultrareview compares to /code-review
1. While writing
Use /code-review low to quickly catch only high-confidence findings.
2. Before pushing
Use /code-review high to look more widely. If you want fixes, commit first, then use --fix.
3. A colleague's PR
Read it with /code-review high 1234, and leave findings on the PR with --comment if needed.
4. Before merging a big change
Check the estimate, then run /code-review ultra. On Pro, Max, and Ultra, spend the 3 free runs here.
Because ultra's 3 free runs don't refresh, it pays to save them for changes with a wide blast radius, or changes where the local review didn't settle the question, rather than small fixes. Likewise, use /security-review when you want to focus on vulnerabilities and /simplify when you want to tidy readability rather than find bugs; splitting by purpose is how the docs describe them.
9. I tried it on this site's code
On October 2, 2026, I ran /code-review high on the code for the AI image checker tool published on this site. The tool reads an image's metadata and provenance (C2PA) entirely inside the browser, and the target was four files: the UI logic, the parsing logic (a Web Worker), the controller, and the page template. I ran it in the Claude Code desktop app (bundled Claude Code 2.1.284, model Opus 5.5), right after I had hunted for bugs myself and fixed five.
Results from one run
Source: author's own test (October 2, 2026, /code-review high, 4 target files)
Findings
10
Confirmed real bugs
9
Cleanup suggestion
1
Every finding came back in the form "which file, which line" and "what input causes what to happen." I checked each one against the source code of the library the tool uses to read image metadata (exifr) and against test images I actually built, then fixed all 9 that turned out to be real. The main ones:
| Type of finding | What it was |
|---|---|
| Wrong assumptions about a library | The image comment field (UserComment), the Windows comment fields, and WebP camera data weren't actually being read (caused by the library's default settings and the formats it supports) |
| A gap in the verdict logic | One combination could show the record of a different image used as an ingredient as a trusted organization's signature |
| Stuck with no way back | If the network stalled, loading the library had no timeout and stayed on "Loading" forever |
| Concurrent processing | Dropping images in quick succession ran two images' processing in parallel, and the results could get mixed |
| Large files | For large PNGs, it stopped reading before reaching data written near the end |
| String handling | Special characters in strings read from an image could break the displayed text |
So even right after I'd searched and fixed things myself, 9 bugs of a different kind were still there. The findings about assumptions ("the library should behave like this") in particular were hard to spot without reading the library's source. That said, this is the result of one run on one codebase. It won't necessarily find real bugs at the same rate every time, and I didn't compare it with low, medium, or max, or try the paid ultra.
10. Downsides and caveats
From using it and reading the official docs, here are five things to watch out for:
- It uses your limits. Local reviews also come out of your normal Claude usage, and higher levels use more. With ultra, once Pro, Max, and Ultra users use up the 3 free runs (Team and Enterprise from the start), you pay roughly $5–25 per run in usage credits.
- Don't take findings at face value. The docs themselves describe the level as a trade-off between coverage and confidence, with medium and above broadening coverage. This time 9 of 10 were real, but checking each one still takes work.
--fixcan't be undone with/rewind. Changes made in the background have to be reverted with git, so commit before you use it.- It only checks code correctness. It doesn't check whether prose or configuration content matches the facts. For example, whether the wording in an article or description matches the official spec is out of scope.
- Claude may start it on its own. If you don't want that, the setting in section 7 limits it to manual runs.
My take: running it once at high after writing new code or making a big change was the use that justified the effort and the usage. On the other hand, it isn't suited to prose edits or small configuration changes.
Summary
/code-review is a bundled skill that reviews your local diff or a PR, focused on correctness bugs. It runs in the background so it doesn't interrupt your work, and its cost stays within your normal usage. At low you get only high-confidence findings; at medium to max it casts a wider net but you need to sort the results; and if you leave the level out, it reuses the last one you typed.
--fix, which goes as far as fixing, is convenient, but background edits can't be undone with /rewind, so committing first is the safe move. When you want to look deeper, ultra spends about 15 to 25 minutes in the cloud and returns only verified findings; Pro, Max, and Ultra get 3 one-time free runs, after which it costs roughly $5–25 per run in usage credits. The similarly named GitHub App Code Review and claude-code-action are different things, both in where they run and in what they cost.
When I ran it once on this site's code, 9 of its 10 findings were real bugs, even right after I'd fixed things myself. You do need to check each finding, but it's well worth running once after new code or a big change.
FAQ
Q. What's the difference between /review and /code-review?
A. They're the same now. /review is an alias of /code-review and takes the same levels and flags. According to the official docs, before v2.1.223 /review was a separate, read-only command that did a single-pass review of a GitHub PR.
Q. Does using /code-review cost extra?
A. Not at low to max. In the comparison table in the official docs, its cost "counts toward normal usage." The one that costs extra is ultra: after the 3 free runs on Pro, Max, and Ultra, it's roughly $5–25 per run in usage credits.
Q. Do ultra's 3 free runs reset every month?
A. No. The official docs describe the three Pro, Max, and Ultra runs as "a one-time allotment per account" that "don't refresh." Reviews you stop partway or that fail still count as one run. Team and Enterprise get no free runs.
Q. Can I undo changes made by --fix?
A. Use git. Edits from a review that ran in the background happen outside your checkpoints, so /rewind doesn't undo them. If the review ran in the foreground (an earlier review still running, -p, and so on), /rewind can restore them. If in doubt, commit before using --fix.
Q. Do rules in REVIEW.md apply to /code-review?
A. No. The local /code-review follows CLAUDE.md but doesn't read REVIEW.md. REVIEW.md is the instruction file for the GitHub App version of Code Review. Put rules you want the local review to follow in CLAUDE.md.
Sources
- Claude Code official docs: Review locally with /code-review
- Claude Code official docs: Code Review and Code Review costs and usage
- Anthropic: Code Review is now generally available (October 15, 2026)
- Claude Code official docs: Find bugs with ultrareview
- Claude Code official docs: Commands
- Claude Code official docs: Claude Code GitHub Actions
- Claude Code: CHANGELOG
All sources were checked against the original text on October 2, 2026 (the level descriptions and v2.1.290 in the CHANGELOG on October 14; the GitHub App version of Code Review, the duration of ultra, the PR targets, and the /code-review page on October 18). The official docs state that ultrareview is a research preview, and its features, pricing, and availability may change.