Documentation — Spybara

agent-sdk/file-checkpointing.md +1 −1

Details

622| Limitation | Description |622| Limitation | Description |

623| - | - |623| - | - |

624| Write/Edit/NotebookEdit tools only | Changes made through Bash commands are not tracked |624| Write/Edit/NotebookEdit tools only | Changes made through Bash commands are not tracked |

625| Subagent edits | Edits a [subagent](/docs/en/agent-sdk/subagents) applies aren't tracked or restored, except a skill with `context: fork` running in the foreground; use git to revert untracked edits |625| Subagent edits | Edits a [subagent](/docs/en/agent-sdk/subagents) applies aren't tracked, except a skill with `context: fork` running in the foreground. A rewind reverts them only in files the main conversation had already edited; use git to revert the rest |

626| Same session | Checkpoints are tied to the session that created them |626| Same session | Checkpoints are tied to the session that created them |

627| File content only | Creating, moving, or deleting directories is not undone by rewinding |627| File content only | Creating, moving, or deleting directories is not undone by rewinding |

628| Local files | Remote or network files are not tracked |628| Local files | Remote or network files are not tracked |

agent-sdk/observability.md +4 −0

Details

17 17

18This guide explains how the SDK emits telemetry, how to configure the export, and how to tag and filter the data once it reaches your backend. To read token usage and cost directly from the SDK response stream instead of exporting to a backend, see [Track cost and usage](/docs/en/agent-sdk/cost-tracking).18This guide explains how the SDK emits telemetry, how to configure the export, and how to tag and filter the data once it reaches your backend. To read token usage and cost directly from the SDK response stream instead of exporting to a backend, see [Track cost and usage](/docs/en/agent-sdk/cost-tracking).

19 19

20<Note>

