4 4
5# Code Review5# Code Review
6 6
7> Set up automated PR reviews that catch logic errors, security vulnerabilities, and regressions using multi-agent analysis of your full codebase7> Catch bugs in GitHub pull requests with Code Review: Claude reviews each change, verifies its findings, and comments inline. For Team and Enterprise plans
8 8
9<Note>9With Code Review, Claude reviews the pull requests in your GitHub repositories. Several agents read each change alongside the surrounding code, looking for issues such as logic errors, security vulnerabilities, or broken edge cases. A verification step checks findings against the code before they're reported.
10 Code Review is in research preview, available for [Team and Enterprise](https://claude.ai/admin-settings/claude-code) subscriptions. It is not available for organizations with [Zero Data Retention](/docs/en/zero-data-retention) enabled or with the [HIPAA configuration](/docs/en/hipaa-setup) applied, and is not covered under Anthropic's BAA. On other plans, you can still [review a diff locally](#review-a-diff-locally) with the `/code-review` command.
11</Note>
12
13Code Review analyzes your GitHub pull requests and posts findings as inline comments on the lines of code where it found issues. A fleet of specialized agents examine the code changes in the context of your full codebase, looking for logic errors, security vulnerabilities, broken edge cases, and subtle regressions.
14
15Findings are tagged by severity and don't approve or block your PR, so existing review workflows stay intact. You can tune what Claude flags by adding a `CLAUDE.md` or `REVIEW.md` file to your repository.
16
17To run Claude in your own CI infrastructure instead of this managed service, see [GitHub Actions](/docs/en/github-actions) or [GitLab CI/CD](/docs/en/gitlab-ci-cd). For repositories on a self-hosted GitHub instance, see [GitHub Enterprise Server](/docs/en/github-enterprise-server).
18
19This page covers:
20
21* [How reviews work](#how-reviews-work)
22* [Setup](#set-up-code-review)
23* [Triggering reviews manually](#manually-trigger-reviews) with `@claude review` and `@claude review always`
24* [Customizing reviews](#customize-reviews) with `CLAUDE.md` and `REVIEW.md`
25* [Pricing](#pricing)
26* [Troubleshooting](#troubleshooting) failed runs and missing comments
27* [Reviewing a diff locally](#review-a-diff-locally) with the `/code-review` command
28
29## How reviews work
30
31Once an Owner [enables Code Review](#set-up-code-review) for your organization, reviews trigger when a PR opens, on every push, or when manually requested, depending on the repository's configured behavior. Commenting `@claude review` [starts a review on a PR](#manually-trigger-reviews) in any mode.
32
33When a review runs, multiple agents analyze the diff and surrounding code in parallel on Anthropic infrastructure. Each agent looks for a different class of issue, then a verification step checks candidates against actual code behavior to filter out false positives. The results are deduplicated, ranked by severity, and posted as inline comments on the specific lines where issues were found, with a summary in the review body. If no issues are found, Code Review updates the GitHub check run to show that no issues were detected. Claude may also post a short confirmation comment on the PR.
34
35Reviews scale in cost with PR size and complexity, completing in 20 minutes on average. Owners can monitor review activity and spend via the [analytics dashboard](#view-usage).
36
37### Severity levels
38
39Each finding is tagged with a severity level:
40
41| Marker | Severity | Meaning |
42| :- | :- | :- |
43| 🔴 | Important | A bug that should be fixed before merging |
44| 🟡 | Nit | A minor issue, worth fixing but not blocking |
45| 🟣 | Pre-existing | A bug that exists in the codebase but was not introduced by this PR |
46
47Findings include a collapsed **Why this was flagged** section that you can expand to read why Claude flagged the issue and how it verified the problem.
48
49### Rate and reply to findings
50
51Each review comment from Claude arrives with 👍 and 👎 already attached so both buttons appear in the GitHub UI for one-click rating. Click 👍 if the finding was useful or 👎 if it was wrong or noisy. Anthropic collects reaction counts after the PR merges and uses them to tune the reviewer. Reactions do not trigger a re-review or change anything on the PR.
52
53Replying to an inline comment does not prompt Claude to respond or update the PR. To act on a finding, fix the code and push. If the PR is subscribed to push-triggered reviews, the next run resolves the thread when the issue is fixed. To request a fresh review without pushing, comment `@claude review` as a [top-level PR comment](#manually-trigger-reviews).
54
55To dismiss a finding without a code change, resolve its thread; replying doesn't dismiss it.
56
57### Check run output
58
59Beyond the inline review comments, each review populates the **Claude Code Review** check run that appears alongside your CI checks. Expand its **Details** link to see a summary of every finding in one place, sorted by severity:
60
61| Severity | File:Line | Issue |
62| - | - | - |
63| 🔴 Important | `src/auth/session.ts:142` | Token refresh races with logout, leaving stale sessions active |
64| 🟡 Nit | `src/auth/session.ts:88` | `parseExpiry` silently returns 0 on malformed input |
65
66Each finding also appears as an annotation in the **Files changed** tab, marked directly on the relevant diff lines. Important findings render with a red marker, nits with a yellow warning, and pre-existing bugs with a gray notice. Annotations and the severity table are written to the check run independently of inline review comments, so they remain available even if GitHub rejects an inline comment on a line that moved.
67
68The check run always completes with a neutral conclusion so it never blocks merging through branch protection rules. If you want to gate merges on Code Review findings, read the severity breakdown from the check run output in your own CI. The last line of the Details text is a machine-readable comment your workflow can parse with `gh` and jq. To find the check run ID, list the commit's check runs with `gh api repos/OWNER/REPO/commits/<commit-sha>/check-runs --jq '.check_runs[] | {id, name}'` and take the `id` of the `Claude Code Review` run. Replace `OWNER`, `REPO`, and `CHECK_RUN_ID` with your repository owner, repository name, and that ID:
69
70```bash theme={null}
71gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
72 --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'
73```
74
75This returns a JSON object with counts per severity, for example `{"normal": 2, "nit": 1, "pre_existing": 0}`. The `normal` key holds the count of Important findings; a non-zero value means Claude found at least one bug worth fixing before merge.
76
77### What Code Review checks
78 10
79By default, Code Review focuses on correctness: bugs that would break production, not formatting preferences or missing test coverage. You can expand what it checks by [adding guidance files](#customize-reviews) to your repository.11Findings arrive as inline comments on the lines concerned, ranked by [severity](/docs/en/code-review-pull-requests#severity-levels), with a summary and a check run on the pull request. A review never approves or blocks the pull request, so the decision to merge stays with your team.
80 12
81## Set up Code Review13<img src="https://mintcdn.com/claude-code/gLJVaPQEgKC8ZyUD/images/code-review-pipeline.svg?fit=max&auto=format&n=gLJVaPQEgKC8ZyUD&q=85&s=0351c96df9efa3105172eb00a672f130" className="dark:hidden" alt="Diagram of a review in four stages. A pull request on GitHub goes to several agents that search in parallel on Anthropic infrastructure. A verification step drops false positives, the remaining findings are deduplicated and ranked by severity, and the review posts inline comments, a summary, and a check run back on GitHub." width="760" height="300" data-path="images/code-review-pipeline.svg" />
82 14
83An Owner enables Code Review once for the organization and selects which repositories to include.15<img src="https://mintcdn.com/claude-code/gLJVaPQEgKC8ZyUD/images/code-review-pipeline-dark.svg?fit=max&auto=format&n=gLJVaPQEgKC8ZyUD&q=85&s=9cf26bde98f4e999d0d9ff5bf5bdff40" className="hidden dark:block" alt="Diagram of a review in four stages. A pull request on GitHub goes to several agents that search in parallel on Anthropic infrastructure. A verification step drops false positives, the remaining findings are deduplicated and ranked by severity, and the review posts inline comments, a summary, and a check run back on GitHub." width="760" height="300" data-path="images/code-review-pipeline-dark.svg" />
84
85<Steps>
86 <Step title="Open Claude Code admin settings">
87 Go to [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) and find the Code Review section. You need the Owner or Primary Owner role in your Claude organization and permission to install GitHub Apps in your GitHub organization.
88 </Step>
89
90 <Step title="Start setup">
91 Click **Setup**. This begins the GitHub App installation flow.
92 </Step>
93
94 <Step title="Install the Claude GitHub App">
95 Follow the prompts to install the Claude GitHub App: pick the GitHub organization that owns the repositories you want reviewed, choose which repositories the app can access, and approve the requested permissions.
96
97 To review a pull request, Claude reads your repository contents through the app's read access, and posts comments and the [check run](#check-run-output) through its write access to pull requests and checks. During installation, you grant a broader permission set shared by other Claude features, such as [GitHub Actions](/docs/en/github-actions); see [GitHub App permissions](/docs/en/github-actions#github-app-permissions) for the full list.
98 </Step>
99
100 <Step title="Select repositories">
101 Choose which repositories to enable for Code Review. If you don't see a repository, make sure you gave the Claude GitHub App access to it during installation. You can add more repositories later.
102 </Step>
103
104 <Step title="Set review triggers per repo">
105 After setup completes, the Code Review section shows your repositories in a table. For each repository, use the **Review Behavior** dropdown to choose when reviews run:
106
107 * **Once after PR creation**: review runs once when a PR is opened or marked ready for review
108 * **After every push**: review runs on every push to the PR branch, catching new issues as the PR evolves and auto-resolving threads when you fix flagged issues
109 * **Manual**: opening or pushing to a PR doesn't start a review; comment [`@claude review`](#manually-trigger-reviews) to request one, or `@claude review always` to also subscribe the PR to reviews on subsequent pushes
110
111 Whichever option you choose, Claude reviews a [pull request from a fork](#review-pull-requests-from-forks) only when someone comments `@claude review` on it.
112
113 Reviewing on every push runs the most reviews and costs the most. Manual mode is useful for high-traffic repos where you want to opt specific PRs into review, or to only start reviewing your PRs once they're ready.
114 </Step>
115</Steps>
116
117The repositories table also shows the average cost per review for each repo based on recent activity. Use the row actions menu to turn Code Review on or off per repository, or to remove a repository entirely.
118
119To verify setup, open a test PR. If you chose an automatic trigger, a check run named **Claude Code Review** appears within a few minutes. If you chose Manual, comment `@claude review` on the PR to start the first review. If no check run appears, confirm the repository is listed in your admin settings and the Claude GitHub App has access to it.
120
121## Manually trigger reviews
122
123Comment commands start a review on demand. They work regardless of the repository's configured trigger, so you can use them to opt specific PRs into review in Manual mode or to get an immediate re-review in other modes.
124
125| Command | What it does |
126| :- | :- |
127| `@claude review` | Starts a single review without subscribing the PR to future pushes |
128| `@claude review always` | Starts a review and subscribes the PR to push-triggered reviews going forward |
129| `@claude review once` | Same as `@claude review`: starts a single review without subscribing |
130
131Use `@claude review always` when you want every subsequent push to the PR to start a fresh review, such as on a high-priority PR in a repository set to Manual mode. Because the bare command doesn't subscribe the PR, you can request a one-off second opinion without changing whether later pushes trigger reviews.
132 16
133<Note>17<Note>
134 Before a July 2026 update, `@claude review` subscribed the PR to push-triggered reviews. If you relied on that behavior, comment `@claude review always` instead. `@claude review once` still works and behaves the same as the bare command.18 Code Review uses AI to review code and may miss bugs, security vulnerabilities, or other issues. A review with no findings doesn't mean your code is error-free or secure.
135</Note>19</Note>
136 20
137For any of these commands to trigger a review:21<span id="review-a-diff-locally" />
138
139* Post it as a top-level PR comment, not an inline comment on a diff line
140* Put the command at the start of the comment, with `once` or `always` on the same line as the rest of the command
141* You must have write, maintain, or admin permission on the repository
142* The PR must be open
143
144Unlike automatic triggers, manual triggers run on draft PRs, since an explicit request signals you want the review now regardless of draft status.
145
146If a review is already running on that PR, the request is queued until the in-progress review completes. You can monitor progress via the check run on the PR.
147
148### Review pull requests from forks
149
150Claude doesn't review a pull request from a fork automatically, regardless of the repository's **Review Behavior** setting. To start one, comment `@claude review` on the pull request. The [requirements for comment commands](#manually-trigger-reviews) still apply, and the write access you need is to the base repository, not the fork.
151
152To get another review of a fork pull request, post a new `@claude review` comment. `@claude review always` works too, but doesn't subscribe the pull request to reviews on later pushes. Nothing other than a comment command starts a review on a fork pull request:
153
154* Clicking **Re-run** on the check run doesn't start a review
155* Pushing new commits doesn't start a review, even in a repository set to **After every push**
156
157## Customize reviews
158
159Code Review reads two files from your repository to guide what it flags. They differ in how strongly they influence the review:
160
161* **`CLAUDE.md`**: shared project instructions that Claude Code uses for all tasks, not just reviews. Code Review reads it as project context and flags newly introduced violations as nits.
162* **`REVIEW.md`**: review-only instructions, given to the agents that find and verify findings and consulted by the agents that rank and report them. Use it to say what your team wants flagged, at what severity, and how findings are reported.
163
164### CLAUDE.md
165
166Code Review reads your repository's `CLAUDE.md` files and treats newly introduced violations as [nit-level](#severity-levels) findings. This works bidirectionally: if your PR changes code in a way that makes a `CLAUDE.md` statement outdated, Claude flags that the docs need updating too.
167 22
168Claude reads `CLAUDE.md` files at every level of your directory hierarchy, so rules in a subdirectory's `CLAUDE.md` apply only to files under that path. See the [memory documentation](/docs/en/memory) for more on how `CLAUDE.md` works.23To turn on Code Review, an Owner of your Claude organization follows [Set up Code Review](/docs/en/code-review-setup). Claude can also review code without this service. Run [`/code-review`](/docs/en/code-review-local) in your Claude Code session on any plan, or [compare all the options](#compare-ways-to-get-a-review).
169 24
170For review-specific guidance that you don't want applied to general Claude Code sessions, use [`REVIEW.md`](#review-md) instead.25## Availability
171 26
172### REVIEW\.md27Check that your organization qualifies before you set up Code Review:
173 28
174`REVIEW.md` is a file at your repository root that tailors Code Review to your repo. The agents in the review pipeline that find and verify findings receive its contents as your repository's review instructions, alongside Code Review's default review guidance, and the agents that rank and report findings consult it before settling severity and writing the review.29* **Plans**: [Team and Enterprise](/docs/en/feature-availability)
30* **Code hosts**: repositories hosted on GitHub, including [GitHub Enterprise Server](/docs/en/github-enterprise-server) and GitHub Enterprise Cloud with data residency. For data residency, have an Owner follow the [GitHub Enterprise Server admin setup](/docs/en/github-enterprise-server#admin-setup) and enter your enterprise's `ghe.com` hostname.
31* **Data retention**: Code Review isn't available to organizations with [Zero Data Retention](/docs/en/zero-data-retention) enabled or with the [HIPAA configuration](/docs/en/hipaa-setup) applied, and isn't covered under Anthropic's Business Associate Agreement (BAA).
32* **Encryption keys**: Code Review isn't yet available for organizations that use customer-managed encryption keys (CMEK).
33* **Cloud providers**: you need a Claude organization on one of these plans even if your developers use Claude Code through Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry
175 34
176Put the rules you want enforced directly in `REVIEW.md`.35## Set up and use Code Review
177 36
178#### What you can tune37<span id="set-up-code-review" />
179 38
180`REVIEW.md` is freeform markdown, so anything you can express as a review instruction is in scope. The patterns below have the most impact in practice.39<span id="pricing" />
181 40
182**Severity**: redefine what 🔴 Important means for your repo. The default calibration targets production code; a docs repo, a config repo, or a prototype might want a much narrower definition. State explicitly which classes of finding are Important and which are Nit at most. You can also escalate in the other direction, for example treating any `CLAUDE.md` violation as Important rather than the default nit.41<span id="manually-trigger-reviews" />
183 42
184**Nit volume**: cap how many 🟡 Nit comments a single review posts. Prose and config files can be polished forever. A cap like "report at most five nits, mention the rest as a count in the summary" keeps reviews actionable.43<span id="customize-reviews" />
185 44
186**Skip rules**: list paths, branch patterns, and finding categories where Claude should post no findings. Common candidates are generated code, lockfiles, vendored dependencies, and machine-authored branches, along with anything your CI already enforces like linting or spellcheck. For paths that warrant some review but not full scrutiny, set a higher bar instead of skipping entirely: "in `scripts/`, only report if near-certain and severe."45<span id="troubleshooting" />
187 46
188**Repo-specific checks**: add rules you want flagged on every PR, like "new API routes must have an integration test." Because `REVIEW.md` reaches every finding and verification agent directly, these land more reliably than the same rules in a long `CLAUDE.md`.47Pick the page for what you need to do:
189 48
190**Verification bar**: require evidence before a class of finding is posted. For example, "behavior claims need a `file:line` citation in the source, not an inference from naming" cuts false positives that would otherwise cost the author a round trip.49<CardGroup cols={2}>
50 <Card title="Set up Code Review" icon="toggle-on" href="/docs/en/code-review-setup">
51 Check the requirements, install the Claude GitHub App, and choose repositories, a review level, and when reviews run
52 </Card>
191 53
192**Re-review convergence**: tell Claude how to behave when a PR has already been reviewed. A rule like "after the first review, suppress new nits and post Important findings only" stops a one-line fix from reaching round seven on style alone.54 <Card title="Customize Code Review" icon="sliders" href="/docs/en/code-review-customize">
55 Tune what gets flagged with `REVIEW.md` and `CLAUDE.md` files in your repository
56 </Card>
193 57
194**Summary shape**: ask for the review body to open with a one-line tally such as `2 factual, 4 style`, and to lead with "no factual issues" when that's the case. The author wants to know the shape of the work before the details.58 <Card title="Read and request reviews on a pull request" icon="code-pull-request" href="/docs/en/code-review-pull-requests">
59 Read the findings and their severities, and request another review with a comment
60 </Card>
195 61
196#### Example62 <Card title="Troubleshoot Code Review" icon="wrench" href="/docs/en/code-review-troubleshooting">
63 Fix a review that didn't start, failed, or was skipped for budget
64 </Card>
197 65
198This `REVIEW.md` recalibrates severity for a backend service, caps nits, skips generated files, and adds repo-specific checks.66 <Card title="Code Review costs and usage" icon="chart-line" href="/docs/en/code-review-costs">
67 See how reviews are billed, estimate spend, set the monthly spend limit, and track review activity
68 </Card>
69</CardGroup>
199 70
200```markdown theme={null}71## How reviews work
201# Review instructions
202
203## What Important means here
204
205Reserve Important for findings that would break behavior, leak data,
206or block a rollback: incorrect logic, unscoped database queries, PII
207in logs or error messages, and migrations that aren't backward
208compatible. Style, naming, and refactoring suggestions are Nit at
209most.
210
211## Cap the nits
212
213Report at most five Nits per review. If you found more, say "plus N
214similar items" in the summary instead of posting them inline. If
215everything you found is a Nit, lead the summary with "No blocking
216issues."
217
218## Do not report
219
220- Anything CI already enforces: lint, formatting, type errors
221- Generated files under `src/gen/` and any `*.lock` file
222- Test-only code that intentionally violates production rules
223
224## Always check
225
226- New API routes have an integration test
227- Log lines don't include email addresses, user IDs, or request bodies
228- Database queries are scoped to the caller's tenant
229```
230
231#### Keep it focused
232
233Length has a cost: a long `REVIEW.md` dilutes the rules that matter most. Keep it to instructions that change review behavior, and leave general project context in `CLAUDE.md`.
234
235## View usage
236
237Go to [claude.ai/analytics/code-review](https://claude.ai/analytics/code-review) to see Code Review activity across your organization. The dashboard shows:
238
239| Section | What it shows |
240| :- | :- |
241| PRs reviewed | Daily count of pull requests reviewed over the selected time range |
242| Code Review cost | Code Review spend so far this month |
243| Feedback | Count of review comments that were auto-resolved because a developer addressed the issue |
244| Repository breakdown | Per-repo counts of PRs reviewed, comments resolved, and review runs, with estimated cost and a per-PR view |
245
246The Code Review cost card shows an amount only when the current month is selected. Cost figures in analytics can differ from your invoice. Repository breakdown costs are estimated at list price, before any discounts or credits, and cover only reviews that Claude posted on a pull request. For invoice-accurate spend, refer to your Anthropic bill.
247
248## Pricing
249
250Code Review is billed based on token usage. Each review averages \$15-25 in cost, scaling with PR size, codebase complexity, and how many issues require verification. Code Review usage is billed separately through [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) and does not count against your plan's included usage.
251
252The review trigger you choose affects total cost:
253
254* **Once after PR creation**: runs once per PR
255* **After every push**: runs on each push, multiplying cost by the number of pushes
256* **Manual**: no reviews on open or push, so cost accrues only from reviews someone requests
257
258In Once after PR creation or Manual mode, commenting `@claude review always` [opts the PR into push-triggered reviews](#manually-trigger-reviews), so additional cost accrues per push after that comment. In After every push mode, pushes already trigger reviews, so the subscription doesn't change per-push cost. Commenting `@claude review` runs a single review without subscribing to future pushes. Claude reviews a [pull request from a fork](#review-pull-requests-from-forks) only when someone comments `@claude review`, so a fork pull request never accrues per-push cost in any mode.
259
260Costs appear on your Anthropic bill regardless of whether your organization uses Amazon Bedrock or Google Cloud's Agent Platform for other Claude Code features. To set a monthly spend cap for Code Review, go to [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage) and configure the limit for the Claude Code Review service.
261
262To monitor spend, use the [analytics dashboard](#view-usage).
263
264## Troubleshooting
265
266Review runs are best-effort, and a failed run never blocks your PR. Code Review retries some interrupted reviews on its own. This section covers how to run a review again yourself and where to look when the check run reports issues you can't find.
267
268### Retrigger a failed or timed-out review
269
270When a review fails or exceeds its time limit, the check run completes with a title such as **Code review failed** or **Code review timed out**. The conclusion is still neutral, so nothing blocks your merge. Unless the check run's summary says a new review of the commit has been queued automatically, run the review again yourself.
271
272To run the review again, comment `@claude review` on the PR. This starts a fresh review without subscribing the PR to future pushes. If the PR isn't [from a fork](#review-pull-requests-from-forks), you can instead click **Re-run** on the **Claude Code Review** check in GitHub's Checks tab. A re-run also starts a fresh review without subscribing the PR.
273
274### Review didn't run and the PR shows a budget message
275
276When your organization's monthly spend cap for Code Review is reached or its usage-credits balance is used up, Code Review skips the review and posts a single comment on the PR. The comment and the check-run card both name the cause and link the admin page where an admin fixes it:
277
278* **Spend cap reached**: reviews resume at the start of the next billing period, or immediately after an admin raises the cap at [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage)
279* **Usage credits used up**: reviews resume once an admin adds more [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) at [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage)
280
281### Find issues that aren't showing as inline comments
282
283If the check run title says issues were found but you don't see inline review comments on the diff, look in these other locations where findings are surfaced:
284
285* **Check run Details**: click **Details** next to the Claude Code Review check in the Checks tab. The severity table lists every finding with its file, line, and summary regardless of whether the inline comment was accepted.
286* **Files changed annotations**: open the **Files changed** tab on the PR. Findings render as annotations attached directly to the diff lines, separate from review comments.
287* **Review body**: if you pushed to the PR while a review was running, some findings may reference lines that no longer exist in the current diff. Those appear under an **Additional findings** heading in the review body text rather than as inline comments.
288
289## Review a diff locally
290
291The [`/code-review` command](/docs/en/commands) reviews a diff in your terminal without installing the GitHub App. It reports correctness bugs. Depending on your model and effort level, the review also covers reuse, simplification, and efficiency cleanups.
292
293`/review` is an alias of `/code-review`; before v2.1.223, it was a separate command that ran a single-pass, read-only review of a GitHub pull request.
294
295<Steps>
296 <Step title="Run /code-review">
297 From the session where you're working, run the command:
298
299 ```text theme={null}
300 /code-review
301 ```
302
303 It reviews your branch's commits ahead of its upstream plus any uncommitted changes, so it needs work on the branch or in the working tree to have something to report. To review something else, pass a target: a file path, a PR number, a branch name, or a ref range such as `main...my-feature`.
304
305 You can also add flags:
306
307 * `--fix`: applies the findings to your working tree after the review
308 * `--comment`: posts the findings on a GitHub pull request as inline comments, or on a GitLab merge request as a single note
309 * `--post`: on an `ultra` cloud review of a `github.com` pull request, preselects posting the finished findings to the PR in the launch dialog; see [Post findings to the pull request](/docs/en/ultrareview#post-findings-to-the-pull-request). Requires Claude Code v2.1.227 or later
310 * `--max-findings <n>`, `--max-findings all`, or `--max-findings default`: reports up to `n` findings, or every finding with `all`, in place of the review's usual limit. Later reviews reuse the value you typed until you pass `--max-findings default`. Requires Claude Code v2.1.288 or later
311
312 When you pass `--comment` for a GitLab merge request, Claude Code posts the findings through GitLab's `glab` CLI. Requires Claude Code v2.1.257 or later. When `glab` isn't installed, Claude prints the findings in the terminal instead.
313
314 Pass the merge request as its URL or a `!123` reference. Claude Code treats a bare number or branch name as a merge request only when the checkout's origin is on `gitlab.com`. On a self-managed GitLab instance, pass the URL or `!123` form.
315 </Step>
316
317 <Step title="Keep working">
318 The review runs as a background [subagent](/docs/en/sub-agents) with its own context window, so it doesn't fill your conversation. The findings arrive in your conversation when the review completes.
319 </Step>
320
321 <Step title="Act on the findings">
322 Ask Claude to fix what the review found. If you passed `--fix` or `--comment`, the review has already applied or posted its findings.
323 </Step>
324</Steps>
325
326Claude reports the findings as text in the reply in both of these runs, even when a host application requests a findings list:
327
328* In a terminal session, where `/code-review` runs the review as a [forked subagent](/docs/en/skills#run-skills-in-a-subagent)
329* In a `-p` run with text or JSON output
330
331In a host application that requests the findings list, such as the [desktop app](/docs/en/desktop#review-your-code), Claude reports the review's findings through the [`ReportFindings` tool](/docs/en/tools-reference) instead. Claude Code renders the report as a findings list, and each entry shows the file location, a one-sentence summary, and a category tag such as `correctness` when the finding carries one. A host request applies at every effort level and requires Claude Code v2.1.218 or later.
332
333When Claude fixes reported findings later in the session, it reports them again, and Claude Code marks each finding in the updated findings list as fixed, skipped, or no change needed.
334
335### What the review reads and edits
336
337The review follows your `CLAUDE.md` like any Claude Code session, but it doesn't read [`REVIEW.md`](#review-md). A background review applies its `--fix` edits outside your session's [checkpoints](/docs/en/checkpointing#subagent-edits-not-restored), so `/rewind` doesn't undo them; use git to revert them. When the review [runs in the foreground](#run-in-the-foreground), it edits your working tree during your own turn, so `/rewind` restores its edits as usual.
338
339### Tune effort and arguments
340 72
341Pass an [effort level](/docs/en/model-config#adjust-effort-level) to trade coverage for confidence. At `low`, the review reports the findings it's most confident in, so you see fewer false positives. From `medium` through `max`, the review broadens coverage.73<span id="what-code-review-checks" />
342 74
343When you don't type a level, the review reuses the last level from `low` through `max` you typed, even in an earlier session, and Claude Code shows a notice such as `Reusing high effort, the level you typed last time`. Type a level, like `/code-review high`, to change what later runs reuse; a level you pass in a non-interactive `-p` run doesn't update it. `ultra` neither updates nor uses the remembered level. If you've never typed a level, the review uses the session's current effort. Before v2.1.223, a `/code-review` without a level always used the session's current effort.75By default, Code Review focuses on correctness: bugs that would break production, not formatting preferences or missing test coverage. To change what it flags, [add guidance files](/docs/en/code-review-customize) to your repository.
344 76
345After the effort level and flags, Claude Code reads the rest of the line in one of two ways:77A review runs on Anthropic infrastructure in four stages:
346 78
347* **Without `ultra`**: everything left is the review target, even when it starts with another command name. `/code-review /fix-issue 123` reviews with `/fix-issue 123` as target text instead of loading `/fix-issue` as a second [stacked skill](/docs/en/skills#pass-arguments-to-skills). Before v2.1.218, a command stacked after `/code-review` expanded as its own skill.791. **Find**: several agents examine the diff and the surrounding code in parallel.
348* **With `ultra`**: Claude Code reads a single word as a base branch or PR number, and turns longer text that doesn't name a branch or PR into [a note attached to the review](/docs/en/ultrareview#pass-a-request-in-plain-words). `/code-review ultra check my auth changes` reviews your current branch, and Claude relates the findings to your note.802. **Verify**: a verification step checks the candidate findings against the code and filters out false positives.
813. **Rank**: the findings that remain are deduplicated and ranked by severity.
824. **Post**: the review posts its results on the pull request.
349 83
350### Run in the foreground84Each review leaves these on the pull request:
351 85
352The review runs in the background by default; before v2.1.218, it ran inside your conversation. It runs in the foreground instead in cases like these:86* **Findings**: inline comments on the lines concerned, with a summary in the review body
87* **A check run**: named **Claude Code Review**, with the findings listed in its [details](/docs/en/code-review-pull-requests#check-run-output). The check run doesn't conclude as a failure.
88* **When it finds nothing**: the check run's title reads **Code review found no issues**, and Claude posts the same short note on the pull request
353 89
354* You run `/code-review` again while an earlier review is still in progress90Code Review chooses the Claude models that reviews run on, and its admin settings don't offer a model choice. To make reviews more or less thorough, change the [review level](#review-levels).
355* You run it in non-interactive mode, with the `-p` flag or the Agent SDK; Claude Code waits for the review and includes the findings in the response, except for `ultra`, which [doesn't wait for the cloud review](/docs/en/ultrareview#run-ultrareview-non-interactively)
356* You set [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/en/env-vars) to `1`, which also turns off every other background task feature
357 91
358### Let Claude start the review92After an Owner turns on Code Review, each repository has a setting for [when reviews run](/docs/en/code-review-setup#set-when-reviews-run): once when a pull request opens, after every push, or only on request. Whichever it is, someone with write access to the repository can comment `@claude review` on a pull request to [start a review](/docs/en/code-review-pull-requests#comment-commands).
359 93
360Claude can start `/code-review` on its own. Ask it to review your changes in plain language and it can run the skill without you typing the command, and a [scheduled task](/docs/en/scheduled-tasks) with `/code-review` as its prompt runs the review.94### Review levels
361 95
362A scheduled task never launches the [cloud review](#escalate-to-ultrareview), so schedule `/code-review` without the `ultra` argument.96The review level sets how thorough each review is, and a more thorough review costs more:
363 97
364To stop both Claude and scheduled tasks from starting the review while keeping `/code-review` available for you to type, add a [`skillOverrides`](/docs/en/skills#override-skill-visibility-from-settings) entry to a [settings file](/docs/en/settings#where-settings-live) such as `~/.claude/settings.json`:98* **Quick**: a lighter pass. The fastest level, at the lowest cost.
99* **Standard**: balanced depth, speed, and cost. The default level.
100* **Deep**: the most thorough pass. Takes the longest and costs the most.
365 101
366```json theme={null}102An Owner [chooses one level for the organization](/docs/en/code-review-setup#set-the-default-review-level) and can give an individual repository its own, such as Quick for a routine codebase and Deep for a critical one. For what else drives the cost of each review, see [Code Review costs and usage](/docs/en/code-review-costs).
367{
368 "skillOverrides": {
369 "code-review": "user-invocable-only"
370 }
371}
372```
373 103
374Before v2.1.246, Claude started `/code-review` on its own only where a feature flag fetched from Anthropic turned it on. In [sessions that don't fetch feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching), `/code-review` ran only when you typed it, and a scheduled `/code-review` reached Claude as plain text.104### What a review can access
375 105
376### Escalate to ultrareview106A review reaches your repository through the Claude GitHub App that an Owner [installs during setup](/docs/en/code-review-setup#turn-on-code-review):
377 107
378`/code-review ultra --fix` runs the deeper [ultrareview](/docs/en/ultrareview) in the cloud, then applies its findings to your working tree when they arrive back in your session.108* **Where it runs**: on Anthropic infrastructure, in a managed environment. Reviews don't run in [self-hosted environments](/docs/en/self-hosted-environments).
109* **What it reads and writes**: inside a review, access to your repository is read-only, and a review doesn't push commits. On the pull request, it posts comments and the [check run](/docs/en/code-review-pull-requests#check-run-output), resolves its own earlier comment threads, and can react to a comment command with 👀. The app itself holds a [broader permission set](/docs/en/github-actions#github-app-permissions) that other Claude features share.
110* **How it examines your code**: a review works from reading the diff and the surrounding code, without building or running your code.
379 111
380Ultrareview uses its own scope: your current branch against the repository's default branch, plus uncommitted and staged changes in the working tree. For uncommitted changes to files named like credentials or keys, such as `.env` and `*.tfvars` files, Claude Code follows the rules for [uploading a local repository to a cloud session](/docs/en/claude-code-on-the-web#send-local-repositories-without-github). Pass a branch name, such as `/code-review ultra develop`, to compare against a different base.112### Who controls a review
381 113
382When the target is a `github.com` pull request, you can have Claude [post the finished findings to the PR](/docs/en/ultrareview#post-findings-to-the-pull-request) as a comment from your GitHub account. Requires Claude Code v2.1.227 or later.114* **Who can start one**: where reviews run automatically, opening or pushing to a pull request starts a review, [except on drafts and forks](/docs/en/code-review-pull-requests#review-drafts-and-pull-requests-from-forks). A [comment command](/docs/en/code-review-pull-requests#comment-commands) starts one only when it comes from a person with write access to the repository.
115* **Which instructions it follows**: `REVIEW.md` from the base or default branch and [never from the pull request's own changes](/docs/en/code-review-customize#which-branch-review-md-is-read-from).
383 116
384<Note>117## Compare ways to get a review
385 Ultrareview requires authentication with a claude.ai account and is not available on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, or to organizations with Zero Data Retention enabled or with the [HIPAA configuration](/docs/en/hipaa-setup) applied. When ultrareview is not available, `/code-review ultra` runs a local review in your session instead.
386</Note>
387 118
388To run a cloud review from a script or CI job, use the [`claude ultrareview` subcommand](/docs/en/ultrareview#run-ultrareview-non-interactively), which waits for the findings and prints them to stdout.119To find the options open to you, check the **Who can use it** column against your plan and code host:
389 120
390The command was named `/simplify` before v2.1.147, when it applied fixes by default. `/simplify` runs a separate cleanup-only review that applies fixes without hunting for bugs. If you scripted `/simplify` for bug-finding, switch to `/code-review --fix`.121| Option | What starts a review | Where it runs | Who can use it |
122| :- | :- | :- | :- |
123| [Code Review](#how-reviews-work) | Pull request activity, as each repository is set, or an `@claude review` comment | Anthropic infrastructure | Organizations on a Team or Enterprise plan with GitHub repositories, once an Owner turns it on |
124| [`/code-review`](/docs/en/code-review-local) | You run the command on your branch | Your Claude Code session | Anyone, on any plan |
125| [Ultrareview](/docs/en/ultrareview) | You start it from Claude Code | A cloud sandbox | Requires signing in with a claude.ai account. See [Ultrareview](/docs/en/ultrareview) for where it isn't available |
126| Claude in your own CI, with [GitHub Actions](/docs/en/github-actions) or [GitLab CI/CD](/docs/en/gitlab-ci-cd) | Your pipeline's events, such as every pull request or merge request | Your own CI runners | Anyone with a Claude API key or cloud provider credentials, on GitHub or GitLab |
127| Your own reviewer, as a [subagent](/docs/en/sub-agents) or [skill](/docs/en/skills) | You or Claude invoke it during a session | Wherever you run Claude Code | Anyone who writes one |
391 128
392## Related resources129## Related resources
393 130
394* [Commands](/docs/en/commands): run `/code-review` in a local Claude Code session to check a diff before pushing131* [GitHub Enterprise Server](/docs/en/github-enterprise-server): use Code Review with a self-hosted GitHub instance
395* [GitHub Actions](/docs/en/github-actions): run Claude in your own GitHub Actions workflows for custom automation beyond code review132* [GitHub App permissions](/docs/en/github-actions#github-app-permissions): the full permission set the Claude GitHub App requests
396* [GitLab CI/CD](/docs/en/gitlab-ci-cd): self-hosted Claude integration for GitLab pipelines
397* [Memory](/docs/en/memory): how `CLAUDE.md` files work across Claude Code
398* [Analytics](/docs/en/analytics): track Claude Code usage beyond code review
399* [How Anthropic secures its AI-native software development lifecycle](https://claude.com/blog/how-anthropic-secures-its-ai-native-software-development-lifecycle): how automated review fits as one layer of Anthropic's secure development process133* [How Anthropic secures its AI-native software development lifecycle](https://claude.com/blog/how-anthropic-secures-its-ai-native-software-development-lifecycle): how automated review fits as one layer of Anthropic's secure development process
