One read of Claude Code CLIclaude-code-20261104T003701Z
8 pages moved out of 228 read.
Pages moved
8
significant first
Pages read
228
in this capture
Captured
00:37 UTC
Corpus hash
327d6b3bda26
corpus-hash
What this read moved
1-8 of 8changelog Changed · +100 / -0 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 6
66
77Run `claude --version` to check your installed version.
88
9**2.1.318**
10
11November 4, 2026
12
13**Added**
14
15* Added a record of your answer when Claude Code asks to turn on the mods it writes in a session
16* Added `assume_role` on `mantle` upstreams of the Claude apps gateway, for a role in another AWS account and for per-developer AWS cost attribution
17* Added an `effort` option to a mod's `$.model.fork`, so a quick side job can run at `low` whatever effort the session uses; the result reports the effort sent
18* Added the date a stored claude.ai sign-in ends to `claude auth status` (`loginExpiresAt`) and to `claude -p` JSON results (`credential_expires_at`)
19* Added a one-line stderr warning to `claude -p` text output, starting 10 days before a stored claude.ai sign-in ends
20* Gateway: Added a log warning when the Google access token from a federation (`external_account`) credentials file is about to expire
21* Self-hosted runner: Added `CLAUDE_RUNNER_SPAWN_REASON` to the orchestrator's spawn-runner hook environment: why Anthropic sent the request (e.g. `runner_lost`, `resumed`); unset when none was sent
22* Self-hosted runner: Added a startup warning when `--release-idle-session-min` is the last argument with no value (still ignored) or has a value of only spaces (still read as `0`)
23* \[Cloud sessions] Added a No repository option: a cloud session on an Anthropic-hosted environment can now start without picking a repository
24* \[Cloud sessions] Added the usual Chrome names to cloud sessions, so tools other than Playwright can find the built-in Chromium through google-chrome and CHROME\_PATH
25* \[Cloud sessions] Added a New session button to the card shown when a cloud session's environment was deleted, where the message box is hidden
26
27**Changed**
28
29* Changed Claude Code to no longer install or update the IDE extension when started in an IDE terminal; use `/ide` from an outside terminal or your editor's extensions view
30* Changed subagents to stop instead of switching models when "Switch models when a message is flagged" is set to "Ask each time"
31* Changed background subagents to move a shell command to the background after 3 minutes on all providers, so the prompt cache doesn't expire while it runs
32* Changed subagent progress summaries on Bedrock, Vertex, Foundry, or with telemetry off: on a cold prompt cache, one can now wait up to 5 minutes for the subagent's pending response
33* Changed what a mod attaches at `prompt.submit` to stay in the user's turn rather than go out as a system message
34* Changed `deniedMcpServers` URL entries to also block Anthropic-provided servers whose upstream URL matches, and connectors in cloud sessions and on self-hosted runners, where the session is given the connector's own URL; otherwise deny a connector by name
35* Changed the `/permissions` rule details, built-in rules and delete confirmation views to use the standard dialog; pressing Ctrl+C twice there now goes back or cancels instead of quitting
36* Changed `/claude-api managed-agents-onboard` to give a new agent's built-in tools, and a quickstart template's MCP tools, the `auto` permission policy ("Judge risky actions") by default, matching the Claude Console; say "run without asking" to opt out
37* Removed the 2.1.288 fix that kept the model's earlier thinking when resuming a conversation started on 2.1.286 or earlier; that thinking can now be dropped
38* Self-hosted runner: Changed the orchestrator's log lines: `ok session=…` now prints at every log level on stdout (was debug only, stderr) with `reason=…` after `jti=…`, and `nack session=…` ends its fields with `reason=…` after `retryable=…`; update scripts that match `retryable=true:` or `retryable=false:`
39* \[Cloud sessions] Changed connector search results to tell Claude that the search covers only part of the connector directory
40
41**15 improvements**
42
43* Improved how `~/.claude.json`, settings files and the stored login survive saves on shared network home directories: they are less often deleted, briefly emptied or replaced by a near-empty or older copy
44* Improved sessions on network file systems to look again when the configuration file is wrongly reported as missing, so fewer start without your MCP servers and trusted folders
45* Improved MCP tool errors: a call made before the tool is loaded now returns its input schema
46* Improved the reliability of git commits and pull request creation when the Bash tool runs macOS's built-in `/bin/bash`
47* Improved "Ask your admin for more usage" in the usage limit menu to send the request in one step
48* Improved how fast remote sessions reconnect after a pause or sleep
49* Improved You should know toasts to say "try again" instead of "press 2", which only works in the terminal
50* Improved auto-update reliability: a brief network failure while verifying a release is now retried right away instead of waiting for the next check
51* Improved unattended runs (`claude -p`, SDK apps) to stop rewriting `~/.claude.json` on every run when nothing in it changed
52* Gateway: Improved the log hints about `listen.trusted_proxies`: they now say to list only a proxy that adds the connecting address to `X-Forwarded-For` itself
53* Gateway: Improved the warning when AWS CountTokens fails on Amazon Bedrock: it says Claude Code, not the gateway, counts after the 501, and points at IAM only when AWS denies access
54* Remote Control: Improved the title a fork of a terminal fork is created with when the app doesn't set one: "Name (fork 2)"
55* \[VSCode] Improved the sign-in screen to show what Claude Code printed when its sign-in status check fails
56* \[Cloud sessions] Improved most Create PR failure messages in cloud and Remote Control sessions: they now give the reason or a link to GitHub instead of saying Try again
57* \[Code Review] Improved the Code Review analytics page to retry once after a server or network failure, then show a Try again banner instead of empty cards
58
59**47 bug fixes**
60
61* Fixed `--continue` sometimes losing the earlier conversation after a malformed tool call's retries ran out (regression in 2.1.314)
62* Fixed macOS sessions with many running Bash commands stalling while memory grew
63* Fixed permission prompts being answered by keys typed just after sending a message, or before a slow prompt appeared
64* Fixed `/logout`, `claude auth logout` and `claude mcp remove` reporting success, and changes to trust, consent or MCP settings being dropped with no word, when the config file could not be updated on a shared network home directory
65* Fixed jobs exiting with `Not logged in` when another terminal or host signs in again to the same account and organization on the same home
66* Fixed `claude mcp add` and `remove` writing the config without its lock: they now wait for it or exit 1, though another job's save can still replace a saved server
67* Fixed `claude plugin` commands exiting before a slow token refresh was saved, which could sign you out on the next run
68* Fixed `claude plugin validate` passing a custom-named marketplace file that `claude plugin marketplace add` rejects
69* Fixed stdio MCP servers that exit on the version probe being re-probed on every start; a server that dies in under 3s for its own reason is also pinned to the legacy handshake for 7 days
70* Fixed sessions being refused at startup by an `allowedProviders` list that another login on the same machine had stored
71* Fixed idle compaction replacing a conversation with a reply that was not a summary
72* Fixed the "Now using usage credits" notice reappearing about every 30 seconds while a background subagent is running
73* Fixed custom slash commands that fail, or that only Claude can invoke, printing nothing in `claude -p` and SDK sessions
74* Fixed `claude -p` and Agent SDK sessions reporting success when an API error cut off a reply while a mod hooked `turn.step`
75* Fixed a message sent right after a model change still running after Stop in headless sessions: Stop now cancels or stops it as it would a queued message
76* Fixed a deleted session transcript being re-created with its last prompt when an idle non-interactive session exited
77* Fixed `claude remote-control` hosts, the background daemon and self-hosted runners failing to start new sessions (`spawn ENOENT`) after an update or version cleanup removed the binary of a still-running process
78* Fixed a running Claude Code process owned by another user (for example one left by `sudo claude`) being treated as dead by version cleanup, which could delete its binary
79* Fixed `/remote-control` showing a session as available after a failed connection
80* Fixed `/design revoke` reporting success when the request failed with a 404
81* Fixed a shell command approved after a self-hosted runner or cloud session restart running in the session's start folder, not the folder it was asked in; if that folder can't be entered, it is not run
82* Fixed Claude not being told when an approved connector tool was unavailable after a cloud session restart
83* Fixed cloud sessions being stopped in the middle of a turn when the service refuses uploads for several minutes
84* Fixed variables a `Setup` hook writes to `CLAUDE_ENV_FILE` not reaching the Bash tool in some cloud sessions
85* Fixed the iPhone app showing a cloud session's turn as finished while it kept running, after a response was cut off at a tool call or a refused image or document was removed
86* Fixed a restarted session re-sending a message that failed with an API error, ahead of the newer message waiting behind it
87* Fixed a restarted session dropping its interrupted turn when the restart came right after Claude read a large image or retried a tool call
88* Fixed every connection failing when the `NODE_EXTRA_CA_CERTS` file is empty, not PEM, or starts with a damaged certificate: readable certificates are now used, with a warning on stderr
89* Fixed workflows re-running finished agents when resumed after a usage limit
90* Fixed `/mcp` in cloud sessions counting tools the model can't use; a server's row now shows how many of its tools are available
91* Fixed a duplicate notification when Claude left the status field out of a PushNotification call
92* Fixed the error for a too-large image in a request with more than 20 images always saying the limit was 2000px; it now shows the API's limit
93* Fixed the runtime in background shell details not updating while the dialog is open
94* Fixed a mod's `turn.step` hook making a stopped reply finish as a success in headless runs
95* Fixed retention cleanup leaving a home that only runs `claude -p` with no `~/.claude.json` backup: it now takes a fresh backup before deleting the last good one
96* Fixed the stored login being replaced by an empty file when a network home directory has no room left for data but still takes new files
97* Fixed tokens from `setup-token` being refused at start on machines with `forceLoginOrgUUID`, when the token belongs to a permitted organization
98* Fixed non-interactive launches replacing a `~/.claude.json` that isn't valid JSON with defaults; the start now fails, says how to restore the file, and leaves it as is (anthropics/claude-code#87551)
99* Fixed an empty `~/.claude.json` with no backup being reported as corrupted; Claude Code now starts as it does when the file is missing
100* Fixed the restore command printed for a damaged or missing `~/.claude.json` naming an empty or cut-off backup, or failing on a read-only file
101* Fixed the sign-in failure when a stored claude.ai login reaches its time limit: it now says so, and in `claude -p` names `claude auth login` and `claude setup-token`
102* Remote Control: Fixed a misleading "spawn error: ENOENT" when a session's working folder is missing; the error now names the folder
103* \[VSCode] Fixed a window whose sign-in the organization's settings refuse starting a new Claude Code process in the background every minute
104* \[VSCode] Fixed a long word in the chat panel's error banner pushing its close button out of view
105* \[Cloud sessions] Fixed reading GitHub Actions logs in cloud sessions: `gh run view --log` and `gh api` log requests now get the log in most environments, not an unreachable redirect
106* \[Remote Control] Fixed side-by-side checkouts of one repository looking identical in the environment menu's Remote Control rows; each now shows its own folder name
107* \[Claude Tag] Fixed keyboard focus and screen reader announcements in Claude Tag admin setup; pressing Escape in the connect form no longer also closes the Add dialog
108
9109**2.1.317**
10110
11111November 3, 2026
from line 2143
20432143* Fixed auto mode on Bedrock and Mantle switching to the local classifier for the rest of the session after a request to an older model, such as a WebFetch summary or a `sonnet` subagent
20442144* Fixed cloud sessions that restarted on a newly picked model replying with that model after the server refused it
20452145* Fixed Cowork cloud sessions staying marked as waiting for input after a WebFetch permission prompt for an unapproved URL went unanswered for five minutes
2046* Fixed prompt suggestions not appearing on a phone that joins a Cowork cloud session started on another device
2047* Fixed a mod's button sometimes running a different button's action when pressed on a view drawn before Claude Code restarted
2048* Fixed a plugin's pane showing nothing when one `Code` element held a diff that does not parse; it now draws as plain code
2049* Fixed plugin LSP servers receiving literal `${user_config.*}` and `${CLAUDE_PLUGIN_ROOT}` placeholders in `initializationOptions` and `settings` instead of substituted values or manifest defaults
2050* Fixed a plugin's `tool.call` hook making Bash fail and file searches read the wrong folder in subagents that run in a worktree
2051* Fixed `git-subdir` plugin installs failing, or caching an incomplete plugin, on older git (before 2.39, e.g. Ubuntu 22.04's 2.34)
2052* Fixed plugins loaded with `--plugin-dir` not showing "Configure options" in `/plugin`
2053* Fixed background sessions ending when a plugin was reloaded or disabled while one of its timers or reads was still running
2054* Fixed sandboxed heredocs with an unquoted delimiter (`python3 <<EOF`) asking for approval on every run under sandbox auto-allow when the body holds only plain text and simple `$VAR` references
2055* Fixed Bash tool permission check to prompt before a `BASHPID` assignment whose value the shell would evaluate as arithmetic, instead of allowing it silently
2056* Fixed fullscreen sessions exiting with "unrecoverable interface error" when opening the background tasks dialog while a plugin or mod showed rows above the prompt
2057* Fixed Claude reporting a message to another session as delivered when that session held it: the notice now says it wasn't delivered and names the session, and in SDK sessions Claude can now learn of it mid-turn
2058* Fixed OpenTelemetry `claude_code.tool.blocked_on_user` spans reporting `unknown` source or decision in `-p` and SDK sessions and for PreToolUse hook approvals
2059* Fixed permission asks that ended unanswered, in `-p` or on an interrupted turn, emitting no `tool_decision` event
2060* Fixed Edit and Retry in Cowork cloud sessions refusing a message sent before `/compact` even though its history was still saved
2061* Fixed unattended sessions (`CLAUDE_CODE_RETRY_WATCHDOG`) retrying for hours after a very long response stream failed; Claude Code now streams again, and gives up after three timeouts
2062* Fixed `/login` reporting "Login successful" when credentials could not be saved to secure storage; it now shows the failure, and offers a retry when the new login didn't take effect (anthropics/claude-code#73861)
2063* Fixed a Stop during Bedrock credential lookup sometimes moving the session to a fallback model instead of ending the request
2064* Fixed a second `gcpAuthRefresh`/`awsAuthRefresh` browser sign-in opening when a laptop wakes from sleep while another Claude Code process is signing in
2065* Fixed agent teams: a plugin-defined agent spawned by name now runs with its own prompt, tools, disallowedTools and effort instead of the defaults
2066* Fixed headless (`-p` / SDK) sessions occasionally ignoring SIGTERM when a supervisor such as `timeout` or systemd sends SIGCONT alongside it
2067* Fixed restarted cloud sessions restoring a model that the organization's enforced model list refuses
2068* Fixed MCP tool calls sometimes running twice when a remote server's result was over 16 MB or could not be parsed
2069* Fixed subagents in Claude Desktop's Code tab getting none of the tools of a user-configured MCP server named `memory`
2070* Fixed Claude in Chrome asking before every screenshot and page read on a site you allowed when auto mode is unavailable (such as with `disableAutoMode` or an older model); typing, navigation and JavaScript still ask
2071* Fixed `claude plugin install` failing for GitHub-source plugins on macOS and Linux machines with no GitHub SSH key: the clone now falls back to HTTPS and prints a notice
2072* Fixed `sandbox.credentials.files` entries on git config files not taking effect while `permissions.blockReadsOutsideWorkingDirectories` is on
2073* Fixed Claude leaving out your organization's design systems when starting slides or a design with the Artifact tool on Team and Enterprise plans or machines with managed settings
2074* Fixed the keyboard not working on Windows after Claude Code restarts itself (first sign-in to a Claude apps gateway, provider setup, `/tui`)
2075* Fixed a stall when launching an agent whose `tools:` lists very many `Agent(...)` entries
2076* Fixed sessions on Claude 3 Opus and Claude 3 Sonnet failing on every turn after a whole PDF entered the conversation
2077* Fixed the npm auto-updater reporting success when the platform-native binary failed to download and only the placeholder `claude` stub was installed
2078* Fixed Remote Control cleanup archiving a session that is still connected or was just re-attached by another Claude Code process
2079* Fixed `owner/repo` plugin marketplaces showing only the second attempt's error when both the SSH and HTTPS fetch fail; both errors are now shown, with the transport tried first on top
2080* Fixed path-scoped `.claude/rules` and nested CLAUDE.md files not loading when Write or Edit creates or changes a file in their scope (previously only Read loaded them)
2081* Fixed a dangerous `rm` (such as one on `/` or the home directory) inside a `bash -c` or `sh -c` script running without a prompt in bypassPermissions mode or under a shell allow rule (anthropics/claude-code#96300)
2082* Fixed LSP tool calls hanging indefinitely when a language server uses dynamic capability registration or stops responding; requests now time out after 60s (per-server `requestTimeout`)
2083* Fixed `idle_prompt` notification hooks firing while background agents are still running (anthropics/claude-code#93672)
2084* Fixed PreToolUse and PermissionRequest hooks being skipped when matching them failed or the tool's input could not be serialized to JSON; the call is now blocked
2085* Fixed the first request in a fresh environment or after a model switch using the built-in output limit and auto-compact window, not the server's; that request may now wait up to 1.5 seconds
2086* Fixed the "What should Claude do instead?" hint showing on the Interrupted row after sending queued messages with ctrl+enter
2087* Fixed `/login` in a `--bare` session running a sign-in the session never reads, which could replace your saved login; it now says which credentials work
2088* Fixed the InstructionsLoaded hook omitting agent\_id and agent\_type when a subagent's file access loads a rule or nested CLAUDE.md; rules and nested CLAUDE.md files loaded on file access now also report effort
2089* Fixed the Agent tool in `claude mcp serve` always reporting no available agents and rejecting every subagent\_type
2090* Fixed the terminal cursor not following the typed text in the fullscreen transcript viewer's search and in `/theme`'s custom color search
2091* Fixed `/permissions` in screen reader mode: typing a rule's number now picks it instead of opening the search box
2092* \[VSCode] Fixed a claude.ai connector staying on "Needs authentication" after you authorize it: the MCP servers dialog now offers Check connection
2093* \[VSCode] Fixed the opt-in New Conversation shortcut (Cmd/Ctrl+N) starting a conversation in every visible Claude view instead of only the one you are in
2094* \[VSCode] Fixed the chat view resuming the next saved session after you archive the one it shows; it now starts a new conversation instead
2095* \[Cloud sessions] Fixed the Cloud sessions switch in Claude Code admin settings staying locked off while an unrelated security setting was loading or had failed to load
2096* \[Cloud sessions] Fixed pressing Stop while a self-hosted runner was still starting not cancelling the queued message, which could then run once the runner was up
2097* \[Claude Tag] Fixed Claude Tag admin settings offering a "Remove this scope" option, which always failed, on channels whose settings were created automatically
2098* Fixed `claude plugin test` reporting mods as turned off remotely when it had only read an out-of-date saved setting
2099
2100**2.1.287**
2101
2102October 1, 2026
2103
2104**Added**
2105
2106* Added Claude Mods: plugins may now modify deeper behavior
2107* Added You should know, a built-in mod where a side agent watches your back and flags things you or Claude might miss. Turn it on with `/plugin enable cc-plugin-you-should-know@builtin` (for first-party sessions with telemetry on)
2108* Added an `n:<text>` filter to the agents view that matches session names and tasks; a filter now shows matches in collapsed sections and Enter opens the first match
2109* Added `prompt_text` to the OpenTelemetry `user_prompt` event, a copy of `prompt` for backends that nest dotted keys; drop or mask it wherever you drop or mask `prompt` (anthropics/claude-code#70763)
2110* Added URL prompts from MCP servers on the 2025-11-25 protocol, for example to sign in. If a server no longer connects after this update, add "bareElicitationCapability": true to its MCP config entry
2111* Windows: Added a startup warning when denying the Bash tool also turns off the PowerShell tool, so Claude has no shell tool
2112* Self-hosted runner: Added a built-in `gh api` (REST only) for sessions that use Anthropic-managed git on macOS and Linux machines where the GitHub CLI is not installed
2113* \[VSCode] Added "Run in background" to a running command or sub-agent, to move it to the background and keep working
2114* \[VSCode] Added the output of background shells and Monitors to their cards in the agent map
2115
2116**Changed**
2117
2118* Changed a shell write through a repo-committed symlink onto a sensitive file or out of the working tree to name where it lands and wait for a person, on lines with a `~` target too
2119* Changed Opus 4.7+ and Fable to use a 1M context window by default on Bedrock, Vertex, Foundry and the Claude apps gateway, with no `[1m]` suffix (`CLAUDE_CODE_DISABLE_1M_CONTEXT=1` keeps 200K)
2120* Changed replies from `claude agents` to arrive as queued messages; slash commands other than `/stop` sent while a turn is running now run when it ends
2121* Changed whole-tool `Bash` allow rules and allowing hooks to prompt for, not run, shell writes to files Claude Code's file tools refuse outright (the Anthropic profile store, the host credentials file)
2122* Changed right-click paste on Windows and Linux, and middle-click paste on Linux, to happen when the button is released; moving the pointer away before releasing cancels it
2123* Changed MCP server `alwaysLoad: false` to defer all of that server's tools behind tool search
2124* Changed screen reader mode to write new or changed lines without first pausing with the cursor at the start of the line; set `CLAUDE_AX_PREPARK_MS=50` to restore the pause
2125* Changed automatic model switches after a flagged message to keep your current effort level instead of the new model's default
2126* Changed waiting permission prompts to show oldest first, so a new prompt no longer covers the one you're reading (prompts with a countdown still open on top)
2127* \[VSCode] Changed the Claude in Chrome "Enabled by default" switch to also connect the editor's own sessions, which still ask before browser actions
2128
2129**20 improvements**
2130
2131* Improved `/config`: settings that cycle show ‹ › and step both ways with ←/→, narrow terminals stack each value under its label, and PgUp/PgDn page the list
2132* Improved plugin marketplace errors to say in plain words why a marketplace was ignored or refused, and what to do
2133* Improved plugin listings to note when a plugin's dependencies were not installed, and updating a plugin now retries an install that did not finish
2134* Improved the Claude apps gateway's error when Amazon Bedrock rejects a model ID: developers now see which model is unavailable, and the gateway log names the ID that was sent
2135* Improved SDK sessions so a message sent with priority "now" no longer cancels a running web fetch or web search; it keeps loading in the background
2136* Improved `/memory`: the left and right arrow keys now flip its on/off settings, such as Auto-memory
2137* Improved `/skill` names typed mid-message: Claude is now told they are skills, including `disable-model-invocation` ones
2138* Improved the contrast of the prompt input border in light themes and of the ❯ before your earlier messages
2139* Improved delivery of files Claude sends from cloud sessions and Remote Control: an upload that fails on a timeout, a network error or a 502, 503 or 504 is now retried once
2140* Improved what Claude says when a file cannot be sent for a reason that may be temporary: it now mentions that you can ask for t
2146* Fixed prompt suggestions not appearing on a phone that joins a Cowork cloud session started on another d
desktop Changed · +67 / -11 lines
##### Write the command on Windows ##### Wrap a Windows tool that prints other lines
from line 1598
15981598
15991599> [!NOTE]
16001600>
1601> Connections from a command require Claude Desktop v3.6556.0 or later on macOS or Linux, signed in with a Claude account. Administrators can [distribute commands to a team](#distribute-commands-to-your-team).
1601> Connections from a command require Claude Desktop v3.6556.0 or later on macOS or Linux, or v4.16336.0 or later on Windows, signed in with a Claude account. On Windows, Desktop also has to [connect through the OpenSSH client](#use-your-ssh-configuration). Administrators can [distribute commands to a team](#distribute-commands-to-your-team).
16021602
16031603Desktop runs the command only when you create the connection or [create another machine](#create-another-machine), not each time you connect. Each entry is one connection, which points at the host that Desktop last saved from the entry's command.
16041604
from line 1628
16281628}
16291629```
16301630
1631On Windows, a bare name such as `acme-dev` doesn't work, so [start the command with the program's full path](#write-the-command-on-windows).
1632
16311633Each entry takes these fields, and `id`, `name`, and `command` are required:
16321634
16331635| Field | Value |
from line 1644
16421644
16431645##### Write the command
16441646
1645Desktop starts the program directly, with no shell and no terminal:
1647On Windows, start with [Write the command on Windows](#write-the-command-on-windows), which says which of these rules apply there.
16461648
1647* **Program**: write its name, or its full path from `/`, without spaces. Desktop looks for a bare name on the `PATH` that your login shell exports. Relative paths such as `./acme-dev`, paths that start with `~`, and shell aliases and functions don't work.
1648* **Arguments**: separate plain arguments with spaces. The command can hold only spaces, ASCII letters, digits, and the characters `+,-./:=@_~`, and no word can start with `~`.
1649* **Scripts**: if the command needs anything else, such as quotes, pipes, variables, or a URL with `?` or `&`, put it in a script. Make the script executable, start it with a `#!` line, and set `command` to its full path, such as `/Users/you/bin/make-devbox`. On macOS, keep the script out of the Documents, Desktop, and Downloads folders, where macOS can block it.
1649On macOS and Linux, Desktop starts the program directly, with no shell and no terminal:
1650
1651* **Program**: write its name, or its full path from `/`. Desktop looks for a bare name on the `PATH` that your login shell exports. Relative paths such as `./acme-dev`, paths that start with `~`, and shell aliases and functions don't work.
1652* **Spaces in the path**: put the program's full path in single quotes, such as `'/Users/you/My Tools/make-devbox' create`. Quotes, single or double, require Claude Desktop v4.16336.0 or later, and work only around the program's path.
1653* **Arguments**: separate arguments with spaces. Outside quotes, the command can hold only spaces, ASCII letters, digits, and the characters `+,-./:=@_~`, and no word can start with `~`. A quoted path can also hold some other characters, such as `(`, `)`, and `&`.
1654* **Scripts**: if the command needs anything else, such as quoted arguments, pipes, variables, or a URL with `?` or `&`, put it in a script. Make the script executable, start it with a `#!` line, and set `command` to its full path, such as `/Users/you/bin/make-devbox`. On macOS, keep the script out of the Documents, Desktop, and Downloads folders, where macOS can block it.
16501655* **Input**: the program gets no input and no terminal, so it can't prompt you there. If your tool signs you in through a browser or a prompt, sign in from a terminal first, and again whenever that sign-in lapses.
16511656* **Environment**: the program runs in your home directory with the variables that your login shell exports. Desktop reads them when it starts, as it does for [a `ProxyCommand`](#use-variables-from-your-shell-in-a-proxycommand), so quit and reopen Desktop after you change them.
16521657* **Time limit**: Desktop stops a program that is still running after 10 minutes. Desktop's progress message doesn't show the program's output. To stop the program sooner, select **Cancel** next to that message.
from line 1681
16761681
16771682If the command fails, **View details** in Desktop's message shows the last line that the command wrote to standard error, if any.
16781683
1684##### Write the command on Windows
1685
1686On Windows, start `command` with the full path of an `.exe`, `.cmd`, or `.bat` file, from the drive letter. Desktop doesn't look for a bare name on your `PATH`, so an entry whose `command` is `acme-dev create` is [gray](#if-a-command-is-missing-or-gray).
1687
1688The following entry in `%USERPROFILE%\.claude\settings.json` runs `C:\Program Files\Acme\acme-dev.exe` with the argument `create`. In JSON, write each backslash twice, or write `/` instead. The single quotes are there because the path has a space:
1689
1690```json settings.json theme={null}
1691{
1692 "sshHostCommands": [
1693 {
1694 "id": "devbox",
1695 "name": "Dev box",
1696 "command": "'C:\\Program Files\\Acme\\acme-dev.exe' create"
1697 }
1698 ]
1699}
1700```
1701
1702Follow the rules in [Write the command](#write-the-command) on spaces in the path, input, the time limit, and what the program prints. In place of its other rules, follow these:
1703
1704* **Program**: don't use a network path such as `\\server\share`, a variable such as `%USERPROFILE%`, or a letter outside ASCII. With any of these in the path, the entry is gray. If your user folder's name has such a letter, keep the program outside that folder.
1705* **Arguments**: follow the Arguments rule in Write the command. The command can also hold `\`, but no word can end with it.
1706* **Scripts**: use a `.cmd` or `.bat` file, which Desktop runs through `cmd.exe`. Even in quotes, the file's path can't hold `&`, `^`, or `;`. In a file that you write, read the arguments with `%*`, because `%1` to `%9` split an argument at `,` and `=`.
1707* **Environment**: the program gets the Desktop app's environment variables, not a shell profile's. After you change a variable, quit and reopen Desktop.
1708* **Test**: to see the output that Desktop reads, run the command in Command Prompt. Put a path that has a space in double quotes and use `NUL` for no input, as in `"C:\Program Files\Acme\acme-dev.exe" create < NUL > host.txt`. The file has to hold only the host. The test makes a machine too, so delete it with your tool afterward.
1709
1710##### Wrap a Windows tool that prints other lines
1711
1712If your tool prints other lines before the host, such as progress messages, wrap it in a batch file that prints only the host. The following file prints the last line of your tool's output, and exits with your tool's code if it fails:
1713
1714```batch make-devbox.cmd theme={null}
1715@echo off
1716setlocal
1717set "host="
1718set "out=%TEMP%\acme-dev-%RANDOM%.txt"
1719call "C:\Program Files\Acme\acme-dev.exe" create > "%out%"
1720set "code=%ERRORLEVEL%"
1721for /f "usebackq delims=" %%L in ("%out%") do set "host=%%L"
1722del "%out%"
1723if not "%code%"=="0" exit /b %code%
1724setlocal EnableDelayedExpansion
1725echo(!host!
1726```
1727
1728Set `command` to the file's full path, such as `C:\\tools\\make-devbox.cmd` in JSON. Keep its last two lines as they are, because they print the host without running it as a command.
1729
16791730##### Connect to a new host
16801731
16811732Answer two questions the first time you connect to each new host:
16821733
1683* **Host key**: with OpenSSH's default host key checking, check the key's fingerprint, then choose whether to connect. To skip the question, have your command add the key to `~/.ssh/known_hosts` before it prints the host, using a key that your tool learned when it made the machine. For a port other than 22, that line starts with `[host]:port`. If your tool reuses host names, remove the old key's line too.
1734* **Host key**: with OpenSSH's default host key checking, check the key's fingerprint, then choose whether to connect. To skip the question, have your command add the key to `~/.ssh/known_hosts`, or `%USERPROFILE%\.ssh\known_hosts` on Windows, before it prints the host:
1735 * Use a key that your tool learned when it made the machine
1736 * For a port other than 22, start the line with `[host]:port`
1737 * If your tool reuses host names, remove the old key's line too
16841738* **Folder**: choose whether you trust the folder that you open there
16851739
16861740Keep host key checking on for these hosts, and keep a `known_hosts` file for them. If `StrictHostKeyChecking` is `no` or `accept-new` and `UserKnownHostsFile` is also `/dev/null` or `none`, nothing records the key. When your tool then reuses a name, you can connect to a different machine without a warning.
from line 1796
17421796
17431797* **Where to put the key**: if your MDM policy for Claude Code already sets a [policy key](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources), put it there. Otherwise, put it in the managed settings file. By default, such a policy outranks the file, and Desktop then ignores entries in the file. Set it on the computer even where [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) apply: Desktop ignores the key there, and in project and local settings.
17441798* **The `id`**: if a user's `sshHostCommands` entry has your `id`, only yours works. If any other SSH connection has it, such as one in a user's `sshConfigs`, your entry is gray. Pick an `id` that users are unlikely to choose.
1745* **The program**: give its full path, because Desktop looks up a bare name on each user's own `PATH`. The program runs as the user, with the variables that their login shell exports.
1799* **The program**: give its full path, because on macOS and Linux Desktop looks up a bare name on each user's `PATH`, and on Windows an entry with a bare name is gray. The program runs as the user, with [that user's variables](#write-the-command).
1800* **Each platform**: deploy one entry to Windows computers and another to macOS and Linux computers. An entry with a [Windows path](#write-the-command-on-windows) is gray on macOS and Linux, and one with a macOS or Linux path is gray on Windows.
17461801* **Users' own entries**: Desktop treats a user's entry like a [hook](https://code.claude.com/docs/en/hooks.md), because both run a program on the computer. To allow only your entries, set [`strictPluginOnlyCustomization`](https://code.claude.com/docs/en/settings-reference#strictpluginonlycustomization) to `["hooks"]`, or add `"hooks"` to its list. You also stop Claude Code hooks from user, project, and local settings, with no way to keep them. If you set that key or [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) to `true` instead, you block more, as each key's entry lists.
17471802* **Every entry**: to turn off your entries too, set [`disableAllHooks`](https://code.claude.com/docs/en/settings-reference#disableallhooks) in managed settings. If you set [`disableDesktopLocalSessions`](https://code.claude.com/docs/en/settings-reference#disabledesktoplocalsessions), or an `sshHostAllowlist` that allows no host, the selector lists no **Create** or **Create another** items.
17481803* **Where the locks count**: for these entries, Desktop reads `allowManagedHooksOnly`, `strictPluginOnlyCustomization`, and `disableAllHooks` from server-managed settings and from the computer's own file or policy, and applies the stricter result. Every entry stays gray until Desktop has checked claude.ai for server-managed settings, even if your organization has none.
from line 1810
17551810The environment selector lists no **Create** or **Create another** item in these cases:
17561811
17571812* **The file**: `~/.claude/settings.json` has [invalid JSON or a value that the schema rejects](https://code.claude.com/docs/en/settings.md#fix-a-broken-settings-file), you misspelled the key, or you put it in a project's settings. Fix the file.
1758* **Platform and account**: you use Windows, or a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md) instead of a Claude account. Add each host as an [SSH connection](#ssh-sessions) yourself.
1813* **Account**: you use a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md) instead of a Claude account. Add each host as an [SSH connection](#ssh-sessions) yourself.
1814* **Windows**: Desktop is older than v4.16336.0, or it doesn't connect through the OpenSSH client. Update Desktop and meet [the requirements for the OpenSSH client](#use-your-ssh-configuration), then quit and reopen Desktop.
17591815* **Your organization's settings**: your administrator turned off local sessions, or turned off SSH sessions. Ask them whether you can use commands.
17601816* **No `ssh` program**: Desktop couldn't start the OpenSSH client on your computer. Install it, or ask your administrator to allow it, then restart Desktop.
17611817
17621818An entry that you can't select is gray. Hover over it to see the reason:
17631819
1764* **A mistake in the entry**: fix the field or the command that the message names. If the `id` is in use, give the entry another one.
1820* **A mistake in the entry**: fix the field or the command that the message names. If the `id` is in use, give the entry another one. On Windows, the command has to [start with the program's full path](#write-the-command-on-windows).
17651821* **A broken settings file**: while your own settings file is broken, your administrator's entries may be gray, with a message that names the file. [Fix the file](https://code.claude.com/docs/en/settings.md#fix-a-broken-settings-file).
17661822* **A new host**: [**Create another**](#create-another-machine) is gray for one minute after Desktop saves a host. Select it after that minute. Before Claude Desktop v4.4212.0, **Replace Dev box's host** is gray for 10 minutes.
17671823* **Hooks are off or restricted**: your own entries work only where your own hooks can run. Remove `disableAllHooks` from your settings, or ask your administrator.
from line 1992
19361992| `disableMobileSimulatorTools` | set to `true` to block Claude's tools for controlling and capturing devices in the [iOS Simulator pane](https://code.claude.com/docs/en/desktop-ios-simulator.md#turn-off-simulator-access). The pane stays usable for the user's own taps; only Claude's access is removed. The value must be the JSON boolean `true`; the string `"true"` is ignored. |
19371993| `disableBrowserExternalNavigation` | set to `true` to turn off external browsing in the [Browser pane](#browse-external-sites) entirely. Neither users nor Claude can navigate to external sites, and localhost dev server previews are unaffected. The value must be the JSON boolean `true`; the string `"true"` is ignored. |
19381994| `sshConfigs` | pre-configure [SSH connections](#pre-configure-ssh-connections-for-your-team) that appear in the environment selector. Users can't delete managed connections or edit anything but their own **Worktree folder**. |
1939| `sshHostCommands` | give users [SSH connections whose host comes from a command](#distribute-commands-to-your-team), alongside their own. Desktop reads it from the managed settings file or MDM policy on the computer, and ignores it in [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md). Requires Claude Desktop v3.6556.0 or later on macOS or Linux, signed in with a Claude account. |
1995| `sshHostCommands` | give users [SSH connections whose host comes from a command](#distribute-commands-to-your-team), alongside their own. Desktop reads it from the managed settings file or MDM policy on the computer, and ignores it in [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md). Requires Claude Desktop v3.6556.0 or later on macOS or Linux, or v4.16336.0 or later on Windows, signed in with a Claude account. On Windows, Desktop also has to [connect through the OpenSSH client](#use-your-ssh-configuration). |
19401996| `sshHostAllowlist` | restrict [SSH sessions](#restrict-which-ssh-hosts-users-can-connect-to) to hosts whose resolved hostname matches one of these patterns. Read from managed settings only. |
19411997| `disableDesktopLocalSessions` | set to `true` to turn off [Code sessions that run on the device](#local-sessions-on-managed-devices), leaving SSH sessions to other hosts and cloud sessions available. The value must be the JSON boolean `true`. Read from managed settings only. Requires Claude Desktop v1.37937.0 or later. |
19421998| `disableSshSavedPasswords` | set to `true` to stop Desktop from offering to remember SSH passwords and from using or showing the ones it saved earlier. Turning it on doesn't delete them. Read from managed settings only. Requires Claude Desktop v1.49585.0 or later. |
plugins/mods/reference Changed · +9 / -3 lines
from line 150
150150| Event | Fires when | A hook can return |
151151| :- | :- | :- |
152152| `agent.offer` | A subagent type is offered to Claude | `{ isOffered: false }` to withhold it |
153| `agent.spawn` | A subagent or an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate is about to start. For a teammate, `e.isTeammate` is `true`. | `next({ ...e, model })` to choose its model, or `{ deny: reason }` |
153| `agent.spawn` | A subagent or an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate is about to start, or a subagent that finished or stopped is about to run again. For a teammate, `e.isTeammate` is `true`. For a resumed run, `e.resume` is set. | `next({ ...e, model })` to choose the model of one that is starting, or `{ deny: reason }` |
154154
155When Claude resumes a subagent with the [`SendMessage`](https://code.claude.com/docs/en/sub-agents#resume-subagents) tool, your `agent.spawn` hook doesn't run again. To refuse the `SendMessage` calls that resume a subagent, match that tool in a [`tool.call`](https://code.claude.com/docs/en/plugins/mods/events#guard-or-change-a-tool-call) hook.
155Your `agent.spawn` hook also runs when a subagent that finished or stopped is about to run again, such as when Claude sends it a message with the [`SendMessage`](https://code.claude.com/docs/en/sub-agents#resume-subagents) tool. On that event, `e.resume` is `{ agentId }`. If your hook counts subagents, skip the events where `e.resume` is set, so a resumed subagent isn't counted again.
156
157Return `{ deny: reason }` to refuse a resumed run. The run doesn't start, and the subagent stays as it was. When a `SendMessage` call asked for the run, Claude reads `a plugin declined the resume:` followed by your reason as that call's result. If you pass a changed event to `next` for a resumed run, such as a different `model`, Claude Code ignores the change.
158
159> [!NOTE]
160>
161> The event for a resumed run requires Claude Code v2.1.299 or later. Before v2.1.299, your `agent.spawn` hook didn't run when a subagent resumed. On those versions, to refuse the `SendMessage` calls that resume a subagent, match that tool in a [`tool.call`](https://code.claude.com/docs/en/plugins/mods/events#guard-or-change-a-tool-call) hook.
156162
157163### Interface
158164
sandboxing Changed · +60 / -28 lines
#### Add an AppArmor profile for bubblewrap ### Ubuntu's AppArmor restriction stops bubblewrap ### Sandboxed commands fail with `bwrap: setting up uid map: Permission denied`
from line 67
6767* **Overrides**: choose whether commands that fail under the sandbox can fall back to running unsandboxed. This is the [`allowUnsandboxedCommands`](https://code.claude.com/docs/en/settings-reference#sandbox-allowunsandboxedcommands) setting
6868* **Config**: view the resolved sandbox settings
6969
70If the panel shows only a Dependencies tab, a required package is missing. Install it as described in [Set up Linux and WSL2](#set-up-linux-and-wsl2), restart Claude Code, and run `/sandbox` again.
70If the panel shows only a Dependencies tab, the sandbox can't start yet. Fix what the tab reports as described in [Set up Linux and WSL2](#set-up-linux-and-wsl2), restart Claude Code, and run `/sandbox` again.
7171
7272**2. Choose a mode**
7373
from line 93
9393
9494> [!WARNING]
9595>
96> By default, if the sandbox can't start because a dependency is missing or the platform is unsupported, Claude Code runs commands without sandboxing. To make Claude Code exit at startup instead, set [`sandbox.failIfUnavailable`](https://code.claude.com/docs/en/settings-reference#sandbox-failifunavailable) to `true`. Managed deployments that require sandboxing as a security gate can use this setting.
96> By default, when the platform doesn't support the sandbox or the dependency check at startup fails, Claude Code runs commands without sandboxing. To make Claude Code exit at startup instead, set [`sandbox.failIfUnavailable`](https://code.claude.com/docs/en/settings-reference#sandbox-failifunavailable) to `true`. Managed deployments that require sandboxing as a security gate can use this setting.
9797
9898### Confirm commands run inside the sandbox
9999
from line 131
131131
132132Ripgrep is bundled with the native Claude Code binary. The seccomp filter is optional and adds Unix domain socket blocking. Install it with `npm install -g @anthropic-ai/sandbox-runtime` if it is missing.
133133
134When a required dependency is missing, the Dependencies tab is the only tab shown until you install it. When only the optional seccomp filter is missing, the Dependencies tab appears alongside the other tabs. The dependency check runs at startup, so restart Claude Code after installing packages for `/sandbox` to detect them.
134* **Dependencies is the only tab**: the sandbox can't start. Install what the tab lists as missing, or if it reports Ubuntu's AppArmor restriction, [add an AppArmor profile for bubblewrap](#add-an-apparmor-profile-for-bubblewrap)
135* **Dependencies appears beside the other tabs**: the tab lists a missing optional item, such as the seccomp filter. The sandbox can start without it, so install it only if you want what it adds
135136
136> [accordion] Ubuntu 24.04 and later: allow bubblewrap to create user namespaces
137>
138> On Ubuntu 24.04 and later, the default AppArmor policy prevents bubblewrap from creating the user namespaces it needs for isolation.
139>
140> To check whether your environment enforces this restriction, including inside WSL2, run `sysctl kernel.apparmor_restrict_unprivileged_userns`. If the command returns `0`, skip this step. If it prints a `No such file or directory` error, the key doesn't exist and you can skip this step. If it returns `1`, add an AppArmor profile that grants `bwrap` this capability:
141>
142> ```bash theme={null}
143> sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
144> abi <abi/4.0>,
145> include <tunables/global>
146>
147> profile bwrap /usr/bin/bwrap flags=(unconfined) {
148> userns,
149> include if exists <local/bwrap>
150> }
151> EOF
152> ```
153>
154> The profile applies only to `bwrap` itself, not to the commands it runs inside the sandbox. Reload AppArmor to apply it:
155>
156> ```bash theme={null}
157> sudo systemctl reload apparmor
158> ```
137The dependency check runs at startup, so restart Claude Code after installing packages for `/sandbox` to detect them.
159138
160139> [accordion] WSL2 notes
161140>
from line 142
163142>
164143> On WSL2, WSL hands a launch of a Windows binary such as `cmd.exe`, `powershell.exe`, or anything under `/mnt/c/` to the Windows host over a Unix socket, so whether a sandboxed command can launch one follows the sandbox's [Unix-socket settings](https://code.claude.com/docs/en/settings-reference.md#sandbox-network-allowunixsockets): the optional seccomp filter has to be installed to block the socket in the first place. To allow these launches, set `allowAllUnixSockets`, which opens every Unix socket to sandboxed commands.
165144
145#### Add an AppArmor profile for bubblewrap
146
147Add the profile if Claude Code runs `/usr/bin/bwrap` and either of these happens:
148
149* Claude Code [reports Ubuntu's AppArmor restriction on user namespaces](#apparmor-restriction-stops-bubblewrap)
150* Sandboxed commands fail with `bwrap: setting up uid map: Permission denied` or `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` while [that restriction is on](#bwrap-uid-map-permission-denied)
151
152Claude Code runs the first `bwrap` on `PATH`, unless managed settings name one in [`sandbox.bwrapPath`](https://code.claude.com/docs/en/settings-reference#sandbox-bwrappath). To see which `bwrap` is first, run `which bwrap` in the shell you start Claude Code from. If Claude Code runs any path other than `/usr/bin/bwrap`, [lift the restriction with `sysctl`](#apparmor-restriction-stops-bubblewrap) instead.
153
154To add the profile for `/usr/bin/bwrap`, run this command:
155
156```bash theme={null}
157sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
158abi <abi/4.0>,
159include <tunables/global>
160
161profile bwrap /usr/bin/bwrap flags=(unconfined) {
162 userns,
163 include if exists <local/bwrap>
164}
165EOF
166```
167
168Reload AppArmor to apply it:
169
170```bash theme={null}
171sudo systemctl reload apparmor
172```
173
174Then restart Claude Code and [confirm the sandbox works](#confirm-commands-run-inside-the-sandbox).
175
166176### Sandbox modes
167177
168178Claude Code offers two sandbox modes. In both, the sandbox enforces the same filesystem and network restrictions; the difference is only in whether sandboxed commands are auto-approved or require explicit permission.
from line 722
712722
713723The two keys beyond `enabled` control what happens when the sandbox cannot run a command:
714724
715* **`failIfUnavailable`**: a missing dependency such as bubblewrap on Linux blocks Claude Code from starting rather than falling back to unsandboxed execution
725* **`failIfUnavailable`**: when the platform doesn't support the sandbox or the dependency check at startup fails, Claude Code refuses to start rather than falling back to unsandboxed execution
716726* **`allowUnsandboxedCommands: false`**: Claude Code ignores the `dangerouslyDisableSandbox` escape hatch, so when a command fails under the sandbox, Claude can't retry it unsandboxed
717727
718728Consider these additions alongside them:
from line 907
897907### Bubblewrap fails to start inside a container
898908
899909In an unprivileged container, [bubblewrap](#os-level-enforcement) can't mount a fresh `/proc` filesystem, so sandboxed commands fail with a `bwrap` error such as `Can't mount proc on /newroot/proc: Operation not permitted`. Set [`enableWeakerNestedSandbox`](https://code.claude.com/docs/en/settings-reference#sandbox-enableweakernestedsandbox) to `true` so the sandbox bind-mounts the container's existing `/proc` instead. Only use this setting when the outer container already provides the isolation boundary you need, since the setting exposes process information to sandboxed commands that a fresh `/proc` mount would hide.
910
911### Ubuntu's AppArmor restriction stops bubblewrap
912
913On Linux and WSL2, the message `Ubuntu's AppArmor restriction on user namespaces stops bubblewrap here` means that Ubuntu's AppArmor restriction keeps the sandbox from starting.
914
915To get the sandbox to start, lift the restriction in one of these two ways:
916
917* [Add an AppArmor profile for bubblewrap](#add-an-apparmor-profile-for-bubblewrap) if Claude Code runs `/usr/bin/bwrap`
918* In your shell, run `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, which lifts the restriction for every program on the machine and lasts until you reboot
919
920Then restart Claude Code and [confirm the sandbox works](#confirm-commands-run-inside-the-sandbox).
921
922Until you lift the restriction, commands run without the sandbox under the regular permission flow, or Claude Code refuses to start if [`sandbox.failIfUnavailable`](https://code.claude.com/docs/en/settings-reference#sandbox-failifunavailable) is `true`.
923
924### Sandboxed commands fail with `bwrap: setting up uid map: Permission denied`
925
926On Linux and WSL2, this error or `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` can mean that Ubuntu's AppArmor restriction on user namespaces is stopping bubblewrap. To check, run `sysctl kernel.apparmor_restrict_unprivileged_userns` in your shell:
927
928* `kernel.apparmor_restrict_unprivileged_userns = 1`: the restriction is on. [Add an AppArmor profile](#add-an-apparmor-profile-for-bubblewrap) if Claude Code runs `/usr/bin/bwrap`, or run `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, which lifts it for every program until you reboot. Then restart Claude Code and [confirm the sandbox works](#confirm-commands-run-inside-the-sandbox)
929* Any other output: the restriction isn't the cause. To report the failure, run [`/feedback`](https://code.claude.com/docs/en/commands#all-commands) at the Claude Code prompt
930
931Before v2.1.310, Claude Code didn't check for this restriction at startup, so `/sandbox` didn't report it.
900932
901933### 0-byte read-only files appear at `.claude` settings paths, and "Yes, and don't ask again" doesn't save
902934
settings-reference Changed · +11 / -7 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 36
3636| [`autoCompactWindow`](#autocompactwindow) | Set how full the context gets before Claude Code [compacts](https://code.claude.com/docs/en/context-window.md) | Memory and context | Any file |
3737| [`autoConnectIde`](#autoconnectide) | Connect to a running [VS Code](https://code.claude.com/docs/en/vs-code.md) or [JetBrains](https://code.claude.com/docs/en/jetbrains.md#from-external-terminals) IDE automatically from an external terminal | Global config settings | Global config |
3838| [`autoContinueAtUsageLimit`](#autocontinueatusagelimit) | Wait in the open session and [continue the task automatically](https://code.claude.com/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset) after a claude.ai usage limit resets | Interface and terminal | User or managed |
39| [`autoInstallIdeExtension`](#autoinstallideextension) | Turn off automatic install of the [IDE extension](https://code.claude.com/docs/en/vs-code.md#install-the-extension) from a VS Code terminal | Global config settings | Global config |
39| [`autoInstallIdeExtension`](#autoinstallideextension) | Let `/ide` install the [IDE extension](https://code.claude.com/docs/en/vs-code.md#install-the-extension) from an external terminal | Global config settings | Global config |
4040| [`autoMemoryDirectory`](#automemorydirectory) | Store [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) in a directory you choose | Memory and context | Any file |
4141| [`autoMemoryEnabled`](#automemoryenabled) | Turn [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) off or on | Memory and context | Any file |
4242| [`autoMode`](#automode) | Add your own allow and deny rules to the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier | Permission settings | User or managed |
from line 1263
12631263
12641264### `sandbox.failIfUnavailable`
12651265
1266Make Claude Code exit with an error at startup when `sandbox.enabled` is `true` but the sandbox can't start, because a dependency is missing or the platform is unsupported. Without this key, Claude Code runs commands unsandboxed. Managed deployments that require sandboxing as a security gate can use this setting.
1266Make Claude Code exit with an error at startup when `sandbox.enabled` is `true` but the sandbox can't start because the platform doesn't support it or the dependency check fails. Without this key, Claude Code runs commands unsandboxed. Managed deployments that require sandboxing as a security gate can use this setting.
12671267
12681268On a platform the sandbox doesn't support, Claude Code doesn't start with this key on. See [Enforce sandboxing with managed settings](https://code.claude.com/docs/en/sandboxing.md#enforce-sandboxing-with-managed-settings).
12691269
from line 3398
33983398
33993399To hide all attribution, set `attribution` to `false`. In a settings file that earlier versions also read, set [`commit`](#attribution-commit) and [`pr`](#attribution-pr) to empty strings and [`sessionUrl`](#attribution-sessionurl) to `false` instead.
34003400
3401This example replaces the commit attribution, removes pull request attribution, and
3401This example replaces the commit attribution, removes pull request attribution, and dr
vs-code Changed · +7 / -2 lines
from line 814
814814
815815### Run CLI in VS Code
816816
817To use the CLI while staying in VS Code, press `` Ctrl+` `` on Windows/Linux or `` Cmd+` `` on Mac to open the integrated terminal, then run `claude`. The CLI automatically integrates with your IDE for features like diff viewing and diagnostic sharing. If you use an external terminal, run `/ide` inside Claude Code to connect it to VS Code.
817To use the CLI while staying in VS Code, press `` Ctrl+` `` on Windows/Linux or `` Cmd+` `` on Mac to open the integrated terminal, then run `claude`. Starting `claude` doesn't install the extension. Without it, `/ide` in the integrated terminal reports "No available IDEs detected" and `/status` shows the IDE as "Not connected".
818818
819To get features like diff viewing and diagnostic sharing, connect the CLI to the extension from the integrated terminal or an external terminal:
820
821* **Integrated terminal**: [install the extension](#install-the-extension), then start `claude`. The CLI connects automatically.
822* **External terminal**: run `/ide` inside Claude Code to connect to VS Code. If VS Code is running without the extension, `/ide` installs it, unless you turned off [`autoInstallIdeExtension`](https://code.claude.com/docs/en/settings-reference#autoinstallideextension).
823
819824Installing the extension does not put `claude` on your shell PATH. The extension bundles a private copy of the CLI for its chat panel, but typing `claude` in a terminal requires the [standalone CLI install](https://code.claude.com/docs/en/setup.md). Run the install once and the commands on this page, including `claude mcp add` and `claude --resume`, work in any terminal. If `claude` is still not found after installing, [verify your PATH](https://code.claude.com/docs/en/troubleshoot-install.md#verify-your-path).
820825
821826### Switch between extension and CLI
from line 1087
108210872. Search for "Claude Code"
108310883. Click **Uninstall**
10841089
1085If you run `claude` in a VS Code integrated terminal, Claude Code reinstalls the extension automatically. To keep it uninstalled, turn off **Auto-install IDE extension** in `/config`, or set [`autoInstallIdeExtension`](https://code.claude.com/docs/en/settings-reference#autoinstallideextension) to `false`. You can also set the [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](https://code.claude.com/docs/en/env-vars) environment variable to `1`.
1090The extension stays uninstalled when you start `claude`. If you run `/ide` from an external terminal while VS Code is running, Claude Code reinstalls it. To stop that, set [`autoInstallIdeExtension`](https://code.claude.com/docs/en/settings-reference#autoinstallideextension) to `false` in `~/.claude.json`, or turn off **Auto-install IDE extension** in `/config` from the integrated terminal. You can also set the [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](https://code.claude.com/docs/en/env-vars) environment variable to `1`.
10861091
10871092To also remove extension data and reset all settings, delete the extension's storage directory for your platform.
10881093
claude-tag Changed · +1 / -1 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.
errors Changed · +2 / -0 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 453
453453| `is ignored — managed settings set allowManagedReadPathsOnly` / `is ignored — managed settings set allowManagedDomainsOnly` | [Configuration warnings](#sandbox-allow-entries-are-ignored-under-a-managed-lock) |
454454| `Sandbox mask files left behind at write-deny paths` | [Configuration warnings](#stale-sandbox-mask-files-left-by-a-killed-session) |
455455| `Stale sandbox mask files left by a killed session` | [Configuration warnings](#stale-sandbox-mask-files-left-by-a-killed-session) |
456| `Ubuntu's AppArmor restriction on user namespaces stops bubblewrap here` | [Sandboxing troubleshooting](https://code.claude.com/docs/en/sandboxing.md#apparmor-restriction-stops-bubblewrap) |
457| `bwrap: setting up uid map: Permission denied` / `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` | [Sandboxing troubleshooting](https://code.claude.com/docs/en/sandboxing.md#bwrap-uid-map-permission-denied) |
456458| Responses seem lower quality than usual | [Response quality](#responses-seem-lower-quality-than-usual) |
457459
458460## Automatic retries
from line 2510
25082510* If the message contains `context_management: Extra inputs are not permitted`, [update Claude Code](https://code.claude.com/docs/en/setup.md#update-claude-code) to v2.1.304 or later. After you update, Claude Code answers this rejection by sending the request once more without the field. Before v2.1.304, Claude Code didn't retry this rejection.
25092511* If the message names `defer_loading` or `tool_reference`, [update Claude Code](https://code.claude.com/docs/en/setup.md#update-claude-code) to v2.1.305 or later. Claude Code then answers this rejection by [sending the request once more](https://code.claude.com/docs/en/llm-gateway-protocol.md#retry-without-tool-search) without tool search fields.
25102512* If your gateway drops the header, configure it to forward the `anthropic-beta` header. See [feature pass-through](https://code.claude.com/docs/en/llm-gateway-protocol.md#feature-pass-through) for what gateways must forward.
2511* As a fallback, set [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](https://code.claude.com/docs/en/env-vars) before launching. [Disable pre-release capabilities](https://code.claude.com/docs/en/llm-gateway-protocol.md#disable-pre-release-capabilities) covers the exact scope.
2512
2513Before v2.1.302, this error could also name the field `diagnostics` with no gateway involved. It appeared when a session that had already used the Anthropic API moved to Amazon Bedrock or Google Cloud's Agent Platform without a restart. For example, a session you left open moves to Bedrock when you run [`/setup-bedrock`](https://code.
2513* As a fallback, set [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](https://code.claude.com/docs/en/env-vars) before launching. [Disable pre-release capabilities](https://code.claude.com/docs/en/