21 For the Claude API or Managed Agents, see [OpenTelemetry for the Claude API](https://platform.claude.com/docs/en/manage-claude/opentelemetry).

22</Note>

20## How telemetry flows from the SDK24## How telemetry flows from the SDK

21 25

22The Agent SDK runs the Claude Code CLI as a child process and communicates with it over a local pipe. The CLI has OpenTelemetry instrumentation built in: it records spans around each model request and tool execution, emits metrics for token and cost counters, and emits structured log events for prompts and tool results. The SDK does not produce telemetry of its own. Instead, it passes configuration through to the CLI process, and the CLI exports directly to your collector.26The Agent SDK runs the Claude Code CLI as a child process and communicates with it over a local pipe. The CLI has OpenTelemetry instrumentation built in: it records spans around each model request and tool execution, emits metrics for token and cost counters, and emits structured log events for prompts and tool results. The SDK does not produce telemetry of its own. Instead, it passes configuration through to the CLI process, and the CLI exports directly to your collector.

analytics.md +2 −0

Details

13| Claude for Teams / Enterprise | [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code) | Usage metrics, contribution metrics with GitHub integration, leaderboard, data export | [Details](#access-analytics-for-team-and-enterprise) |13| Claude for Teams / Enterprise | [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code) | Usage metrics, contribution metrics with GitHub integration, leaderboard, data export | [Details](#access-analytics-for-team-and-enterprise) |

15 15

16Code Review has its own dashboard. For review activity and spend, see [View usage](/docs/en/code-review-costs#view-usage).

16## Access analytics for Team and Enterprise18## Access analytics for Team and Enterprise

17 19

18Navigate to [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code). Admins and Owners can view the dashboard.20Navigate to [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code). Admins and Owners can view the dashboard.

artifacts.md +5 −3

Details

67| The session is in [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode) | Asks before the first publish of each artifact |67| The session is in [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode) | Asks before the first publish of each artifact |

68| The publish declares runtime capabilities for the page, such as [connector calls](#pull-live-data-with-mcp-connectors) or [file downloads](#offer-a-file-download) | Asks before that publish |68| The publish declares runtime capabilities for the page, such as [connector calls](#pull-live-data-with-mcp-connectors) or [file downloads](#offer-a-file-download) | Asks before that publish |

69| You shared the artifact publicly | Asks once per conversation before changing it |69| You shared the artifact publicly | Asks once per conversation before changing it |

~~70| You turned [feature-flag fetching](/docs/en/env-vars#features-that-need-feature-flag-fetching) off | Asks before the first publish of each artifact |~~

71| Claude publishes in a turn that a [scheduled task](/docs/en/scheduled-tasks) firing in your session started, rather than a prompt you typed | Asks before the first publish of each artifact |70| Claude publishes in a turn that a [scheduled task](/docs/en/scheduled-tasks) firing in your session started, rather than a prompt you typed | Asks before the first publish of each artifact |

72| Claude can't read the file without your approval | Asks before publishing it. An allow rule for the `Artifact` tool doesn't skip this prompt |71| Claude can't read the file without your approval | Asks before publishing it. An allow rule for the `Artifact` tool doesn't skip this prompt |

72| In [Manual](/docs/en/permission-modes) or `acceptEdits` mode, Claude makes a small change to an artifact's file it can't edit without your approval, such as a project file in Manual mode | Asks before publishing the change. You're asked even if an allow rule covers the `Artifact` tool, because the edit to the file needs your approval |

73 73

74Claude reads files in your session's [working directories](/docs/en/permissions#working-directories), and in the temporary directory it writes pages to, without asking. To let Claude publish from another folder without the prompt, add the folder as a working directory with [`--add-dir`](/docs/en/cli-reference#cli-flags) at launch or `/add-dir` during the session.74To let Claude read a file outside your [working directories](/docs/en/permissions#working-directories) without your approval, add its folder as a working directory with [`--add-dir`](/docs/en/cli-reference#cli-flags) at launch or `/add-dir` during the session. Claude already reads files in those directories, and in the temporary directory it writes pages to, without asking.

76If a publish prompt includes a sentence such as `Also makes 1 edit to that file on disk.`, Claude is changing the artifact's file and publishing it in one step. When you approve the prompt, Claude Code publishes the page, then writes the change to your file.

75 77

76## Update an artifact78## Update an artifact

77 79

131* **Cloud session without network access**: for a [cloud environment](/docs/en/cloud-environments#access-levels), that's the **None** level. In [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode), the classifier can approve instead; in a [Cowork](https://claude.com/product/cowork) session, the approval is yours alone.133* **Cloud session without network access**: for a [cloud environment](/docs/en/cloud-environments#access-levels), that's the **None** level. In [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode), the classifier can approve instead; in a [Cowork](https://claude.com/product/cowork) session, the approval is yours alone.

132* **Another organization's public artifact**: Claude Code asks you first, even in auto mode. Where Claude Code can't ask you, such as in `bypassPermissions` mode, Claude can't read the artifact. Claude can read these artifacts only while [feature-flag fetching](/docs/en/env-vars#features-that-need-feature-flag-fetching) is on.134* **Another organization's public artifact**: Claude Code asks you first, even in auto mode. Where Claude Code can't ask you, such as in `bypassPermissions` mode, Claude can't read the artifact. Claude can read these artifacts only while [feature-flag fetching](/docs/en/env-vars#features-that-need-feature-flag-fetching) is on.

133* **Unconfirmed owner or network setting**: when Claude Code can't confirm who made the artifact, or can't confirm a cloud session's network setting, it asks, and your approval covers that one request.135* **Unconfirmed owner or network setting**: when Claude Code can't confirm who made the artifact, or can't confirm a cloud session's network setting, it asks, and your approval covers that one request.

134* **Plan mode, or feature-flag fetching turned off**: in [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode), or if you turned [feature-flag fetching](/docs/en/env-vars#features-that-need-feature-flag-fetching) off, Claude Code asks before the Artifact tool reads an artifact someone else in your organization made.136* **Plan mode**: in [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode), Claude Code asks before the Artifact tool reads an artifact someone else in your organization made.

135 137

136When Claude reads the artifact with WebFetch, WebFetch's own [prompting rules](/docs/en/tools-reference#webfetch-tool-behavior) still apply.138When Claude reads the artifact with WebFetch, WebFetch's own [prompting rules](/docs/en/tools-reference#webfetch-tool-behavior) still apply.

137 139

checkpointing.md +1 −1

Details

84A [subagent](/docs/en/sub-agents) makes edits with Claude's file editing tools, but Claude Code usually doesn't capture those edits in your session's checkpoints. Whether rewinding restores them depends on how the subagent runs:84A [subagent](/docs/en/sub-agents) makes edits with Claude's file editing tools, but Claude Code usually doesn't capture those edits in your session's checkpoints. Whether rewinding restores them depends on how the subagent runs:

85 85

86* **Foreground forked skill**: a [skill with `context: fork`](/docs/en/skills#run-skills-in-a-subagent) that runs in the foreground edits your working tree during your own turn, so rewinding restores its edits as usual. Set `background: false` to run a fork in the foreground; a few situations, [listed on the skills page](/docs/en/skills#run-skills-in-a-subagent), run it there regardless of the setting.86* **Foreground forked skill**: a [skill with `context: fork`](/docs/en/skills#run-skills-in-a-subagent) that runs in the foreground edits your working tree during your own turn, so rewinding restores its edits as usual. Set `background: false` to run a fork in the foreground; a few situations, [listed on the skills page](/docs/en/skills#run-skills-in-a-subagent), run it there regardless of the setting.

87* **Any other subagent**: rewinding doesn't restore the edits. Use git to revert them. This includes a forked skill that runs in the background, the default, and a background [`/code-review --fix`](/docs/en/code-review) run.87* **Any other subagent**: rewinding restores only the files Claude had already edited in your conversation. The subagent's edits to other files stay, so use git to revert them. This includes a forked skill that runs in the background, the default, and a background [`/code-review --fix`](/docs/en/code-review-local) run.

88 88

89### External changes not tracked89### External changes not tracked

90 90

claude-code-on-the-web.md +1 −1

Details

60See [Connect from your terminal](/docs/en/web-quickstart#connect-from-your-terminal) for the `/web-setup` walkthrough, including what `/web-setup` stores and how to remove it.60See [Connect from your terminal](/docs/en/web-quickstart#connect-from-your-terminal) for the `/web-setup` walkthrough, including what `/web-setup` stores and how to remove it.

61 61

62<Note>62<Note>

63 Organizations with [Zero Data Retention](/docs/en/zero-data-retention) enabled, or with the [HIPAA configuration](/docs/en/hipaa-setup) applied, can't use `/web-setup` or other cloud session features.63 Organizations with [Zero Data Retention](/docs/en/zero-data-retention) enabled, or with the [HIPAA configuration](/docs/en/hipaa-setup) applied, can't use `/web-setup` or other cloud session features. Organizations that use [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek) (CMEK) can't start cloud sessions either.

64</Note>64</Note>

65 65

66### Quick setup for Team and Enterprise66### Quick setup for Team and Enterprise

cloud-environments.md +19 −4

Details

499 499

500The `matcher` limits the hook to the `startup` and `resume` events, and `$CLAUDE_PROJECT_DIR` resolves to the repository root, so the hook finds the script regardless of the session's working directory.500The `matcher` limits the hook to the `startup` and `resume` events, and `$CLAUDE_PROJECT_DIR` resolves to the repository root, so the hook finds the script regardless of the session's working directory.

501 501

502Next, create the script at `scripts/install_pkgs.sh`. It exits immediately outside the cloud, then installs your dependencies:502Next, create the script at `scripts/install_pkgs.sh`. It exits immediately outside the cloud, then installs your dependencies. It skips `npm install` while `package.json`, `package-lock.json`, and the script itself are unchanged since the last successful install:

503 503

504```bash theme={null}504```bash theme={null}

505#!/bin/bash505#!/bin/bash

508 exit 0508 exit 0

509fi509fi

510 510

511npm install511cd "$CLAUDE_PROJECT_DIR" || exit 1

512hashes=node_modules/.install_pkgs.sha256

513

514if ! sha256sum --check --status "$hashes" 2>/dev/null; then

515 # Delete the old hashes first, so a failed install runs again next time

516 rm -f "$hashes"

517 if npm install; then

518 sha256sum scripts/install_pkgs.sh package.json package-lock.json > "$hashes" || rm -f "$hashes"

519 fi

520fi

521

522# pip skips requirements that are already satisfied

512pip install -r requirements.txt523pip install -r requirements.txt

513exit 0524exit 0

514```525```

515 526

516The `CLAUDE_CODE_REMOTE` check is what scopes the install to cloud sessions: the session VM's environment carries that variable as `true`, it's never `true` locally, so on your laptop the script exits before installing anything.527The `CLAUDE_CODE_REMOTE` check is what scopes the install to cloud sessions: the session VM's environment carries that variable as `true`, it's never `true` locally, so on your laptop the script exits before installing anything.

517 528

518Together, the two files give every cloud session a fresh `npm install` and `pip install` at startup while leaving local sessions untouched.529To confirm `npm install` succeeded, start a cloud session and ask Claude to show `node_modules/.install_pkgs.sha256`. The file lists a hash for each of the three files. If the file is missing, ask Claude to run `npm install` and report the error.

530

531<Note>

532 If `npm install` reads other files, such as a workspace's `package.json`, an `.npmrc`, or your `postinstall` script's inputs, add them to the `sha256sum` command that saves the hashes. Otherwise, you keep the old packages after one of those files changes.

533</Note>

519 534

520#### Limitations in cloud sessions535#### Limitations in cloud sessions

521 536

525* **No cloud-only scoping**: hooks run in both local and cloud sessions. To skip local execution, exit early unless the `CLAUDE_CODE_REMOTE` environment variable is `true`, the way the [dependency install script](#install-dependencies-with-a-sessionstart-hook) does.540* **No cloud-only scoping**: hooks run in both local and cloud sessions. To skip local execution, exit early unless the `CLAUDE_CODE_REMOTE` environment variable is `true`, the way the [dependency install script](#install-dependencies-with-a-sessionstart-hook) does.

526* **Requires network access**: install commands need to reach package registries. If your environment uses **None** network access, these hooks fail. The [default allowlist](#default-allowed-domains) under **Trusted** covers npm, PyPI, RubyGems, and crates.io.541* **Requires network access**: install commands need to reach package registries. If your environment uses **None** network access, these hooks fail. The [default allowlist](#default-allowed-domains) under **Trusted** covers npm, PyPI, RubyGems, and crates.io.

527* **Proxy compatibility**: in Anthropic-hosted environments, all outbound traffic passes through a [security proxy](#security-proxy), and some package managers don't work correctly with it; Bun is a known example. In a [self-hosted environment](/docs/en/self-hosted-environments-deploy#default-deny-egress), outbound traffic goes through your own network boundary instead.542* **Proxy compatibility**: in Anthropic-hosted environments, all outbound traffic passes through a [security proxy](#security-proxy), and some package managers don't work correctly with it; Bun is a known example. In a [self-hosted environment](/docs/en/self-hosted-environments-deploy#default-deny-egress), outbound traffic goes through your own network boundary instead.

528* **Adds startup latency**: hooks run each time a session starts or resumes, unlike setup scripts which benefit from [environment caching](#environment-caching). Keep install scripts fast by checking whether dependencies are already present before reinstalling.543* **Adds startup latency**: hooks run each time a session starts or resumes, unlike setup scripts which benefit from [environment caching](#environment-caching). Keep install scripts fast by skipping work that's already done, the way the [dependency install script](#install-dependencies-with-a-sessionstart-hook) does.

529 544

530To customize the base image, use a setup script to install what you need on top of the [provided image](#installed-tools), or run your own image as a container alongside Claude with `docker compose`. Replacing the base image entirely isn't supported yet.545To customize the base image, use a setup script to install what you need on top of the [provided image](#installed-tools), or run your own image as a container alongside Claude with `docker compose`. Replacing the base image entirely isn't supported yet.

531 546

code-review.md +78 −344

Details

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 codebase~~7> 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>~~

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.

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.

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).

~~19This page covers:~~

~~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~~

~~29## How reviews work~~

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.

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.

~~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).~~

~~37### Severity levels~~

~~39Each finding is tagged with a severity level:~~

~~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 |~~

~~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.~~

~~49### Rate and reply to findings~~

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.

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).

~~55To dismiss a finding without a code change, resolve its thread; replying doesn't dismiss it.~~

~~57### Check run output~~

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:

~~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 |~~

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.

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:

~~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```~~

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.

~~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 Review~~13<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" />

~~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>~~

~~90 <Step title="Start setup">~~

~~91 Click **Setup**. This begins the GitHub App installation flow.~~

~~92 </Step>~~

~~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.

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>~~

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 |

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 |

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

code-review-costs.md +76 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Code Review costs and usage

7> Estimate and cap what your organization spends on Claude Code Review: how reviews are billed through usage credits, what drives cost, and where to track usage.

9[Code Review](/docs/en/code-review) has no flat per-review price. What you spend depends on the cost of each review and on how many reviews run:

11* **Cost of each review**: scales with the [review level](/docs/en/code-review-setup#set-the-default-review-level), the size of the change, the complexity of the surrounding code, and how many candidate issues need verification

12* **Number of reviews**: set by [how often reviews run](#how-often-reviews-run) in each repository

14## Pricing

16Code Review is billed on token usage through [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans), separately from your plan's included usage. Reviews are billed to your organization, not to the developer who opened the PR or requested the review. Costs appear on your Anthropic bill regardless of whether your organization uses Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry for other Claude Code features.

18### How often reviews run

20A repository you add from the admin page starts at **After every push**, which runs the most reviews. Each repository's [**Review runs** setting](/docs/en/code-review-setup#set-when-reviews-run) decides how many reviews a pull request gets:

22* **Once after PR creation**: a review runs when the pull request is opened, reopened, or marked ready for review

23* **After every push**: runs on each push, multiplying cost by the number of pushes

24* **Manual (@claude review)**: no reviews on open or push

26Comment commands, drafts, and pull requests from forks adjust those counts:

28* **`@claude review always` in Once after PR creation or Manual mode**: [opts the PR into push-triggered reviews](/docs/en/code-review-pull-requests#comment-commands), so additional cost accrues per push after that comment

29* **`@claude review always` in After every push mode**: pushes already trigger reviews, so the subscription doesn't change per-push cost

30* **`@claude review`**: runs a single review without subscribing to future pushes

31* **Drafts and pull requests from forks**: [automatic reviews skip both](/docs/en/code-review-pull-requests#review-drafts-and-pull-requests-from-forks), so pushes to them don't add reviews

33## Estimate your spend

35Before a wide rollout, run a small pilot to estimate monthly spend from your own pull requests.

371. Set a [monthly spend limit](#limit-your-spend) for the pilot.

382. Turn on Code Review for a few representative repositories with **Review runs** set to **Once after PR creation** or **Manual (@claude review)**.

393. After several reviews have run, read each repository's average cost per review in the **Average cost** column of the **Repositories** table, in the **Code review** section of [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code#code-review).

404. Multiply that average by the number of pull requests the repository opens in a month. For **After every push**, multiply again by the typical number of pushes per pull request.

42A repository's average moves with the size of its pull requests and with the review level you choose.

44## Limit your spend

46To set a monthly spend limit 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. The limit applies to the whole organization.

48Code Review skips reviews when any of these runs out:

50* **Code Review spend limit**: the monthly limit you set for the Claude Code Review service. It resets at the start of the next billing period, and reviews resume sooner if you raise it.

51* **Organization spend limit**: your organization's overall monthly spend limit for usage credits. Raise it on the same page.

52* **Usage credits balance**: your organization's balance of usage credits. Add credits on the same page.

54Code Review also skips reviews once what's left is less than the expected cost of one review. When a review is skipped, developers see a [comment on the PR](/docs/en/code-review-troubleshooting#review-didn’t-run-and-the-pr-shows-a-budget-message) that names the cause and links to the usage settings.

56To monitor spend, use the [analytics dashboard](#view-usage).

58## View usage

60Go to [claude.ai/analytics/code-review](https://claude.ai/analytics/code-review) to see Code Review activity across your organization.

62| Section | What it shows |

63| :- | :- |

64| PRs reviewed | Daily count of pull requests reviewed over the selected time range |

65| Code Review cost | Code Review spend so far this month |

66| Feedback | Count of review comments that were auto-resolved because a developer addressed the issue |

67| Repository breakdown | Per-repo counts of PRs reviewed, comments resolved, and review runs, with estimated cost and a per-PR view |

69The 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.

71## Related resources

73* [Set up Code Review](/docs/en/code-review-setup): where to choose the review level and when reviews run in each repository

74* [Read and request reviews on a pull request](/docs/en/code-review-pull-requests): the comment commands, pull requests from forks, and the budget message developers see when a review is skipped

75* [Code Review](/docs/en/code-review): what a review checks and what it posts

76* [Manage costs effectively](/docs/en/costs): spend controls and usage tracking for the rest of Claude Code

code-review-customize.md +133 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Customize Code Review

7> Tune what Code Review flags on your pull requests with REVIEW.md and CLAUDE.md: recalibrate severity, skip paths, add checks, and see which copy applies.

9You can change what [Code Review](/docs/en/code-review) flags on your repository by committing instructions to it. This is how you cut nit volume, stop comments on generated files, or add a rule your team cares about. Put them in one of two files:

11* **`CLAUDE.md`**: [project instructions](/docs/en/memory) that Claude Code reads for every task, reviews included. Code Review reads them as project context and flags changes that violate them.

12* **`REVIEW.md`**: instructions for reviews alone. Use it to say what your team wants flagged, at what severity, and what to skip.

14Add `REVIEW.md` at your repository root and merge it. Then [protect your default branch](#which-branch-review-md-is-read-from).

16<Note>

17 To change how thorough reviews are or when they run, ask an Owner to change the [review level](/docs/en/code-review-setup#set-the-default-review-level) or the [**Review runs** setting](/docs/en/code-review-setup#set-when-reviews-run).

18</Note>

20## Use CLAUDE.md for project-wide rules

22Code Review reads your repository's `CLAUDE.md` files as project context. A change that violates one of their rules becomes a finding at whichever [severity level](/docs/en/code-review-pull-requests#severity-levels) fits the issue.

24A review reads the `CLAUDE.md` at your repository root and the `CLAUDE.md` files in the parent directories of each changed file. A subdirectory's `CLAUDE.md` is read when the pull request changes a file under that path.

26## Use REVIEW\.md for review-only rules

28`REVIEW.md` is a file at your repository root that tailors Code Review to your repository. You can also add a `REVIEW.md` in a subdirectory to add checks for changes under that path, on top of the root file.

30The agents that find issues and the agents that verify them receive its contents as your repository's review instructions, alongside Code Review's default review guidance. The step that writes the final review consults it before settling severity and writing the summary.

32This example layout has a root file and one subdirectory file:

34```text theme={null}

35your-repo/

36├── REVIEW.md # Root file

37├── services/

38│ └── billing/

39│ └── REVIEW.md # Adds checks for changes under services/billing/

40└── src/

41```

43Before you rely on a subdirectory file, protect your default branch and check [what a review reads for your branch setup](#what-a-review-reads-for-each-branch-setup).

45<Note>

46 The Code Review service and the local [`/code-review` command](/docs/en/code-review-local) are two separate tools, and they read different files. The service reads both `CLAUDE.md` and `REVIEW.md`. The `/code-review` command, which you run inside a Claude Code session on your own machine, reads your `CLAUDE.md` files and not `REVIEW.md`. Put guidance you want applied in both places in `CLAUDE.md`, and keep `REVIEW.md` for rules specific to pull request review.

47</Note>

49### Example REVIEW\.md

51This `REVIEW.md` recalibrates severity for a backend service, caps nits, skips generated files, and adds repo-specific checks.

53```markdown theme={null}

54# Review instructions

56## What Important means here

58Reserve Important for findings that would break behavior, leak data,

59or block a rollback: incorrect logic, unscoped database queries, PII

60in logs or error messages, and migrations that aren't backward

61compatible. Style, naming, and refactoring suggestions are Nit at

62most.

64## Cap the nits

66Report at most five Nits per review.

68## Do not report

70- Anything CI already enforces: lint, formatting, type errors

71- Generated files under `src/gen/` and any `*.lock` file

72- Test-only code that intentionally violates production rules

74## Always check

76- New API routes have an integration test

77- Log lines don't include email addresses, user IDs, or request bodies

78- Database queries are scoped to the caller's tenant

79```

81### Choose what to write in REVIEW\.md

83`REVIEW.md` is freeform Markdown that changes what a review finds and reports. It doesn't change the format of the review. Find the problem you're seeing, then add an instruction like the one shown. The [example](#example-review-md) uses the first four.

85* **The wrong things are marked Important**: redefine what 🔴 Important means for your repository. The default calibration targets production code, and a docs repository, a config repository, or a prototype might want a much narrower definition. State which classes of finding are Important and which are Nit at most. You can also escalate, for example treating any `CLAUDE.md` violation as Important.

86* **Too many nits**: cap how many 🟡 Nit comments a single review posts. A cap like "report at most five nits" keeps reviews actionable.

87* **Comments on generated files or on what CI already checks**: list paths and finding categories where Claude should skip findings. Common candidates are generated code, lockfiles, and vendored dependencies, 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: "in `scripts/`, only report if near-certain and severe."

88* **A team rule isn't being checked**: add rules you want flagged on every pull request, like "new API routes must have an integration test."

89* **Findings that turn out to be wrong**: 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.

91Some of these instructions [need the root file on a protected default branch](#which-branch-review-md-is-read-from).

93Keep `REVIEW.md` to instructions that change review behavior, and leave general project context in `CLAUDE.md`.

95### Which branch REVIEW\.md is read from

97Code Review reads `REVIEW.md` from the pull request's base branch or from the default branch, never from the pull request's own changes. To change review behavior, merge the `REVIEW.md` change first.

99Keep `REVIEW.md` on your default branch and protect that branch. When a review reads the copy on a protected default branch, the first row of the table below, it honors these instructions from the root file:

100

101* Lowering a finding's severity

102* Excluding paths, files, or classes of issue

103* Capping nit comments

104

105#### What counts as branch protection

106

107Code Review counts these settings as protection:

108

109* **Default branch**: a classic branch protection rule or a ruleset

110* **Any other branch**: a ruleset only

111

112A ruleset counts when it restricts updates or requires pull requests with at least one approval. If it requires pull requests, it must also dismiss that approval on a new push or require the approval to come after the last push.

113

114#### What a review reads for each branch setup

115

116Find your repository's situation in the first column of the table below.

117

118| Branch protection | Copy read | Files read |

119| :- | :- | :- |

120| The default branch is protected, and the pull request targets it or targets a branch no ruleset protects | Default branch | Root and subdirectory files |

121| The pull request targets another branch that a ruleset protects | That base branch | Root and subdirectory files |

122| The default branch isn't protected, and the base branch has no protection rule of either kind | Default branch | Root file |

123| Code Review can't confirm the protection settings. This includes an unprotected default branch with a base branch that has only a classic rule | None | None |

124

125If the check run mentions `REVIEW.md`, see [The check run mentions REVIEW.md](/docs/en/code-review-troubleshooting#the-check-run-mentions-review-md).

126

127## Related resources

128

129* [Code Review](/docs/en/code-review): what the service is and how a review runs

130* [Read and request reviews on a pull request](/docs/en/code-review-pull-requests#severity-levels): what each severity level means and how findings appear

131* [Set up Code Review](/docs/en/code-review-setup): the review level and when reviews run, which an Owner sets

132* [Review locally with `/code-review`](/docs/en/code-review-local): the `/code-review` command, its arguments, and effort levels

133* [Memory](/docs/en/memory): how `CLAUDE.md` files work across Claude Code

code-review-local.md +175 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Review locally with /code-review

7> Run `/code-review` in a Claude Code session to find bugs in your branch's changes, point the review at a pull request or path, and have Claude apply the fixes.

9`/code-review` is a command you type at the Claude Code prompt, in the session where you're working. Claude reviews the changes on your branch, looks for correctness bugs, and reports what it found in your conversation. Depending on your model and effort level, the review also covers reuse, simplification, and efficiency cleanups.

11The command works on any plan. The review runs in your own session, so it counts toward your plan's usage or API billing the same way the rest of the session does.

13<Note>

14 To have every pull request in a repository reviewed automatically on GitHub, see [Code Review](/docs/en/code-review), a managed service that an Owner turns on for your organization.

15</Note>

17`/review` is an alias of `/code-review`. Before v2.1.223, `/review` was a separate command that ran a single-pass, read-only review of a GitHub pull request.

19<Steps>

20 <Step title="Run /code-review">

21 Run the command:

23 ```text theme={null}

24 /code-review

25 ```

27 With no target, the review covers the changes on your current branch. To point the review at a pull request, another branch, a path, or a range of commits instead, see [Choose what to review](#choose-what-to-review).

29 You can also add flags:

31 * `--fix`: also asks Claude to apply the findings to your working tree after the review. Its edits go through your [permission mode](/docs/en/permission-modes).

32 * `--comment`: posts the findings on a GitHub pull request as inline comments, or on a [GitLab merge request](#post-findings-to-a-gitlab-merge-request) as a single note

33 </Step>

35 <Step title="Keep working">

36 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.

37 </Step>

39 <Step title="Act on the findings">

40 Ask Claude to fix what the review found. With `--fix` or `--comment`, Claude applies or posts the findings as part of the review, and you may be asked to approve its edits.

41 </Step>

42</Steps>

44## Choose what to review

46To review something other than your current branch, type a target after the effort level and any flags. Claude receives that text as the review target. A target can be a pull request number, a branch name, a file path, or a Git revision range. Find what you want reviewed in the first column and type what the second column shows:

48| To point the review at | Type |

49| :- | :- |

50| Your current branch and uncommitted changes | `/code-review` |

51| Your last 15 commits | `/code-review HEAD~15..HEAD` |

52| One branch against another | `/code-review main...my-feature` |

53| A single commit, where `abc1234` is the commit's hash | `/code-review abc1234^..abc1234` |

54| A pull request by number | `/code-review 1234` |

55| A file or directory path | `/code-review src/auth` |

57With no target, `/code-review` reviews your branch's commits ahead of its upstream branch plus your uncommitted changes. If the branch has no upstream, Claude compares against `main`, or against the previous commit.

59With `ultra`, Claude Code reads the target differently, as [Text after the effort level and flags](#text-after-the-effort-level-and-flags) describes.

61## What the review reads and edits

63Check these before you run a review, especially with `--fix`:

65* **Edits**: without `--fix`, the review's instructions ask Claude for a report only. With `--fix`, they also ask it to apply the findings to your working tree. Either way, any edit goes through your permission mode.

66* **Rewinding**: a background review applies its `--fix` edits outside your session's [checkpoints](/docs/en/checkpointing#subagent-edits-not-restored). After one, `/rewind` restores only the files Claude had already edited in your conversation. The review's edits to other files stay, so 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.

67* **Instructions**: the review follows your `CLAUDE.md`, including in a non-interactive `-p` run. It doesn't read `REVIEW.md`. That file configures the managed [Code Review service](/docs/en/code-review-customize#use-review-md-for-review-only-rules) on GitHub pull requests.

69## How findings are reported

71Claude reports the findings as text in the reply in both of these runs:

73* In a terminal session, where `/code-review` runs the review as a [forked subagent](/docs/en/skills#run-skills-in-a-subagent)

74* In a `-p` run with text or JSON output

76In 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. The report appears 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.

78When Claude fixes reported findings later in the session, it reports them again. Claude Code then marks each finding in the updated findings list as fixed, skipped, or no change needed.

80## Tune effort and arguments

82Beyond `--fix` and `--comment`, the command takes these flags:

84* `--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.

85* `--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. Where the review reports through the findings tool, the limit is 32. Later reviews reuse the value you typed until you pass `--max-findings default`, but a value passed in a non-interactive `-p` run isn't remembered. Requires Claude Code v2.1.288 or later.

87Pass 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.

89When you don't type a level, the review reuses the last level from `low` through `max` you typed, even in an earlier session. Claude Code shows a notice such as `Reusing high effort, the level you typed last time`. These rules decide which level a run uses:

91* **Typing a level**: a level you type, like `/code-review high`, changes what later runs reuse

92* **Non-interactive runs**: a level you pass in a non-interactive `-p` run doesn't update the remembered level

93* **`ultra`**: the review neither uses nor updates the remembered level

94* **No level ever typed**: the review uses the session's current effort

96Before v2.1.223, a `/code-review` without a level always used the session's current effort.

98### Post findings to a GitLab merge request

100When 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.

101

102Pass 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.

103

104### Text after the effort level and flags

105

106After the effort level and flags, Claude Code reads the rest of the line as the review target. The `ultra` argument changes that reading:

107

108* **With `ultra`**: Claude Code reads a single word as a base branch or PR number. Longer text that doesn't name a branch or PR becomes [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.

109* **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.

110

111## Run in the foreground

112

113To make the review run in the foreground, do one of these:

114

115* 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).

116* Set [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/en/env-vars) to `1`, which also turns off every other background task feature

117* Run `/code-review` again while an earlier review is still in progress

118

119Before v2.1.218, the review ran inside your conversation.

120

121## Let Claude start the review

122

123Claude can start `/code-review` on its own, without you typing the command:

124

125* **When you ask in plain language**: ask Claude to review your changes and it can run the skill

126* **From a scheduled task**: a [scheduled task](/docs/en/scheduled-tasks) with `/code-review` as its prompt runs the review

127

128A scheduled task never launches the [cloud review](#escalate-to-ultrareview), so schedule `/code-review` without the `ultra` argument.

129

130To 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`:

131

132```json theme={null}

133{

134 "skillOverrides": {

135 "code-review": "user-invocable-only"

136 }

137}

138```

139

140Before 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.

141

142## Escalate to ultrareview

143

144`/code-review ultra --fix` runs the deeper [ultrareview](/docs/en/ultrareview) in the cloud, then asks Claude to apply its findings to your working tree when they arrive back in your session.

145

146Ultrareview uses its own scope:

147

148* **What it compares**: your current branch against the repository's default branch, plus uncommitted and staged changes in the working tree

149* **Sensitive files**: 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)

150* **A different base**: pass a branch name, such as `/code-review ultra develop`, to compare against a different base

151

152When 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.

153

154<Note>

155 Ultrareview requires authentication with a claude.ai account. It isn't 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. In these cases, `/code-review ultra` runs a local review in your session instead. Organizations that use [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek) (CMEK) can't run ultrareview. To review your changes locally, run `/code-review`.

156</Note>

157

158To 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.

159

160## Change or build on the review

161

162`/code-review` is a [bundled skill](/docs/en/skills#bundled-skills): its instructions are built into Claude Code, so there is no `SKILL.md` file on disk to open or edit. To give every review project rules to follow, add them to your `CLAUDE.md`. To go further, start from one of these pages:

163

164* **Replace the command**: a project or personal skill named `code-review` runs in place of the bundled one, and the `/review` alias keeps running the bundled review. See [Resolve skills that share a name](/docs/en/skills#resolve-skills-that-share-a-name).

165* **Build your own reviewer**: write a reviewer [subagent](/docs/en/sub-agents) or a review [skill](/docs/en/skills)

166* **Use a neighboring command**: [`/simplify`](/docs/en/commands) reviews for cleanup only and applies its fixes, and [`/verify`](/docs/en/commands) runs your app to confirm a change works

167

168The command was named `/simplify` before v2.1.147, when it applied fixes by default. If you scripted `/simplify` for bug-finding, switch to `/code-review --fix`.

169

170## Related resources

171

172* [Code Review](/docs/en/code-review): the managed service that reviews every pull request on GitHub for your organization

173* [Ultrareview](/docs/en/ultrareview): setup, limits, and cost of the deeper cloud review

174* [Commands](/docs/en/commands): the one-line reference for `/code-review`, `/review`, `/simplify`, and `/verify`

175* [Skills](/docs/en/skills): how bundled skills work and how to write your own

code-review-pull-requests.md +149 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Read and request reviews on a pull request

7> Read Code Review findings on your GitHub pull request, respond to or dismiss them, and request a review with `@claude review`.

9Code Review is a managed service that an Owner in your Claude organization turns on for a set of GitHub repositories. Once it's on, Claude reviews pull requests in those repositories and posts its findings as inline comments, a summary in the review body, and a check run named **Claude Code Review**. A review never approves or blocks your pull request, and the check run never concludes as a failure.

11An Owner controls [when reviews run](/docs/en/code-review-setup#set-when-reviews-run) and [how thorough they are](/docs/en/code-review-setup#set-the-default-review-level) for each repository.

13<Note>

14 If your plan doesn't include Code Review, you can still have Claude review your branch from a Claude Code session: see [Review locally with `/code-review`](/docs/en/code-review-local).

15</Note>

17## Severity levels

19Claude posts each finding as an inline comment on the lines concerned and marks it with one of three severity levels:

21| Marker | Severity | Meaning |

22| :- | :- | :- |

23| 🔴 | Important | A bug that should be fixed before merging |

24| 🟡 | Nit | A minor issue, worth fixing but not blocking |

25| 🟣 | Pre-existing | A bug that exists in the codebase but wasn't introduced by this PR |

27When the review recorded its reasoning, the finding has a collapsed **Why this was flagged** section. Expand it to read why Claude flagged the issue and how it verified the problem.

29To change what Claude flags in your repository or how it ranks severity, see [Customize Code Review](/docs/en/code-review-customize).

31## Respond to findings

33You can merge without responding to a finding, unless your repository's own rules require it. If its branch protection [requires conversation resolution](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-conversation-resolution-before-merging), resolve each finding's thread before you merge.

35To clear a finding, resolve its thread or push a fix.

37* **Dismiss it without a code change**: resolve the thread yourself on GitHub. Replying alone doesn't dismiss a finding.

38* **Fix the issue**: change the code and push. The next review of the pull request resolves its earlier thread when it judges the issue fixed, whether that review runs automatically on your push or you request it.

39* **Explain or disagree**: reply to the comment. Claude doesn't respond right away, and a reply doesn't start a review. The next review of the pull request reads the replies on its earlier findings, and can resolve the thread or post one follow-up reply. If the same kind of finding keeps coming back, ask a maintainer to add a rule to [`REVIEW.md`](/docs/en/code-review-customize#choose-what-to-write-in-review-md).

41To get that next review without pushing, comment `@claude review` as a [top-level pull request comment](#comment-commands).

43## Check run output

45The **Details** link on the **Claude Code Review** check run opens the findings in one table sorted by severity, including any finding whose inline comment GitHub didn't accept:

47| Severity | File:Line | Issue |

48| - | - | - |

49| 🔴 Important | `src/auth/session.ts:142` | Token refresh races with logout, leaving stale sessions active |

50| 🟡 Nit | `src/auth/session.ts:88` | `parseExpiry` silently returns 0 on malformed input |

52A finding that has a line but wasn't posted as an inline comment appears as an annotation in the **Files changed** tab, on the lines concerned. Important findings show in red, nits in yellow, and pre-existing bugs in gray.

54The check run concludes as neutral, or as skipped when an automatic review didn't run because a push changed no files. It never concludes as a failure, so a finished review doesn't fail a required check. If you don't see findings, or a review didn't run, see [Troubleshoot Code Review](/docs/en/code-review-troubleshooting).

56### Read the result from a script

58To gate a merge or post a summary from your own CI, parse the last line of the Details text with `gh` and jq. That line is a machine-readable comment.

60<Steps>

61 <Step title="Find the check run ID">

62 From your shell, list the commit's check runs and take the `id` of the `Claude Code Review` run. Replace `OWNER` and `REPO` with your repository owner and name, and `<commit-sha>` with the pull request's head commit:

64 ```bash theme={null}

65 gh api repos/OWNER/REPO/commits/<commit-sha>/check-runs --jq '.check_runs[] | {id, name}'

66 ```

67 </Step>

69 <Step title="Read the severity counts">

70 Read the counts from that check run, replacing `CHECK_RUN_ID` with the ID:

72 ```bash theme={null}

73 gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \

74 --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

75 ```

77 This prints a JSON object with a count per severity and its keys in alphabetical order, for example `{"nit": 1, "normal": 2, "pre_existing": 0}`. The counts include findings from earlier reviews of the pull request whose threads are still open.

78 </Step>

80 <Step title="Act on the result">

81 Have your script handle these cases:

83 * **`normal` is above zero**: fail the job if you want to gate the merge. The `normal` key holds the count of Important findings, so Claude found at least one bug worth fixing before merge.

84 * **The line is missing**: treat it as no verdict rather than as zero findings. A check run for a review that failed, timed out, was canceled, or was superseded by a newer one has no such line, and some completed reviews have none either.

85 </Step>

86</Steps>

88## Request a review

90If your pull request is a draft or comes from a fork, automatic reviews skip it, so [request the review with a comment command](#review-drafts-and-pull-requests-from-forks). To get a review on your pull request, do one of these:

92* **Open it or mark it ready**: in a repository set to **Once after PR creation** or **After every push**, a review starts when you open or reopen the pull request, or mark a draft ready for review.

93* **Comment a command**: post [`@claude review`](#comment-commands) on the pull request.

94* **Push a commit**: a push starts a review in a repository set to **After every push**, or on a pull request you subscribed with `@claude review always`.

95* **Click Re-run**: after a review fails or times out on a pull request that isn't from a fork, [run it again](/docs/en/code-review-troubleshooting#retrigger-a-failed-or-timed-out-review) from the check run.

96* **Wait for the automatic retry**: a review whose session was interrupted is retried once automatically. The [check run's summary](/docs/en/code-review-troubleshooting#retrigger-a-failed-or-timed-out-review) says when that's happening.

98### Comment commands

100Post one of these commands as a comment on the pull request:

101

102| Command | What it does | When to use it |

103| :- | :- | :- |

104| `@claude review` | Starts a single review without subscribing the PR to future pushes | You want one review now, such as on a pull request in a repository set to Manual, or another review right away in the other modes |

105| `@claude review always` | Starts a review and subscribes the PR to push-triggered reviews going forward | You want every subsequent push to start a fresh review, such as on a high-priority PR in a repository set to Manual |

106| `@claude review once` | Same as `@claude review`: starts a single review without subscribing | The same cases as `@claude review` |

107

108For any of these commands to start a review, all of these conditions have to hold:

109

110* Post it as a new top-level pull request comment, not an inline comment on a diff line and not the body of a review. Editing an earlier comment doesn't count.

111* Put the command at the start of the comment, with `always` on the same line as the rest of the command. Capitalization doesn't matter.

112* You need write, maintain, or admin permission on the repository. Claude checks this with GitHub for each person who comments, and comments from bots don't start reviews.

113* The pull request must be open.

114

115When the command is accepted, a **Claude Code Review** check run appears on the pull request with the title **Code review queued...**. The title changes to **Code review in progress...** when the review starts. Claude may also react to your comment with 👀, but that reaction can appear when no review starts, so look for the check run instead.

116

117If a review is already running on the pull request's latest commit, a new request doesn't start a second one.

118

119<Note>

120 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.

121</Note>

122

123### What a later review covers

124

125A later review that starts on its own, such as after a push, focuses on what changed since the last review and posts fewer nits and pre-existing findings. Its summary counts what it left out, in a line that ends "found and not posted" or "outside the scope of this re-review and not posted."

126

127To get a review that leaves none of these out, comment [`@claude review`](#comment-commands). It covers the whole pull request again.

128

129### Review drafts and pull requests from forks

130

131Automatic reviews skip both of these, so request the review with a comment command:

132

133* **Draft pull requests**: a comment command runs on a draft, so you can request a review before you mark the pull request ready. Pushes to a draft don't start reviews, even after `@claude review always`. The subscription takes effect once you mark the pull request ready.

134* **Pull requests from forks**: Claude doesn't review a pull request from a fork automatically, regardless of the repository's **Review runs** setting. To start one, comment `@claude review` on the pull request. The [conditions for comment commands](#comment-commands) still apply, and the write access you need is to the base repository, not the fork.

135

136On a pull request from a fork, `@claude review always` works too, but doesn't subscribe the pull request to reviews on later pushes. Clicking **Re-run** on the check run doesn't start a review there.

137

138### Use Code Review alongside the Claude Code GitHub Action

139

140If the repository also runs the [Claude Code GitHub Action](/docs/en/github-actions) in interactive mode with its default `@claude` trigger phrase, an `@claude review` comment starts the Action as well. To keep the two apart, set the Action's `trigger_phrase` input to a different phrase.

141

142## Related resources

143

144* [Troubleshoot Code Review](/docs/en/code-review-troubleshooting): a review that didn't start, failed, or was skipped for budget

145* [Code Review](/docs/en/code-review): what the service is and how a review runs

146* [Set up Code Review](/docs/en/code-review-setup): for Owners, turn on Code Review and choose when reviews run and at what level

147* [Customize Code Review](/docs/en/code-review-customize): change what Claude flags with `REVIEW.md` and `CLAUDE.md`

148* [Code Review costs and usage](/docs/en/code-review-costs): how reviews are billed and where the spend limit is set

149* [Review locally with `/code-review`](/docs/en/code-review-local): run a review of your branch from a Claude Code session

code-review-setup.md +165 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Set up Code Review

7> Turn on Code Review for your Claude organization: connect GitHub, install the Claude GitHub App, choose repositories, and set when reviews run

9As an Owner of your Claude organization, you turn on Code Review in [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code#code-review) on claude.ai. Reviews run on Anthropic infrastructure, so you don't add workflow files to your repositories.

11After setup, you choose how thorough reviews are and when they run in each repository. You spend more at a higher review level and when reviews run more often. See [Code Review costs](/docs/en/code-review-costs#pricing).

13## What you need to turn on Code Review

15First check that your organization [qualifies for Code Review](/docs/en/code-review#availability). Then make sure you have this access, or someone who does:

17| Access | Needed for |

18| :- | :- |

19| [Owner role](/docs/en/server-managed-settings#access-control) in your Claude organization | Every step on the admin page |

20| Owner of the GitHub organization | Installing the Claude GitHub App and [linking it to your Claude organization](/docs/en/admin-setup#connected-github-accounts). If you aren't an owner, have one install and link the app before you start |

21| Write access to each repository you add, from the GitHub account you connect to Claude | Adding the repository |

23## Turn on Code Review

25<Steps>

26 <Step title="Click the Allow code review switch">

27 Go to the **Code review** section of [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code#code-review) and click the **Allow code review** switch.

29 If Code Review turns on right away with no dialog, your organization already has the Claude GitHub App linked or repositories added. Go to [Add more repositories](#add-more-repositories), then come back for the last step.

30 </Step>

32 <Step title="Connect your GitHub account">

33 If a **Connect GitHub** dialog opens, click **Connect**. If your organization uses GitHub Enterprise Server, select your instance in the dialog first. GitHub asks you to authorize Claude, then returns you to the admin page with the **Add a repository** dialog open.

35 If **Add a repository** opened straight away, your account is already connected, so go on to the next step.

36 </Step>

38 <Step title="Install the Claude GitHub App">

39 If the repositories you want are listed in the **Add a repository** dialog, or you find them by searching there, go on to the next step. The dialog lists a repository only if the Claude GitHub App can access it, so if they aren't there, install the app:

41 * Click **Install GitHub App**. When no repositories are listed, it's a button in the dialog. Otherwise, it's at the bottom of the dialog's GitHub organization filter menu. GitHub's install page opens in a new tab.

42 * Pick the GitHub organization that owns the repositories.

43 * Choose which repositories the app can access.

44 * Approve the requested permissions. The set is broader than a review uses and is shared by other Claude features, such as [GitHub Actions](/docs/en/github-actions). See [what a review can access](/docs/en/code-review#what-a-review-can-access) and the [full permission list](/docs/en/github-actions#github-app-permissions).

45 * When the install completes, the tab returns to Claude. If it shows a **Finish connecting GitHub** button, click it to link the installation to your Claude organization.

46 * Go back to the admin page's tab, where the list in the dialog refreshes.

47 </Step>

49 <Step title="Choose repositories">

50 Select the repositories you want reviewed, then click **Continue**. Adding a repository needs write access to it from the GitHub account you connected. You can [add more repositories](#add-more-repositories) later.

51 </Step>

53 <Step title="Click Finish">

54 A **Code review is set up** dialog follows. Click **Finish** to turn Code Review on. If you close the dialog any other way, your repositories stay added but **Allow code review** stays off, and you turn it on from the switch.

56 Each repository starts set to review after every push, which runs the most reviews. To run fewer, [set when reviews run](#set-when-reviews-run).

57 </Step>

59 <Step title="Verify with a test pull request">

60 Open a test pull request in one of the repositories you added, and don't mark it as a draft. A check run named **Claude Code Review** appears within a few minutes. If you already set the repository to **Manual (@claude review)**, comment `@claude review` on the pull request to start the first review.

62 If no check run appears, see [No check run appears on the test pull request](/docs/en/code-review-troubleshooting#no-check-run-appears-on-the-test-pull-request).

64 Once the review arrives, send your developers [Read and request reviews on a pull request](/docs/en/code-review-pull-requests), which covers the severity levels, the comment commands, and how to respond to findings.

65 </Step>

66</Steps>

68## Set defaults for your organization

70As an Owner, you decide how thorough reviews are and how often they run. Both are in the **Code review** section of [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code#code-review).

72### Set the default review level

74The review level sets how thorough each review is, and a more thorough review costs more. You set one default for the organization and can override it for individual repositories.

76| Level | What it trades |

77| :- | :- |

78| Quick | A lighter pass. The fastest level, at the lowest cost |

79| Standard | Balanced depth, speed, and cost. The default level |

80| Deep | The most thorough pass. Takes the longest and costs the most |

82* **Organization default**: select a level under **Review level** and confirm with **Change level**. Every repository uses it unless you give that repository its own.

83* **One repository**: click **Edit** on the repository's row, then select a **Review level** there. The first option, **Default**, follows the organization. The level saves as soon as you select it.

85A new level applies to reviews that start after the change. For what else drives the cost of each review, see [Code Review costs and usage](/docs/en/code-review-costs).

87### Set when reviews run

89Each repository has its own **Review runs** setting, which decides when its pull requests get reviewed.

91* **Once after PR creation**: a review runs when a pull request is opened, reopened, or marked ready for review

92* **After every push**: a review runs on pushes to the pull request branch, catching new issues as the pull request evolves and auto-resolving threads when you fix flagged issues

93* **Manual (@claude review)**: opening or pushing to a pull request doesn't start a review. Comment [`@claude review`](/docs/en/code-review-pull-requests#comment-commands) to request one, or `@claude review always` to also subscribe the pull request to reviews on subsequent pushes.

95Manual is useful for high-traffic repositories where you want to opt specific pull requests into review, or to start reviewing pull requests only once they're ready. To compare what each option does to spend, see [How often reviews run](/docs/en/code-review-costs#how-often-reviews-run).

97To change the setting, click **Edit** on the repository's row in the **Repositories** table and select a **Review runs** option. The choice saves as soon as you select it, and the table's **Review runs** column shows it shortened to Once per PR, Every push, or Manual.

99* **Drafts and pull requests from forks**: whichever option you choose, [automatic reviews skip both](/docs/en/code-review-pull-requests#review-drafts-and-pull-requests-from-forks)

100* **New repositories**: a repository you add from the **Add a repository** dialog starts at **After every push**. If its GitHub organization is [covered as a whole](#cover-a-whole-github-organization), it takes that organization row's setting instead.

101

102### Turn tip comments on or off

103

104A tip comment is a short comment Claude posts on a pull request when no review starts, saying why and what to do next. **Show tips on pull requests** is on by default. With it on, Claude posts a tip in each of these cases, explaining:

105

106* **The repository is set to Manual**: how to request a review with a comment

107* **The pull request comes from a fork**: that a maintainer can request the review

108* **A bot, or someone without write access, comments `@claude review`**: that no review was started, and who can request one

109* **The GitHub organization isn't linked to your Claude organization**: that reviews are paused, and how to link it

110

111Turn the setting off to stop these comments.

112

113### What developers can change

114

115Developers come to you to change the review level, the **Review runs** setting, or which repositories get reviews. From GitHub, without the Owner role, they can do these:

116

117* **Request a review**: comment [`@claude review`](/docs/en/code-review-pull-requests#comment-commands) on a pull request. This needs write access to the repository, and it works on [drafts and pull requests from forks](/docs/en/code-review-pull-requests#review-drafts-and-pull-requests-from-forks), which automatic reviews skip.

118* **Subscribe one pull request to a review on each push**: comment `@claude review always` on a pull request that isn't [a draft or from a fork](/docs/en/code-review-pull-requests#review-drafts-and-pull-requests-from-forks), such as in a repository set to Manual

119* **Change what reviews flag**: commit [`REVIEW.md` and `CLAUDE.md` files](/docs/en/code-review-customize) to the repository, for example to add a check

120

121Reviews that developers request are [billed to your organization](/docs/en/code-review-costs#pricing). To limit what Code Review spends in a month, see [Limit your spend](/docs/en/code-review-costs#limit-your-spend).

122

123## Manage repositories

124

125You can add repositories one at a time or cover a whole GitHub organization at once, and stop reviews wherever you don't want them.

126

127### Add more repositories

128

129To add repositories after setup, click **Add** above the **Repositories** table in the **Code review** section. The **Add a repository** dialog opens. Select repositories and click **Continue**.

130

131* **A repository isn't listed**: see [A repository isn't listed in Add a repository](/docs/en/code-review-troubleshooting#a-repository-isn’t-listed-in-add-a-repository).

132* **You want every repository in a GitHub organization**: [cover the organization](#cover-a-whole-github-organization) instead of selecting repositories one at a time

133

134### Cover a whole GitHub organization

135

136To turn on Code Review for every repository in a GitHub organization, set **Review runs** on the organization's row in the **Repositories** table. That covers every repository there that the Claude GitHub App can access, including repositories added later. This can raise spend significantly. It requires all of these:

137

138* The GitHub account you connected to Claude is an owner of that GitHub organization.

139* The organization is on github.com. GitHub Enterprise Server instances and personal GitHub accounts aren't eligible.

140* A [monthly spend limit](/docs/en/code-review-costs#limit-your-spend) is set, for your Claude organization or for Code Review.

141

142To cover the organization, click **Edit** on its row, select a **Review runs** option, and confirm. The options are the three from [Set when reviews run](#set-when-reviews-run) plus **Off**.

143

144After you confirm, these changes take effect:

145

146* **Coverage**: each repository is covered from its next pull request. If the Claude GitHub App was installed on selected repositories rather than all of them, Claude reviews those repositories; change the app's repository access on GitHub to cover the rest.

147* **Existing settings**: every repository in that GitHub organization takes the option you select, including repositories you had set individually. Setting the row again does the same. Repositories you turned off on their own rows stay off.

148* **Individual changes afterward**: a repository you later set differently from its organization is marked **Custom** in the table.

149* **Review level**: an organization row has no review level of its own.

150

151### Turn off Code Review or remove a repository

152

153In the **Code review** section of [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code#code-review), pick the control that matches what you want to stop:

154

155* **One repository, keeping it in the list**: click **Edit** on its row and turn off **Code review**. The table shows the repository as Off.

156* **One repository, removing it**: click **Edit** on its row, then **Remove repository** at the bottom of the dialog. Reviews stop there, and another Claude organization can then set that repository up. While the repository's GitHub organization is covered as a whole, you can't remove it; turn off its **Code review** switch instead.

157* **A whole GitHub organization**: click **Edit** on the organization's row and select **Off**. This also turns off repositories in that organization that you added one at a time.

158* **Everything**: turn off **Allow code review**. No new reviews start in any repository, and your repository list stays so you can turn it back on later.

159

160## Related resources

161

162* [Code Review costs and usage](/docs/en/code-review-costs): how the review level and when reviews run affect spend, how to set a spend limit, and where to see usage

163* [Read and request reviews on a pull request](/docs/en/code-review-pull-requests): what developers see on a pull request and the comment commands

164* [Customize Code Review](/docs/en/code-review-customize): tune what Claude flags with `REVIEW.md` and `CLAUDE.md`

165* [GitHub Enterprise Server](/docs/en/github-enterprise-server): connect a self-hosted GitHub instance before setup

code-review-troubleshooting.md +91 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Troubleshoot Code Review

7> Fix a Code Review that didn't start, failed, or was skipped for budget, find missing findings, and resolve setup and `REVIEW.md` problems.

9When [Code Review](/docs/en/code-review) doesn't do what you expect on a pull request, start with the **Claude Code Review** check run. Its title says how far the review got.

11## Check how far the review got

13Find the **Claude Code Review** check run on your pull request, then match its title to one of these common ones:

15| Check run title | What it means | What to do |

16| :- | :- | :- |

17| **Code review queued...** or **Code review in progress...** | The review hasn't finished | Wait for the title to change |

18| **Code review found no issues** | The review finished and found nothing to flag | Nothing |

19| A title that says issues were found | The review finished with findings | If you don't see them on the diff, see [Find issues that aren't showing as inline comments](#find-issues-that-aren’t-showing-as-inline-comments) |

20| **Code review skipped — no new changes** | An automatic review didn't run on your latest push | To get a review anyway, comment `@claude review` |

21| **Code review failed** or **Code review timed out** | The review didn't finish | To run it again, see [Retrigger a failed or timed-out review](#retrigger-a-failed-or-timed-out-review) |

22| **Code review declined** | The review didn't run | Read the check run's summary. If it names a budget or a spend limit, see [Review didn't run and the PR shows a budget message](#review-didn’t-run-and-the-pr-shows-a-budget-message) |

23| No check run | No review started | Comment `@claude review`. If no check run appears after that, see [A comment command didn't start a review](#a-comment-command-didn’t-start-a-review) |

25## A review didn't start

27Check these cases when no **Claude Code Review** check run appears, or when Claude posts a comment saying the review was skipped.

29### A comment command didn't start a review

31After you comment `@claude review`, look for a **Claude Code Review** check run titled **Code review queued...** or **Code review in progress...** on the pull request. An 👀 reaction on your comment doesn't confirm a review is coming. If no check run appears, check for each of these causes:

33* **Code Review isn't on for this repository**: Claude posts no comment and no check run in response to the command. Ask an Owner to [add the repository](/docs/en/code-review-setup#add-more-repositories).

34* **The comment doesn't meet a condition**: it was an inline comment or a review body rather than a new top-level comment, or the command wasn't at the start of the comment. Editing an earlier comment instead of posting a new one doesn't count either, and the pull request has to be open. See the [conditions for comment commands](/docs/en/code-review-pull-requests#comment-commands) and post a new comment that meets them.

35* **You don't have write access**: you need write, maintain, or admin permission on the repository, and on a pull request from a fork the permission that counts is on the base repository. If your organization has tips turned on, Claude replies "No review was started: manual reviews can only be requested by someone with write access to this repository." Ask someone with write access to comment instead.

36* **The budget ran out**: Claude posts a comment that begins with "⚠️ Code review skipped". See [Review didn't run and the PR shows a budget message](#review-didn’t-run-and-the-pr-shows-a-budget-message).

38### Review didn't run and the PR shows a budget message

40When your organization's budget can't cover a review, Code Review skips the review and Claude posts a comment on the pull request that begins with "⚠️ Code review skipped". In some of these cases a check run titled **Code review declined** also appears.

42The comment links [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage), where an admin restores the budget. Its wording tells you which limit was reached:

44* **"has reached its monthly code review spending cap"**: the [monthly spend limit for Code Review](/docs/en/code-review-costs#limit-your-spend) was reached. Reviews resume at the start of the next billing period. To get them sooner, ask an admin to raise the limit.

45* **"has no extra usage available to pay for this review"**: your organization's [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) balance is empty, or its overall monthly spend limit was reached. Ask an admin to add usage credits or raise that limit.

46* **"is too low to start another review"**: what's left of the budget or balance is less than the expected cost of one review. Ask an admin to raise the limit or add usage credits.

48After the budget is restored, comment `@claude review` on the pull request to get the review that was skipped. The [conditions for comment commands](/docs/en/code-review-pull-requests#comment-commands) apply, so the commenter needs write access.

50## Retrigger a failed or timed-out review

52If the check run's summary says "The review session was interrupted before it could finish. A new review of this commit has been queued automatically.", you don't need to do anything. That review is retried once automatically.

54Otherwise, when the check run's title is **Code review failed** or **Code review timed out**, run the review again with a comment or a re-run:

56* **Comment `@claude review`**: post it as a top-level comment on the pull request. This starts a fresh review without subscribing the pull request to future pushes.

57* **Click Re-run**: if the pull request isn't [from a fork](/docs/en/code-review-pull-requests#review-drafts-and-pull-requests-from-forks), click **Re-run** on the **Claude Code Review** check in GitHub's **Checks** tab. The re-run covers the pull request's current head commit and doesn't subscribe the pull request either.

59## Find issues that aren't showing as inline comments

61If 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:

63* **Check run Details**: click **Details** next to the **Claude Code Review** check in the **Checks** tab. The severity table lists findings with their file, line, and summary regardless of whether the inline comment was accepted.

64* **Files changed annotations**: open the **Files changed** tab on the PR. A finding that has a line but wasn't posted as an inline comment appears there as an annotation on the lines concerned.

65* **Review body**: findings that have no inline location, or that fall outside the current diff, appear under an **Additional findings** heading in the review body.

67## The check run mentions REVIEW\.md

69Two of the messages a check run can carry about `REVIEW.md` concern branch protection:

71* **"This review applied the repository's review instructions (REVIEW\.md) from its default branch, which is not protected against direct pushes."**: the review read the root file only. See [Which branch REVIEW.md is read from](/docs/en/code-review-customize#which-branch-review-md-is-read-from) for what protecting the branch changes.

72* **"were not applied to this review: branch protection could not be confirmed"**: the review read no `REVIEW.md`.

74## Setup problems

76These cases come up for an Owner while [setting up Code Review](/docs/en/code-review-setup).

78### A repository isn't listed in Add a repository

80Search for the repository by name first, because the dialog doesn't load a long list in full. The dialog lists a repository only if the Claude GitHub App can access it. Click **Install GitHub App** and give the app access to the repository. When no repositories are listed, **Install GitHub App** is a button in the dialog. Otherwise, it's at the bottom of the dialog's GitHub organization filter menu.

82### No check run appears on the test pull request

84Confirm that **Allow code review** is on, that the repository is listed under **Repositories** in the **Code review** section, and that the Claude GitHub App has access to it. Automatic reviews skip draft pull requests, and a repository set to **Manual (@claude review)** needs an `@claude review` comment to start the first review.

86## Related resources

88* [Read and request reviews on a pull request](/docs/en/code-review-pull-requests): what the findings and the check run mean, and the comment commands

89* [Set up Code Review](/docs/en/code-review-setup): for Owners, turn on Code Review and manage repositories

90* [Code Review costs and usage](/docs/en/code-review-costs): the spend limits behind a budget message

91* [Customize Code Review](/docs/en/code-review-customize): which copy of `REVIEW.md` a review reads

commands.md +2 −2

Details

68| `/claude-api [migrate\|upgrade\|managed-agents-onboard\|prompt-audit\|cost-optimize\|build-eval\|hillclimb\|preserved-thinking-migration]` | **[Skill](/docs/en/skills#bundled-skills).** Load [Claude API](https://platform.claude.com/docs/en/api/overview) and [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) reference material for your project's language. Also activates automatically when your code imports `anthropic` or `@anthropic-ai/sdk`. For what each subcommand does and the version it requires, see [Work on Claude API projects](/docs/en/skills#work-on-claude-api-projects) |68| `/claude-api [migrate\|upgrade\|managed-agents-onboard\|prompt-audit\|cost-optimize\|build-eval\|hillclimb\|preserved-thinking-migration]` | **[Skill](/docs/en/skills#bundled-skills).** Load [Claude API](https://platform.claude.com/docs/en/api/overview) and [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) reference material for your project's language. Also activates automatically when your code imports `anthropic` or `@anthropic-ai/sdk`. For what each subcommand does and the version it requires, see [Work on Claude API projects](/docs/en/skills#work-on-claude-api-projects) |

69| `/claude-in-chrome [task]` | **[Skill](/docs/en/skills#bundled-skills).** Have Claude carry out a task in your browser, such as testing a page, filling a form, or reading console logs, through [Claude in Chrome](/docs/en/chrome). Available when Chrome integration is enabled for the session, for example with `claude --chrome`, or when Claude Code can offer to [install the extension](/docs/en/chrome#install-the-extension-when-claude-asks) |69| `/claude-in-chrome [task]` | **[Skill](/docs/en/skills#bundled-skills).** Have Claude carry out a task in your browser, such as testing a page, filling a form, or reading console logs, through [Claude in Chrome](/docs/en/chrome). Available when Chrome integration is enabled for the session, for example with `claude --chrome`, or when Claude Code can offer to [install the extension](/docs/en/chrome#install-the-extension-when-claude-asks) |

70| `/clear [name]` | Start a new conversation with empty context. Pass a name to label the previous conversation in the `/resume` picker. To free up context while continuing the same conversation, use `/compact` instead. Resume the previous conversation with `/resume`, or, in the same Claude Code process, restore it from [the rewind menu's previous-session entry](/docs/en/checkpointing#rewind-past-a-cleared-conversation). Aliases: `/reset`, `/new` |70| `/clear [name]` | Start a new conversation with empty context. Pass a name to label the previous conversation in the `/resume` picker. To free up context while continuing the same conversation, use `/compact` instead. Resume the previous conversation with `/resume`, or, in the same Claude Code process, restore it from [the rewind menu's previous-session entry](/docs/en/checkpointing#rewind-past-a-cleared-conversation). Aliases: `/reset`, `/new` |

71| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | **[Skill](/docs/en/skills#bundled-skills).** Review the current diff, or a PR number, branch, or path you pass, for correctness bugs. Depending on your model and effort level, the review also covers cleanup opportunities. Pass `--fix` to apply findings, `--comment` to post them on the GitHub PR or GitLab merge request, or `ultra` to run a deep [cloud review](/docs/en/ultrareview). Posting to a GitLab merge request requires Claude Code v2.1.257 or later. With `ultra` on a `github.com` PR target, pass `--post` to preselect [posting the finished findings to the PR](/docs/en/ultrareview#post-findings-to-the-pull-request) in the launch dialog; `--post` requires Claude Code v2.1.227 or later. See [Review a diff locally](/docs/en/code-review#review-a-diff-locally) for the effort levels, targeting, and how it relates to `/simplify`. Alias: `/review` |71| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | **[Skill](/docs/en/skills#bundled-skills).** Review the current diff, or a PR number, branch, or path you pass, for correctness bugs. Depending on your model and effort level, the review also covers cleanup opportunities. Pass `--fix` to have Claude apply the findings, `--comment` to post them on the GitHub PR or GitLab merge request, or `ultra` to run a deep [cloud review](/docs/en/ultrareview). Posting to a GitLab merge request requires Claude Code v2.1.257 or later. With `ultra` on a `github.com` PR target, pass `--post` to preselect [posting the finished findings to the PR](/docs/en/ultrareview#post-findings-to-the-pull-request) in the launch dialog; `--post` requires Claude Code v2.1.227 or later. See [Review locally with `/code-review`](/docs/en/code-review-local) for the effort levels, targeting, and how it relates to `/simplify`. Alias: `/review` |

72| `/color [color\|default]` | Set the prompt bar color for the current session. Available colors: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` to reset, or run with no argument to pick a random color. When [Remote Control](/docs/en/remote-control) is connected, the color syncs to claude.ai/code. Also available in non-interactive mode (`-p`) |72| `/color [color\|default]` | Set the prompt bar color for the current session. Available colors: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` to reset, or run with no argument to pick a random color. When [Remote Control](/docs/en/remote-control) is connected, the color syncs to claude.ai/code. Also available in non-interactive mode (`-p`) |

73| `/compact [instructions]` | Free up context by summarizing the conversation so far. Optionally pass focus instructions for the summary. See [how compaction handles rules, skills, and memory files](/docs/en/context-window#what-survives-compaction) |73| `/compact [instructions]` | Free up context by summarizing the conversation so far. Optionally pass focus instructions for the summary. See [how compaction handles rules, skills, and memory files](/docs/en/context-window#what-survives-compaction) |

74| `/config [key=value ...]` | Open the [Settings](/docs/en/settings) interface to adjust theme, model, [output style](/docs/en/output-styles), and other preferences. Pass one or more `key=value` pairs to set a setting directly without opening the interface, for example `/config thinking=false`, `/config theme=dark`, or `/config model=sonnet`. The `key=value` form also works in non-interactive mode (`-p`) and from the Claude mobile app via [Remote Control](/docs/en/remote-control). The `key=value` form can't turn on a setting that needs your confirmation in the panel, such as [`autoContinueAtUsageLimit`](/docs/en/interactive-mode#turn-automatic-continue-off), though it can turn one off. Run `/config --help` to list the keys it accepts. Alias: `/settings` |74| `/config [key=value ...]` | Open the [Settings](/docs/en/settings) interface to adjust theme, model, [output style](/docs/en/output-styles), and other preferences. Pass one or more `key=value` pairs to set a setting directly without opening the interface, for example `/config thinking=false`, `/config theme=dark`, or `/config model=sonnet`. The `key=value` form also works in non-interactive mode (`-p`) and from the Claude mobile app via [Remote Control](/docs/en/remote-control). The `key=value` form can't turn on a setting that needs your confirmation in the panel, such as [`autoContinueAtUsageLimit`](/docs/en/interactive-mode#turn-automatic-continue-off), though it can turn one off. Run `/config --help` to list the keys it accepts. Alias: `/settings` |

130| `/remote-env` | Choose the default [cloud environment](/docs/en/cloud-environments#select-an-environment-from-the-cli) for cloud sessions you start from the CLI |130| `/remote-env` | Choose the default [cloud environment](/docs/en/cloud-environments#select-an-environment-from-the-cli) for cloud sessions you start from the CLI |

131| `/rename [name]` | Rename the current session and show the name on the prompt bar. Without a name, auto-generates one from conversation history. Also available in non-interactive mode (`-p`). From every rename surface, including claude.ai and the desktop app, Claude Code replaces control and invisible characters in the new name with spaces and caps the name at 200 characters. If the name is empty once invisible characters are removed, Claude Code rejects it and shows `That name is empty once invisible characters are removed. Usage: /rename <name>`. The character replacement and length cap require Claude Code v2.1.221 or later |131| `/rename [name]` | Rename the current session and show the name on the prompt bar. Without a name, auto-generates one from conversation history. Also available in non-interactive mode (`-p`). From every rename surface, including claude.ai and the desktop app, Claude Code replaces control and invisible characters in the new name with spaces and caps the name at 200 characters. If the name is empty once invisible characters are removed, Claude Code rejects it and shows `That name is empty once invisible characters are removed. Usage: /rename <name>`. The character replacement and length cap require Claude Code v2.1.221 or later |

132| `/resume [session]` | Resume a conversation by ID or name, or open the session picker. [Background sessions](/docs/en/agent-view) appear in the picker marked with `bg`. Resuming one that is still running, from the picker or by ID or name, [opens that session](/docs/en/sessions#resume-a-running-background-session): your current conversation moves to the background and this terminal attaches to the running one. Press `←` on an empty prompt to return to agent view, which also lists the conversation you left. Before v2.1.285, Claude Code refused and told you to open the session with `claude attach` or stop it first. Alias: `/continue` |132| `/resume [session]` | Resume a conversation by ID or name, or open the session picker. [Background sessions](/docs/en/agent-view) appear in the picker marked with `bg`. Resuming one that is still running, from the picker or by ID or name, [opens that session](/docs/en/sessions#resume-a-running-background-session): your current conversation moves to the background and this terminal attaches to the running one. Press `←` on an empty prompt to return to agent view, which also lists the conversation you left. Before v2.1.285, Claude Code refused and told you to open the session with `claude attach` or stop it first. Alias: `/continue` |

133| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | Alias of [`/code-review`](/docs/en/code-review#review-a-diff-locally): reviews the current diff, or a PR number, branch, or path you pass, such as `/review 1234`, and takes the same effort levels and flags. With no level given, the review reuses the last `low` through `max` level you typed; see [Review a diff locally](/docs/en/code-review#review-a-diff-locally) for the exact rules. For a deep cloud review, use [`/code-review ultra`](/docs/en/ultrareview). Before v2.1.223, `/review` was a separate command that ran a single-pass, read-only review of a GitHub pull request by number, listing open PRs to pick from when run with no argument; from v2.1.186 through v2.1.201, it ran the same multi-agent engine as `/code-review medium` |133| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | Alias of [`/code-review`](/docs/en/code-review-local): reviews the current diff, or a PR number, branch, or path you pass, such as `/review 1234`, and takes the same effort levels and flags. With no level given, the review reuses the last `low` through `max` level you typed; see [Review locally with `/code-review`](/docs/en/code-review-local) for the exact rules. For a deep cloud review, use [`/code-review ultra`](/docs/en/ultrareview). Before v2.1.223, `/review` was a separate command that ran a single-pass, read-only review of a GitHub pull request by number, listing open PRs to pick from when run with no argument; from v2.1.186 through v2.1.201, it ran the same multi-agent engine as `/code-review medium` |

134| `/rewind` | Rewind the conversation and/or code to a previous point, or summarize from a selected message. See [checkpointing](/docs/en/checkpointing). Aliases: `/checkpoint`, `/undo` |134| `/rewind` | Rewind the conversation and/or code to a previous point, or summarize from a selected message. See [checkpointing](/docs/en/checkpointing). Aliases: `/checkpoint`, `/undo` |

135| `/run` | **[Skill](/docs/en/skills#bundled-skills).** Launch and drive your project's app to see a change working, not only passing tests. See [Run and verify your app](/docs/en/skills#run-and-verify-your-app) |135| `/run` | **[Skill](/docs/en/skills#bundled-skills).** Launch and drive your project's app to see a change working, not only passing tests. See [Run and verify your app](/docs/en/skills#run-and-verify-your-app) |

136| `/run-skill-generator` | **[Skill](/docs/en/skills#bundled-skills).** Teach `/run` and `/verify` how to build, launch, and drive your project's app from a clean environment by writing a per-project [skill](/docs/en/skills#run-and-verify-your-app) |136| `/run-skill-generator` | **[Skill](/docs/en/skills#bundled-skills).** Teach `/run` and `/verify` how to build, launch, and drive your project's app from a clean environment by writing a per-project [skill](/docs/en/skills#run-and-verify-your-app) |

desktop.md +233 −3

Details

181* Click **Walk through in diff** to open the diff view and step through the findings one at a time. A finding in the current diff appears at its line, where you can click **Fix this one** or dismiss it.181* Click **Walk through in diff** to open the diff view and step through the findings one at a time. A finding in the current diff appears at its line, where you can click **Fix this one** or dismiss it.

182* Click **Apply fixes** to ask Claude to fix the findings that are still open.182* Click **Apply fixes** to ask Claude to fix the findings that are still open.

183 183

184In any session, you can also ask Claude in the prompt box to fix what the review found. For what `/code-review` looks for and the arguments it takes, see [Review a diff locally](/docs/en/code-review#review-a-diff-locally).184In any session, you can also ask Claude in the prompt box to fix what the review found. For what `/code-review` looks for and the arguments it takes, see [Review locally with `/code-review`](/docs/en/code-review-local).

185 185

186### Monitor pull request status186### Monitor pull request status

187 187

757* **Sessions per connection**: Desktop on macOS and Linux opens several sessions on one SSH connection. If the server's `sshd_config` sets `MaxSessions 1`, raise it, for example to OpenSSH's default of 10.757* **Sessions per connection**: Desktop on macOS and Linux opens several sessions on one SSH connection. If the server's `sshd_config` sets `MaxSessions 1`, raise it, for example to OpenSSH's default of 10.

758* **Install folder**: Desktop installs a helper program and Claude Code under `~/.claude/remote/` in your home directory. It runs them from there, so that folder can't be on a file system mounted `noexec`. Allow about 1 GB of disk space in the home directory of each user who connects. For what that folder holds, see [Files and processes on the remote machine](#files-and-processes-on-the-remote-machine).758* **Install folder**: Desktop installs a helper program and Claude Code under `~/.claude/remote/` in your home directory. It runs them from there, so that folder can't be on a file system mounted `noexec`. Allow about 1 GB of disk space in the home directory of each user who connects. For what that folder holds, see [Files and processes on the remote machine](#files-and-processes-on-the-remote-machine).

759* **Shell**: the shell set for your account on the remote machine has to run commands sent over SSH, as Bash, Zsh, and `sh` do759* **Shell**: the shell set for your account on the remote machine has to run commands sent over SSH, as Bash, Zsh, and `sh` do

760* **Network**: Claude Code runs on the remote machine and makes its network requests from there, so the machine needs the [network access that Claude Code requires](/docs/en/network-config#network-access-requirements). If the machine can't download Claude Code, Desktop downloads it on your computer and uploads it. Claude Code's other requests still go out from the remote machine.760* **Network**: Claude Code runs on the remote machine and makes its network requests from there, so the machine needs the [network access that Claude Code requires](/docs/en/network-config#network-access-requirements). If the machine can't download Claude Code, Desktop downloads it on your computer and uploads it. Claude Code's other requests still go out from the remote machine. On a Linux remote machine, if those requests need a proxy, [set it for SSH sessions](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions).

761

762#### Set a proxy or a CA certificate for SSH sessions

763

764If a Linux remote machine reaches the internet through a proxy or needs a CA certificate, add the [proxy and CA variables](/docs/en/network-config) under `env` in `~/.claude/settings.json` there. Add them even if you already export them in `~/.profile`, `~/.bash_profile`, `~/.zprofile`, or `~/.zshrc` on that machine.

765

766An SSH session doesn't get them from those files, even when `claude` in a terminal on that machine does. The session can then hang, or show **The connection from … to the API failed** or **Authentication failed**, and signing in again doesn't help.

767

768<Steps>

769 <Step title="Add the variables">

770 For the CA file, use [`NODE_EXTRA_CA_CERTS`](/docs/en/network-config#custom-ca-certificates), because Claude Code doesn't trust a CA from `SSL_CERT_FILE` in `~/.claude/settings.json`. This example sets a proxy and a CA file:

771

772 ```json ~/.claude/settings.json theme={null}

773 {

774 "env": {

775 "HTTPS_PROXY": "http://proxy.example.com:8080",

776 "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/example-ca.pem"

777 }

778 }

779 ```

780 </Step>

781

782 <Step title="Send your message again">

783 Send your message again, because a variable that you add or change in that file takes effect within seconds. Start a new session if it still fails.

784 </Step>

785</Steps>

786

787##### Find a proxy or CA variable set elsewhere on the remote machine

788

789Check whether the Linux remote machine sets the proxy or CA variable elsewhere, because sessions use that value and [ignore the one in any settings file](/docs/en/settings-reference#how-env-values-interact-with-your-shell):

790

791<Steps>

792 <Step title="List the variables that the remote machine sets">

793 In a terminal on your computer, run `ssh devbox env`, with your own host.

794 </Step>

795

796 <Step title="Change the variable where it is set">

797 If the list has the variable, change it in the file that sets it, such as `~/.zshenv`, `/etc/environment`, or `~/.bashrc` on the remote machine.

798 </Step>

799

800 <Step title="Give sessions the new value">

801 Restart the remote machine, or quit Desktop and end the helper's processes, as in the first two steps to [remove the helper](#files-and-processes-on-the-remote-machine). Do this when no task is running, because either way interrupts Claude's work.

802 </Step>

803</Steps>

761 804

762#### Use your SSH configuration on macOS and Linux805#### Use your SSH configuration on macOS and Linux

763 806

786 829

787Enter `devbox` in the **SSH host** field.830Enter `devbox` in the **SSH host** field.

788 831

832##### Reach a container on a remote machine

833

834To run a session inside a container that publishes no SSH port, reach it with a `ProxyCommand`, because Desktop doesn't run the `RemoteCommand` of the entry you connect to. If your entry uses `RemoteCommand` to step into the container, the session runs on the machine that the entry logs in to, not in the container.

835

836<Steps>

837 <Step title="Add the entry">

838 Add the following entry at the end of your `~/.ssh/config`, or directly above your first `Host *` entry if you have one. Replace the Docker container `devbox`, its user `dev`, and the machine `build.example.com` with your own. The entry's command starts an SSH server inside the container for each connection:

839

840 ```text ~/.ssh/config theme={null}

841 Host devbox-container

842 User dev

843 ProxyCommand ssh build.example.com docker exec -i devbox /usr/sbin/sshd -i

844 ```

845 </Step>

846

847 <Step title="Prepare the container">

848 * Install the OpenSSH server, with a host key that stays the same when you rebuild the image or recreate the container

849 * Give the account named in `User` a way to log in, such as an `authorized_keys` file

850 * Check that the container meets the [remote machine requirements](#remote-machine-requirements-for-ssh-sessions)

851 </Step>

852

853 <Step title="Check the allowlist">

854 If your administrator [restricts SSH hosts](#restrict-which-ssh-hosts-users-can-connect-to), run `ssh -G devbox-container` in a terminal on your computer. Ask them to allow the `hostname` that it prints, here `devbox-container`, in `sshHostAllowlist`. When they allow that name, they allow whatever your entry's `ProxyCommand` connects to.

855 </Step>

856

857 <Step title="Test the entry, then connect">

858 Run `ssh devbox-container` in a terminal on your computer. Fix what it reports, and run it again until it opens a shell in the container without asking you anything:

859

860 * **If `ssh` asks for a password, passphrase, or code**: switch to a login that works without a prompt, such as a key that your SSH agent holds

861 * **If `ssh` reports `Cannot execute command-line and remote command.` or `Bad packet length`**: take `RemoteCommand` and `RequestTTY` out of your entry for `build.example.com`. After that, `ssh build.example.com` in a terminal on your computer opens a shell on that machine, not in the container.

862 * **If `ssh` reports `Connection closed by UNKNOWN port 65535`**: run `ssh build.example.com docker exec devbox /usr/sbin/sshd -t` in the same terminal.

863 * If it prints `Missing privilege separation directory: /run/sshd`, create that folder in the container.

864 * If it prints `no hostkeys available` and the container has host keys, add `-u root` after `exec` in this command and in the entry.

865

866 Then enter `devbox-container` in the **SSH host** field.

867 </Step>

868</Steps>

869

789##### Use variables from your shell in a `ProxyCommand`870##### Use variables from your shell in a `ProxyCommand`

790 871

791To use an environment variable of your own in a `ProxyCommand` or `Match exec` command, export it in a shell startup file, such as `~/.zshrc`, then quit and reopen Desktop. When Desktop starts, it reads what your login shell exports, and it keeps those values until you quit.872To use an environment variable of your own in a `ProxyCommand` or `Match exec` command, export it in a shell startup file, such as `~/.zshrc`, then quit and reopen Desktop. When Desktop starts, it reads what your login shell exports, and it keeps those values until you quit.

792 873

793This requires Claude Desktop v2.37337.0 or later and an `env` command that accepts `-0`, which you can check by running `env -0` in a terminal on your computer.874This requires Claude Desktop v2.37337.0 or later and an `env` command that accepts `-0`, which you can check by running `env -0` in a terminal on your computer.

794 875

876<Note>

877 If your shell sets temporary AWS credentials, [give the AWS CLI a profile](#use-aws-credentials-in-a-proxycommand) instead of exporting `AWS_*` variables.

878</Note>

879

880<a id="use-aws-credentials-in-a-proxycommand" />

881

882##### Use AWS credentials in a `ProxyCommand`

883

884If you set temporary AWS credentials in a shell startup file, a `ProxyCommand` that runs the AWS CLI can connect in a terminal and fail in Desktop. When your shell exports `AWS_SESSION_TOKEN`, `AWS_SECURITY_TOKEN`, or `AWS_CREDENTIAL_EXPIRATION`, `ssh` and your `ProxyCommand` in Desktop don't get the shell's AWS credentials, `AWS_REGION`, or `AWS_PROFILE`.

885

886If the AWS CLI has no other source for a region or credentials, it fails with `You must specify a region` or `Unable to locate credentials`. To connect from Desktop, give the AWS CLI a profile that it reads from `~/.aws/config`:

887

888<Steps>

889 <Step title="Add a profile with a region and a source of credentials">

890 This example adds a profile named `corp` that gets its credentials from a helper program:

891

892 ```ini ~/.aws/config theme={null}

893 [profile corp]

894 region = us-east-1

895 credential_process = /full/path/to/your-credential-helper

896 ```

897

898 * **`region`**: give the AWS Region of the machines you connect to

899 * **`credential_process`**: give the full path of a program that prints credentials in the [JSON form that AWS documents](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html). Choose a program that needs no input from you, because the AWS CLI runs it at every connection, including reconnects while you're away.

900 * **IAM Identity Center**: add the profile's [IAM Identity Center settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) in place of `credential_process`. Run `aws sso login --profile corp` in a terminal before you connect, and again when that sign-in lapses.

901 </Step>

902

903 <Step title="Name the profile in the ProxyCommand">

904 This example adds `--profile` to the [command that AWS documents for Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started-enable-ssh-connections.html):

905

906 ```text ~/.ssh/config theme={null}

907 Host i-*

908 ProxyCommand sh -c "aws ssm start-session --profile corp --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

909 ```

910 </Step>

911

912 <Step title="Connect again">

913 Run `ssh` with the host in a terminal to confirm that the entry still connects there, then connect from Desktop.

914 </Step>

915</Steps>

916

795##### Raise the SSH connection timeout917##### Raise the SSH connection timeout

796 918

797If your SSH configuration sets no `ConnectTimeout` for the host, Desktop gives `ssh` 30 seconds to connect. Through a jump host or a `ProxyCommand`, that time includes the time the route takes to connect. If your route needs longer, add a higher value to the entry:919If your SSH configuration sets no `ConnectTimeout` for the host, Desktop gives `ssh` 30 seconds to connect. Through a jump host or a `ProxyCommand`, that time includes the time the route takes to connect. If your route needs longer, add a higher value to the entry:

806 928

807`ssh` uses the first value it finds for a host, so keep the entry above any `Host *` entry that sets `ConnectTimeout`. To confirm, run `ssh -G devbox` in a terminal on your computer. Its output includes `connecttimeout 120`. After you change the value, quit and reopen Desktop.929`ssh` uses the first value it finds for a host, so keep the entry above any `Host *` entry that sets `ConnectTimeout`. To confirm, run `ssh -G devbox` in a terminal on your computer. Its output includes `connecttimeout 120`. After you change the value, quit and reopen Desktop.

808 930

931If the remote machine itself waits for an approval on your phone, approve within 45 seconds, whatever `ConnectTimeout` you set. You can't raise this limit, because Desktop sets `ServerAliveInterval` and `ServerAliveCountMax` itself, and `ssh` then closes a login in which the remote machine sends nothing for that long. If a jump host or a `ProxyCommand` waits for you instead, raise `ConnectTimeout` in the remote machine's entry to cover that time.

932

933##### Fix a `Match host` block that only Desktop applies

934

935If Desktop uses a setting that `ssh devbox` in a terminal doesn't, look for a `Match host` block above the entry's `HostName` line. In a terminal, `ssh` reads a block there before the `HostName` line, so it compares the block with `devbox`. Desktop gives `ssh` the `HostName` value on the command line, so `ssh` compares the block with that value.

936

937To check, run `ssh -G` in a terminal on your computer with the entry's `HostName` and `User` values on the command line, as Desktop does:

938

939```bash theme={null}

940ssh -G -o HostName=devbox.internal.example.com -l alice devbox

941```

942

943Compare the output with that of `ssh -G devbox`. If the block's settings, such as `proxycommand`, show only in the first output, the block takes effect only in Desktop. To have Desktop skip it too, add `!originalhost devbox` to its `Match` line:

944

945```text ~/.ssh/config theme={null}

946Match host *.internal.example.com !originalhost devbox

947```

948

949To confirm, run the first command again. The block's settings no longer show in its output.

950

809##### Forwarding settings that Desktop leaves off951##### Forwarding settings that Desktop leaves off

810 952

811On its connection to the remote machine, Desktop leaves `ForwardAgent`, `ForwardX11`, `LocalForward`, `RemoteForward`, `DynamicForward`, and `Tunnel` off, even where your SSH configuration turns them on. In the [terminal](#run-commands-in-the-terminal) or a `!` command, expect your forwarding settings to apply [only sometimes](#limits-while-desktop-is-disconnected), because Desktop can start a separate `ssh` there that follows them.953On its connection to the remote machine, Desktop leaves `ForwardAgent`, `ForwardX11`, `LocalForward`, `RemoteForward`, `DynamicForward`, and `Tunnel` off, even where your SSH configuration turns them on. In the [terminal](#run-commands-in-the-terminal) or a `!` command, expect your forwarding settings to apply [only sometimes](#limits-while-desktop-is-disconnected), because Desktop can start a separate `ssh` there that follows them.

1022 </Step>1164 </Step>

1023 1165

1024 <Step title="End the processes">1166 <Step title="End the processes">

1025 Logged in as that user on the remote machine, run `kill` with each process ID that [`pgrep`](#files-and-processes-on-the-remote-machine) lists.1167 Logged in as that user on the remote machine, run `kill` with the ID of each Claude Code process that [`pgrep`](#files-and-processes-on-the-remote-machine) lists. Once those are gone from the list, run `kill` with the ID of each `server` process. If you end a `server` process first, a command that Claude Code is running can keep running.

1168

1169 Then list the user's remaining processes, for example with `ps -u "$(id -un)" -f`, and end any that you recognize as started by Claude Code. Programs that it left in the background can keep running after it ends, without being in the `pgrep` list.

1026 </Step>1170 </Step>

1027 1171

1028 <Step title="Delete the folder">1172 <Step title="Delete the folder">

1036 1180

1037Before you archive a session that has a worktree, see [Work in parallel with sessions](#work-in-parallel-with-sessions).1181Before you archive a session that has a worktree, see [Work in parallel with sessions](#work-in-parallel-with-sessions).

1038 1182

1183##### See which user the processes run as

1184

1185The helper and Claude Code run as the user that Desktop logs in as over SSH. Installing and starting them takes no `sudo`. To check the user, run `ps -o user= -p` on the remote machine with a process ID that [`pgrep`](#files-and-processes-on-the-remote-machine) lists.

1186

1187Programs that Claude Code starts, such as shell commands and MCP servers, start as that user too. Review that user's rights on the remote machine, its `sudo` rules included, as you would for a person who runs commands there.

1188

1039##### See who connected to the remote machine1189##### See who connected to the remote machine

1040 1190

1041To find out who connected to a remote machine, read the SSH server's log on that machine, where a login from Desktop looks like one from a terminal. With Desktop on macOS or Linux, expect an entry each time Desktop connects, not one for each session.1191To find out who connected to a remote machine, read the SSH server's log on that machine, where a login from Desktop looks like one from a terminal. With Desktop on macOS or Linux, expect an entry each time Desktop connects, not one for each session.

1042 1192

1193You won't find Desktop's SSH connections in Claude Code's [metrics and events](/docs/en/monitoring-usage#available-metrics-and-events). To find out from them which remote machine an SSH session ran on, see [Attribute telemetry to Desktop SSH sessions](/docs/en/monitoring-usage#attribute-telemetry-to-desktop-ssh-sessions). For Desktop's own record of its connections, see [Get Desktop's logs for an SSH problem](#get-desktops-logs-for-an-ssh-problem).

1194

1195#### Connections that close before login

1196

1197If the SSH server's log shows connections that close before any login, they can be Desktop's tests of the SSH port. Desktop tests whether a machine answers, for example after a connection to it failed. It opens a connection to the port and closes it at once, without sending anything. Expect one test or several in a row, for example eight in about two minutes.

1198

1199If nothing bans or refuses addresses for such connections, you don't have to do anything about Desktop's tests. If an address that Desktop connects from is refused or banned, check [whether the SSH server itself refuses the address](#check-whether-the-ssh-server-itself-refuses-the-address) and [whether fail2ban counts Desktop's tests](#check-whether-fail2ban-counts-desktops-tests).

1200

1201##### Recognize a test in the SSH server's log

1202

1203Compare the lines in your log with those that an OpenSSH server on Linux writes for a test at the default `LogLevel`, in the row for your server's version. You can see the lines in the last column instead if the server's greeting arrives before Desktop closes the connection:

1204

1205| OpenSSH version | Lines for a test | Lines if the greeting arrives first |

1206| - | - | - |

1207| 6.6 to 7.9 | A line with `Did not receive identification string from 203.0.113.7` | The same line |

1208| 8.0 to 8.2 | `error: kex_exchange_identification: Connection closed by remote host` | `error: kex_exchange_identification: read: Connection reset by peer` |

1209| 8.3 to 9.4 | `error: kex_exchange_identification: Connection closed by remote host`, then `Connection closed by 203.0.113.7 port 51234` | `error: kex_exchange_identification: read: Connection reset by peer`, then `Connection reset by 203.0.113.7 port 51234` |

1210| 9.5 to 10.2 | `Connection closed by 203.0.113.7 port 51234` | `error: kex_exchange_identification: read: Connection reset by peer`, then `Connection reset by 203.0.113.7 port 51234` |

1211| 10.3 to 10.5 | `Connection closed by 203.0.113.7 port 51234 [preauth]` | `error: kex_exchange_identification: read: Connection reset by peer [preauth]`, then `Connection reset by 203.0.113.7 port 51234 [preauth]` |

1212

1213Other programs that open the port and close it can leave the same lines. Where a line has an address, check that it is one that a computer with Desktop connects from.

1214

1215The lines of 8.0 to 8.2 have no address. To get one, set `LogLevel VERBOSE` in `sshd_config` and run `sshd -T | grep -i loglevel` as root. If it prints `loglevel VERBOSE`, reload the SSH server. Then look for a line with `Connection from 203.0.113.7 port 51234` before the test's line.

1216

1217<a id="check-whether-the-ssh-server-itself-refuses-the-address" />

1218

1219##### Check whether the SSH server itself refuses the address

1220

1221If connections are refused from an address that many computers with Desktop share, look in the SSH server's log for a line that ends like this one:

1222

1223```text theme={null}

1224drop connection #0 from [203.0.113.7]:51234 on [192.0.2.10]:22 penalty: connections without attempting authentication

1225```

1226

1227With the default `LogLevel`, OpenSSH 9.8 and later can write such a line when refusing an address for connections that closed without trying to log in, as Desktop's tests do. With the default settings, you don't see such a line after a few tests alone.

1228

1229To prevent the refusal, set `PerSourcePenaltyExemptList` in `sshd_config` to the addresses that people connect from, for example `PerSourcePenaltyExemptList 203.0.113.7`. The server then applies none of its penalties to those addresses, including those for failed logins. To check the file, run `sshd -T | grep -i persourcepenalt` as root. If it prints your list, reload the SSH server.

1230

1231<a id="check-whether-fail2ban-counts-desktops-tests" />

1232

1233##### Check whether fail2ban counts Desktop's tests

1234

1235If fail2ban 0.10.5 or later banned an address that Desktop connects from, find your jail's mode in `jail.conf`, `jail.local` or under `jail.d/`:

1236

1237* **A `filter` line that names a mode in brackets**, such as `filter = sshd[mode=aggressive]`: use that mode.

1238* **Only the stock `filter` line**, with `[mode=%(mode)s]`: use the `mode` line, or `normal` if there is none.

1239

1240If the mode is `normal`, fail2ban doesn't count the lines of Desktop's tests, so look for another cause of the ban.

1241

1242For another mode, copy the lines from your own log to a file on the remote machine. Copy each line whole, from its date to its end, and both lines where a test leaves two. Run `fail2ban-regex` there with the file and your jail's mode, for example `aggressive`:

1243

1244```bash theme={null}

1245fail2ban-regex -o ip lines.log "sshd[mode=aggressive]"

1246```

1247

1248For each failure that fail2ban counts, the command prints the address on a line of its own, such as `203.0.113.7`. In that case, [prevent a ban](#prevent-a-ban-by-fail2ban). If it prints nothing, fail2ban counts none of those lines in that mode, so look for another cause of the ban.

1249

1250<a id="prevent-a-ban-by-fail2ban" />

1251

1252##### Prevent a ban by fail2ban

1253

1254To keep fail2ban from banning an address for Desktop's tests, change one of two settings of the jail, each at a cost:

1255

1256* **`mode`**: set it to `normal` wherever your jail sets it, in a `mode` line or in the brackets of a line such as `filter = sshd[mode=aggressive]`. You give up every count that only the other modes make, for example of clients that connect and leave without trying to log in.

1257* **`ignoreip`**: set it to the addresses that people connect from, for example `ignoreip = 203.0.113.7`. fail2ban then counts nothing from those addresses, failed logins included.

1258

1043#### Use MCP servers set up on the remote machine1259#### Use MCP servers set up on the remote machine

1044 1260

1045To use an [MCP server](/docs/en/mcp) from `~/.claude.json` or a project's `.mcp.json` in an SSH session, set it up in those files on the remote machine. Claude Code starts their stdio servers there, so install the commands those servers run on the remote machine. For servers from `claude_desktop_config.json`, see [Limits while Desktop is disconnected](#limits-while-desktop-is-disconnected).1261To use an [MCP server](/docs/en/mcp) from `~/.claude.json` or a project's `.mcp.json` in an SSH session, set it up in those files on the remote machine. Claude Code starts their stdio servers there, so install the commands those servers run on the remote machine. For servers from `claude_desktop_config.json`, see [Limits while Desktop is disconnected](#limits-while-desktop-is-disconnected).

1488 1704

1489For any other message, check the [remote machine requirements](#remote-machine-requirements-for-ssh-sessions).1705For any other message, check the [remote machine requirements](#remote-machine-requirements-for-ssh-sessions).

1490 1706

1707<a id="get-desktops-logs-for-an-ssh-problem" />

1708

1709### Get Desktop's logs for an SSH problem

1710

1711You get `ssh.log`, Desktop's record of its SSH connections, in a zip file of Desktop's logs that you save from the **Help** menu. To save it, open **Help > Troubleshooting** and select the item for your system:

1712

1713* **macOS**: **Show Logs in Finder**

1714* **Windows**: **Show Logs in File Explorer**

1715* **Linux**: **Show Logs in File Manager**

1716

1717Look through the files before you send them, because they can include names and other details from your environment. `<host>` and `<user>` stand for names that Desktop replaced. Desktop doesn't replace every name, and an SSH host or user name can still appear as written. If you send the zip file to someone, tell them which host failed and when, because the logs may not name it.

1718

1719The zip file doesn't hold the log of the helper program that Desktop installs on the remote machine. To get that log as well, copy `remote-server.log` from the helper's folder under [`~/.claude/remote/run/`](#files-and-processes-on-the-remote-machine) in the home directory of the user who connected. Look through that file too before you send it.

1720

1491### App won't quit1721### App won't quit

1492 1722

1493* **macOS**: press Cmd+Q. If the app doesn't respond, use Force Quit with Cmd+Option+Esc, select Claude, and click Force Quit.1723* **macOS**: press Cmd+Q. If the app doesn't respond, use Force Quit with Cmd+Option+Esc, select Claude, and click Force Quit.

env-vars.md +3 −1

Details

215| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | Set to `0` to stop Claude Code from opening the browser automatically when a new [artifact](/docs/en/artifacts#create-an-artifact) is published |215| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | Set to `0` to stop Claude Code from opening the browser automatically when a new [artifact](/docs/en/artifacts#create-an-artifact) is published |

216| `CLAUDE_CODE_ARTIFACT_COMMENTS` | Set to `0` to stop Claude reading and replying to [comments on an artifact](/docs/en/artifacts#collect-comments-on-an-artifact). Has no effect when `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` has [turned artifacts off](/docs/en/artifacts#availability). Requires Claude Code v2.1.221 or later |216| `CLAUDE_CODE_ARTIFACT_COMMENTS` | Set to `0` to stop Claude reading and replying to [comments on an artifact](/docs/en/artifacts#collect-comments-on-an-artifact). Has no effect when `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` has [turned artifacts off](/docs/en/artifacts#availability). Requires Claude Code v2.1.221 or later |

217| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | Set to `0` to stop Claude [replying on its own to comments sent to it](/docs/en/artifacts#let-claude-reply-to-comments-on-its-own). Requires Claude Code v2.1.228 or later |217| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | Set to `0` to stop Claude [replying on its own to comments sent to it](/docs/en/artifacts#let-claude-reply-to-comments-on-its-own). Requires Claude Code v2.1.228 or later |

218| `CLAUDE_CODE_ARTIFACT_PUBLISH_EDITS` | Set to `0` to stop Claude from applying small changes to an [artifact's](/docs/en/artifacts#update-an-artifact) file as part of publishing it. Claude then edits the file with its file-editing tools and publishes it as a separate step. Requires Claude Code v2.1.300 or later |

218| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Set to `0` to omit the [attribution block](/docs/en/llm-gateway-protocol#system-prompt-attribution-block), which carries the client version and a prompt fingerprint, from the start of the system prompt. Caching on a direct connection to the Anthropic API is unaffected either way. In some direct-connection setups, Claude Code keeps the block on [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier requests even when you set `0`. In [System prompt attribution block](/docs/en/llm-gateway-protocol#system-prompt-attribution-block), check which connections and credentials this covers. Before v2.1.181 the block included a per-request token on custom base URLs and Microsoft Foundry connections, so on those versions set it to `0` when your LLM gateway caches on the request body or forwards requests to a third-party provider, or when you connect to Microsoft Foundry directly |219| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Set to `0` to omit the [attribution block](/docs/en/llm-gateway-protocol#system-prompt-attribution-block), which carries the client version and a prompt fingerprint, from the start of the system prompt. Caching on a direct connection to the Anthropic API is unaffected either way. In some direct-connection setups, Claude Code keeps the block on [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier requests even when you set `0`. In [System prompt attribution block](/docs/en/llm-gateway-protocol#system-prompt-attribution-block), check which connections and credentials this covers. Before v2.1.181 the block included a per-request token on custom base URLs and Microsoft Foundry connections, so on those versions set it to `0` when your LLM gateway caches on the request body or forwards requests to a third-party provider, or when you connect to Microsoft Foundry directly |

219| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | Removed in v2.1.283. Use `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` instead |220| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | Removed in v2.1.283. Use `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` instead |

220| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Set the [auto-compact window](/docs/en/model-config#set-the-auto-compact-window) in tokens, from `100000` to `1000000`. Accepts a plain integer such as `500000` only: a value like `500k` reads as `500` and clamps to the 100K minimum. The effective window is also capped at the model's context window. Takes precedence over the `/autocompact` command, the `--autocompact` flag, and the `autoCompactWindow` setting. The status line's `used_percentage` always measures against the model's full context window, so once this variable is set, that percentage no longer indicates when compaction will run |221| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Set the [auto-compact window](/docs/en/model-config#set-the-auto-compact-window) in tokens, from `100000` to `1000000`. Accepts a plain integer such as `500000` only: a value like `500k` reads as `500` and clamps to the 100K minimum. The effective window is also capped at the model's context window. Takes precedence over the `/autocompact` command, the `--autocompact` flag, and the `autoCompactWindow` setting. The status line's `used_percentage` always measures against the model's full context window, so once this variable is set, that percentage no longer indicates when compaction will run |

322| `CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` | Context size, in tokens, at which [idle compaction](/docs/en/settings-reference#idlecompaction) applies to a conversation (default: `200000`). Accepts a positive whole number, and anything else is ignored. Values below `100000` are raised to `100000`, the lowest threshold. Idle compaction is on by default for conversations that meet its conditions. To turn it off, set `idleCompaction` to `false`. Requires Claude Code v2.1.290 or later |323| `CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` | Context size, in tokens, at which [idle compaction](/docs/en/settings-reference#idlecompaction) applies to a conversation (default: `200000`). Accepts a positive whole number, and anything else is ignored. Values below `100000` are raised to `100000`, the lowest threshold. Idle compaction is on by default for conversations that meet its conditions. To turn it off, set `idleCompaction` to `false`. Requires Claude Code v2.1.290 or later |

323| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | How many [subagents](/docs/en/sub-agents#concurrent-subagent-limit) can be running in one session before the Agent tool refuses to spawn another (default: 20). Accepts a positive whole number in plain digits; anything else is ignored, so the variable can adjust the cap but can't disable it. Requires Claude Code v2.1.217 or later |324| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | How many [subagents](/docs/en/sub-agents#concurrent-subagent-limit) can be running in one session before the Agent tool refuses to spawn another (default: 20). Accepts a positive whole number in plain digits; anything else is ignored, so the variable can adjust the cap but can't disable it. Requires Claude Code v2.1.217 or later |

324| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Override the context window size Claude Code assumes for the active model. As of v2.1.193, how it applies depends on how Claude Code resolves the model ID; see [Correct the window for a gateway or custom model ID](/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id). Use this when routing to a model through `ANTHROPIC_BASE_URL` whose context window does not match the built-in size for its name |325| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Override the context window size Claude Code assumes for the active model. As of v2.1.193, how it applies depends on how Claude Code resolves the model ID; see [Correct the window for a gateway or custom model ID](/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id). Use this when routing to a model through `ANTHROPIC_BASE_URL` whose context window does not match the built-in size for its name |

325| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Maximum length in characters of each MCP tool description and each MCP server's instructions that Claude Code sends to the model. The value you set replaces both [default limits](/docs/en/mcp#for-mcp-server-authors): 4096, and 16384 for the description of a tool that Claude loads through tool search. Claude Code truncates longer text. Accepts a positive whole number in plain digits. Anything else is ignored and the defaults apply. Requires Claude Code v2.1.280 or later |326| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Maximum length in characters of MCP tool descriptions and MCP server instructions that Claude Code sends to the model. The value you set replaces both [default limits](/docs/en/mcp#for-mcp-server-authors): 4096, and 16384 for the description of a tool that Claude loads through tool search. Accepts a positive whole number in plain digits. Anything else is ignored and the defaults apply. Requires Claude Code v2.1.280 or later |

326| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests. Defaults and caps vary by model; see [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). Claude Code lowers a value above a model's cap to the cap. For a model ID Claude Code can't resolve to a model it knows, the default is 32000 and the cap is 128000. Increasing this value reduces the effective context window available before [auto-compaction](/docs/en/costs#reduce-token-usage) triggers |327| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests. Defaults and caps vary by model; see [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). Claude Code lowers a value above a model's cap to the cap. For a model ID Claude Code can't resolve to a model it knows, the default is 32000 and the cap is 128000. Increasing this value reduces the effective context window available before [auto-compaction](/docs/en/costs#reduce-token-usage) triggers |

327| `CLAUDE_CODE_MAX_RETRIES` | Override the number of times to retry failed API requests (default: 10). Capped at 15 as of v2.1.186; as of v2.1.199, `CLAUDE_CODE_RETRY_WATCHDOG` raises the default and removes the cap. For unattended sessions that need to wait through longer outages, set `CLAUDE_CODE_RETRY_WATCHDOG` instead |328| `CLAUDE_CODE_MAX_RETRIES` | Override the number of times to retry failed API requests (default: 10). Capped at 15 as of v2.1.186; as of v2.1.199, `CLAUDE_CODE_RETRY_WATCHDOG` raises the default and removes the cap. For unattended sessions that need to wait through longer outages, set `CLAUDE_CODE_RETRY_WATCHDOG` instead |

328| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | Removed in v2.1.224 and now a no-op. Previously capped the total number of [subagents](/docs/en/sub-agents) Claude could spawn with the Agent tool in one session (default: 200); spawning past the cap failed with `Subagent spawn limit reached`. The [concurrent subagent limit](/docs/en/sub-agents#concurrent-subagent-limit) and the [depth limit](/docs/en/sub-agents#let-subagents-spawn-their-own-subagents) still apply |329| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | Removed in v2.1.224 and now a no-op. Previously capped the total number of [subagents](/docs/en/sub-agents) Claude could spawn with the Agent tool in one session (default: 200); spawning past the cap failed with `Subagent spawn limit reached`. The [concurrent subagent limit](/docs/en/sub-agents#concurrent-subagent-limit) and the [depth limit](/docs/en/sub-agents#let-subagents-spawn-their-own-subagents) still apply |

584* Run [`/skill-doctor`](/docs/en/skills#find-unused-skills) or open its report in the `/plugin` **Stats** tab585* Run [`/skill-doctor`](/docs/en/skills#find-unused-skills) or open its report in the `/plugin` **Stats** tab

585* Sync the [skills](/docs/en/skills#where-synced-skills-load) and [plugins](/docs/en/plugins/loading#synced-plugins) enabled for your claude.ai account into your terminal sessions586* Sync the [skills](/docs/en/skills#where-synced-skills-load) and [plugins](/docs/en/plugins/loading#synced-plugins) enabled for your claude.ai account into your terminal sessions

586* Turn on the [You should know mod](/docs/en/interactive-mode#you-should-know-suggestions)587* Turn on the [You should know mod](/docs/en/interactive-mode#you-should-know-suggestions)

588* See what a [mod](/docs/en/plugins/mods/overview#where-mods-run) draws in the VS Code extension's chat panel; the mod's hooks still run

587* Use [the advisor tool](/docs/en/advisor#requirements)589* Use [the advisor tool](/docs/en/advisor#requirements)

588* Read or reply to [comments on an artifact](/docs/en/artifacts#collect-comments-on-an-artifact)590* Read or reply to [comments on an artifact](/docs/en/artifacts#collect-comments-on-an-artifact)

589* Have Claude read [another organization's public artifact](/docs/en/artifacts#read-an-artifact-shared-with-you)591* Have Claude read [another organization's public artifact](/docs/en/artifacts#read-an-artifact-shared-with-you)

errors.md +197 −7

Details

70| `Claude.ai login was rejected — run /login, then /remote-control` | [Authentication](#remote-control-couldnt-refresh-your-login) |70| `Claude.ai login was rejected — run /login, then /remote-control` | [Authentication](#remote-control-couldnt-refresh-your-login) |

71| `OAuth token unavailable — run /login to restore Remote Control` | [Authentication](#remote-control-couldnt-refresh-your-login) |71| `OAuth token unavailable — run /login to restore Remote Control` | [Authentication](#remote-control-couldnt-refresh-your-login) |

72| `Signed out of Claude — run /login, then /remote-control` | [Authentication](#remote-control-couldnt-refresh-your-login) |72| `Signed out of Claude — run /login, then /remote-control` | [Authentication](#remote-control-couldnt-refresh-your-login) |

73| `Remote Control could not renew this computer's connection` | [Authentication](#remote-control-could-not-renew-this-computers-connection) |

73| `signed-in claude.ai account or organization changed on this machine` | [Authentication](#remote-control-stopped-because-the-signed-in-account-changed) |74| `signed-in claude.ai account or organization changed on this machine` | [Authentication](#remote-control-stopped-because-the-signed-in-account-changed) |

74| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [Authentication](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |75| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [Authentication](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |

75| `Remote Control stopped — the app running this session is signed out of Claude` | [Authentication](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |76| `Remote Control stopped — the app running this session is signed out of Claude` | [Authentication](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |

155| `API Error: an image in the conversation could not be processed and was removed` | [Request errors](#image-was-too-large) |

177| `Effort '<level>' isn't available with thinking turned off on this model` | [Request errors](#effort-isnt-available-with-thinking-turned-off) |179| `Effort '<level>' isn't available with thinking turned off on this model` | [Request errors](#effort-isnt-available-with-thinking-turned-off) |

178| `effort '<level>' is not supported when thinking is disabled` | [Request errors](#effort-isnt-available-with-thinking-turned-off) |180| `effort '<level>' is not supported when thinking is disabled` | [Request errors](#effort-isnt-available-with-thinking-turned-off) |

182| `Claude's response exceeded the ... output token maximum` | [Request errors](#response-exceeded-the-output-token-maximum) |

182| `API Error: 400 duplicate tool_use ID in conversation history` | [Request errors](#tool-use-or-thinking-block-mismatch) |185| `API Error: 400 duplicate tool_use ID in conversation history` | [Request errors](#tool-use-or-thinking-block-mismatch) |

197| `The connection dropped while downloading the update` | [Troubleshoot installation and login](/docs/en/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |200| `The connection dropped while downloading the update` | [Troubleshoot installation and login](/docs/en/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |

198| `Download timed out: exceeded the total deadline` | [Troubleshoot installation and login](/docs/en/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |201| `Download timed out: exceeded the total deadline` | [Troubleshoot installation and login](/docs/en/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |

203| `Couldn't tell whether --bg is a flag or text here, so nothing was started` | [Command-line errors](#couldnt-tell-whether-bg-is-a-flag-or-text) |

200| `Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.` | [Command-line errors](#conflict-between-a-system-prompt-flag-and-its-file-form) |204| `Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.` | [Command-line errors](#conflict-between-a-system-prompt-flag-and-its-file-form) |

201| `Cloud sessions cannot be created from a --restricted session` | [Command-line errors](#cloud-sessions-cannot-be-created-from-a-restricted-session) |205| `Cloud sessions cannot be created from a --restricted session` | [Command-line errors](#cloud-sessions-cannot-be-created-from-a-restricted-session) |

202| `Cloud sessions are disabled by your organization's policy` | [Command-line errors](#cloud-sessions-are-disabled-by-your-organizations-policy) |206| `Cloud sessions are disabled by your organization's policy` | [Command-line errors](#cloud-sessions-are-disabled-by-your-organizations-policy) |

215| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [Command-line errors](#directory-couldnt-be-resolved-to-a-real-location) |219| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [Command-line errors](#directory-couldnt-be-resolved-to-a-real-location) |

216| `Error: Workspace not trusted` when starting Remote Control | [Command-line errors](#workspace-not-trusted-when-starting-remote-control) |220| `Error: Workspace not trusted` when starting Remote Control | [Command-line errors](#workspace-not-trusted-when-starting-remote-control) |

217| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [Command-line errors](#not-carried-over-to-the-sessions-remote-control-starts) |221| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [Command-line errors](#not-carried-over-to-the-sessions-remote-control-starts) |

222| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [Command-line errors](#sandbox-is-not-supported-by-claude-remote-control) |

218| `` `claude import` is not yet available in this build `` | [Command-line errors](#claude-import-is-not-yet-available-in-this-build) |223| `` `claude import` is not yet available in this build `` | [Command-line errors](#claude-import-is-not-yet-available-in-this-build) |

231| `Shell command failed for pattern "..."`, from `/security-review` or any skill that injects dynamic context | [Command-line errors](#security-review-fails-without-origin-head) |236| `Shell command failed for pattern "..."`, from `/security-review` or any skill that injects dynamic context | [Command-line errors](#security-review-fails-without-origin-head) |

232| `Shell command permission check failed for pattern "..."`, from a skill that injects dynamic context | [Command-line errors](#security-review-fails-without-origin-head) |237| `Shell command permission check failed for pattern "..."`, from a skill that injects dynamic context | [Command-line errors](#security-review-fails-without-origin-head) |

233| ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found`` | [Command-line errors](#security-review-fails-without-origin-head) |238| ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found`` | [Command-line errors](#security-review-fails-without-origin-head) |

239| `No shell command in <name> was run, because the <tool> tool does not accept one of them` | [Command-line errors](#no-shell-command-was-run) |

234| `Input must be provided either through stdin or as a prompt argument when using --print` | [Command-line errors](#input-must-be-provided-when-using-print) |240| `Input must be provided either through stdin or as a prompt argument when using --print` | [Command-line errors](#input-must-be-provided-when-using-print) |

235| `Claude Code can't read the keyboard here: stdin is not a terminal` | [Command-line errors](#claude-code-cant-read-the-keyboard-here) |241| `Claude Code can't read the keyboard here: stdin is not a terminal` | [Command-line errors](#claude-code-cant-read-the-keyboard-here) |

365| `Claude Code exited after an unrecoverable interface error (...)` | [Configuration warnings](#exited-after-an-unrecoverable-interface-error) |371| `Claude Code exited after an unrecoverable interface error (...)` | [Configuration warnings](#exited-after-an-unrecoverable-interface-error) |

366| `Agent descriptions are over the 15.0k-token limit` | [Configuration warnings](#agent-descriptions-are-over-the-15000-token-limit) |372| `Agent descriptions are over the 15.0k-token limit` | [Configuration warnings](#agent-descriptions-are-over-the-15000-token-limit) |

367| `hook needs quotes around a path with a space` | [Configuration warnings](#hook-needs-quotes-around-a-path-with-a-space) |373| `hook needs quotes around a path with a space` | [Configuration warnings](#hook-needs-quotes-around-a-path-with-a-space) |

374| `Instruction file not loaded` | [Configuration warnings](#instruction-file-not-loaded) |

368| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [Configuration warnings](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |375| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [Configuration warnings](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |

369| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [Configuration warnings](#skill-or-command-name-refused) |376| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [Configuration warnings](#skill-or-command-name-refused) |

370| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Configuration warnings](#workspace-has-not-been-trusted) |377| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Configuration warnings](#workspace-has-not-been-trusted) |

375| `Your organization's managed settings allow Claude Code to use: <providers>` | [Configuration warnings](#managed-settings-dont-allow-this-api-provider) |382| `Your organization's managed settings allow Claude Code to use: <providers>` | [Configuration warnings](#managed-settings-dont-allow-this-api-provider) |

376| `Your organization's managed settings allow Claude Code to use no API provider at all` | [Configuration warnings](#managed-settings-dont-allow-this-api-provider) |383| `Your organization's managed settings allow Claude Code to use no API provider at all` | [Configuration warnings](#managed-settings-dont-allow-this-api-provider) |

377| `MCP server <name> is blocked by enterprise managed policy` | [Configuration warnings](#mcp-server-is-blocked-by-enterprise-managed-policy) |384| `MCP server <name> is blocked by enterprise managed policy` | [Configuration warnings](#mcp-server-is-blocked-by-enterprise-managed-policy) |

385| `"<name>" is a reserved MCP server name and was not loaded` | [Configuration warnings](#mcp-server-name-is-reserved) |

378| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [Configuration warnings](#managed-settings-document-could-not-be-parsed) |386| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [Configuration warnings](#managed-settings-document-could-not-be-parsed) |

379| `Managed settings drop-in directory could not be read` | [Configuration warnings](#managed-settings-document-could-not-be-parsed) |387| `Managed settings drop-in directory could not be read` | [Configuration warnings](#managed-settings-document-could-not-be-parsed) |

389| `Managed settings contain invalid entries, including PreToolUse/PermissionRequest hooks that are NOT loaded; fix or remove each entry:` | [Configuration warnings](#managed-settings-hooks-not-loaded) |

381| `otelHeadersHelper failed; telemetry is not being exported. See /status: ...` | [Configuration warnings](#otelheadershelper-failed) |390| `otelHeadersHelper failed; telemetry is not being exported. See /status: ...` | [Configuration warnings](#otelheadershelper-failed) |

382| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [Configuration warnings](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |391| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [Configuration warnings](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |

383| `API Error: ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name` | [Configuration warnings](#anthropic-foundry-resource-must-be-a-foundry-resource-name) |392| `API Error: ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name` | [Configuration warnings](#anthropic-foundry-resource-must-be-a-foundry-resource-name) |

387| `... has a wildcard before the rest of the command` | [Configuration warnings](#has-a-wildcard-before-the-rest-of-the-command) |396| `... has a wildcard before the rest of the command` | [Configuration warnings](#has-a-wildcard-before-the-rest-of-the-command) |

388| `Denying Bash also turns off the PowerShell tool, so Claude has neither` | [Configuration warnings](#denying-bash-also-turns-off-the-powershell-tool) |397| `Denying Bash also turns off the PowerShell tool, so Claude has neither` | [Configuration warnings](#denying-bash-also-turns-off-the-powershell-tool) |

389| `CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced` | [Configuration warnings](#the-200k-limit-isnt-enforced) |398| `CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced` | [Configuration warnings](#the-200k-limit-isnt-enforced) |

399| `Model "<model>" isn't recognized · context assumed to be 200k tokens` | [Correct the window for a gateway or custom model ID](/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

400| `Claude Code doesn't recognize the model "<model>", so it assumes a context window of 200k tokens` | [Correct the window for a gateway or custom model ID](/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

402| `is ignored — managed settings set allowManagedReadPathsOnly` / `is ignored — managed settings set allowManagedDomainsOnly` | [Configuration warnings](#sandbox-allow-entries-are-ignored-under-a-managed-lock) |

391| `Stale sandbox mask files left by a killed session` | [Configuration warnings](#stale-sandbox-mask-files-left-by-a-killed-session) |403| `Stale sandbox mask files left by a killed session` | [Configuration warnings](#stale-sandbox-mask-files-left-by-a-killed-session) |

392| Responses seem lower quality than usual | [Response quality](#responses-seem-lower-quality-than-usual) |404| Responses seem lower quality than usual | [Response quality](#responses-seem-lower-quality-than-usual) |

393 405

1149 1161

1150Before v2.1.238, Claude Code reported the cases that now say `Signed out of Claude` as `JWT refresh failed: no OAuth token — run /login`, and stopped Remote Control with `Claude.ai login expired — run /login to restore Remote Control` as soon as one login refresh got no answer.1162Before v2.1.238, Claude Code reported the cases that now say `Signed out of Claude` as `JWT refresh failed: no OAuth token — run /login`, and stopped Remote Control with `Claude.ai login expired — run /login to restore Remote Control` as soon as one login refresh got no answer.

1151 1163

1164<h3 id="remote-control-could-not-renew-this-computers-connection">

1165 Remote Control could not renew this computer's connection

1166</h3>

1167

1168This warning appears in the terminal running [`claude remote-control`](/docs/en/remote-control#start-a-remote-control-session) when the server can't use your claude.ai login to renew its connection's credential before it expires. The warning's last sentence says how long the current credential still works, or that it has already expired:

1169

1170```text theme={null}

1171Remote Control could not renew this computer's connection: claude.ai did not accept the sign-in it uses. Run `claude /login` to sign in again. The connection keeps working for about 26 hours; if it still cannot sign in then, it stops.

1172```

1173

1174**What to do:**

1175

1176* If the warning tells you to run `claude /login`, open another terminal on the machine running the server, run `claude /login` there, and sign in with your claude.ai account

1177* If the server still can't sign in once the connection's credential has expired, it prints an error containing `Poll: Authentication failed (401)` and stops. Sign in again as the warning's second sentence says, then run `claude remote-control` again in the terminal where the server stopped.

1178

1152<h3 id="remote-control-stopped-because-the-signed-in-account-changed">1179<h3 id="remote-control-stopped-because-the-signed-in-account-changed">

1153 Remote Control stopped because the signed-in account changed1180 Remote Control stopped because the signed-in account changed

1154</h3>1181</h3>

2149* Disable MCP servers you are not using with `/mcp disable <name>` to remove their tool definitions from context2176* Disable MCP servers you are not using with `/mcp disable <name>` to remove their tool definitions from context

2150* Trim large `CLAUDE.md` memory files, or move instructions into [path-scoped rules](/docs/en/memory#path-specific-rules) that load only when relevant2177* Trim large `CLAUDE.md` memory files, or move instructions into [path-scoped rules](/docs/en/memory#path-specific-rules) that load only when relevant

2151* Auto-compact is on by default and normally prevents this error. If you turned it off in `/config` or with [`DISABLE_AUTO_COMPACT`](/docs/en/env-vars), turn it back on. If you keep it off, run `/compact` yourself before the window fills.2178* Auto-compact is on by default and normally prevents this error. If you turned it off in `/config` or with [`DISABLE_AUTO_COMPACT`](/docs/en/env-vars), turn it back on. If you keep it off, run `/compact` yourself before the window fills.

2179* If the error appears near 200K tokens on a model that accepts more, one cause is a model ID that Claude Code doesn't recognize. Claude Code assumes a 200K window for such an ID, so to keep working past that point, [give it the model's real context window](/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id).

2152 2180

2153See [Explore the context window](/docs/en/context-window) for an interactive view of how context fills up.2181See [Explore the context window](/docs/en/context-window) for an interactive view of how context fills up.

2154 2182

2204```text theme={null}2232```text theme={null}

2205Image was too large. Double press esc to go back and try again with a smaller image.2233Image was too large. Double press esc to go back and try again with a smaller image.

2206API Error: 400 ... image dimensions exceed max allowed size2234API Error: 400 ... image dimensions exceed max allowed size

2235API Error: an image in the conversation could not be processed and was removed.

2207```2236```

2208 2237

2209Claude Code replaces the unprocessable image with a text placeholder and retries, so subsequent messages succeed. On versions before 2.1.142, a pasted image could remain in the conversation and repeat the same error on every subsequent message. To recover on those versions, press Esc twice and step back past the turn where the image was added.2238The `could not be processed and was removed` line means the API refused an image in the conversation, such as one over the size or dimension limits.

2239

2240If one of these errors keeps coming back, update Claude Code. On older versions, an image error could repeat for reasons such as these:

2241

2242* Before v2.1.299, in a long conversation with many images, Claude Code could remove the images you attached last instead of the one over the limit. The `was removed` line then repeated on every turn, and Claude didn't see your new images.

2243* Before v2.1.299, in VS Code, the Desktop app, and the Agent SDK, images you attached while Claude was working didn't get the resizing that other attached images get. They reached the API at their original size, which led to repeated image errors in long conversations.

2244* Before v2.1.166, a pasted image could remain in the conversation, and the same error then repeated on every subsequent message

2210 2245

2211**What to do:**2246**What to do:**

2212 2247

2638* Raise [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/en/env-vars) above the thinking budget2673* Raise [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/en/env-vars) above the thinking budget

2639* See [Extended thinking](/docs/en/model-config#extended-thinking) for how the budget interacts with output length2674* See [Extended thinking](/docs/en/model-config#extended-thinking) for how the budget interacts with output length

2640 2675

2676### Response exceeded the output token maximum

2677

2678Claude's reply reached the largest number of output tokens the request allowed and was cut off there:

2679

2680```text theme={null}

2681API Error: Claude's response exceeded the ... output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.

2682API Error: Claude's response exceeded the 64000 output token maximum for a request sent without streaming. The CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable cannot raise this limit.

2683```

2684

2685The form that names `a request sent without streaming` means a streaming request failed and Claude Code re-sent it without streaming, which limits the reply to 64,000 output tokens. Before v2.1.299, a reply cut off on such a re-sent request ended the turn without this message, as if the reply were complete.

2686

2687**What to do:**

2688

2689* If Claude wrote some text before the reply was cut off, reply `continue` in an interactive session to ask for the rest. That text stays in the conversation.

2690* If the message says to set `CLAUDE_CODE_MAX_OUTPUT_TOKENS`, see [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/en/env-vars) for how the value is capped and [Set environment variables](/docs/en/env-vars#set-environment-variables) for where to set it

2691* To keep each reply under the limit, ask Claude for the output in smaller pieces, such as one file or one section per reply

2692

2641### Tool use or thinking block mismatch2693### Tool use or thinking block mismatch

2642 2694

2643The conversation history reached the API in an inconsistent state.2695The conversation history reached the API in an inconsistent state.

2766The model's safety measures flagged content in the conversation as a cybersecurity topic. The message names the model that flagged the request:2818The model's safety measures flagged content in the conversation as a cybersecurity topic. The message names the model that flagged the request:

2767 2819

2768```text theme={null}2820```text theme={null}

2769API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude2821API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude

2770```2822```

2771 2823

2772If the message includes the line `` Details: `[reasoning_extraction]` ``, see [Safeguards flagged a request for Claude's reasoning](#safeguards-flagged-a-request-for-claudes-reasoning).2824If the message includes the line `` Details: `[reasoning_extraction]` ``, see [Safeguards flagged a request for Claude's reasoning](#safeguards-flagged-a-request-for-claudes-reasoning).

2775 2827

2776On [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), and [Microsoft Foundry](/docs/en/microsoft-foundry), a cybersecurity flag produces the [Usage Policy refusal](#usage-policy-refusal) message instead.2828On [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), and [Microsoft Foundry](/docs/en/microsoft-foundry), a cybersecurity flag produces the [Usage Policy refusal](#usage-policy-refusal) message instead.

2777 2829

2778The safeguard itself is server-side and predates v2.1.203; client releases since then have changed only the message's wording.

2779From v2.1.203 through v2.1.218, the message read `<model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:` followed by the same help-center link, and interactive sessions appended `If you were not engaging in a cybersecurity topic, please send feedback via /feedback.`

2780Before v2.1.203, it read `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` followed by an exemption form link.

~~2781~~

2782**What to do:**2830**What to do:**

2783 2831

2784* If your work requires this content, apply for access through the [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)2832* If your work requires this content, apply for access through the [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)

2785* If your request wasn't about a cybersecurity topic, run `/feedback` to report the false positive2833* If your request wasn't about a cybersecurity topic, run `/feedback` to report the false positive

2786* To keep working in the same session, press Esc twice or run `/rewind` to step back to a checkpoint before the turn that triggered the flag, then take a different approach. See [Checkpointing](/docs/en/checkpointing).2834* To keep working in the same session, press Esc twice or run `/rewind` to step back to a checkpoint before the turn that triggered the flag, then take a different approach. See [Checkpointing](/docs/en/checkpointing).

2787 2835

2836If the message you see is worded like one of these instead, it's the same flag on an earlier Claude Code version:

2837

2838* From v2.1.219 through v2.1.296, the message could also include `Apply to the Cyber Verification Program to reduce these interruptions.` before its closing sentence

2839* From v2.1.203 through v2.1.218, the message read `<model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:` followed by the same help-center link. In interactive sessions, it continued with `If you were not engaging in a cybersecurity topic, please send feedback via /feedback.`

2840* Before v2.1.203, it read `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` followed by an exemption form link

2841

2788<h3 id="safeguards-flagged-a-request-for-claudes-reasoning">2842<h3 id="safeguards-flagged-a-request-for-claudes-reasoning">

2789 Safeguards flagged a request for Claude's reasoning2843 Safeguards flagged a request for Claude's reasoning

2790</h3>2844</h3>

2838* Drop `-p` or `--print`. `--bg` takes the prompt as its positional argument, so `claude --bg "<task>"` is the complete command. See [Dispatch new agents from your shell](/docs/en/agent-view#from-your-shell).2892* Drop `-p` or `--print`. `--bg` takes the prompt as its positional argument, so `claude --bg "<task>"` is the complete command. See [Dispatch new agents from your shell](/docs/en/agent-view#from-your-shell).

2839* To run the prompt non-interactively and print the result instead of creating a background session, drop `--bg` and run `claude -p "<task>"`2893* To run the prompt non-interactively and print the result instead of creating a background session, drop `--bg` and run `claude -p "<task>"`

2840 2894

2895<h3 id="couldnt-tell-whether-bg-is-a-flag-or-text">

2896 Couldn't tell whether `--bg` is a flag or text

2897</h3>

2898

2899You ran `claude` with `--bg` or `--background` at a position where Claude Code couldn't tell whether you meant it as the background flag or as text. The command started nothing, printed this line, and exited with code 1:

2900

2901```text theme={null}

2902Couldn't tell whether --bg is a flag or text here, so nothing was started. To start a background session put it first: claude --bg <prompt>

2903```

2904

2905If you typed `--background`, the line names `--background` instead.

2906

2907**What to do:**

2908

2909* To start a [background session](/docs/en/agent-view#from-your-shell), run the command again in your shell with the flag first: `claude --bg --name nightly-audit "<task>"`

2910

2841<h3 id="conflict-between-a-system-prompt-flag-and-its-file-form">2911<h3 id="conflict-between-a-system-prompt-flag-and-its-file-form">

2842 Conflict between a system prompt flag and its file form2912 Conflict between a system prompt flag and its file form

2843</h3>2913</h3>

3116 3186

3117Before v2.1.248, `claude remote-control` didn't accept its own flags when a global flag came first, and the command failed with an `unknown option` error.3187Before v2.1.248, `claude remote-control` didn't accept its own flags when a global flag came first, and the command failed with an `unknown option` error.

3118 3188

3189<h3 id="sandbox-is-not-supported-by-claude-remote-control">

3190 `--sandbox` or `--no-sandbox` is not supported by claude remote-control

3191</h3>

3192

3193This error means the command that starts your [Remote Control](/docs/en/remote-control) server passes `--sandbox` or `--no-sandbox` after `remote-control`, and `claude remote-control` accepts neither flag. The server exits with code 1 instead of starting:

3194

3195```text theme={null}

3196Error: --sandbox is not supported by claude remote-control. The flag had no effect and was removed. To sandbox sessions, set sandbox.enabled to true in settings.

3197Error: --no-sandbox is not supported by claude remote-control. The flag had no effect and was removed. Remove it from the command.

3198```

3199

3200**What to do:**

3201

3202* Remove the flag from the command, including in a script or service definition that starts the server for you, then run it again

3203* To sandbox the sessions the server starts, turn on [sandboxing](/docs/en/sandboxing) by setting [`sandbox.enabled`](/docs/en/settings-reference#sandbox-enabled) to `true` in a [settings file](/docs/en/settings#where-settings-live)

3204

3205Both flags were removed from `claude remote-control` in v2.1.300, so a command written for an earlier version can still carry one.

3206

3119### claude import is not yet available in this build3207### claude import is not yet available in this build

3120 3208

3121You ran [`claude import`](/docs/en/cli-reference#cli-commands), and Claude Code found the import flow turned off, so the command exits with code 1 instead of starting the import. Before v2.1.222, a build with the import flow off treated `import` as a prompt and started an interactive session instead of printing this message.3209You ran [`claude import`](/docs/en/cli-reference#cli-commands), and Claude Code found the import flow turned off, so the command exits with code 1 instead of starting the import. Before v2.1.222, a build with the import flow off treated `import` as a prompt and started an interactive session instead of printing this message.

3348* A remote whose server-side HEAD points at a branch nobody pushed3436* A remote whose server-side HEAD points at a branch nobody pushed

3349* A repository with no `origin` remote, or one you never fetched3437* A repository with no `origin` remote, or one you never fetched

3350 3438

3351Claude Code shows the same error for any skill that [injects dynamic context](/docs/en/skills#when-an-injected-command-fails), and a failed injected command aborts that skill's invocation. Two sibling strings fire before the command runs at all:3439Claude Code shows the same error for any skill that [injects dynamic context](/docs/en/skills#when-an-injected-command-fails), and a failed injected command aborts that skill's invocation.

3440

3441Sibling strings fire before the command runs at all:

3352 3442

3353* `Shell command permission check failed for pattern "..."`: the command's permission check didn't allow it. [Permission checks on injected commands](/docs/en/skills#permission-checks-on-injected-commands) covers which results abort in each permission mode and how to pre-approve a command with `allowed-tools`3443* `Shell command permission check failed for pattern "..."`: the command's permission check didn't allow it. [Permission checks on injected commands](/docs/en/skills#permission-checks-on-injected-commands) covers which results abort in each permission mode and how to pre-approve a command with `allowed-tools`

3354* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: the skill's frontmatter demands bash on a machine without it. Install Git for Windows or change the frontmatter to `shell: powershell`. See [How injected commands run](/docs/en/skills#how-injected-commands-run)3444* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: the skill's frontmatter demands bash on a machine without it. Install Git for Windows or change the frontmatter to `shell: powershell`. See [How injected commands run](/docs/en/skills#how-injected-commands-run)

3445* `No shell command in <name> was run`: one of the file's `!` commands contains a raw control character other than tab or newline, so none of them runs. See [how to find and remove the character](#no-shell-command-was-run)

3355 3446

3356**What to do:**3447**What to do:**

3357 3448

3359* If you'd rather not name the branch, run `git fetch origin` and then `git remote set-head origin --auto`, which asks the remote which branch is its default. It fails with `error: Cannot determine remote HEAD` when the remote advertises no default branch, because it is empty or its HEAD points at a branch nobody pushed; name the branch explicitly instead. It fails with `error: Not a valid ref` when your clone doesn't fetch that branch; widen the refspec as above first.3450* If you'd rather not name the branch, run `git fetch origin` and then `git remote set-head origin --auto`, which asks the remote which branch is its default. It fails with `error: Cannot determine remote HEAD` when the remote advertises no default branch, because it is empty or its HEAD points at a branch nobody pushed; name the branch explicitly instead. It fails with `error: Not a valid ref` when your clone doesn't fetch that branch; widen the refspec as above first.

3360* If the repository has no remote, add one with `git remote add origin <url>` and fetch before creating the ref. If the remote is empty, push your branch first with `git push -u origin HEAD` and name that branch in the set-head command; `origin/HEAD` then points at the branch you just pushed, so `/security-review` sees an empty diff until the branch diverges from it.3451* If the repository has no remote, add one with `git remote add origin <url>` and fetch before creating the ref. If the remote is empty, push your branch first with `git push -u origin HEAD` and name that branch in the set-head command; `origin/HEAD` then points at the branch you just pushed, so `/security-review` sees an empty diff until the branch diverges from it.

3361 3452

3453<h3 id="no-shell-command-was-run">

3454 No shell command in a skill or command was run

3455</h3>

3456

3457One of the `` !`<command>` `` [dynamic context commands](/docs/en/skills#inject-dynamic-context) in a skill or custom command file contains a raw control character other than tab or newline. Claude Code refuses the whole invocation before any of the file's commands runs.

3458

3459The message names the shell tool that would have run the commands, Bash or PowerShell, and ends with the refused command. Each such character is replaced by `�` so you can see where it is:

3460

3461```text theme={null}

3462No shell command in /my-skill was run, because the Bash tool does not accept one of them: command contains control characters that would be hidden in the approval dialog. Unprintable characters are shown as � below: remove them from the skill or command file, or from the arguments or options substituted into it.

3463build.sh --target�dist

3464```

3465

3466**What to do:**

3467

3468* Find each `�` in the command quoted at the end of the message. Remove the character it stands for from the skill or command file, or from the arguments or options substituted into the file.

3469

3362<h3 id="input-must-be-provided-when-using-print">3470<h3 id="input-must-be-provided-when-using-print">

3363 Input must be provided when using `--print`3471 Input must be provided when using `--print`

3364</h3>3472</h3>

5215 5323

5216* In the `command` of the hook that runs the script the notification names, wrap the path in double quotes. In a JSON file, write it as `"command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/check.py\""`.5324* In the `command` of the hook that runs the script the notification names, wrap the path in double quotes. In a JSON file, write it as `"command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/check.py\""`.

5217 5325

5326<h3 id="instruction-file-not-loaded">

5327 Instruction file not loaded

5328</h3>

5329

5330This notice in the conversation view of an interactive session means a [memory file](/docs/en/memory#how-claude-md-files-load) that exists wasn't loaded. A read restriction is in force.

5331

5332```text theme={null}

5333Instruction file not loaded (a Read deny rule covers it):

5334path: .claude/rules/shared.md

5335```

5336

5337The parenthetical names the reason, for example:

5338

5339* **`a Read deny rule covers it`**: a `Read` [deny rule](/docs/en/permissions#read-and-edit) matches the file's path as written or where a link on it leads

5340* **`it's read from outside your working directories, where reads are blocked`**: the file resolves outside the [working directories](/docs/en/settings-reference#permissions-blockreadsoutsideworkingdirectories) while [`permissions.blockReadsOutsideWorkingDirectories`](/docs/en/settings-reference#permissions-blockreadsoutsideworkingdirectories) is on

5341* **`where it leads couldn't be worked out`**: for example, the file is a link that leads back to itself, directly or through other links

5342

5343When a subdirectory's own memory file can't be loaded as Claude works with files there, the same lines appear in the conversation during the turn. When more files are withheld than the lines name, a final line counts the rest, such as `and 3 more instruction files not loaded`.

5344

5345**What to do:**

5346

5347* Nothing, if the restriction is intended: the session runs without that file's instructions.

5348* To load a file withheld because `a Read deny rule covers it`, [remove or narrow that rule](/docs/en/permissions#manage-permissions). Then start a new session.

5349* To load a file withheld because `it's read from outside your working directories, where reads are blocked`, move it or its link target inside the working directories. Then start a new session.

5350* To load a file withheld because `where it leads couldn't be worked out`, check whether the file is a link that leads back to itself. If it is, point the link at a file that exists or put a regular file in its place. Then start a new session.

5351

5352Before v2.1.292, the notice named the file at the end of the same line after the reason.

5353

5218<h3 id="a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved">5354<h3 id="a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved">

5219 A skill, command, or workflow wasn't loaded because its name is reserved5355 A skill, command, or workflow wasn't loaded because its name is reserved

5220</h3>5356</h3>

5395 5531

5396Before v2.1.257, **Reconnect** and re-enable in `/mcp` could connect a server that a mid-session policy update blocked.5532Before v2.1.257, **Reconnect** and re-enable in `/mcp` could connect a server that a mid-session policy update blocked.

5397 5533

5534<h3 id="mcp-server-name-is-reserved">

5535 MCP server name is reserved

5536</h3>

5537

5538This message names one of your MCP servers, whose name is among those Claude Code reserves, such as the names of its built-in servers:

5539

5540```text theme={null}

5541"workspace" is a reserved MCP server name and was not loaded

5542```

5543

5544**What to do:**

5545

5546* Rename the server where you define it, for example from `workspace` to `my-workspace`

5547* For other reserved names to avoid, see [MCP configuration warnings](/docs/en/mcp#configuration-warnings)

5548

5398<h3 id="managed-settings-document-could-not-be-parsed">5549<h3 id="managed-settings-document-could-not-be-parsed">

5399 Managed settings document could not be parsed5550 Managed settings document could not be parsed

5400</h3>5551</h3>

5449 5600

5450Before v2.1.285, only sessions signed in with claude.ai or Claude Console credentials exited with this message, and a read that the operating system denied produced it too.5601Before v2.1.285, only sessions signed in with claude.ai or Claude Console credentials exited with this message, and a read that the operating system denied produced it too.

5451 5602

5603<h3 id="managed-settings-hooks-not-loaded">

5604 Managed settings contain invalid entries, including PreToolUse/PermissionRequest hooks that are NOT loaded

5605</h3>

5606

5607This stderr block from a `-p` run means that a [managed settings](/docs/en/managed-settings) source holds a hook entry Claude Code can't load. That hook doesn't run, and when a line lists the source's `hooks` field as ignored, none of that source's hooks run.

5608

5609Each line names the source, the field when there is one, and the problem, such as an unknown hook `type` or a hook declared outside the `hooks` key:

5610

5611```text theme={null}

5612Managed settings contain invalid entries, including PreToolUse/PermissionRequest hooks that are NOT loaded; fix or remove each entry:

5613 <source> (<field>): <message>

5614```

5615

5616**What to do:**

5617

5618* If you administer the source, fix or remove each entry the block lists. [Hook configuration](/docs/en/hooks#configuration) shows the shape Claude Code expects under `hooks`.

5619* If a line's source is `parent managed settings`, the application that launched Claude Code passed that entry in as [parent settings](/docs/en/managed-settings#parent-settings-from-embedding-hosts), so report it to that application's developer

5620* Otherwise, send the block to your administrator

5621

5622Before v2.1.300, a `-p` run listed this case under the `Managed settings failed to load; policies from the failed source are NOT in effect:` header.

5623

5452<h3 id="otelheadershelper-failed">5624<h3 id="otelheadershelper-failed">

5453 otelHeadersHelper failed5625 otelHeadersHelper failed

5454</h3>5626</h3>

5659 5831

5660Before v2.1.233, Claude Code wrote no line when it sent a request for a model ID it didn't recognize.5832Before v2.1.233, Claude Code wrote no line when it sent a request for a model ID it didn't recognize.

5661 5833

5834<h3 id="sandbox-allow-entries-are-ignored-under-a-managed-lock">

5835 Sandbox allow entries are ignored under a managed lock

5836</h3>

5837

5838This warning in `/status` and `claude doctor` means managed settings set [`allowManagedReadPathsOnly`](/docs/en/settings-reference#sandbox-filesystem-allowmanagedreadpathsonly) or [`allowManagedDomainsOnly`](/docs/en/settings-reference#sandbox-network-allowmanageddomainsonly), so the [`allowRead`](/docs/en/settings-reference#sandbox-filesystem-allowread) or [`allowedDomains`](/docs/en/settings-reference#sandbox-network-alloweddomains) entries in the file it names don't apply:

5839

5840```text wrap theme={null}

5841sandbox.filesystem.allowRead is ignored — managed settings set allowManagedReadPathsOnly, so only allowRead paths from managed settings are honored. The 3 entries in /home/you/.claude/settings.json will NOT apply (see https://code.claude.com/docs/en/settings#sandbox-settings).

5842```

5843

5844For the network lock, the warning names `sandbox.network.allowedDomains` and `allowManagedDomainsOnly`, and says `only allowed domains (and WebFetch domain rules) from managed settings are honored`.

5845

5846**What to do:**

5847

5848* You don't have to act on the warning

5849* If you need those paths or domains and your organization's managed settings set the lock, ask your administrator to add them to those settings. The warning stays until you also remove the entries from the named file.

5850* To clear the warning, remove the entries from the named file. For a file you share, such as a project's `.claude/settings.json`, you can leave the entries in for teammates without the lock and leave the warning showing.

5851

5662### Stale sandbox mask files left by a killed session5852### Stale sandbox mask files left by a killed session

5663 5853

5664`claude doctor` prints this warning in its diagnostics, and `/status` lists the same line. It appears on Linux and WSL2 when [sandboxing](/docs/en/sandboxing) is enabled with filesystem isolation on.5854`claude doctor` prints this warning in its diagnostics, and `/status` lists the same line. It appears on Linux and WSL2 when [sandboxing](/docs/en/sandboxing) is enabled with filesystem isolation on.

github-enterprise-server.md +1 −1

Details

53 </Step>53 </Step>

54 54

55 <Step title="Enable Code Review">55 <Step title="Enable Code Review">

56 Go to [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) and enable [Code Review](/docs/en/code-review#set-up-code-review) for your GHES repositories using the same configuration as github.com.56 Go to [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) and enable [Code Review](/docs/en/code-review-setup) for your GHES repositories using the same configuration as github.com.

57 </Step>57 </Step>

58</Steps>58</Steps>

59 59

interactive-mode.md +2 −0

Details

194| `T{char}` | Jump to just after previous occurrence of character on the current line |194| `T{char}` | Jump to just after previous occurrence of character on the current line |

195| `;` | Repeat last f/F/t/T motion |195| `;` | Repeat last f/F/t/T motion |

196| `,` | Repeat last f/F/t/T motion in reverse |196| `,` | Repeat last f/F/t/T motion in reverse |

197| `%` | Jump to the matching `()`, `[]`, or `{}` bracket, starting from the next bracket on the current line when the cursor isn't on a bracket. Requires Claude Code v2.1.301 or later |

197| `/` | Open reverse history search, same as `Ctrl+R`. The empty search prompt shows a hint: press `Esc` then `i` then `/` to open the command menu instead |198| `/` | Open reverse history search, same as `Ctrl+R`. The empty search prompt shows a hint: press `Esc` then `i` then `/` to open the command menu instead |

198 199

199<Note>200<Note>

215| `d0`/`c0`/`y0` | Delete, change, or yank from the cursor back to the beginning of the line. Requires Claude Code v2.1.281 or later |216| `d0`/`c0`/`y0` | Delete, change, or yank from the cursor back to the beginning of the line. Requires Claude Code v2.1.281 or later |

217| `d%`/`c%`/`y%` | Delete, change, or yank from the cursor through the bracket that `%` jumps to. Requires Claude Code v2.1.301 or later |

216| `cc` | Change line |218| `cc` | Change line |

217| `C` | Change to end of line |219| `C` | Change to end of line |

mcp.md +1 −1

Details

1482 1482

1483Before v2.1.296, the shorter limit was 2,048 characters, and before v2.1.295 it applied to every tool description, including one loaded through tool search.1483Before v2.1.296, the shorter limit was 2,048 characters, and before v2.1.295 it applied to every tool description, including one loaded through tool search.

1484 1484

1485To change the limits for every MCP server in your session, set [`CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`](/docs/en/env-vars#variables) to a number of characters. The number you set replaces both limits: `8192`, for example, raises the shorter limit and lowers the longer one. This variable requires Claude Code v2.1.280 or later.1485Descriptions and instructions from some of the MCP servers that Anthropic hosts at `api.anthropic.com` reach Claude in full. To change the limits for the other MCP servers in your session, set [`CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`](/docs/en/env-vars#variables) to a number of characters. The number you set replaces both limits: `8192`, for example, raises the shorter limit and lowers the longer one. This variable requires Claude Code v2.1.280 or later.

1486 1486

1487<h4 id="per-tool-alwaysload">1487<h4 id="per-tool-alwaysload">

1488 Mark a tool to load upfront or stay deferred1488 Mark a tool to load upfront or stay deferred

mcp-quickstart.md +2 −0

Details

352 ```powershell theme={null}352 ```powershell theme={null}

353 $env:MCP_TIMEOUT = "60000"; claude353 $env:MCP_TIMEOUT = "60000"; claude

354 ```354 ```

355

356 Before v2.1.299, some connections to HTTP servers that were up timed out at startup regardless of `MCP_TIMEOUT`. If you use one of those versions and an HTTP server that is up still times out after you raise the limit, [update Claude Code](/docs/en/setup#update-claude-code).

355 </Accordion>357 </Accordion>

356 358

357 <Accordion title="Server already exists">359 <Accordion title="Server already exists">

memory.md +1 −0

Details

580To debug:580To debug:

581 581

582* Run `/context` and check the list under **Memory files** to verify the CLAUDE.md and CLAUDE.local.md files that should load at launch. If one is missing there, Claude can't see it. Use `/memory` to open and edit the files.582* Run `/context` and check the list under **Memory files** to verify the CLAUDE.md and CLAUDE.local.md files that should load at launch. If one is missing there, Claude can't see it. Use `/memory` to open and edit the files.

583* If an `Instruction file not loaded` notice appears, see [what it means and what to do about it](/docs/en/errors#instruction-file-not-loaded).

583* A `CLAUDE.md` in a subdirectory of your working directory doesn't appear under **Memory files**, because it loads on demand rather than at launch. When it loads, a `Loaded` line with its path appears in the terminal. To test a new one, create it from your shell rather than asking Claude to write it, then ask Claude to read a file in that subdirectory.584* A `CLAUDE.md` in a subdirectory of your working directory doesn't appear under **Memory files**, because it loads on demand rather than at launch. When it loads, a `Loaded` line with its path appears in the terminal. To test a new one, create it from your shell rather than asking Claude to write it, then ask Claude to read a file in that subdirectory.

584* Check that the relevant CLAUDE.md is in a location that gets loaded for your session (see [Choose where to put CLAUDE.md files](#choose-where-to-put-claude-md-files)).585* Check that the relevant CLAUDE.md is in a location that gets loaded for your session (see [Choose where to put CLAUDE.md files](#choose-where-to-put-claude-md-files)).

585* Make instructions more specific. "Use 2-space indentation" works better than "format code nicely."586* Make instructions more specific. "Use 2-space indentation" works better than "format code nicely."

model-config.md +20 −0

Details

809 809

810### Correct the window for a gateway or custom model ID810### Correct the window for a gateway or custom model ID

811 811

812Either of these startup warnings means Claude Code doesn't recognize your session's model ID, so it can't tell the model's context window and assumes 200K tokens:

813

814```text theme={null}

815⚠ Model "my-gateway-opus" isn't recognized · context assumed to be 200k tokens · ...

816Claude Code doesn't recognize the model "my-gateway-opus", so it assumes a context window of 200k tokens. Update Claude Code, or see https://code.claude.com/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id to set the window.

817```

818

819Claude Code [auto-compacts](#default-auto-compact-thresholds) the conversation at the assumed 200K, so if the model's real context window is 200K, there is nothing to correct. Otherwise, give Claude Code the real window in whichever of these ways fits your ID:

820

821* **A model newer than your Claude Code version**: run `claude update` in your shell. If Claude Code recognizes the ID after the update, you don't need to configure anything else.

822* **Your gateway's or provider's name for a model Claude Code knows**: add a [`modelOverrides`](#override-model-ids-per-version) entry that maps the Anthropic model ID to your ID, such as `"claude-opus-4-8": "my-gateway-opus"`. You can instead list your ID in a [`modelPicker`](/docs/en/settings-reference#fields-for-modelpicker) row with `behavesAs` set to that model. Either way, Claude Code then treats the ID as that model.

823* **A model with a 1M window**: append `[1m]` to the ID where you set the model, such as `claude --model 'my-gateway-opus[1m]'` in your shell. If you [turned off 1M context](#turn-off-1m-context), you get the same window with or without the suffix.

824* **Any other window**: set [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/en/env-vars) to the window size in tokens in the environment that starts Claude Code, such as `CLAUDE_CODE_MAX_CONTEXT_TOKENS=400000`. For an unrecognized ID that doesn't start with `claude-` and has no `[1m]` suffix, the variable takes effect on its own. For any other ID, check [which IDs it applies to](#which-ids-claude_code_max_context_tokens-applies-to) first.

825

826Once Claude Code recognizes the ID or uses the window you gave it, the warning no longer appears when you start a session on that ID.

827

828<h4 id="which-ids-claude_code_max_context_tokens-applies-to">

829 Which IDs `CLAUDE_CODE_MAX_CONTEXT_TOKENS` applies to

830</h4>

831

812On an [LLM gateway](/docs/en/llm-gateway) or other custom deployment, Claude Code can assume a context window for the model ID that differs from the model's real window, whether or not it resolves the ID to a Claude model. Set [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/en/env-vars) to the window Claude Code should assume instead.832On an [LLM gateway](/docs/en/llm-gateway) or other custom deployment, Claude Code can assume a context window for the model ID that differs from the model's real window, whether or not it resolves the ID to a Claude model. Set [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/en/env-vars) to the window Claude Code should assume instead.

813 833

814How the variable applies depends on the ID. Claude Code treats an ID as a provider or custom spelling when it doesn't start with `claude-`, in any casing, or when it carries a suffix that Claude Code strips when reading the ID, such as the `@YYYYMMDD` date used on Google Cloud's Agent Platform. Before v2.1.259, Claude Code didn't count a stripped suffix, so an unrecognized `claude-` ID with a date suffix was treated as a bare `claude-` name.834How the variable applies depends on the ID. Claude Code treats an ID as a provider or custom spelling when it doesn't start with `claude-`, in any casing, or when it carries a suffix that Claude Code strips when reading the ID, such as the `@YYYYMMDD` date used on Google Cloud's Agent Platform. Before v2.1.259, Claude Code didn't count a stripped suffix, so an unrecognized `claude-` ID with a date suffix was treated as a bare `claude-` name.

monitoring-usage.md +5 −1

Details

6 6

7> Learn how to enable and configure OpenTelemetry for Claude Code.7> Learn how to enable and configure OpenTelemetry for Claude Code.

8 8

9Track Claude Code usage, costs, and tool activity across your organization by exporting telemetry data through OpenTelemetry (OTel). Claude Code exports metrics as time series data via the standard metrics protocol, events via the logs/events protocol, and optionally distributed traces via the [traces protocol](#traces-beta).9Track Claude Code usage, costs, and tool activity across your organization by exporting telemetry data through OpenTelemetry (OTel). Claude Code exports metrics as time series data via the standard metrics protocol, events via the logs/events protocol, and optionally [distributed traces via OpenTelemetry](#traces-beta).

11<Note>

12 For the Claude API or Managed Agents, see [OpenTelemetry for the Claude API](https://platform.claude.com/docs/en/manage-claude/opentelemetry).

13</Note>

10 14

11## Quick start15## Quick start

12 16

plugins/mods/admin.md +4 −1

Details

78* **Network policy covers `$.http.fetch`.**78* **Network policy covers `$.http.fetch`.**

79 79

80 * **Your organization's policy doesn't allow WebFetch**: Claude Code also refuses every mod's `$.http.fetch` request. See [WebFetch availability](/docs/en/tools-reference#webfetch-availability).80 * **Your organization's policy doesn't allow WebFetch**: Claude Code also refuses every mod's `$.http.fetch` request. See [WebFetch availability](/docs/en/tools-reference#webfetch-availability).

81 * **You turn off the WebFetch tool with [`CLAUDE_CODE_DISABLE_WEB_FETCH`](/docs/en/env-vars#variables) or a `WebFetch` [deny rule](/docs/en/permissions#tool-specific-permission-rules), in managed settings or any other settings file**: mods can still make `$.http.fetch` requests.

83 To stop them for every mod your users install, [keep user-installed mods from loading](#stop-user-installed-mods-from-loading), or hook `http.fetch` in a [policy mod](#enforce-a-policy-with-a-mod-of-your-own) and refuse requests from users' mods. Give that hook a [`.catch` handler](/docs/en/plugins/mods/events#handle-a-hook-that-fails) that refuses too, because Claude Code skips a hook that fails and the request then goes ahead. If you only [restrict which plugins users can install](/docs/en/plugins/org#restrict-what-users-can-install), fewer mods load, but those you allow still make these requests.

81 * **You set [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/en/env-vars)**: a mod that you or your users install can still make these requests. The variable stops only the [mods built into Claude Code](/docs/en/plugins/mods/overview#mods-built-into-claude-code), plus any `$.http.fetch` request that carries the session's Anthropic credentials. Before v2.1.288, the variable stopped every mod's `$.http.fetch` request.84 * **You set [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/en/env-vars)**: a mod that you or your users install can still make these requests. The variable stops only the [mods built into Claude Code](/docs/en/plugins/mods/overview#mods-built-into-claude-code), plus any `$.http.fetch` request that carries the session's Anthropic credentials. Before v2.1.288, the variable stopped every mod's `$.http.fetch` request.

82 85

~~83 Neither covers a program the mod starts with `$.process.run`, which reaches the network with the user's own access.~~86 None of these covers a program the mod starts with `$.process.run`, which reaches the network with the user's own access.

84* **Plugin controls cover mods.** A mod is a plugin, so the [settings that restrict what users can install](/docs/en/plugins/org#restrict-what-users-can-install), such as `strictKnownMarketplaces`, decide whether it can be installed at all.87* **Plugin controls cover mods.** A mod is a plugin, so the [settings that restrict what users can install](/docs/en/plugins/org#restrict-what-users-can-install), such as `strictKnownMarketplaces`, decide whether it can be installed at all.

85* **Mods can't change the permission prompt.** A mod can restyle much of Claude Code's interface, but not the permission prompt, so it can't change what a prompt shows. A mod can still approve or deny a tool call before the prompt appears, as [Know what happens by default](#know-what-happens-by-default) describes.88* **Mods can't change the permission prompt.** A mod can restyle much of Claude Code's interface, but not the permission prompt, so it can't change what a prompt shows. A mod can still approve or deny a tool call before the prompt appears, as [Know what happens by default](#know-what-happens-by-default) describes.

86* **Trust prompts come first.** In an interactive session in a directory the user hasn't trusted yet, no mod loads until they answer the trust prompt.89* **Trust prompts come first.** In an interactive session in a directory the user hasn't trusted yet, no mod loads until they answer the trust prompt.

plugins/mods/api.md +2 −0

Details

212| `$.ui.toast(text)` | A toast notification with the mod's name that disappears after a few seconds. It's a box at the top right in [fullscreen rendering](/docs/en/fullscreen), and one line at the right under the prompt in the classic renderer. |212| `$.ui.toast(text)` | A toast notification with the mod's name that disappears after a few seconds. It's a box at the top right in [fullscreen rendering](/docs/en/fullscreen), and one line at the right under the prompt in the classic renderer. |

213| `$.ui.log(text)` | A dim line in the transcript that Claude doesn't read. It starts with `●` and the mod's name, as in `● my-mod: build finished`. |213| `$.ui.log(text)` | A dim line in the transcript that Claude doesn't read. It starts with `●` and the mod's name, as in `● my-mod: build finished`. |

214 214

215In the [VS Code extension](/docs/en/plugins/mods/interface#draw-in-the-vs-code-extension), status lines and toasts show above the prompt box instead, and log lines in the conversation.

216

215### Start a turn from a background job217### Start a turn from a background job

216 218

217When a background job finds something that needs Claude's attention, it can start a turn by submitting a prompt with `$.prompt.submit({ text })`. Claude reads the text after a sentence that names your mod as the sender. To send it as the user's own words, without that sentence, add `asUser: true`. The call waits until the session is idle and then starts a new turn. It resolves when that turn starts, so don't `await` it in a handler that runs while Claude is working.219When a background job finds something that needs Claude's attention, it can start a turn by submitting a prompt with `$.prompt.submit({ text })`. Claude reads the text after a sentence that names your mod as the sender. To send it as the user's own words, without that sentence, add `asUser: true`. The call waits until the session is idle and then starts a new turn. It resolves when that turn starts, so don't `await` it in a handler that runs while Claude is working.

plugins/mods/gallery.md +3 −3

Details

163 163

164## Show code and changes164## Show code and changes

165 165

166`Code` draws source text with Claude Code's own syntax colors, or a diff.166`Code` draws source text with Claude Code's own syntax colors, or a diff. In the VS Code extension, `Code` shows its `source` as plain text, with none of the colors, line numbers, or diff shading in these screenshots.

167 167

168### `Code`168### `Code`

169 169

235 235

236`Button`, `Input`, and `Select` are controls: the user moves between them with Tab and uses the one that has the focus. [Keyboard focus and hotkeys](/docs/en/plugins/mods/interface#know-which-keys-your-mod-can-receive) covers which keys reach them.236`Button`, `Input`, and `Select` are controls: the user moves between them with Tab and uses the one that has the focus. [Keyboard focus and hotkeys](/docs/en/plugins/mods/interface#know-which-keys-your-mod-can-receive) covers which keys reach them.

237 237

238Opening a pane with `focus: true` gives the pane keyboard focus. Typed letters reach an `Input` once it has the focus, so add `autoFocus: true` to a field that should take typing as soon as the pane opens.238Open a pane with `focus: true` to request keyboard focus for it. Typed letters reach an `Input` once it has the focus. To choose which field has the focus when the pane opens, see [Set a hotkey and the first focus](/docs/en/plugins/mods/interface#set-a-hotkey-and-the-first-focus).

239 239

240### `Button`240### `Button`

241 241

359 359

360### `Svg`360### `Svg`

361 361

362An `Svg` draws an SVG document in the Desktop app:362An `Svg` draws an SVG document in the Desktop app and the VS Code extension:

363 363

364```javascript theme={null}364```javascript theme={null}

365Svg({365Svg({

plugins/mods/interface.md +32 −15

Details

220| `Spinner`, `ToolProgress`, `TurnDuration` | Status lines for a turn: the line that animates while Claude works, a running tool's live progress line, and the line that closes a turn |220| `Spinner`, `ToolProgress`, `TurnDuration` | Status lines for a turn: the line that animates while Claude works, a running tool's live progress line, and the line that closes a turn |

221| `InfoNotice`, `SessionMode`, `PromptHint` | Status lines under the logo, the mode labels in the footer, and the hint line under the prompt |221| `InfoNotice`, `SessionMode`, `PromptHint` | Status lines under the logo, the mode labels in the footer, and the hint line under the prompt |

222 222

223`Pane`, `AskUserQuestion`, `Spinner`, `UserMessage`, `AssistantMessage`, and the tool call sites work in the terminal, the Desktop app, and the VS Code extension. The [render sites table](/docs/en/plugins/mods/reference#render-sites) lists where each of the others is raised.

224

223At a site Claude Code already draws, your hook can change a detail, replace the drawing, or leave it alone. Select a tab to see each one applied to the spinner. The examples read a `calls` variable that another hook counts, as in the [tutorial mod](/docs/en/plugins/mods/create#write-a-mod-yourself).225At a site Claude Code already draws, your hook can change a detail, replace the drawing, or leave it alone. Select a tab to see each one applied to the spinner. The examples read a `calls` variable that another hook counts, as in the [tutorial mod](/docs/en/plugins/mods/create#write-a-mod-yourself).

224 226

225<Tabs>227<Tabs>

291 293

292The permission prompt isn't a render site, so a mod can't change what it shows. The question dialog, `AskUserQuestion`, is one, so a mod can change that. A tree for the dialog has to hold the reference exactly once, with your elements above it. Otherwise, Claude Code draws its own dialog.294The permission prompt isn't a render site, so a mod can't change what it shows. The question dialog, `AskUserQuestion`, is one, so a mod can change that. A tree for the dialog has to hold the reference exactly once, with your elements above it. Otherwise, Claude Code draws its own dialog.

293 295

294The terminal and the Desktop app don't raise all the same sites. `Pane`, `AbovePrompt`, `Spinner`, and the transcript sites work in both. A few other status lines are raised in the terminal only. The [render sites table](/docs/en/plugins/mods/reference#render-sites) lists where each one is raised.

~~295~~

296### Open a pane at the right time296### Open a pane at the right time

297 297

298A pane appears only when your mod opens it. How and when you open it decides whether it takes keyboard focus, how much room it asks for, and whether it shows at all in a narrow terminal.298A pane appears only when your mod opens it. How and when you open it decides whether it takes keyboard focus, how much room it asks for, and whether it shows at all in a narrow terminal.

322 322

323The [VS Code extension](#draw-in-the-vs-code-extension) ignores `rows` and `columns` and sizes the pane itself.

324

323`focus`, `closeOnEscape`, and `holdToasts` are optional and accept only `true`. To leave one off, omit it. Passing `false` throws an error such as `ui.open: focus is true or left out`. To set one of them conditionally, add the field only when the condition holds. This call asks for keyboard focus only when `items` isn't empty:325`focus`, `closeOnEscape`, and `holdToasts` are optional and accept only `true`. To leave one off, omit it. Passing `false` throws an error such as `ui.open: focus is true or left out`. To set one of them conditionally, add the field only when the condition holds. This call asks for keyboard focus only when `items` isn't empty:

324 326

325```javascript theme={null}327```javascript theme={null}

344 346

345When the pane appears, `$.ui.open` resolves to `{ isPlaced: true }`. When the pane is waiting, `isPlaced` is `false` and `reason` is a string that says why. A waiting pane appears when the user opens it or widens the terminal. To say something is available without opening a pane, call `$.ui.toast('Your message')`, which shows a toast notification.347When the pane appears, `$.ui.open` resolves to `{ isPlaced: true }`. When the pane is waiting, `isPlaced` is `false` and `reason` is a string that says why. A waiting pane appears when the user opens it or widens the terminal. To say something is available without opening a pane, call `$.ui.toast('Your message')`, which shows a toast notification.

346 348

349### Draw in the VS Code extension

350

351In the VS Code extension, what a mod draws appears in the chat panel with extension version 2.1.299 or later, in a session that [fetches feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching). In a `ui.render` hook for the panel, `e.surface` is `vscode`. To check which sites and elements the panel draws, and which props it ignores, see the [render sites](/docs/en/plugins/mods/reference#render-sites) and [elements](/docs/en/plugins/mods/reference#elements) tables.

352

353To make a mod work in the panel as well as the terminal, account for these differences:

354

355* **Panes**: in a panel 800 pixels or wider, panes dock beside the conversation, `e.props.placement` is `'dock'`, and `e.viewport.isFullscreen` is `true`. In a narrower panel, panes draw above the prompt box, `placement` is `'inline'`, and a pane shows 12 rows before it scrolls.

356* **Toasts and status lines**: these sit in one stack directly above the prompt box, together with the panes when the panel is narrow, with one status line per mod. The stack is hidden while a permission request or a dialog shows.

357* **Labels**: the panel frames what a mod draws or rewrites and labels it with the plugin's name, as in **From the token-chart plugin** or **Edited by the token-chart plugin**.

358* **Keyboard**: buttons have no hotkeys, so the user clicks a button or presses Enter on it once it has focus.

359* **Keyboard focus**: the panel grants a pane's `focus: true` request only when the panel has focus, Claude is idle with no question waiting, and the prompt box is empty.

360* **The question dialog**: at `AskUserQuestion`, the panel keeps its own question card and draws your elements above it. Props you pass to `next` don't change the card.

361* **Prompt suggestions**: `$.prompt.suggest` resolves with `isShown: false` and shows nothing, because the panel keeps the prompt box's dim suggestion text for Claude's own suggestions.

362* **Text limits**: the panel cuts a status line at 200 characters or two rows, and a toast at 500 characters.

363

347## Build a tree from elements364## Build a tree from elements

348 365

349What a `ui.render` hook returns is an element tree: a description of what to draw, made of boxes, text, and controls nested inside each other. You describe the drawing, and Claude Code renders it in the terminal or the Desktop app.366What a `ui.render` hook returns is an element tree: a description of what to draw, made of boxes, text, and controls nested inside each other. You describe the drawing, and Claude Code renders it in whichever app the user has open: the terminal, the Desktop app, or the VS Code extension.

350 367

351To get the elements, call `$.ui.resolve(e)` in your hook, as in `const { Box, Text, Button } = $.ui.resolve(e)`. Each element is a function. You pass it props, and you put the elements and strings that go inside it in `children`.368To get the elements, call `$.ui.resolve(e)` in your hook, as in `const { Box, Text, Button } = $.ui.resolve(e)`. Each element is a function. You pass it props, and you put the elements and strings that go inside it in `children`.

352 369

426| `Text` | Styled text. Takes `color`, `bold`, `dimColor`, `italic`, and `wrap`. A `color` is a theme key or a color such as `'red'`. A `wrap` is `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'`, or `'truncate-end'`. | Everywhere |443| `Text` | Styled text. Takes `color`, `bold`, `dimColor`, `italic`, and `wrap`. A `color` is a theme key or a color such as `'red'`. A `wrap` is `'wrap'`, `'truncate'`, `'truncate-start'`, `'truncate-middle'`, or `'truncate-end'`. | Everywhere |

428| `Link`, `Code`, `Markdown` | A link with `href` and an optional `label`, a code block, and text formatted the way Claude's replies are. `Markdown` takes its content in a `text` prop, not in `children`, and needs a `key` when you pass `onLinkPress`. | Everywhere |445| `Link`, `Code`, `Markdown` | A link with `href` and an optional `label`, a code block, and text formatted the way Claude's replies are. `Markdown` takes its content in a `text` prop, not in `children`, and needs a `key` when you pass `onLinkPress`. | Everywhere |

430| `Svg` | An SVG document | Desktop |447| `Svg` | An SVG document | Desktop, VS Code |

431| `Client` | A region drawn by a second file of yours, for animation and pointer input. That file gets no mods API. It reaches your hooks by posting data, which arrives as a `ui.message` event. If it fails to load, draw, or run, your hooks receive a [`ui.fault`](/docs/en/plugins/mods/reference#interface) event. | Terminal, Desktop |448| `Client` | A region drawn by a second file of yours, for animation and pointer input. That file gets no mods API. It reaches your hooks by posting data, which arrives as a `ui.message` event. If it fails to load, draw, or run, your hooks receive a [`ui.fault`](/docs/en/plugins/mods/reference#interface) event. | Terminal, Desktop |

433 450

438In a session started with `--plugin-dir`, a transcript line says so, such as `ui.render (Pane) refused: Text prop "bogusProp" is not allowed; the engine drew its own`. The [debug log](/docs/en/plugins/mods/troubleshoot#read-the-debug-log) records it as `ui.render (Pane): a hook returned a tree that does not validate` with the same reason. Nothing else appears in the session, so when a drawing doesn't show up, check that line or the log.455In a session started with `--plugin-dir`, a transcript line says so, such as `ui.render (Pane) refused: Text prop "bogusProp" is not allowed; the engine drew its own`. The [debug log](/docs/en/plugins/mods/troubleshoot#read-the-debug-log) records it as `ui.render (Pane): a hook returned a tree that does not validate` with the same reason. Nothing else appears in the session, so when a drawing doesn't show up, check that line or the log.

439 456

440<h3 id="link-in-the-desktop-app">457<h3 id="link-in-the-desktop-app">

441 `Link` in the Desktop app458 `Link` in the Desktop app and VS Code

442</h3>459</h3>

443 460

444In the Desktop app, a `Link` draws as plain text unless its `href` meets these requirements:461In the Desktop app and the VS Code extension, a `Link` draws as plain text unless its `href` meets these requirements:

445 462

446* **Scheme and host**: an `https:` URL, or an `http://localhost` URL such as `http://localhost:3000`463* **Scheme and host**: an `https:` URL, or an `http://localhost` URL such as `http://localhost:3000`

447* **No `@`**: write an `@` in the path or query as `%40`464* **No `@`**: write an `@` in the path or query as `%40`

461 478

462For a heat map, a sparkline, or a game board in the terminal, draw one `Raster` and not a `Box` for each cell. A `Raster` takes a `key`, its size in `columns` and `rows`, and `cells`, a base64 string that packs every cell. Each cell is three numbers: the character's code point, its color, and its background color. A color is a 24-bit RGB value in hexadecimal, such as `0xc62828` for a red. The value `0x01000000`, one above that range, means the terminal's default.479For a heat map, a sparkline, or a game board in the terminal, draw one `Raster` and not a `Box` for each cell. A `Raster` takes a `key`, its size in `columns` and `rows`, and `cells`, a base64 string that packs every cell. Each cell is three numbers: the character's code point, its color, and its background color. A color is a 24-bit RGB value in hexadecimal, such as `0xc62828` for a red. The value `0x01000000`, one above that range, means the terminal's default.

463 480

464The Desktop app has no `Raster`, so check `e.surface` and draw text there. This pane body draws a three by two heat map:481Apps other than the terminal have no `Raster`, so check `e.surface` and draw text there. This pane body draws a three by two heat map:

465 482

466```javascript theme={null}483```javascript theme={null}

467// The value that means "use the terminal's default color"484// The value that means "use the terminal's default color"

517 534

518Your mod never reads the keyboard itself. The user presses a key, Claude Code decides which of your controls it's for, and that control's callback runs. Apart from a [digit hotkey on the band](/docs/en/plugins/mods/reference#elements), that happens only while your pane or band has keyboard focus. The rest of the time, keys go to the prompt.535Your mod never reads the keyboard itself. The user presses a key, Claude Code decides which of your controls it's for, and that control's callback runs. Apart from a [digit hotkey on the band](/docs/en/plugins/mods/reference#elements), that happens only while your pane or band has keyboard focus. The rest of the time, keys go to the prompt.

519 536

537In the [VS Code extension](#draw-in-the-vs-code-extension), buttons have no hotkeys: the user clicks a button or presses Enter on it, and types into fields.

538

520#### How a pane gets keyboard focus539#### How a pane gets keyboard focus

521 540

522A pane gets keyboard focus when:541A pane gets keyboard focus when:

546 565

547#### Set a hotkey and the first focus566#### Set a hotkey and the first focus

548 567

549These props on a control decide how the keyboard reaches it:

~~550~~

551* **`hotkey`**: to let the user press a `Button` with one key, give it a `hotkey` of one digit or one lowercase letter, as in `hotkey: 'a'`568* **`hotkey`**: to let the user press a `Button` with one key, give it a `hotkey` of one digit or one lowercase letter, as in `hotkey: 'a'`

552* **`autoFocus`**: to choose which control has the focus when the pane opens, add `autoFocus: true` to it. The prop accepts only `true`, so omit it on the other controls.569* **`autoFocus`**: to choose which control has the focus when the pane opens, add `autoFocus: true` to it. In the [VS Code extension](#draw-in-the-vs-code-extension), `autoFocus` does nothing: the control draws as if you had left it out, and you don't need to change anything. The prop accepts only `true`, so omit it on the other controls.

553 570

554How a hotkey shows depends on the button and the app:571How a hotkey shows depends on the button and the app:

555 572

557| :- | :- | :- |574| :- | :- | :- | :- |

559| With `plain: true` | `1: One` | The label with a small key beside it |576| With `plain: true` | `1: One` | The label with a small key beside it | The label, and the hotkey does nothing |

560 577

561In the terminal, name the key in a bracketed button's label, or use `plain: true`, so the user can see what to press. The [elements reference](/docs/en/plugins/mods/reference#elements) has the other `Button` rules: `action`, digit hotkeys on the band, and two buttons on one hotkey.578In the terminal, name the key in a bracketed button's label, or use `plain: true`, so the user can see what to press. The [elements reference](/docs/en/plugins/mods/reference#elements) has the other `Button` rules: `action`, digit hotkeys on the band, and two buttons on one hotkey.

562 579

plugins/mods/overview.md +3 −3

Details

22* **Run your own code on a command**: a `/command` that runs your function at once, with no Claude turn, even while Claude is working. See [Add a command or a tool](/docs/en/plugins/mods/api#add-a-command-or-a-tool).22* **Run your own code on a command**: a `/command` that runs your function at once, with no Claude turn, even while Claude is working. See [Add a command or a tool](/docs/en/plugins/mods/api#add-a-command-or-a-tool).

23* **Share data between hooks**: a mod's hooks share the variables in its file, so what one hook records, another can show. For example, one hook can count tool calls while another shows the count beside the spinner, or one can read each request's token usage while another charts it in a pane. See [React to events](/docs/en/plugins/mods/events).23* **Share data between hooks**: a mod's hooks share the variables in its file, so what one hook records, another can show. For example, one hook can count tool calls while another shows the count beside the spinner, or one can read each request's token usage while another charts it in a pane. See [React to events](/docs/en/plugins/mods/events).

24 24

25Mods work in the Claude Code CLI and in the Code tab of the Claude Desktop app. See [Where mods run](#where-mods-run) to understand how they behave elsewhere, such as in the VS Code extension, `claude -p`, and cloud sessions. If a settings hook, a skill, or an MCP server already does what you need, [compare them](#compare-mods-settings-hooks-skills-and-mcp-servers) before you write a mod. To manage mods for an organization, see [Manage mods for your organization](/docs/en/plugins/mods/admin).25Mods work in the Claude Code CLI, the Code tab of the Claude Desktop app, and the VS Code extension. See [Where mods run](#where-mods-run) for how they behave elsewhere, such as in `claude -p` and cloud sessions. If a settings hook, a skill, or an MCP server already does what you need, [compare them](#compare-mods-settings-hooks-skills-and-mcp-servers) before you write a mod. To manage mods for an organization, see [Manage mods for your organization](/docs/en/plugins/mods/admin).

26 26

27## Get a mod27## Get a mod

28 28

188 188

189### Where mods run189### Where mods run

190 190

191A mod's hooks run in every kind of session that loads the plugin, whichever provider serves the model, including Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry. Drawing is narrower: only the terminal and the Desktop app show a mod's panes, bands, and replaced rows. This table lists each place you might run Claude Code:191A mod's hooks run in every kind of session that loads the plugin, whichever provider serves the model, including Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry. Drawing is narrower: what a mod draws appears in the terminal, the Desktop app, and the VS Code extension. This table lists each place you might run Claude Code:

192 192

194| :- | :- | :- |194| :- | :- | :- |

195| `claude` in a terminal, including an editor's integrated terminal and the JetBrains plugin | Yes | Yes |195| `claude` in a terminal, including an editor's integrated terminal and the JetBrains plugin | Yes | Yes |

196| The Code tab of the Desktop app, except in a WSL session | Yes | Yes, except elements the [elements table](/docs/en/plugins/mods/reference#elements) marks terminal-only |196| The Code tab of the Desktop app, except in a WSL session | Yes | Yes, except elements the [elements table](/docs/en/plugins/mods/reference#elements) marks terminal-only |

197| A [WSL session](/docs/en/desktop-wsl) in the Desktop app | No, because plugins aren't available in WSL sessions | No |197| A [WSL session](/docs/en/desktop-wsl) in the Desktop app | No, because plugins aren't available in WSL sessions | No |

198| The VS Code extension's chat panel | Yes | No |198| The VS Code extension's chat panel | Yes | Yes, with extension version 2.1.299 or later, in a session that [fetches feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching). The [render sites](/docs/en/plugins/mods/reference#render-sites) and [elements](/docs/en/plugins/mods/reference#elements) tables mark what the panel draws. |

199| `claude -p` and the [Agent SDK](/docs/en/agent-sdk/overview) | Yes | No |199| `claude -p` and the [Agent SDK](/docs/en/agent-sdk/overview) | Yes | No |

201| A [cloud session](/docs/en/claude-code-on-the-web) | Yes, for a plugin that [reaches the cloud session](/docs/en/cloud-environments#what-carries-over-from-your-setup) | No |201| A [cloud session](/docs/en/claude-code-on-the-web) | Yes, for a plugin that [reaches the cloud session](/docs/en/cloud-environments#what-carries-over-from-your-setup) | No |

plugins/mods/reference.md +33 −24

Details

6 6

7> Complete reference for Claude Code mods: hooks module layout, events, mods API methods, render sites, elements by surface, limits, and settings.7> Complete reference for Claude Code mods: hooks module layout, events, mods API methods, render sites, elements by surface, limits, and settings.

8 8

9Look up any event a [mod](/docs/en/plugins/mods/overview) can handle, mods API method it can call, or render site it can draw in, for the Claude Code CLI and the Desktop app as of v2.1.290. Each entry gives the name and a one-line description, and links to the guide section that explains it where there is one.9Look up any event a [mod](/docs/en/plugins/mods/overview) can handle, mods API method it can call, or render site it can draw in. Entries cover the Claude Code CLI and the Desktop app as of v2.1.290, and the VS Code extension as of v2.1.299. Each entry gives the name and a one-line description, and links to the guide section that explains it where there is one.

10 10

11<Note>11<Note>

12 The complete reference is Claude Code's [TypeScript declarations for mods](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts), which describe every event, method, and element, with examples. The copy on GitHub can be older than the Claude Code version you have installed. When the two disagree, trust [the copy Claude Code writes for your version](/docs/en/plugins/mods/create#get-the-types-for-your-build).12 The complete reference is Claude Code's [TypeScript declarations for mods](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts), which describe every event, method, and element, with examples. The copy on GitHub can be older than the Claude Code version you have installed. When the two disagree, trust [the copy Claude Code writes for your version](/docs/en/plugins/mods/create#get-the-types-for-your-build).

223 223

224## Render sites224## Render sites

225 225

226A render site is an extension point in Claude Code's interface. Each row is a value of `e.component` in a `ui.render` hook, with the fields of `e.props` and the apps that render it. `e.surface` is `terminal` or `desktop`. [Change what Claude Code already draws](/docs/en/plugins/mods/interface#change-what-claude-code-already-draws) shows what a hook can do at a site, with an example of each choice.226A render site is an extension point in Claude Code's interface. Each row is a value of `e.component` in a `ui.render` hook, with the fields of `e.props` and the apps that render it. `e.surface` names the app that's drawing, such as `terminal`, `desktop`, or `vscode`. [Change what Claude Code already draws](/docs/en/plugins/mods/interface#change-what-claude-code-already-draws) shows what a hook can do at a site, with an example of each choice.

227

228Rendering in the VS Code extension requires extension version 2.1.299 or later and a session that [fetches feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching). [Draw in the VS Code extension](/docs/en/plugins/mods/interface#draw-in-the-vs-code-extension) lists what the extension draws differently.

227 229

229| :- | :- | :- | :- |231| :- | :- | :- | :- |

243 245

244`e.viewport` holds `columns`, `rows`, and `isFullscreen`. It's absent until the app has measured its window. Its `rows` is the height of the whole window, not of your pane.246`e.viewport` holds `columns`, `rows`, and `isFullscreen`. In the terminal and the Desktop app, it's absent until the app has measured its window. There, its `rows` is the height of the whole window, not of your pane. In the VS Code extension, it's always present.

245 247

246To fit a tree to its site, read these props in the hook:248To fit a tree to its site, read these props in the hook:

247 249

248* **Width of a `Pane` or the band**: draw to `e.props.bodyColumns`250* **Width of a `Pane` or the band**: draw to `e.props.bodyColumns`

249* **Height of a `Pane` beside the transcript**: where `e.props.placement` is `'dock'`, `e.props.scroll.bodyRows` is the number of rows the pane has for your tree251* **Height of a `Pane` beside the transcript**: where `e.props.placement` is `'dock'`, `e.props.scroll.bodyRows` is the number of rows the pane has for your tree

250* **Height of a `Pane` above the prompt**: where `e.props.placement` is `'inline'`, the pane grows with your tree up to a limit, and `bodyRows` is that limit. The [`rows` field of `$.ui.open`](/docs/en/plugins/mods/interface#open-a-pane-at-the-right-time) asks for a different one.252* **Height of a `Pane` above the prompt**: where `e.props.placement` is `'inline'`, the pane grows with your tree up to a limit, and `bodyRows` is that limit. To ask for a different limit, see the [`rows` field of `$.ui.open`](/docs/en/plugins/mods/interface#open-a-pane-at-the-right-time).

251 253

252A tree taller than the pane scrolls as a whole.254A tree taller than the pane scrolls as a whole.

253 255

255 257

256Elements are the building blocks of a tree a `ui.render` hook returns, and you get them from `$.ui.resolve(e)`. [Build a tree from elements](/docs/en/plugins/mods/interface#build-a-tree-from-elements) shows the common ones with how the terminal draws them, and the [interface gallery](/docs/en/plugins/mods/gallery) has screenshots of most. A check mark means the app can draw the element.258Elements are the building blocks of a tree a `ui.render` hook returns, and you get them from `$.ui.resolve(e)`. [Build a tree from elements](/docs/en/plugins/mods/interface#build-a-tree-from-elements) shows the common ones with how the terminal draws them, and the [interface gallery](/docs/en/plugins/mods/gallery) has screenshots of most. A check mark means the app can draw the element.

257 259

259| :- | :- | :-: | :-: |261| :- | :- | :-: | :-: | :-: |

260| [`Box`](/docs/en/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex layout, `gap`, `padding`, `margin`, `width`, `height`, [`borderStyle`](#box-border-styles), `backgroundColor`, `position`, `hover` | ✓ | ✓ |262| [`Box`](/docs/en/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex layout, `gap`, `padding`, `margin`, `width`, `height`, [`borderStyle`](#box-border-styles), `backgroundColor`, `position`, `hover` | ✓ | ✓ | ✓ |

261| [`Text`](/docs/en/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ |263| [`Text`](/docs/en/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ | ✓ |

262| [`Button`](/docs/en/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ |264| [`Button`](/docs/en/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ | ✓ |

263| [`Link`](/docs/en/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. See [Limits](#limits). | ✓ | ✓ |265| [`Link`](/docs/en/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. See [Limits](#limits). | ✓ | ✓ | ✓ |

264| [`Code`](/docs/en/plugins/mods/gallery#show-code-and-changes) | `source`, `language`, `path`, `startLine`, `format`, `wrap` | ✓ | ✓ |266| [`Code`](/docs/en/plugins/mods/gallery#show-code-and-changes) | `source`, `language`, `path`, `startLine`, `format`, `wrap` | ✓ | ✓ | ✓ |

265| `Markdown` | `text`, `key`, `dimColor`, `onLinkPress`, `pressableLinks` | ✓ | ✓ |267| `Markdown` | `text`, `key`, `dimColor`, `onLinkPress`, `pressableLinks` | ✓ | ✓ | ✓ |

266| [`Input`](/docs/en/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`, `label`, `placeholder`, `value`, `submitLabel`, `onSubmit`, `onInput`, `autoFocus` | ✓ | ✓ |268| [`Input`](/docs/en/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`, `label`, `placeholder`, `value`, `submitLabel`, `onSubmit`, `onInput`, `autoFocus` | ✓ | ✓ | ✓ |

267| `Select` | `key`, `label`, `options`, `value`, `onSelect`, `autoFocus` | ✓ | ✓ |269| `Select` | `key`, `label`, `options`, `value`, `onSelect`, `autoFocus` | ✓ | ✓ | ✓ |

268| `Svg` | An SVG document, up to 131,072 characters | | ✓ |270| `Svg` | An SVG document, up to 131,072 characters | | ✓ | ✓ |

269| [`Client`](/docs/en/plugins/mods/interface#build-a-tree-from-elements) | `module`, `key` | ✓ | ✓ |271| [`Client`](/docs/en/plugins/mods/interface#build-a-tree-from-elements) | `module`, `key` | ✓ | ✓ | |

270| [`Raster`](/docs/en/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`, `columns` up to 512, `rows` up to 256, `cells`. See [Draw a grid of colored cells](/docs/en/plugins/mods/interface#draw-a-grid-of-colored-cells). | ✓ | |272| [`Raster`](/docs/en/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`, `columns` up to 512, `rows` up to 256, `cells`. See [Draw a grid of colored cells](/docs/en/plugins/mods/interface#draw-a-grid-of-colored-cells). | ✓ | | |

271| `Image` | PNG or RGBA bytes up to 2 MiB, or a file path, `columns` and `rows` up to 255, and `alt` text. | ✓ | |273| `Image` | PNG or RGBA bytes up to 2 MiB, or a file path, `columns` and `rows` up to 255, and `alt` text. | ✓ | | |

272 274

273More `Button` rules: `action` names one of Claude Code's own [keybinding actions](/docs/en/keybindings), and the user's binding for it presses the button when that binding is a chord or a modified key. A digit `hotkey` on a button in the band also fires when the user types that digit alone into an empty prompt and pauses. When two buttons in one drawing name the same `hotkey`, the later one gets it. `autoFocus` accepts only `true` on any control, so omit the prop to leave it off.275More `Button` rules: `action` names one of Claude Code's own [keybinding actions](/docs/en/keybindings), and the user's binding for it presses the button when that binding is a chord or a modified key. A digit `hotkey` on a button in the band also fires when the user types that digit alone into an empty prompt and pauses. When two buttons in one drawing name the same `hotkey`, the later one gets it. `autoFocus` accepts only `true` on any control, so omit the prop to leave it off.

274 276

277The VS Code extension ignores some element props and draws the element as if you had left them out:

278

279* **`Box`**: `position` and `hover`

280* **`Button`**: `hotkey`, `plain`, `autoFocus`, and `action`, so the user presses a button there with a click, or with Enter once it has focus

281* **`Code`**: `language`, `path`, `startLine`, `format`, and `wrap`, so code draws without colors or line numbers, and a `format: 'diff'` block shows the diff's raw text

282* **`Input` and `Select`**: `autoFocus`

283

275<h3 id="box-border-styles">284<h3 id="box-border-styles">

276 `Box` border styles285 `Box` border styles

277</h3>286</h3>

plugins/mods/troubleshoot.md +8 −5

Details

225 225

226### Hotkeys do nothing226### Hotkeys do nothing

227 227

228Your pane doesn't have keyboard focus.228Your pane doesn't have keyboard focus, or the drawing is in the VS Code extension, where buttons have no hotkeys. Do the one that matches:

229 229

230Press Ctrl+X then Tab, or click the pane. Open it with `focus: true` from a command.230* **No keyboard focus**: press Ctrl+X then Tab, or click the pane. To have the pane take focus when it opens, open it with `focus: true` from a command.

231* **In the VS Code extension**: click the button, or press Enter on it once it has focus

231 232

232### A drawing works in the terminal and not in the Desktop app233### A drawing works in the terminal and not in the Desktop app or VS Code

233 234

234The site or element isn't available there.235Either that app doesn't draw the site or element, or the session is one where the VS Code extension draws nothing for mods. The mod's other hooks still run. Check for these causes:

235 236

236Check the [render sites](/docs/en/plugins/mods/reference#render-sites) and [elements](/docs/en/plugins/mods/reference#elements) tables.237* **The site or element isn't drawn in that app**: look up your site in the [render sites](/docs/en/plugins/mods/reference#render-sites) table and your elements in the [elements](/docs/en/plugins/mods/reference#elements) table. For an element the app lacks, check `e.surface` in the hook and return a tree the app can draw.

238* **The VS Code extension is older than 2.1.299**: the chat panel draws for mods from [extension version](/docs/en/vs-code#install-the-extension) 2.1.299. Check the version in VS Code's Extensions view and update the extension there.

239* **The VS Code session doesn't fetch feature flags**: drawing in the chat panel requires it. Sessions on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, or through a [Claude apps gateway](/docs/en/claude-apps-gateway), skip it, among others that [Features that need feature-flag fetching](/docs/en/env-vars#features-that-need-feature-flag-fetching) lists. To see the drawing in such a session, run `claude` in a terminal instead, such as VS Code's integrated terminal.

237 240

238## An edit or a value is lost241## An edit or a value is lost

239 242

remote-control.md +1 −0

Details

68 | `-d`, `--debug[=<filter>]` | Turn on debug logging for the server, optionally filtered by category. Pass a filter only in the `=` form, such as `--debug=api,hooks`. Requires Claude Code v2.1.282 or later. |68 | `-d`, `--debug[=<filter>]` | Turn on debug logging for the server, optionally filtered by category. Pass a filter only in the `=` form, such as `--debug=api,hooks`. Requires Claude Code v2.1.282 or later. |

69 | `--debug-file <path>` | Write debug logs to the given file. |69 | `--debug-file <path>` | Write debug logs to the given file. |

70 | `--verbose` | Show detailed connection and session logs. |70 | `--verbose` | Show detailed connection and session logs. |

71 | `--sandbox`, `--no-sandbox` | Removed in v2.1.300. If you pass either flag, the server [exits with an error](/docs/en/errors#sandbox-is-not-supported-by-claude-remote-control) instead of starting. |

71 72

72 If you pass a global `claude` flag before `remote-control`, or a wrapper script adds one, Claude Code doesn't carry the flag over to the sessions the server creates. Claude Code lets the flag through only when dropping it is known not to change what those sessions can do, such as `--verbose` or `--model`. For any other flag, such as `--settings`, Claude Code [refuses to start](/docs/en/errors#not-carried-over-to-the-sessions-remote-control-starts) and names the flag to remove.73 If you pass a global `claude` flag before `remote-control`, or a wrapper script adds one, Claude Code doesn't carry the flag over to the sessions the server creates. Claude Code lets the flag through only when dropping it is known not to change what those sessions can do, such as `--verbose` or `--model`. For any other flag, such as `--settings`, Claude Code [refuses to start](/docs/en/errors#not-carried-over-to-the-sessions-remote-control-starts) and names the flag to remove.

73 74

skills.md +6 −2

Details

668 668

669You can also stack several skills at the start of one message. Typing `/write-tests /fix-issue 123` loads both skills and passes the trailing text `123` as `$ARGUMENTS` to each of them.669You can also stack several skills at the start of one message. Typing `/write-tests /fix-issue 123` loads both skills and passes the trailing text `123` as `$ARGUMENTS` to each of them.

670 670

671Claude Code expands the first skill plus up to five more stacked after it. Expansion stops at the first token that isn't an inline user-invocable skill, so a skill that runs as a [forked subagent](#run-skills-in-a-subagent), such as [`/code-review`](/docs/en/code-review#review-a-diff-locally), or one whose arguments may themselves start with a slash command, such as `/loop`, also ends the run there. That token and everything after it become the argument text for every expanded skill. `/code-review` runs as a forked subagent from v2.1.218; on earlier versions it ran inline and stacked.671Claude Code expands the first skill plus up to five more stacked after it. Expansion stops at the first token that isn't an inline user-invocable skill, so a skill that runs as a [forked subagent](#run-skills-in-a-subagent), such as [`/code-review`](/docs/en/code-review-local), or one whose arguments may themselves start with a slash command, such as `/loop`, also ends the run there. That token and everything after it become the argument text for every expanded skill. `/code-review` runs as a forked subagent from v2.1.218; on earlier versions it ran inline and stacked.

672 672

673To access individual arguments by position, use `$ARGUMENTS[N]` or the shorter `$N`:673To access individual arguments by position, use `$ARGUMENTS[N]` or the shorter `$N`:

674 674

772 772

773With the default `bash` shell, append `|| true` to any other command you expect to exit non-zero. A check script that exits 1 when it finds problems is one example.773With the default `bash` shell, append `|| true` to any other command you expect to exit non-zero. A check script that exits 1 when it finds problems is one example.

774 774

775#### Control characters in injected commands

776

777`No shell command in <name> was run` means one of the file's `!` commands contains a raw control character other than tab or newline, so none of them runs. See [how to find and remove the character](/docs/en/errors#no-shell-command-was-run).

778

775#### Permission checks on injected commands779#### Permission checks on injected commands

776 780

777Injected commands never prompt for permission while the skill renders. Claude Code checks each one against your [permission rules](/docs/en/permissions) first. A command a deny rule matches aborts the invocation with `Shell command permission check failed for pattern "..."`.781Injected commands never prompt for permission while the skill renders. Claude Code checks each one against your [permission rules](/docs/en/permissions) first. A command a deny rule matches aborts the invocation with `Shell command permission check failed for pattern "..."`.

801 805

802A backgrounded fork also runs with the [narrower tool set that applies to background subagents](/docs/en/sub-agents#run-subagents-in-foreground-or-background): the skill's subagent is a regular agent type, so the exemption for subagents that fork the conversation doesn't cover it. If your skill's steps depend on a tool outside that set, set `background: false` to keep the full tool set.806A backgrounded fork also runs with the [narrower tool set that applies to background subagents](/docs/en/sub-agents#run-subagents-in-foreground-or-background): the skill's subagent is a regular agent type, so the exemption for subagents that fork the conversation doesn't cover it. If your skill's steps depend on a tool outside that set, set `background: false` to keep the full tool set.

803 807

804A forked skill that runs in the background applies its edits outside your session's [checkpoints](/docs/en/checkpointing), so `/rewind` doesn't undo them; use git to revert them.808A forked skill that runs in the background applies its edits outside your session's [checkpoints](/docs/en/checkpointing#subagent-edits-not-restored). After one, `/rewind` restores only the files Claude had already edited in your conversation. The skill's edits to other files stay, so use git to revert them.

805 809

806<Warning>810<Warning>

807 `context: fork` only makes sense for skills with explicit instructions. If your skill contains guidelines like "use these API conventions" without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output.811 `context: fork` only makes sense for skills with explicit instructions. If your skill contains guidelines like "use these API conventions" without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output.

ultrareview.md +1 −1

Details

18* **Broader coverage**: a larger fleet of reviewer agents explores the change in parallel, which surfaces issues that a local review can miss18* **Broader coverage**: a larger fleet of reviewer agents explores the change in parallel, which surfaces issues that a local review can miss

19* **No local resource use**: the review runs entirely in a cloud sandbox, so your terminal stays free for other work while it runs19* **No local resource use**: the review runs entirely in a cloud sandbox, so your terminal stays free for other work while it runs

20 20

21Ultrareview requires authentication with a claude.ai account because it runs as a cloud session on Anthropic's infrastructure. If you are signed in with an API key only, run `/login` and authenticate with claude.ai first. Ultrareview is not available when using Claude Code with Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, and it is not available to organizations that have enabled Zero Data Retention or have the [HIPAA configuration](/docs/en/hipaa-setup) applied. When ultrareview is not available, `/code-review ultra` runs a local review in your session instead.21Ultrareview requires authentication with a claude.ai account because it runs as a cloud session on Anthropic's infrastructure. If you are signed in with an API key only, run `/login` and authenticate with claude.ai first. Ultrareview is not available when using Claude Code with Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, and it is not available to organizations that have enabled Zero Data Retention or have the [HIPAA configuration](/docs/en/hipaa-setup) applied. In these cases, `/code-review ultra` runs a local review in your session instead. Organizations that use [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek) (CMEK) can't run ultrareview. To review your changes locally, run `/code-review`.

22 22

23## Run ultrareview from the CLI23## Run ultrareview from the CLI

24 24

vs-code.md +64 −2

Details

208* If a notice such as `Removed 3 invisible characters from the pasted text` appears when you paste, the text went in without those characters.208* If a notice such as `Removed 3 invisible characters from the pasted text` appears when you paste, the text went in without those characters.

209* If a notice about removed characters appears when you send, nothing was sent. The cleaned text is back in the prompt box. Send again to send the text as shown.209* If a notice about removed characters appears when you send, nothing was sent. The cleaned text is back in the prompt box. Send again to send the text as shown.

210 210

211### LaTeX math in responses

212

213The chat panel shows LaTeX math in Claude's responses as typeset formulas. Math rendering requires Claude Code v2.1.301 or later. In [terminal mode](#switch-to-terminal-mode), math isn't typeset. The panel typesets both display math and inline math:

214

215* **Display math**: a `$$ … $$` or `\[ … \]` block on a line or lines of its own, and a fenced code block with `math` as its language

216* **Inline math**: `$…$` or `$…$` that opens and closes on the same line, such as `$E = mc^2$` or `$a^2 + b^2 = c^2$`

217

218The panel tries to tell math apart from other uses of the same characters, so text such as `$HOME`, a price like `$5`, or `sed 's/$foo$/\1/'` isn't typeset. Neither is text inside a code span or inside any code block other than a fenced `math` block. If a formula shows as written when you expected it typeset, see [A formula shows as raw LaTeX](#a-formula-shows-as-raw-latex).

219

220When you select and copy text that includes a typeset formula, you get the formula's TeX source in `$…$` or `$$…$$` delimiters rather than the drawn symbols. [**Copy response**](#use-the-prompt-box) and `/copy` give you the response as Claude wrote it, TeX source included.

221

211### Resume past conversations222### Resume past conversations

212 223

213Click the **Session history** button at the top of the Claude Code panel to access your conversation history. You can search by keyword or browse by time.224Click the **Session history** button at the top of the Claude Code panel to access your conversation history. You can search by keyword or browse by time.

214 225

215Click any conversation to resume it with the full message history. If the conversation is already open in another tab of the current window, clicking it switches to that tab. For more on resuming sessions, see [Manage sessions](/docs/en/sessions).226Click any conversation to resume it with the full message history. If the conversation is already open in another tab of the current window, clicking it switches to that tab. If the messages stay blank at first, see [why they're blank and when they appear](#a-resumed-conversation-is-blank-at-first). For more on resuming sessions, see [Manage sessions](/docs/en/sessions).

216 227

217* **Session titles**: new sessions receive AI-generated titles based on your first message.228* **Session titles**: new sessions receive AI-generated titles based on your first message.

218* **Rename and archive**: hover over a session to reveal these actions. Rename to give it a descriptive title, or archive to move it to the **Archived sessions** group at the bottom of the list.229* **Rename and archive**: hover over a session to reveal these actions. Rename to give it a descriptive title, or archive to move it to the **Archived sessions** group at the bottom of the list.

297* **Editor tab**: the conversation comes back with its tab.308* **Editor tab**: the conversation comes back with its tab.

298* **Sidebar**: the conversation comes back if you sent a message or Claude responded in it within the last 10 minutes. If it doesn't come back, resume the conversation from [Session history](#resume-past-conversations).309* **Sidebar**: the conversation comes back if you sent a message or Claude responded in it within the last 10 minutes. If it doesn't come back, resume the conversation from [Session history](#resume-past-conversations).

299 310

300If another Claude Code process still has the conversation open, you're asked before it opens here, with the same **Open here anyway** notice as when you [resume it from session history](#resume-past-conversations).311If another Claude Code process still has the conversation open, you're asked before it opens here, with the same **Open here anyway** notice as when you [resume it from session history](#resume-past-conversations). If the messages stay blank at first, see [why they're blank and when they appear](#a-resumed-conversation-is-blank-at-first).

301 312

302If the reload interrupted Claude mid-step, Claude continues that step when the conversation comes back, and a notice in the chat marks the continuation. Requires Claude Code v2.1.274 or later. If the step was interrupted more than an hour ago or the session is open elsewhere, the conversation comes back idle instead.313If the reload interrupted Claude mid-step, Claude continues that step when the conversation comes back, and a notice in the chat marks the continuation. Requires Claude Code v2.1.274 or later. If the step was interrupted more than an hour ago or the session is open elsewhere, the conversation comes back idle instead.

303 314

304To turn continuation off, open the [Continue After Reload setting](vscode://settings/claudeCode.continueAfterReload) and uncheck it. Setting [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/en/env-vars#variables) or any other `CLAUDE_CODE_RESUME_` variable in VS Code's environment or in the [`environmentVariables` setting](#extension-settings) has no effect in the panel, because the extension removes those variables before it starts the panel's sessions.315To turn continuation off, open the [Continue After Reload setting](vscode://settings/claudeCode.continueAfterReload) and uncheck it. Setting [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/en/env-vars#variables) or any other `CLAUDE_CODE_RESUME_` variable in VS Code's environment or in the [`environmentVariables` setting](#extension-settings) has no effect in the panel, because the extension removes those variables before it starts the panel's sessions.

305 316

317#### A conversation was not reopened

318

319After a reload, a new chat with a notice like this above its prompt box means the panel left your conversation closed because the conversation's last two opens didn't finish:

320

321```text theme={null}

322“Fix the login bug” was not reopened. It did not finish opening the last 2 times, and opening it again may stop Claude Code from responding here.

323```

324

325An open doesn't finish when the panel crashes or stops responding while loading the conversation, or when you reload or close the window within about three seconds of it opening. Nothing is lost: the conversation is unchanged and stays in [Session history](#resume-past-conversations).

326

327* **To open it anyway**: click **Open it anyway** or pick the conversation from Session history. If it opens and the panel keeps working, it comes back after later reloads as usual. If the panel stops responding again, reload the window to return to a new chat with the notice.

328* **To leave it closed**: keep working in the new chat. The notice disappears once you send a prompt.

329

306### Run multiple conversations330### Run multiple conversations

307 331

308Use **Open in New Tab** or **Open in New Window** from the Command Palette to start additional conversations. Each conversation maintains its own history and context, allowing you to work on different tasks in parallel.332Use **Open in New Tab** or **Open in New Window** from the Command Palette to start additional conversations. Each conversation maintains its own history and context, allowing you to work on different tasks in parallel.

422 446

423For more about the plugin system, see [Plugins](/docs/en/plugins/overview) and [Plugin marketplaces](/docs/en/plugins/overview).447For more about the plugin system, see [Plugins](/docs/en/plugins/overview) and [Plugin marketplaces](/docs/en/plugins/overview).

424 448

449### Plugins that draw in the panel

450

451A plugin that contains a [mod](/docs/en/plugins/mods/overview) can draw in the chat panel. Drawing requires extension version 2.1.299 or later and a session that [fetches feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching). From such a plugin you can see:

452

453* A pane beside the conversation or above the prompt box

454* A toast or a status line above the prompt box

455* A message or a tool call drawn the plugin's own way

456

457When a plugin you installed adds or changes something in the panel, a label names it, in phrases such as these:

458

459* **From the token-chart plugin**: the plugin drew or printed this, or this card is the plugin asking you something

460* **Edited by the token-chart plugin**: the plugin changed something Claude Code draws, such as a tool call

461* **Prompt from the token-chart plugin**: the plugin sent this message on your behalf

462

463To stop a plugin from drawing, turn the plugin off in the [plugin dialog](#install-plugins).

464

425## Automate browser tasks with Chrome465## Automate browser tasks with Chrome

426 466

427Connect Claude to your Chrome browser to test web apps, debug with console logs, and automate browser workflows without leaving VS Code. This requires the [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or later.467Connect Claude to your Chrome browser to test web apps, debug with console logs, and automate browser workflows without leaving VS Code. This requires the [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or later.

808 848

809Alternatively, rebind the extension to a different key: open the VS Code [Keyboard Shortcuts editor](https://code.visualstudio.com/docs/configure/keybindings) (`Cmd+K Cmd+S`), search for `Claude Code: Focus input`, and assign a new binding.849Alternatively, rebind the extension to a different key: open the VS Code [Keyboard Shortcuts editor](https://code.visualstudio.com/docs/configure/keybindings) (`Cmd+K Cmd+S`), search for `Claude Code: Focus input`, and assign a new binding.

810 850

851### A resumed conversation is blank at first

852

853When you [resume a past conversation](#resume-past-conversations) or one [comes back after a reload](#continue-conversations-after-a-reload), its messages can stay blank while the conversation's Claude Code process starts. After about a second, `Waiting for your plugins…` appears in the empty space.

854

855You don't need to do anything. The messages appear once the process has started and confirmed that no plugin needs to check them first, or after 20 seconds if starting takes longer.

856

857### The panel stops responding each time a reload reopens a conversation

858

859If the whole panel crashes, freezes, or shows only `Something went wrong` each time you reload and your conversation comes back, update the extension to v2.1.301 or later. Then reload the window or restart VS Code again. After the conversation fails to finish opening twice in a row, you get a new chat in its place, with a notice that [it was not reopened](#a-conversation-was-not-reopened).

860

861### A formula shows as raw LaTeX

862

863If none of the math in Claude's responses is typeset, check the extension's version in the Extensions view, because [math rendering](#latex-math-in-responses) requires version 2.1.301 or later. If you use [terminal mode](#switch-to-terminal-mode), which doesn't typeset math whatever the version, uncheck the [Use Terminal setting](vscode://settings/claudeCode.useTerminal) so that Claude Code opens in the chat panel instead.

864

865If one formula shows as written while others near it are typeset, check it for these causes:

866

867* **It reads as something other than math**: `$…$` text that reads as a word stays as written, such as `$O(n log n)$`. `$…$` text that starts with a digit, such as `$30$` or `$1/N$`, also stays as written unless a character such as `=`, `+`, or `^` marks it as math. Ask Claude for a `$$` block on its own lines instead, which the panel typesets without this check.

868* **It's padded, long, or split across lines**: `$ x^2 $` with spaces inside the dollars, `$…$` content over 60 characters, and `$…$` or `$…$` split across two lines aren't typeset. Ask Claude for a `$$` block on its own lines instead, which has none of these limits.

869* **The TeX can't be typeset**: a formula with a syntax error, a macro definition such as `\newcommand` or `\def`, or an unescaped `%` shows as written. Ask Claude to rewrite it with the error corrected, without the macro, or with `\%` for a percent sign.

870* **It's too large**: a formula longer than 8,192 characters, or one that would draw far larger than its source, shows as written. Ask Claude to split it into smaller formulas or to write it more compactly.

871* **It follows a large amount of math**: within one block of text in a response, the panel typesets formulas in order up to a limit. A later formula that would go past the limit shows as written. Ask Claude to send the formula you need again by itself.

872

811### Claude Code never responds873### Claude Code never responds

812 874

813If Claude Code isn't responding to your prompts:875If Claude Code isn't responding to your prompts:

web-quickstart.md +1 −1

Details

95If you already connected GitHub in the browser, `/web-setup` warns you that continuing replaces that connection for your cloud sessions.95If you already connected GitHub in the browser, `/web-setup` warns you that continuing replaces that connection for your cloud sessions.

96 96

97<Note>97<Note>

98 Organizations with [Zero Data Retention](/docs/en/zero-data-retention) enabled, or with the [HIPAA configuration](/docs/en/hipaa-setup) applied, cannot use `/web-setup` or other cloud session features. If the GitHub CLI isn't installed or isn't authenticated, Claude Code opens the browser onboarding flow instead.98 Organizations with [Zero Data Retention](/docs/en/zero-data-retention) enabled, or with the [HIPAA configuration](/docs/en/hipaa-setup) applied, cannot use `/web-setup` or other cloud session features. Organizations that use [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek) (CMEK) can't start cloud sessions either. If the GitHub CLI isn't installed or isn't authenticated, Claude Code opens the browser onboarding flow instead.

99</Note>99</Note>

100 100

101<Steps>101<Steps>

whats-new/2026-w30.md +1 −1

Details

74 <p className="digest-wins-title">Other wins</p>74 <p className="digest-wins-title">Other wins</p>

75 75

76 <div className="digest-wins-grid">76 <div className="digest-wins-grid">

77 <div><a href="/docs/en/code-review#review-a-diff-locally"><code>/code-review</code></a> now runs as a background subagent with its own context window, so review work stays out of your conversation and the findings arrive when it completes</div>77 <div><a href="/docs/en/code-review-local"><code>/code-review</code></a> now runs as a background subagent with its own context window, so review work stays out of your conversation and the findings arrive when it completes</div>

78 <div><code>/verify</code>, <code>/code-review</code>, and <code>/deep-research</code> run only when you invoke them; Claude no longer launches them on its own</div>78 <div><code>/verify</code>, <code>/code-review</code>, and <code>/deep-research</code> run only when you invoke them; Claude no longer launches them on its own</div>

79 <div><a href="/docs/en/interactive-mode#emoji-shortcodes">Emoji shortcodes</a> autocomplete in the prompt input: type <code>:heart:</code> to insert an emoji, or two or more characters after <code>:</code> for suggestions; turn it off with <code>emojiCompletionEnabled</code></div>79 <div><a href="/docs/en/interactive-mode#emoji-shortcodes">Emoji shortcodes</a> autocomplete in the prompt input: type <code>:heart:</code> to insert an emoji, or two or more characters after <code>:</code> for suggestions; turn it off with <code>emojiCompletionEnabled</code></div>

80 <div>Skills with <code>context: fork</code> <a href="/docs/en/skills#run-skills-in-a-subagent">run in the background</a> by default, and <code>background: false</code> in the skill's frontmatter waits for the result in the same turn</div>80 <div>Skills with <code>context: fork</code> <a href="/docs/en/skills#run-skills-in-a-subagent">run in the background</a> by default, and <code>background: false</code> in the skill's frontmatter waits for the result in the same turn</div>

whats-new/2026-w32.md +1 −1

Details

87 <div>The VS Code extension gets <a href="/docs/en/vs-code#extension-settings">Focus view</a>, which hides tool activity behind one expandable row per turn; toggle it from the command menu or with <code>Ctrl+Alt+F</code> (<code>Ctrl+Option+F</code> on Mac)</div>87 <div>The VS Code extension gets <a href="/docs/en/vs-code#extension-settings">Focus view</a>, which hides tool activity behind one expandable row per turn; toggle it from the command menu or with <code>Ctrl+Alt+F</code> (<code>Ctrl+Option+F</code> on Mac)</div>

88 <div>Sandbox credential files accept <a href="/docs/en/sandboxing#mask-credential-files"><code>mode: "mask"</code></a> on Linux and WSL2, so sandboxed commands read a sentinel copy while the sandbox proxy substitutes the real value on egress; credential masking also gains <code>extract</code>, JWT-aware <code>decode</code>, and AWS SigV4 re-signing options</div>88 <div>Sandbox credential files accept <a href="/docs/en/sandboxing#mask-credential-files"><code>mode: "mask"</code></a> on Linux and WSL2, so sandboxed commands read a sentinel copy while the sandbox proxy substitutes the real value on egress; credential masking also gains <code>extract</code>, JWT-aware <code>decode</code>, and AWS SigV4 re-signing options</div>

89 <div>Marketplaces can distribute a plugin as a <a href="/docs/en/plugins/marketplace-reference#archive-plugin-source">zip archive</a> with the new <code>archive</code> source, downloaded over HTTPS with an optional SHA-256 pin, so installs work without git or npm</div>89 <div>Marketplaces can distribute a plugin as a <a href="/docs/en/plugins/marketplace-reference#archive-plugin-source">zip archive</a> with the new <code>archive</code> source, downloaded over HTTPS with an optional SHA-256 pin, so installs work without git or npm</div>

90 <div><code>/review</code> is now an alias of <a href="/docs/en/code-review#review-a-diff-locally"><code>/code-review</code></a>, and <code>/code-review</code> with no effort level reuses the level you typed last</div>90 <div><code>/review</code> is now an alias of <a href="/docs/en/code-review-local"><code>/code-review</code></a>, and <code>/code-review</code> with no effort level reuses the level you typed last</div>

91 <div>A session you copy with <a href="/docs/en/agent-view#copy-the-session-with-%2Ffork"><code>/fork</code></a> now makes its code changes in a worktree of its own instead of the original session's checkout</div>91 <div>A session you copy with <a href="/docs/en/agent-view#copy-the-session-with-%2Ffork"><code>/fork</code></a> now makes its code changes in a worktree of its own instead of the original session's checkout</div>

92 <div>Plugins you install from <a href="/docs/en/plugins/install#install-a-plugin"><code>/plugin</code></a> activate in the current session when it's safe to do so; the install summary reports <code>Plugin is now active.</code> or tells you to run <code>/reload-plugins</code></div>92 <div>Plugins you install from <a href="/docs/en/plugins/install#install-a-plugin"><code>/plugin</code></a> activate in the current session when it's safe to do so; the install summary reports <code>Plugin is now active.</code> or tells you to run <code>/reload-plugins</code></div>

93 <div><a href="/docs/en/agent-view#how-file-edits-are-isolated">Background sessions</a> that changed code in a worktree now commit and push before finishing, open a draft pull request only when the task calls for one, and follow the git instructions in your <code>CLAUDE.md</code></div>93 <div><a href="/docs/en/agent-view#how-file-edits-are-isolated">Background sessions</a> that changed code in a worktree now commit and push before finishing, open a draft pull request only when the task calls for one, and follow the git instructions in your <code>CLAUDE.md</code></div>

whats-new/2026-w33.md +1 −1

Details

75 <div>Plugin marketplaces accept <a href="/docs/en/plugins/marketplace-reference#command-plugin-source"><code>command</code> sources</a>: a local command prints the plugin directory, which Claude Code re-resolves each session and applies without a restart</div>75 <div>Plugin marketplaces accept <a href="/docs/en/plugins/marketplace-reference#command-plugin-source"><code>command</code> sources</a>: a local command prints the plugin directory, which Claude Code re-resolves each session and applies without a restart</div>

76 <div>On Linux and WSL, set <a href="/docs/en/tools-reference#memory-limit-on-linux-and-wsl"><code>CLAUDE\_CODE\_TOOL\_MEMORY\_LIMIT</code></a> to a size such as <code>4G</code> to cap the memory Bash and PowerShell tool commands can use</div>76 <div>On Linux and WSL, set <a href="/docs/en/tools-reference#memory-limit-on-linux-and-wsl"><code>CLAUDE\_CODE\_TOOL\_MEMORY\_LIMIT</code></a> to a size such as <code>4G</code> to cap the memory Bash and PowerShell tool commands can use</div>

77 <div>The task-tracking tools, such as <code>TaskCreate</code>, <code>TaskUpdate</code>, and <code>TodoWrite</code>, are <a href="/docs/en/tools-reference#task-tool-availability">no longer available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and later models in those families</a>; set <code>CLAUDE\_CODE\_ENABLE\_TODO\_TOOLS=1</code> to re-enable them</div>77 <div>The task-tracking tools, such as <code>TaskCreate</code>, <code>TaskUpdate</code>, and <code>TodoWrite</code>, are <a href="/docs/en/tools-reference#task-tool-availability">no longer available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and later models in those families</a>; set <code>CLAUDE\_CODE\_ENABLE\_TODO\_TOOLS=1</code> to re-enable them</div>

~~78 <div><a href="/docs/en/code-review#review-a-diff-locally"><code>/code-review</code></a> at high, xhigh, and max effort now runs in a background agent like the other levels</div>~~78 <div><a href="/docs/en/code-review-local"><code>/code-review</code></a> at high, xhigh, and max effort now runs in a background agent like the other levels</div>

79 <div><a href="/docs/en/plugins/install#install-a-plugin"><code>/plugin install plugin\@marketplace</code></a> refreshes the marketplace first, so newly published plugins install without a manual marketplace update</div>79 <div><a href="/docs/en/plugins/install#install-a-plugin"><code>/plugin install plugin\@marketplace</code></a> refreshes the marketplace first, so newly published plugins install without a manual marketplace update</div>

80 <div>Settings accept <a href="/docs/en/settings-reference#marketplace-key-aliases"><code>additionalMarketplaces</code> and <code>allowedMarketplaces</code></a> as aliases for <code>extraKnownMarketplaces</code> and <code>strictKnownMarketplaces</code></div>80 <div>Settings accept <a href="/docs/en/settings-reference#marketplace-key-aliases"><code>additionalMarketplaces</code> and <code>allowedMarketplaces</code></a> as aliases for <code>extraKnownMarketplaces</code> and <code>strictKnownMarketplaces</code></div>

81 <div>On newer models, Claude can <a href="/docs/en/tools-reference#write-tool-behavior">overwrite an existing file with the Write tool</a> without reading it first this session, matching the Edit tool's rules; older models require the read</div>81 <div>On newer models, Claude can <a href="/docs/en/tools-reference#write-tool-behavior">overwrite an existing file with the Write tool</a> without reading it first this session, matching the Edit tool's rules; older models require the read</div>

workflows.md +4 −4

Details

185 185

186In `claude -p` and the Agent SDK, Claude Code never shows this prompt. It runs the Workflow tool call through the same [permission evaluation](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) as the rest of the session, so deny rules, ask rules, and `dontAsk` mode apply to the launch as they apply to every tool call. To let the workflow start in these runs, use one of these:186In `claude -p` and the Agent SDK, Claude Code never shows this prompt. It runs the Workflow tool call through the same [permission evaluation](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) as the rest of the session, so deny rules, ask rules, and `dontAsk` mode apply to the launch as they apply to every tool call. To let the workflow start in these runs, use one of these:

187 187

188* **Permission rule**: `Workflow` in your allow rules approves every workflow, and `Workflow(<name>)` approves one saved workflow by name.188* **Permission rule**: add `Workflow` to your allow rules to approve every workflow, or `Workflow(<name>)` to approve one saved workflow by name.

189* **Auto permission mode**: the [classifier](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) reviews the call and can approve it.189* **Auto permission mode**: run in [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode), where the classifier reviews the call and can approve it.

190* **Bypass permissions mode**: Claude Code approves the call.190* **Bypass permissions mode**: run in bypass permissions mode.

191* **A hook**: a [`PreToolUse`](/docs/en/hooks#pretooluse) hook that allows the call approves it.191* **A hook**: return `"allow"` for the call from a [`PreToolUse`](/docs/en/hooks#pretooluse) hook. In [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode), the workflow doesn't start on the hook's approval alone, so use a permission rule or your host's approval there instead.

192* **Your host**: a [`--permission-prompt-tool`](/docs/en/cli-reference#cli-flags) or, with the Agent SDK, a [`canUseTool`](/docs/en/agent-sdk/permissions) callback approves it.192* **Your host**: a [`--permission-prompt-tool`](/docs/en/cli-reference#cli-flags) or, with the Agent SDK, a [`canUseTool`](/docs/en/agent-sdk/permissions) callback approves it.

193 193

194In the Desktop app, an approval card shows the workflow name, the phase list, and a token-usage caution, with **Once**, **Always**, and **Deny** actions. The progress view appears in the Background tasks side pane.194In the Desktop app, an approval card shows the workflow name, the phase list, and a token-usage caution, with **Once**, **Always**, and **Deny** actions. The progress view appears in the Background tasks side pane.

Documentation 2026-10-14 22:58 UTC to 2026-10-15 23:58 UTC