Home Docs Claude Code CLI

One capture · claude-code

One read of Claude Code CLIclaude-code-20261023T190701Z

220 pages moved out of 228 read.

Pages moved 220 significant first

Pages read 228 in this capture

Captured 23 Oct 2026 19:07 UTC

Corpus hash 7e3663570d29 corpus-hash

What this read moved

176-200 of 220, page 8 of 9

This capture is too large to show at once. Changes 176-200 of 220 are below, significant first; the rest are on the following screens.

setup Changed · +40 / -40 lines

from line 2

33> System requirements, platform-specific installation, version management, and uninstallation for Claude Code.

5This page covers system requirements, platform-specific installation details, updates, and uninstallation. For a guided walkthrough of your first session, see the [quickstart](/docs/en/quickstart.md). If you've never used a terminal before, see the [terminal guide](/docs/en/terminal-guide).

5This page covers system requirements, platform-specific installation details, updates, and uninstallation. For a guided walkthrough of your first session, see the [quickstart](https://code.claude.com/docs/en/quickstart.md). If you've never used a terminal before, see the [terminal guide](https://code.claude.com/docs/en/terminal-guide).

77## System requirements

from line 15

1515 * Debian 10+

1616 * Alpine Linux 3.19+

1717* **Hardware**: 4 GB+ RAM, x64 or ARM64 processor

18* **Network**: internet connection required. See [network configuration](/docs/en/network-config.md#network-access-requirements).

18* **Network**: internet connection required. See [network configuration](https://code.claude.com/docs/en/network-config.md#network-access-requirements).

1919* **Shell**: Bash, Zsh, PowerShell, or CMD.

2020* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)

2121

2222### Additional dependencies

2323

24* **ripgrep**: usually included with Claude Code. If search fails, see [search troubleshooting](/docs/en/troubleshooting.md#search-and-discovery-issues).

24* **ripgrep**: usually included with Claude Code. If search fails, see [search troubleshooting](https://code.claude.com/docs/en/troubleshooting.md#search-and-discovery-issues).

2525

2626## Install Claude Code

2727

2828> [!TIP]

2929>

30> Prefer a graphical interface? The [Desktop app](/docs/en/desktop-quickstart.md) lets you use Claude Code without the terminal. Download it for [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs), [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs), or [Linux](/docs/en/desktop-linux.md).

30> Prefer a graphical interface? The [Desktop app](https://code.claude.com/docs/en/desktop-quickstart.md) lets you use Claude Code without the terminal. Download it for [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs), [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs), or [Linux](https://code.claude.com/docs/en/desktop-linux.md).

3131

32To install Claude Code, open a terminal and run the command for your system. If you haven't used a terminal before, the [terminal guide](/docs/en/terminal-guide) shows how to open one and paste the command.

32To install Claude Code, open a terminal and run the command for your system. If you haven't used a terminal before, the [terminal guide](https://code.claude.com/docs/en/terminal-guide) shows how to open one and paste the command.

3333

3434**Native Install (Recommended)**

3535

from line 53

5353curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

5454```

5555

56The install command shows no progress while it downloads Claude Code. When the installer finishes, open a new terminal window and run `claude --version`. A working installation prints a version number. If your shell says `claude` isn't found or isn't recognized, the install directory isn't on your PATH yet: see [Fix your PATH](/docs/en/troubleshoot-install.md#command-not-found-claude-after-installation).

56The install command shows no progress while it downloads Claude Code. When the installer finishes, open a new terminal window and run `claude --version`. A working installation prints a version number. If your shell says `claude` isn't found or isn't recognized, the install directory isn't on your PATH yet: see [Fix your PATH](https://code.claude.com/docs/en/troubleshoot-install.md#command-not-found-claude-after-installation).

5757

5858If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell.

5959

60If the install command fails with `syntax error near unexpected token '<'`, a `403`, or any other error, see [Troubleshoot installation](/docs/en/troubleshoot-install.md#find-your-error) to match the error to a fix and for alternative install methods.

60If the install command fails with `syntax error near unexpected token '<'`, a `403`, or any other error, see [Troubleshoot installation](https://code.claude.com/docs/en/troubleshoot-install.md#find-your-error) to match the error to a fix and for alternative install methods.

6161

6262[Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.

6363

from line 87

8787>

8888> WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.

8989

90You can also install with [apt, dnf, or apk](/docs/en/setup.md#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.

90You can also install with [apt, dnf, or apk](https://code.claude.com/docs/en/setup.md#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.

9191

9292After installation completes, open a terminal in the project you want to work in and start Claude Code:

9393

from line 97

9797

9898Claude Code opens an interactive session in your terminal.

9999

100If you encounter any issues during installation, see [Troubleshoot installation and login](/docs/en/troubleshoot-install.md).

100If you encounter any issues during installation, see [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install.md).

101101

102102### Set up on Windows

103103

104104You can run Claude Code natively on Windows or inside WSL. Pick based on where your projects are located and which features you need:

105105

107107| - | - | - | - |

from line 111

111111

112112#### Install on native Windows

113113

114Run the [install command](#install-claude-code) from PowerShell or CMD. You do not need to run as Administrator. Installing [Git for Windows](https://git-scm.com/downloads/win) is optional. It provides Git Bash, which the [Bash tool](/docs/en/tools-reference.md#bash-tool-behavior) and the [Monitor tool](/docs/en/tools-reference.md#monitor-tool) need.

114Run the [install command](#install-claude-code) from PowerShell or CMD. You do not need to run as Administrator. Installing [Git for Windows](https://git-scm.com/downloads/win) is optional. It provides Git Bash, which the [Bash tool](https://code.claude.com/docs/en/tools-reference.md#bash-tool-behavior) and the [Monitor tool](https://code.claude.com/docs/en/tools-reference.md#monitor-tool) need.

115115

116Whether you install from PowerShell or CMD only affects which install command you run. Your prompt shows `PS C:\Users\YourName>` in PowerShell and `C:\Users\YourName>` without the `PS` in CMD. If you're new to the terminal, the [terminal guide](/docs/en/terminal-guide#windows) walks through each step.

116Whether you install from PowerShell or CMD only affects which install command you run. Your prompt shows `PS C:\Users\YourName>` in PowerShell and `C:\Users\YourName>` without the `PS` in CMD. If you're new to the terminal, the [terminal guide](https://code.claude.com/docs/en/terminal-guide#windows) walks through each step.

117117

118118After installation, launch `claude` from any terminal.

119119

120* **Without Git for Windows**, Claude Code runs shell commands via the [PowerShell tool](/docs/en/tools-reference.md#powershell-tool).

121* **With Git for Windows**, Claude Code uses Git Bash for the [Bash tool](/docs/en/tools-reference.md#bash-tool-behavior). If Claude Code can't find Git Bash, set the path in your [settings.json file](/docs/en/settings.md):

120* **Without Git for Windows**, Claude Code runs shell commands via the [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool).

121* **With Git for Windows**, Claude Code uses Git Bash for the [Bash tool](https://code.claude.com/docs/en/tools-reference.md#bash-tool-behavior). If Claude Code can't find Git Bash, set the path in your [settings.json file](https://code.claude.com/docs/en/settings.md):

122122

123123 ```json theme={null}

124124 {

from line 128

128128 }

129129 ```

130130

131When Git for Windows is installed, the PowerShell tool is available alongside Bash: on by default for claude.ai and Console accounts, and enabled with `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` in Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry sessions. Set it to `0` to turn the tool off. See [PowerShell tool](/docs/en/tools-reference.md#powershell-tool) for setup and limitations.

131When Git for Windows is installed, the PowerShell tool is available alongside Bash: on by default for claude.ai and Console accounts, and enabled with `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` in Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry sessions. Set it to `0` to turn the tool off. See [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) for setup and limitations.

132132

133133#### Install in WSL

134134

from line 152

152152

153153Run `apk update` to refresh the package index, and retry the `apk add` command.

154154

155Then set `USE_BUILTIN_RIPGREP` to `0` in your [`settings.json`](/docs/en/settings-reference#all-settings) file:

155Then set `USE_BUILTIN_RIPGREP` to `0` in your [`settings.json`](https://code.claude.com/docs/en/settings-reference#all-settings) file:

156156

157157```json theme={null}

158158{

from line 172

172172

173173A working installation prints a version number such as `2.1.211 (Claude Code)`.

174174

175If this fails with `command not found` or another error, see [Troubleshoot installation and login](/docs/en/troubleshoot-install.md).

175If this fails with `command not found` or another error, see [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install.md).

176176

177For a more detailed check of your installation and configuration, run [`claude doctor`](/docs/en/troubleshooting#get-more-help):

177For a more detailed check of your installation and configuration, run [`claude doctor`](https://code.claude.com/docs/en/troubleshooting#get-more-help):

178178

179179```bash theme={null}

180180claude doctor

from line 184

184184

185185## Authenticate

186186

187Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free claude.ai plan does not include Claude Code access. You can also use Claude Code with a third-party API provider like [Amazon Bedrock](/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai.md), or [Microsoft Foundry](/docs/en/microsoft-foundry.md).

187Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free claude.ai plan does not include Claude Code access. You can also use Claude Code with a third-party API provider like [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md).

188188

189After installing, log in by running `claude` and following the browser prompts. If you've set the `ANTHROPIC_API_KEY` environment variable and you approve the key when Claude Code asks whether to use it, Claude Code skips the login prompt. See [Authentication](/docs/en/authentication.md) for all account types and team setup options.

189After installing, log in by running `claude` and following the browser prompts. If you've set the `ANTHROPIC_API_KEY` environment variable and you approve the key when Claude Code asks whether to use it, Claude Code skips the login prompt. See [Authentication](https://code.claude.com/docs/en/authentication.md) for all account types and team setup options.

190190

191191## Update Claude Code

192192

from line 196

196196

197197Claude Code checks for updates on startup and periodically while running. Updates download and install in the background, then take effect the next time you start Claude Code.

198198

199Run `claude doctor` in your shell to see the result of the last update attempt Claude Code recorded. On a native installation, if it reports a failed attempt, see [`Auto-update failed` in the session footer](/docs/en/troubleshoot-install#auto-update-failed) for what to do next.

199Run `claude doctor` in your shell to see the result of the last update attempt Claude Code recorded. On a native installation, if it reports a failed attempt, see [`Auto-update failed` in the session footer](https://code.claude.com/docs/en/troubleshoot-install#auto-update-failed) for what to do next.

200200

201201On macOS and Linux, the native installer manages the launcher at `~/.local/bin/claude` as a symlink into `~/.local/share/claude/versions/`. If you replace that launcher with your own script or symlink, auto-update and `claude update` leave it in place: new versions still install under the `versions/` directory, and your launcher decides which version runs.

202202

from line 204

204204

205205To let Claude Code manage the launcher again, remove `~/.local/bin/claude` and run `claude update`.

206206

207If an npm global install can't auto-update because the npm global directory isn't writable, Claude Code shows a one-time notice at startup, and `claude doctor` lists the available fixes. See [permission errors during installation](/docs/en/troubleshoot-install.md#permission-errors-during-installation) for details.

207If an npm global install can't auto-update because the npm global directory isn't writable, Claude Code shows a one-time notice at startup, and `claude doctor` lists the available fixes. See [permission errors during installation](https://code.claude.com/docs/en/troubleshoot-install.md#permission-errors-during-installation) for details.

208208

209209> [!NOTE]

210210>

211211> Homebrew, WinGet, apt, dnf, and apk installations do not auto-update by default; see below to opt in for Homebrew and WinGet. To upgrade Homebrew manually, run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed. For WinGet, run `winget upgrade Anthropic.ClaudeCode`. For Linux package managers, see the upgrade commands in [Install with Linux package managers](#install-with-linux-package-managers).

212212>

213> To have Claude Code run the upgrade command for you on Homebrew or WinGet, set [`CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE`](/docs/en/env-vars) to `1`. Claude Code then runs the upgrade in the background when a new version is available and shows a restart prompt on success. The upgrade targets only the Claude Code package and does not affect other software you have installed.

213> To have Claude Code run the upgrade command for you on Homebrew or WinGet, set [`CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE`](https://code.claude.com/docs/en/env-vars) to `1`. Claude Code then runs the upgrade in the background when a new version is available and shows a restart prompt on success. The upgrade targets only the Claude Code package and does not affect other software you have installed.

214214>

215215> On WinGet the upgrade may fail while Claude Code is running because Windows locks the executable. In that case Claude Code shows the manual command instead. apt, dnf, and apk continue to require a manual upgrade because those commands need elevated privileges.

216216>

from line 225

225225* `"latest"`, the default: receive new features as soon as they're released

226226* `"stable"`: use a version that is typically about one week old, skipping releases with major regressions

227227

228Configure this via `/config` → **Auto-update channel**, or add it to your [settings.json file](/docs/en/settings.md):

228Configure this via `/config` → **Auto-update channel**, or add it to your [settings.json file](https://code.claude.com/docs/en/settings.md):

229229

230230```json theme={null}

231231{

from line 235

235235

236236A newly launched model can require a Claude Code version newer than the stable channel serves. To run the model now, move to the latest channel.

237237

238For enterprise deployments, you can enforce a consistent release channel across your organization using [managed settings](/docs/en/managed-settings.md).

238For enterprise deployments, you can enforce a consistent release channel across your organization using [managed settings](https://code.claude.com/docs/en/managed-settings.md).

239239

240240Homebrew installations choose a channel by cask name instead of this setting: `claude-code` tracks stable and `claude-code@latest` tracks latest.

241241

from line 247

247247

248248Switching from `"latest"` to `"stable"` via `/config` prompts you to either stay on the current version or allow the downgrade. Choosing to stay sets `minimumVersion` to that version. Switching back to `"latest"` clears it.

249249

250Add it to your [settings.json file](/docs/en/settings.md) to pin a floor explicitly:

250Add it to your [settings.json file](https://code.claude.com/docs/en/settings.md) to pin a floor explicitly:

251251

252252```json theme={null}

253253{

from line 256

256256}

257257```

258258

259In [managed settings](/docs/en/managed-settings.md), this enforces an organization-wide minimum that user and project settings cannot override.

259In [managed settings](https://code.claude.com/docs/en/managed-settings.md), this enforces an organization-wide minimum that user and project settings cannot override.

260260

261The `minimumVersion` pin only constrains updates. To make Claude Code refuse to start outside a version range, use the managed settings `requiredMinimumVersion` and `requiredMaximumVersion` instead. Updates also respect the `requiredMaximumVersion` ceiling. See [`requiredMinimumVersion`](/docs/en/settings-reference#requiredminimumversion) and [`requiredMaximumVersion`](/docs/en/settings-reference#requiredmaximumversion).

261The `minimumVersion` pin only constrains updates. To make Claude Code refuse to start outside a version range, use the managed settings `requiredMinimumVersion` and `requiredMaximumVersion` instead. Updates also respect the `requiredMaximumVersion` ceiling. See [`requiredMinimumVersion`](https://code.claude.com/docs/en/settings-reference#requiredminimumversion) and [`requiredMaximumVersion`](https://code.claude.com/docs/en/settings-reference#requiredmaximumversion).

262262

263263### Disable auto-updates

264264

265Set `DISABLE_AUTOUPDATER` to `"1"` in the `env` key of your [`settings.json`](/docs/en/settings-reference#all-settings) file:

265Set `DISABLE_AUTOUPDATER` to `"1"` in the `env` key of your [`settings.json`](https://code.claude.com/docs/en/settings-reference#all-settings) file:

266266

267267```json theme={null}

268268{

from line 274

274274

275275On a native or npm installation, confirm the change took effect by running `claude doctor` and checking that the `Auto-updates` line shows `disabled (set by env: DISABLE_AUTOUPDATER)` instead of `enabled`.

276276

277`DISABLE_AUTOUPDATER` only stops the background check; `claude update` and `claude install` still work. To block all update paths, including manual updates, set [`DISABLE_UPDATES`](/docs/en/env-vars) instead. Use this when you distribute Claude Code through your own channels and need users to stay on the version you provide.

277`DISABLE_AUTOUPDATER` only stops the background check; `claude update` and `claude install` still work. To block all update paths, including manual updates, set [`DISABLE_UPDATES`](https://code.claude.com/docs/en/env-vars) instead. Use this when you distribute Claude Code through your own channels and need users to stay on the version you provide.

278278

279279### Update manually

280280

from line 462

462462

463463The npm package installs the same native binary as the standalone installer. npm pulls the binary in through a per-platform optional dependency such as `@anthropic-ai/claude-code-darwin-arm64`, and a postinstall step links it into place. The installed `claude` binary does not itself invoke Node.

464464

465Supported npm install platforms are `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64`, and `win32-arm64`. Your package manager must allow optional dependencies. See [troubleshooting](/docs/en/troubleshoot-install.md#native-binary-not-found-after-npm-install) if the binary is missing after install.

465Supported npm install platforms are `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64`, and `win32-arm64`. Your package manager must allow optional dependencies. See [troubleshooting](https://code.claude.com/docs/en/troubleshoot-install.md#native-binary-not-found-after-npm-install) if the binary is missing after install.

466466

467467To upgrade an npm installation, run `npm install -g @anthropic-ai/claude-code@latest`. Avoid `npm update -g`, which respects the semver range from the original install and may not move you to the newest release.

468468

469469> [!WARNING]

470470>

471> Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks. If you encounter permission errors, see [troubleshooting permission errors](/docs/en/troubleshoot-install.md#permission-errors-during-installation).

471> Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks. If you encounter permission errors, see [troubleshooting permission errors](https://code.claude.com/docs/en/troubleshoot-install.md#permission-errors-during-installation).

472472

473473### Install on network storage

474474

from line 479

479479* **Install on local disk**: put the binary on each machine's local filesystem, for example with a [Linux package manager](#install-with-linux-package-managers) or your own deployment tooling. A per-user npm prefix and the native installer's default `~/.local/share/claude/versions/` directory both sit in the home directory.

480480* **Keep each version in its own directory**: upgrading an npm installation in place with `npm install -g` deletes the previous binary. On storage that several machines share, that removes the file that sessions on the other machines are still running. Install each new version next to the old ones and move users to it.

481481* **Delete an old version only when no machine can still be running it**: a machine can't see processes running on other machines, so checking for running processes before you delete isn't enough.

482* **Turn off Claude Code's own updates**: set [`DISABLE_UPDATES`](/docs/en/env-vars) and install new versions with your own tooling. Otherwise an auto-update of an npm installation on one machine runs the same in-place upgrade and removes the binary that sessions on other machines are running. Setting `DISABLE_AUTOUPDATER` alone isn't enough, because users can still run `claude update` and `claude install`. See [Disable auto-updates](#disable-auto-updates).

482* **Turn off Claude Code's own updates**: set [`DISABLE_UPDATES`](https://code.claude.com/docs/en/env-vars) and install new versions with your own tooling. Otherwise an auto-update of an npm installation on one machine runs the same in-place upgrade and removes the binary that sessions on other machines are running. Setting `DISABLE_AUTOUPDATER` alone isn't enough, because users can still run `claude update` and `claude install`. See [Disable auto-updates](#disable-auto-updates).

483483

484484The native installer deletes old versions from `~/.local/share/claude/versions/` on its own, which matters when that directory is on shared storage. Besides the version the launcher points to and any version a session on the same machine is running, it keeps the two newest versions and deletes the rest. A session on another machine that is running a deleted version loses its binary. With a [custom launcher](#auto-updates), Claude Code keeps every installed version and leaves cleanup to you.

485485

from line 570

570570

571571## Uninstall Claude Code

572572

573To remove Claude Code, follow the instructions for your installation method. If `claude` still runs afterward, you likely have a second installation or a leftover shell alias from an older installer. See [Check for conflicting installations](/docs/en/troubleshoot-install.md#check-for-conflicting-installations) to find and remove it.

573To remove Claude Code, follow the instructions for your installation method. If `claude` still runs afterward, you likely have a second installation or a leftover shell alias from an older installer. See [Check for conflicting installations](https://code.claude.com/docs/en/troubleshoot-install.md#check-for-conflicting-installations) to find and remove it.

574574

575575### Uninstall a native installation

576576

from line 652

652652>

653653> Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history.

654654

655The VS Code extension, the JetBrains plugin, and the Desktop app also write to `~/.claude/`. If any of them is still installed, the directory is recreated the next time it runs. To remove Claude Code completely, uninstall the [VS Code extension](/docs/en/vs-code.md#uninstall-the-extension), the JetBrains plugin, and the Desktop app before deleting these files.

655The VS Code extension, the JetBrains plugin, and the Desktop app also write to `~/.claude/`. If any of them is still installed, the directory is recreated the next time it runs. To remove Claude Code completely, uninstall the [VS Code extension](https://code.claude.com/docs/en/vs-code.md#uninstall-the-extension), the JetBrains plugin, and the Desktop app before deleting these files.

656656

657657To remove Claude Code settings and cached data:

658658

skills Changed · +147 / -147 lines

from line 8

99> [!NOTE]

1010>

11> For built-in commands like `/help` and `/compact`, and bundled skills like `/debug` and `/code-review`, see the [commands reference](/docs/en/commands.md).

11> For built-in commands like `/help` and `/compact`, and bundled skills like `/debug` and `/code-review`, see the [commands reference](https://code.claude.com/docs/en/commands.md).

1212>

1313> **Custom commands have been merged into skills.** A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy` and work the same way. Your existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to [control whether you or Claude invokes them](#control-who-invokes-a-skill), and the ability for Claude to load them automatically when relevant.

1414

from line 20

2020

2121You invoke a bundled skill the same way as any other skill, by typing `/` followed by the skill name. Claude invokes some bundled skills automatically when relevant; others, including `/verify`, run only when you invoke them, which keeps you in control of when these longer-running checks spend time and tokens.

2222

23Most bundled skills are available in every session. A few depend on a specific feature: `/workflow-authoring`, for example, is available only when [dynamic workflows](/docs/en/workflows.md) are enabled.

23Most bundled skills are available in every session. A few depend on a specific feature: `/workflow-authoring`, for example, is available only when [dynamic workflows](https://code.claude.com/docs/en/workflows.md) are enabled.

2424

25To turn bundled skills off, use the [`disableBundledSkills`](/docs/en/settings-reference#disablebundledskills) setting.

25To turn bundled skills off, use the [`disableBundledSkills`](https://code.claude.com/docs/en/settings-reference#disablebundledskills) setting.

2626

2727> [!NOTE]

2828>

29> The [`/doctor`](/docs/en/commands#all-commands) setup checkup stays typable when `disableBundledSkills` is on. To hide it, set the `DISABLE_DOCTOR_COMMAND` environment variable or a [`skillOverrides`](#override-skill-visibility-from-settings) entry of `"doctor": "off"`.

29> The [`/doctor`](https://code.claude.com/docs/en/commands#all-commands) setup checkup stays typable when `disableBundledSkills` is on. To hide it, set the `DISABLE_DOCTOR_COMMAND` environment variable or a [`skillOverrides`](#override-skill-visibility-from-settings) entry of `"doctor": "off"`.

3030

31Bundled skills are listed alongside built-in commands in the [commands reference](/docs/en/commands.md), marked **Skill** in the Purpose column.

31Bundled skills are listed alongside built-in commands in the [commands reference](https://code.claude.com/docs/en/commands.md), marked **Skill** in the Purpose column.

3232

3333### Check your setup with `/doctor`

3434

3535Run `/doctor` at the Claude Code prompt for a setup checkup that diagnoses issues and can fix them. Claude reports its findings first and asks for confirmation before changing anything. The checkup covers these areas:

3636

37* **Installation health**: duplicate or leftover installs, `PATH` problems, unparseable settings files, and whether a newer version is available on your [release channel](/docs/en/setup.md#configure-release-channel)

38* **Extensions**: unused skills, MCP servers, and plugins compared with their context cost, and slow [hooks](/docs/en/hooks.md)

39* **`CLAUDE.md` files**: local `CLAUDE.md` files that duplicate checked-in ones, checked-in [`CLAUDE.md` content Claude could derive from the codebase](/docs/en/memory#my-claude-md-is-too-large), and the always-loaded guidance that remains, which Claude offers to migrate into skills and nested `CLAUDE.md` files that load on demand

40* **Permissions**: an offer to make [auto mode](/docs/en/permissions.md#permission-modes) your default permission mode and to [pre-approve](/docs/en/permissions.md) read-only commands that you frequently deny

41* **Usage**: on a Pro, Max, Team, or Enterprise plan, the [changes `/usage` recommends](/docs/en/costs#plan-usage-breakdown) to lower your plan usage, measured over the last 7 days. Claude proposes the changes it can make itself and reports the rest as advice, such as a command for you to run. The usage check requires Claude Code v2.1.305 or later, and `/doctor` leaves it out while [Remote Control](/docs/en/remote-control.md) is connected.

38* **Extensions**: unused skills, MCP servers, and plugins compared with their context cost, and slow [hooks](https://code.claude.com/docs/en/hooks.md)

39* **`CLAUDE.md` files**: local `CLAUDE.md` files that duplicate checked-in ones, checked-in [`CLAUDE.md` content Claude could derive from the codebase](https://code.claude.com/docs/en/memory#my-claude-md-is-too-large), and the always-loaded guidance that remains, which Claude offers to migrate into skills and nested `CLAUDE.md` files that load on demand

40* **Permissions**: an offer to make [auto mode](https://code.claude.com/docs/en/permissions.md#permission-modes) your default permission mode and to [pre-approve](https://code.claude.com/docs/en/permissions.md) read-only commands that you frequently deny

41* **Usage**: on a Pro, Max, Team, or Enterprise plan, the [changes `/usage` recommends](https://code.claude.com/docs/en/costs#plan-usage-breakdown) to lower your plan usage, measured over the last 7 days. Claude proposes the changes it can make itself and reports the rest as advice, such as a command for you to run. The usage check requires Claude Code v2.1.305 or later, and `/doctor` leaves it out while [Remote Control](https://code.claude.com/docs/en/remote-control.md) is connected.

4242

4343For read-only installation diagnostics without starting a session, run `claude doctor` in your terminal instead.

4444

45To audit your instructions rather than your setup, run `/doctor prompt-audit` at the Claude Code prompt. Claude [checks your `CLAUDE.md` files, skills, and other configuration](/docs/en/memory#audit-your-instruction-files) for outdated or conflicting instructions instead of running the checkup. The `prompt-audit` subcommand requires Claude Code v2.1.283 or later.

45To audit your instructions rather than your setup, run `/doctor prompt-audit` at the Claude Code prompt. Claude [checks your `CLAUDE.md` files, skills, and other configuration](https://code.claude.com/docs/en/memory#audit-your-instruction-files) for outdated or conflicting instructions instead of running the checkup. The `prompt-audit` subcommand requires Claude Code v2.1.283 or later.

4646

4747### Run and verify your app

4848

from line 68

6868

6969* **Location**: the skill loads from the enterprise, personal, project, or additional-directory [location](#where-skills-live), or from a `.claude/commands/` file with that name. The recipe that `/verify` records at your repo root is a project skill, so it counts. The bundled `/verify` and `/simplify`, plugin skills, and skills from your claude.ai account don't count.

7070* **Invocation**: Claude can invoke the skill. If you've [stopped Claude from invoking it](#control-who-invokes-a-skill), for example with `disable-model-invocation: true`, Claude doesn't get the instruction.

71* **Git instructions**: you haven't turned off [`includeGitInstructions`](/docs/en/settings-reference#includegitinstructions). Turning it off removes this instruction together with the rest of the built-in commit and PR instructions.

71* **Git instructions**: you haven't turned off [`includeGitInstructions`](https://code.claude.com/docs/en/settings-reference#includegitinstructions). Turning it off removes this instruction together with the rest of the built-in commit and PR instructions.

7272

7373### Work on Claude API projects

7474

from line 151

151151

152152| Location | Path | Loads in |

153153| :- | :- | :- |

154| Enterprise | `.claude/skills/<skill-name>/SKILL.md` in the [managed settings directory](/docs/en/managed-settings.md#delivery-mechanisms) | All users on machines where your organization deploys it |

154| Enterprise | `.claude/skills/<skill-name>/SKILL.md` in the [managed settings directory](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms) | All users on machines where your organization deploys it |

155155| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | All your projects on this machine, but not [Cowork or cloud sessions](#skills-in-cowork-and-cloud-sessions) |

156| Project | `.claude/skills/<skill-name>/SKILL.md` | Sessions in this repository, but not [cloud threads in a project](/docs/en/claude-projects.md#what-threads-pick-up-from-your-repositories). Commit it so your team gets it too |

156| Project | `.claude/skills/<skill-name>/SKILL.md` | Sessions in this repository, but not [cloud threads in a project](https://code.claude.com/docs/en/claude-projects.md#what-threads-pick-up-from-your-repositories). Commit it so your team gets it too |

157157| Nested | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | Sessions started in or below `<subdir>`, but not cloud threads in a project. Outside those threads, a session started above it loads the skill once Claude works on files there. See [monorepos and subdirectories](#discovery-from-parent-and-nested-directories) |

158158| Additional directory | `.claude/skills/<skill-name>/SKILL.md` in a directory you pass with `--add-dir` | That session. See [directories outside the project](#skills-from-additional-directories) |

159| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Wherever the [plugin](/docs/en/plugins/overview.md) is enabled, as `/plugin-name:skill-name` |

159| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Wherever the [plugin](https://code.claude.com/docs/en/plugins/overview.md) is enabled, as `/plugin-name:skill-name` |

160160| claude.ai account | Skills enabled for your claude.ai account | Cowork sessions, cloud sessions, and terminal sessions where you sign in with that account. See [Skills synced from claude.ai](#how-synced-skills-behave) |

161161

162162Skill folders also follow these rules:

163163

164* **Symlinked folders**: a `<skill-name>` entry in the enterprise, personal, or project location can be a symlink to a directory elsewhere on disk. Claude Code reads `SKILL.md` from the target and loads the skill once even if several locations point at the same target. Plugin skills [handle symlinks differently](/docs/en/plugins/host-marketplace.md#share-files-within-a-marketplace-with-symlinks).

164* **Symlinked folders**: a `<skill-name>` entry in the enterprise, personal, or project location can be a symlink to a directory elsewhere on disk. Claude Code reads `SKILL.md` from the target and loads the skill once even if several locations point at the same target. Plugin skills [handle symlinks differently](https://code.claude.com/docs/en/plugins/host-marketplace.md#share-files-within-a-marketplace-with-symlinks).

165165* **Reserved name `synced`**: don't name a skill folder `synced`, in any capitalization. Claude Code uses `~/.claude/skills/synced/` for [skills downloaded from claude.ai](#where-synced-skills-load) and skips a skill you author at that name in the enterprise, personal, and project locations.

166166* **Reserved name `anthropic-skills`**: outside a plugin, a skill folder or command file whose name is `anthropic-skills` or starts with `anthropic-skills:` doesn't load. See [Names reserved for synced skills](#names-reserved-for-synced-skills).

167167* **Characters in the name**: outside a plugin, a skill folder doesn't load when its name has a character such as a zero-width space or `<`. See [Characters a skill name can't hold](#characters-a-skill-name-cant-hold).

168168* **Command files**: a Markdown file in `.claude/commands/` is the older format and still works. It supports the same [frontmatter](#frontmatter-reference) except `name` and `paths`. To find the name you type to invoke it, see [How a skill gets its command name](#how-a-skill-gets-its-command-name). Prefer a skill for new work, since skills also support [supporting files](#add-supporting-files).

169* **Skill folder as a plugin**: add a `.claude-plugin/plugin.json` to a personal or project skill folder and Claude Code can load it as a [plugin](/docs/en/plugins/loading.md#plugins-shared-through-a-repository) named `<name>@skills-dir` with its own agents, hooks, and MCP servers. In a project's `.claude/skills/`, this requires accepting the workspace trust dialog first, and in either location it requires that your administrator hasn't [blocked skills-directory plugins](/docs/en/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings).

169* **Skill folder as a plugin**: add a `.claude-plugin/plugin.json` to a personal or project skill folder and Claude Code can load it as a [plugin](https://code.claude.com/docs/en/plugins/loading.md#plugins-shared-through-a-repository) named `<name>@skills-dir` with its own agents, hooks, and MCP servers. In a project's `.claude/skills/`, this requires accepting the workspace trust dialog first, and in either location it requires that your administrator hasn't [blocked skills-directory plugins](https://code.claude.com/docs/en/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings).

170170

171171### Load skills in monorepos and subdirectories

172172

173Claude Code loads project skills from `.claude/skills/` in the directory where you start it and in every parent directory up to the repository root, so starting in `packages/frontend/` still picks up skills defined at the root. When you [move the session with `/cd`](/docs/en/permissions#move-the-session-to-another-directory) on v2.1.246 or later, Claude Code adds the new directory's project skills.

173Claude Code loads project skills from `.claude/skills/` in the directory where you start it and in every parent directory up to the repository root, so starting in `packages/frontend/` still picks up skills defined at the root. When you [move the session with `/cd`](https://code.claude.com/docs/en/permissions#move-the-session-to-another-directory) on v2.1.246 or later, Claude Code adds the new directory's project skills.

174174

175In a session running in a linked [git worktree](/docs/en/worktrees.md) that you created with `--worktree` or `git worktree add`, Claude Code searches parent directories only up to the worktree root. On Claude Code v2.1.277 or later, when the worktree checkout has no `.claude/skills` directory at its root, Claude Code loads the main checkout's project skills instead. See [What worktrees share with the main checkout](/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout).

175In a session running in a linked [git worktree](https://code.claude.com/docs/en/worktrees.md) that you created with `--worktree` or `git worktree add`, Claude Code searches parent directories only up to the worktree root. On Claude Code v2.1.277 or later, when the worktree checkout has no `.claude/skills` directory at its root, Claude Code loads the main checkout's project skills instead. See [What worktrees share with the main checkout](https://code.claude.com/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout).

176176

177Skills in a `.claude/skills/` directory below where you started don't load at startup. They load the first time Claude reads or edits a file in that subdirectory and stay available for the rest of the session. Until then they don't appear in the `/` menu and you can't invoke them by name. To load them sooner, run `/add-dir` with the subdirectory's path, which requires Claude Code v2.1.257 or later. For a worktree session that you start from the desktop app, see [What worktrees share with the main checkout](/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout).

177Skills in a `.claude/skills/` directory below where you started don't load at startup. They load the first time Claude reads or edits a file in that subdirectory and stay available for the rest of the session. Until then they don't appear in the `/` menu and you can't invoke them by name. To load them sooner, run `/add-dir` with the subdirectory's path, which requires Claude Code v2.1.257 or later. For a worktree session that you start from the desktop app, see [What worktrees share with the main checkout](https://code.claude.com/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout).

178178

179179When a nested skill's directory name matches another skill's name, both stay available. With a `deploy` skill at the repository root and another in `apps/web/.claude/skills/`:

180180

from line 183

183183

184184### Load skills from a directory outside the project

185185

186When you add a directory with `--add-dir` or `/add-dir`, Claude Code loads the skills in that directory's `.claude/skills/`, along with its `.claude/commands/` and `.claude/agents/`. Directories the Agent SDK adds through [`additionalDirectories`](/docs/en/agent-sdk/typescript#options) in TypeScript or [`add_dirs`](/docs/en/agent-sdk/python#claudeagentoptions) in Python load the same way, because the SDK passes them as `--add-dir`. The `permissions.additionalDirectories` setting in `settings.json` grants file access only and loads none of these.

186When you add a directory with `--add-dir` or `/add-dir`, Claude Code loads the skills in that directory's `.claude/skills/`, along with its `.claude/commands/` and `.claude/agents/`. Directories the Agent SDK adds through [`additionalDirectories`](https://code.claude.com/docs/en/agent-sdk/typescript#options) in TypeScript or [`add_dirs`](https://code.claude.com/docs/en/agent-sdk/python#claudeagentoptions) in Python load the same way, because the SDK passes them as `--add-dir`. The `permissions.additionalDirectories` setting in `settings.json` grants file access only and loads none of these.

187187

188188Claude Code watches `.claude/skills/` in a directory you pass with `--add-dir` at launch, as [Edit a skill during a session](#live-change-detection) describes. It doesn't watch the added directory's `.claude/commands/` or `.claude/agents/`, so restart the session after changing a file there.

189189

190These loads depend on the `project` [setting source](/docs/en/agent-sdk/claude-code-features.md#control-filesystem-settings-with-settingsources), which is on by default. A [`strictPluginOnlyCustomization`](/docs/en/settings-reference#strictpluginonlycustomization) policy, [bare mode](/docs/en/headless.md#start-faster-with-bare-mode), and [`--safe-mode`](/docs/en/cli-reference#cli-flags) each restrict them further, as those pages describe. See [Additional directories grant file access, not configuration](/docs/en/permissions.md#additional-directories-grant-file-access-not-configuration) for the full table of what an added directory loads, including `CLAUDE.md` and plugin settings.

190These loads depend on the `project` [setting source](https://code.claude.com/docs/en/agent-sdk/claude-code-features.md#control-filesystem-settings-with-settingsources), which is on by default. A [`strictPluginOnlyCustomization`](https://code.claude.com/docs/en/settings-reference#strictpluginonlycustomization) policy, [bare mode](https://code.claude.com/docs/en/headless.md#start-faster-with-bare-mode), and [`--safe-mode`](https://code.claude.com/docs/en/cli-reference#cli-flags) each restrict them further, as those pages describe. See [Additional directories grant file access, not configuration](https://code.claude.com/docs/en/permissions.md#additional-directories-grant-file-access-not-configuration) for the full table of what an added directory loads, including `CLAUDE.md` and plugin settings.

191191

192192#### Run a same-named skill from an added directory

193193

from line 206

206206| :- | :- |

207207| Two of enterprise, personal, and project | Enterprise over personal, and personal over project. With `deploy` in both `~/.claude/skills/` and the project's `.claude/skills/`, `/deploy` runs the personal one |

208208| Any of those locations and a [bundled skill](#bundled-skills) | Your skill replaces the bundled command, but not its aliases. A project `code-review` skill replaces `/code-review`, and the bundled alias `/review` never runs your skill |

209| Any of those locations and a [built-in command](/docs/en/commands.md) | In a local terminal session, your skill replaces the built-in command, but not its aliases. A project `usage` skill replaces `/usage`, and the built-in alias `/cost` still runs the built-in command |

209| Any of those locations and a [built-in command](https://code.claude.com/docs/en/commands.md) | In a local terminal session, your skill replaces the built-in command, but not its aliases. A project `usage` skill replaces `/usage`, and the built-in alias `/cost` still runs the built-in command |

210210| A skill and a file in `.claude/commands/` | The skill |

211211| A project-root skill and a nested skill | Both load. See [monorepos and subdirectories](#discovery-from-parent-and-nested-directories) |

212212| An enterprise, personal, or project skill and a skill in an [added directory outside the project](#skills-from-additional-directories) | The enterprise, personal, or project skill, while the added directory's skill runs under a prefixed name. See [run a same-named skill from an added directory](#run-a-same-named-skill-from-an-added-directory) |

from line 216

216216

217217### Use skills in Cowork and cloud sessions

218218

219[Cowork](https://claude.com/product/cowork) sessions and [cloud sessions](/docs/en/cloud-environments.md#what-carries-over-from-your-setup), including [cloud scheduled tasks](/docs/en/routines.md), don't read `~/.claude/skills/` on your machine. Both interactive and scheduled Cowork sessions load the skills enabled for your claude.ai account, synced at session start. Manage them from **Customize** in the Desktop app sidebar or from the skills settings on claude.ai.

219[Cowork](https://claude.com/product/cowork) sessions and [cloud sessions](https://code.claude.com/docs/en/cloud-environments.md#what-carries-over-from-your-setup), including [cloud scheduled tasks](https://code.claude.com/docs/en/routines.md), don't read `~/.claude/skills/` on your machine. Both interactive and scheduled Cowork sessions load the skills enabled for your claude.ai account, synced at session start. Manage them from **Customize** in the Desktop app sidebar or from the skills settings on claude.ai.

220220

221If a skill exists only in `~/.claude/skills/` on your machine, Claude Code reports that the skill was not found when a [cloud scheduled task](/docs/en/routines.md) invokes it. This happens because each run starts as a fresh cloud session. To make a personal skill available in these sessions:

221If a skill exists only in `~/.claude/skills/` on your machine, Claude Code reports that the skill was not found when a [cloud scheduled task](https://code.claude.com/docs/en/routines.md) invokes it. This happens because each run starts as a fresh cloud session. To make a personal skill available in these sessions:

222222

223* For Cowork sessions, cloud sessions, and cloud threads in a [project](/docs/en/claude-projects.md#what-threads-pick-up-from-your-repositories), enable the skill for your claude.ai account. In a project's cloud thread, skills committed to a repository's `.claude/skills/` aren't available. [Some sessions in a self-hosted environment](/docs/en/self-hosted-environments-configuration.md#how-each-session’s-config-is-assembled) don't load your account's skills.

224* For cloud sessions other than project threads, you can instead commit the skill to the repository's `.claude/skills/`. Plugins declared in the repository's `.claude/settings.json` and plugins enabled only in your user settings [don't load in cloud sessions](/docs/en/cloud-environments.md#what-carries-over-from-your-setup).

223* For Cowork sessions, cloud sessions, and cloud threads in a [project](https://code.claude.com/docs/en/claude-projects.md#what-threads-pick-up-from-your-repositories), enable the skill for your claude.ai account. In a project's cloud thread, skills committed to a repository's `.claude/skills/` aren't available. [Some sessions in a self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#how-each-session’s-config-is-assembled) don't load your account's skills.

224* For cloud sessions other than project threads, you can instead commit the skill to the repository's `.claude/skills/`. Plugins declared in the repository's `.claude/settings.json` and plugins enabled only in your user settings [don't load in cloud sessions](https://code.claude.com/docs/en/cloud-environments.md#what-carries-over-from-your-setup).

225225

226[Desktop scheduled tasks](/docs/en/desktop-scheduled-tasks.md) run locally on your machine, so they do load `~/.claude/skills/`.

226[Desktop scheduled tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks.md) run locally on your machine, so they do load `~/.claude/skills/`.

227227

228228### Skills synced from claude.ai

229229

from line 242

242242* **While you or Claude work in the session**: a check runs about every 10 minutes.

243243* **While the session is idle**: a check runs about every 40 minutes. When you type in the session again, Claude Code checks within a few minutes if the last check was more than 10 minutes ago.

244244

245The sync never delays startup, because Claude waits for a skill's download only when it invokes that skill. A short [non-interactive](/docs/en/headless.md) run can therefore finish before a newly added skill downloads, in which case a later session downloads it. To make a non-interactive run download your skills and wait for the list before it answers the prompt, set [`CLAUDE_CODE_SYNC_SKILLS`](/docs/en/env-vars#variables) to `1`. Before v2.1.273, terminal sessions downloaded them only in a `-p` run with this variable set.

245The sync never delays startup, because Claude waits for a skill's download only when it invokes that skill. A short [non-interactive](https://code.claude.com/docs/en/headless.md) run can therefore finish before a newly added skill downloads, in which case a later session downloads it. To make a non-interactive run download your skills and wait for the list before it answers the prompt, set [`CLAUDE_CODE_SYNC_SKILLS`](https://code.claude.com/docs/en/env-vars#variables) to `1`. Before v2.1.273, terminal sessions downloaded them only in a `-p` run with this variable set.

246246

247Claude Code syncs only in a session that signs in with your claude.ai account and [fetches feature flags from Anthropic](/docs/en/env-vars.md#features-that-need-feature-flag-fetching). It doesn't sync in these sessions:

247Claude Code syncs only in a session that signs in with your claude.ai account and [fetches feature flags from Anthropic](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching). It doesn't sync in these sessions:

248248

249249* A session that doesn't use a sign-in stored by `/login`, such as one that authenticates with an API key, or one where `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, or an `apiKeyHelper` script supplies the credential

250250* A session that doesn't fetch feature flags, such as one on Amazon Bedrock or one where you set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

251* A session in [bare mode](/docs/en/headless.md#start-faster-with-bare-mode) or one you start with `--safe-mode`

252* A session where your organization's managed settings [lock skills to plugin sources](/docs/en/settings-reference.md#strictpluginonlycustomization-skills), or one you start with a [`--setting-sources`](/docs/en/cli-reference#cli-flags) list that leaves out `user`

251* A session in [bare mode](https://code.claude.com/docs/en/headless.md#start-faster-with-bare-mode) or one you start with `--safe-mode`

252* A session where your organization's managed settings [lock skills to plugin sources](https://code.claude.com/docs/en/settings-reference.md#strictpluginonlycustomization-skills), or one you start with a [`--setting-sources`](https://code.claude.com/docs/en/cli-reference#cli-flags) list that leaves out `user`

253253

254254If you sign in with `/login` during a session, restart Claude Code to start syncing.

255255

from line 261

261261

262262Some of Anthropic's skills, such as `pdf` and `xlsx`, always sync. For the rest, turn a skill on or off in your skills settings on claude.ai to change whether it syncs.

263263

264To stop syncing on a machine, set [`syncClaudeAiSkills`](/docs/en/settings-reference#syncclaudeaiskills) to `false` in your user settings. Claude Code stops downloading, and the next time it starts it moves the skills it already synced to `~/.claude/skills/.trash/` and no longer loads them. Your organization can turn syncing off for everyone by turning off Skills on claude.ai. To stop syncing while leaving Skills on, it can set the same key in [managed settings](/docs/en/managed-settings.md).

264To stop syncing on a machine, set [`syncClaudeAiSkills`](https://code.claude.com/docs/en/settings-reference#syncclaudeaiskills) to `false` in your user settings. Claude Code stops downloading, and the next time it starts it moves the skills it already synced to `~/.claude/skills/.trash/` and no longer loads them. Your organization can turn syncing off for everyone by turning off Skills on claude.ai. To stop syncing while leaving Skills on, it can set the same key in [managed settings](https://code.claude.com/docs/en/managed-settings.md).

265265

266If your organization turns Skills off on claude.ai, Claude Code removes the downloaded skills and they stop loading. The removed skills move to `~/.claude/skills/.trash/`, where you can recover the files until the [retention sweep](/docs/en/claude-directory.md#cleaned-up-automatically) deletes them. Once your organization turns Skills back on, Claude Code downloads the skills you enabled at the next sync.

266If your organization turns Skills off on claude.ai, Claude Code removes the downloaded skills and they stop loading. The removed skills move to `~/.claude/skills/.trash/`, where you can recover the files until the [retention sweep](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically) deletes them. Once your organization turns Skills back on, Claude Code downloads the skills you enabled at the next sync.

267267

268268#### When a synced skill name matches another command

269269

from line 278

278278* A built-in command or a [bundled skill](#bundled-skills), including one that's unavailable in your session, for example after you turn bundled skills off

279279* A skill at any [local level](#where-skills-live) or a file in `.claude/commands/`

280280* A plugin skill

281* An [MCP prompt](/docs/en/mcp.md#use-mcp-prompts-as-commands)

281* An [MCP prompt](https://code.claude.com/docs/en/mcp.md#use-mcp-prompts-as-commands)

282282

283283Claude Code labels synced skills so you can tell where they came from. The `/skills` menu and `/context` group synced skills under `claude.ai sync`, and the `/` command menu marks them as coming from claude.ai.

284284

from line 290

290290

291291Claude Code reserves the name `anthropic-skills`, and every name inside that namespace such as `anthropic-skills:pdf`, for skills synced from claude.ai, so a synced skill's full name never runs anything else. The name is reserved in every session, whether or not you sign in with a claude.ai account.

292292

293* **A skill folder, a frontmatter `name`, a file or subfolder in `.claude/commands/`, or a [saved workflow](/docs/en/workflows.md#save-the-workflow-for-reuse)**: it doesn't load. A [startup notice](/docs/en/errors.md#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) names the first item to rename or edit.

293* **A skill folder, a frontmatter `name`, a file or subfolder in `.claude/commands/`, or a [saved workflow](https://code.claude.com/docs/en/workflows.md#save-the-workflow-for-reuse)**: it doesn't load. A [startup notice](https://code.claude.com/docs/en/errors.md#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) names the first item to rename or edit.

294294* **A plugin named `anthropic-skills`**: it loads. When one of its skills and a synced skill are both named `<name>`, `/anthropic-skills:<name>` runs the synced skill.

295* **An MCP server named `anthropic-skills`**: it connects and its tools work, but [its prompts don't appear as commands](/docs/en/mcp.md#use-mcp-prompts-as-commands). Rename the server in your MCP configuration to list them.

295* **An MCP server named `anthropic-skills`**: it connects and its tools work, but [its prompts don't appear as commands](https://code.claude.com/docs/en/mcp.md#use-mcp-prompts-as-commands). Rename the server in your MCP configuration to list them.

296296

297297#### How Claude Code handles the frontmatter of a synced skill

298298

299299Claude Code applies two rules to a synced skill's frontmatter:

300300

301* The frontmatter applies in every kind of session, so an `allowed-tools` grant goes through the normal [permission flow](/docs/en/permissions.md). If your organization sets `allowManagedPermissionRulesOnly`, the grant [doesn't apply](#when-only-managed-permission-rules-apply).

301* The frontmatter applies in every kind of session, so an `allowed-tools` grant goes through the normal [permission flow](https://code.claude.com/docs/en/permissions.md). If your organization sets `allowManagedPermissionRulesOnly`, the grant [doesn't apply](#when-only-managed-permission-rules-apply).

302302* Claude Code sanitizes the display text the skill supplies, such as its description. It removes control characters, and in text that reaches Claude, such as the description, it also escapes angle brackets so the text can't imitate Claude Code's internal formatting. This sanitization requires Claude Code v2.1.228 or later.

303303

304304#### How Claude Code handles the body of a synced skill

from line 311

311311

312312### Edit a skill during a session

313313

314Claude Code watches skill directories for file changes, except in [bare mode](/docs/en/headless.md#start-faster-with-bare-mode). When you add, edit, or remove a skill under `~/.claude/skills/`, the project `.claude/skills/`, or a `.claude/skills/` inside an `--add-dir` directory, Claude Code picks up the change within the current session, without a restart.

314Claude Code watches skill directories for file changes, except in [bare mode](https://code.claude.com/docs/en/headless.md#start-faster-with-bare-mode). When you add, edit, or remove a skill under `~/.claude/skills/`, the project `.claude/skills/`, or a `.claude/skills/` inside an `--add-dir` directory, Claude Code picks up the change within the current session, without a restart.

315315

316If you create a top-level skills directory that didn't exist when the session started, run [`/reload-skills`](/docs/en/commands#all-commands) to pick up the skills you put there. Claude Code isn't watching that directory yet, so run `/reload-skills` again after each later change there.

316If you create a top-level skills directory that didn't exist when the session started, run [`/reload-skills`](https://code.claude.com/docs/en/commands#all-commands) to pick up the skills you put there. Claude Code isn't watching that directory yet, so run `/reload-skills` again after each later change there.

317317

318Live change detection covers `SKILL.md` text only. For a skill folder that is also a [plugin](/docs/en/plugins/loading.md#plugins-shared-through-a-repository), changes to `hooks/`, `.mcp.json`, `agents/`, and `output-styles/` need `/reload-plugins` to take effect.

318Live change detection covers `SKILL.md` text only. For a skill folder that is also a [plugin](https://code.claude.com/docs/en/plugins/loading.md#plugins-shared-through-a-repository), changes to `hooks/`, `.mcp.json`, `agents/`, and `output-styles/` need `/reload-plugins` to take effect.

319319

320320### Remove a skill

321321

from line 322

322322How you remove a skill depends on where it came from:

323323

324324* **Personal or project skill**: delete the skill's directory, `~/.claude/skills/<skill-name>/` or `.claude/skills/<skill-name>/`. Claude Code [drops it from `/skills` in the current session](#live-change-detection); content Claude Code already loaded from it follows the [skill content lifecycle](#skill-content-lifecycle).

325* **Enterprise skill**: an administrator deletes the skill's directory from `.claude/skills/` inside the [managed settings directory](/docs/en/managed-settings.md#delivery-mechanisms), for example `/etc/claude-code/.claude/skills/<skill-name>/` on Linux.

326* **Plugin skill**: disable or uninstall the plugin that provides it, from the `/plugin` menu or with `/plugin uninstall <plugin-name>@<marketplace-name>`. Claude Code unloads the plugin's skills when [the change applies](/docs/en/plugins/cli-reference.md#reload-plugins) or when you restart.

325* **Enterprise skill**: an administrator deletes the skill's directory from `.claude/skills/` inside the [managed settings directory](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms), for example `/etc/claude-code/.claude/skills/<skill-name>/` on Linux.

326* **Plugin skill**: disable or uninstall the plugin that provides it, from the `/plugin` menu or with `/plugin uninstall <plugin-name>@<marketplace-name>`. Claude Code unloads the plugin's skills when [the change applies](https://code.claude.com/docs/en/plugins/cli-reference.md#reload-plugins) or when you restart.

327327* **Skill synced from claude.ai**: turn the skill off for your claude.ai account, in the same place you [enabled it](#skills-in-cowork-and-cloud-sessions). Claude Code removes it from `~/.claude/skills/synced/` the next time it [syncs your skills](#where-synced-skills-load). If you delete the directory by hand instead, the next sync downloads it again while the skill stays enabled on claude.ai.

328328* **Bundled skill**: set [`disableBundledSkills`](#bundled-skills) to `true` to turn off bundled skills, or set one skill to `"off"` in [`skillOverrides`](#override-skill-visibility-from-settings) to hide it.

329329

from line 367

3673673. Push to the deployment target

368368```

369369

370Keep the body itself concise. Once a skill loads, its content [stays in context across turns](#skill-content-lifecycle), so every line is a recurring token cost. State what to do rather than narrating how or why, and apply the same conciseness test you would for [CLAUDE.md content](/docs/en/best-practices.md#write-an-effective-claude-md).

370Keep the body itself concise. Once a skill loads, its content [stays in context across turns](#skill-content-lifecycle), so every line is a recurring token cost. State what to do rather than narrating how or why, and apply the same conciseness test you would for [CLAUDE.md content](https://code.claude.com/docs/en/best-practices.md#write-an-effective-claude-md).

371371

372372### Frontmatter reference

373373

374Configure a skill with YAML [frontmatter](/docs/en/glossary.md#frontmatter) between `---` markers at the top of `SKILL.md`, and write the skill's instructions as Markdown after the closing `---`. Field names use lowercase words separated by hyphens, except `when_to_use`. A [command file](#where-skills-live) in `.claude/commands/` accepts the same fields except `name` and `paths`. This example sets four fields:

374Configure a skill with YAML [frontmatter](https://code.claude.com/docs/en/glossary.md#frontmatter) between `---` markers at the top of `SKILL.md`, and write the skill's instructions as Markdown after the closing `---`. Field names use lowercase words separated by hyphens, except `when_to_use`. A [command file](#where-skills-live) in `.claude/commands/` accepts the same fields except `name` and `paths`. This example sets four fields:

375375

376376```yaml theme={null}

377377---

from line 397

397397| `when_to_use` | No | Additional context for when Claude should invoke the skill, such as trigger phrases or example requests. Appended to `description` in the skill listing and counts toward the 1,536-character cap. |

398398| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |

399399| `arguments` | No | Named positional arguments for [`$name` substitution](#available-string-substitutions) in the skill content. Accepts a space-separated string or a YAML list. Names map to argument positions in order. |

400| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Also prevents the skill from being [preloaded into subagents](/docs/en/sub-agents.md#preload-skills-into-subagents) and from running when a [session-scoped scheduled task](/docs/en/scheduled-tasks.md) fires with the skill as its prompt. Default: `false`. |

400| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Also prevents the skill from being [preloaded into subagents](https://code.claude.com/docs/en/sub-agents.md#preload-skills-into-subagents) and from running when a [session-scoped scheduled task](https://code.claude.com/docs/en/scheduled-tasks.md) fires with the skill as its prompt. Default: `false`. |

401401| `user-invocable` | No | Set to `false` when only Claude should invoke the skill: Claude Code hides it from the `/` menu and doesn't run it when you type `/name`. Use for background knowledge users shouldn't invoke directly. Default: `true`. |

402402| `allowed-tools` | No | Tools Claude can use without asking permission during the turn that invokes this skill. The grant clears when you send your next message. Accepts a space- or comma-separated string, or a YAML list. See [Pre-approve tools for a skill](#pre-approve-tools-for-a-skill). |

403| `disallowed-tools` | No | Tools removed from Claude's available pool while this skill is active. Use for autonomous skills that should never call certain tools, such as `AskUserQuestion` for a background loop. Accepts a space- or comma-separated string, or a YAML list. The restriction clears when you send your next message. Like deny rules, the field can't remove [`EndConversation`](/docs/en/tools-reference#endconversation-tool-behavior) while any other tool remains. |

404| `model` | No | Model to use when this skill is active. The override applies for the rest of the current turn and isn't saved to settings. The session model resumes when you send your next prompt. Accepts the same values as [`/model`](/docs/en/model-config), or `inherit` to keep the active model. A value excluded by your organization's [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist isn't used, and the session keeps its current model. In [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), and in [plan mode while the classifier reviews commands](/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode), a model that auto mode doesn't support also isn't used, and the session keeps its current model. With `context: fork`, the value sets the [forked subagent's model](#run-skills-in-a-subagent) instead, and an excluded value follows the [same rules as a subagent model override](/docs/en/model-config.md#restrict-model-selection). |

405| `effort` | No | [Effort level](/docs/en/model-config.md#adjust-effort-level) when this skill is active. Overrides the session effort level. When you omit it, the level comes from the [effort resolution order](/docs/en/model-config.md#adjust-effort-level). Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model. |

403| `disallowed-tools` | No | Tools removed from Claude's available pool while this skill is active. Use for autonomous skills that should never call certain tools, such as `AskUserQuestion` for a background loop. Accepts a space- or comma-separated string, or a YAML list. The restriction clears when you send your next message. Like deny rules, the field can't remove [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior) while any other tool remains. |

404| `model` | No | Model to use when this skill is active. The override applies for the rest of the current turn and isn't saved to settings. The session model resumes when you send your next prompt. Accepts the same values as [`/model`](https://code.claude.com/docs/en/model-config), or `inherit` to keep the active model. A value excluded by your organization's [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) allowlist isn't used, and the session keeps its current model. In [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), and in [plan mode while the classifier reviews commands](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode), a model that auto mode doesn't support also isn't used, and the session keeps its current model. With `context: fork`, the value sets the [forked subagent's model](#run-skills-in-a-subagent) instead, and an excluded value follows the [same rules as a subagent model override](https://code.claude.com/docs/en/model-config.md#restrict-model-selection). |

405| `effort` | No | [Effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) when this skill is active. Overrides the session effort level. When you omit it, the level comes from the [effort resolution order](https://code.claude.com/docs/en/model-config.md#adjust-effort-level). Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model. |

406406| `context` | No | Set to `fork` to run in a forked subagent context. See [Run skills in a subagent](#run-skills-in-a-subagent). |

407407| `agent` | No | Which subagent type to use when `context: fork` is set. |

408408| `background` | No | Only applies with `context: fork`. Set to `false` to wait for the forked subagent's result in the turn that invoked the skill, instead of [running it in the background](#run-skills-in-a-subagent). Default: `true`. Requires Claude Code v2.1.218 or later. |

409| `hooks` | No | Hooks that Claude Code registers when the skill is invoked and keeps running for the rest of the session. See [Hooks in skills and agents](/docs/en/hooks.md#hooks-in-skills-and-agents) for the configuration format, the `once` option, and the [limits on skill hooks](/docs/en/hooks.md#limits-on-skill-hooks). |

410| `paths` | No | Glob patterns that limit when this skill is activated. Accepts a comma-separated string or a YAML list. When set, Claude loads the skill automatically only when working with files matching the patterns. Patterns are relative to Claude's current working directory, and files outside that directory don't match. Uses the same glob format as [path-specific rules](/docs/en/memory.md#path-specific-rules). |

411| `shell` | No | Shell to use for `` !`command` `` and ` ```! ` blocks in this skill. Accepts `bash` (default) or `powershell`. Setting `powershell` runs inline shell commands via PowerShell when the [PowerShell tool](/docs/en/tools-reference.md#powershell-tool) is enabled: it's on by default on Windows without Git Bash, on by default with Git Bash for claude.ai and Console accounts, and needs `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` in Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry sessions and on macOS, Linux, and WSL. Set it to `0` to turn the tool off. |

409| `hooks` | No | Hooks that Claude Code registers when the skill is invoked and keeps running for the rest of the session. See [Hooks in skills and agents](https://code.claude.com/docs/en/hooks.md#hooks-in-skills-and-agents) for the configuration format, the `once` option, and the [limits on skill hooks](https://code.claude.com/docs/en/hooks.md#limits-on-skill-hooks). |

411| `shell` | No | Shell to use for `` !`command` `` and ` ```! ` blocks in this skill. Accepts `bash` (default) or `powershell`. Setting `powershell` runs inline shell commands via PowerShell when the [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) is enabled: it's on by default on Windows without Git Bash, on by default with Git Bash for claude.ai and Console accounts, and needs `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` in Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry sessions and on macOS, Linux, and WSL. Set it to `0` to turn the tool off. |

412412| `metadata` | No | Free-form YAML map for your own key-value data, such as entitlement or catalog fields, read by your own tooling from `SKILL.md`. Claude Code doesn't act on its contents, and drops a value that isn't a map. Don't reuse frontmatter field names such as `paths` as keys. |

413413| `license` | No | License covering the skill. Part of the [Agent Skills](https://agentskills.io) spec; see [Using skill frontmatter outside Claude Code](#using-skill-frontmatter-outside-claude-code). Claude Code accepts the field but doesn't act on it. |

414414| `compatibility` | No | Environment requirements for the skill, such as intended products or system prerequisites, as defined by the [Agent Skills](https://agentskills.io) spec; see [Using skill frontmatter outside Claude Code](#using-skill-frontmatter-outside-claude-code). Accepts a string of up to 500 characters. Claude Code accepts the field but doesn't act on it. |

from line 419

419419

420420| Distribution path | Frontmatter fields you can use |

421421| :- | :- |

422| Claude Code skills at [any level](#where-skills-live), including [plugin](/docs/en/plugins/overview.md) skills | Every field in the table above |

422| Claude Code skills at [any level](#where-skills-live), including [plugin](https://code.claude.com/docs/en/plugins/overview.md) skills | Every field in the table above |

423423| claude.ai skill uploads, the Skills API, and packaging with `package_skill.py` from [anthropics/skills](https://github.com/anthropics/skills) | `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` |

424424

425425When you enable a personal skill for your claude.ai account, for example to use it in [Cowork and cloud sessions](#skills-in-cowork-and-cloud-sessions) and scheduled tasks, you upload it to claude.ai. The same rules apply to that upload.

from line 446

446446| File under `.claude/commands/` | File name without extension | `.claude/commands/deploy.md` → `/deploy` |

447447| File in a subdirectory of `.claude/commands/` | Subdirectory path relative to `commands/` with each `/` replaced by `:`, then the file name without extension | `.claude/commands/frontend/component.md` → `/frontend:component` |

448448| Plugin `skills/` subdirectory | Frontmatter `name` or the directory name, namespaced by plugin | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review`, or `/my-plugin:fancy` with `name: fancy` |

449| Plugin root `SKILL.md` | Frontmatter `name`, with the plugin directory name as a fallback | `my-plugin/SKILL.md` with `name: review` → `/my-plugin:review`. See [a single skill at the plugin root](/docs/en/plugins/components.md#skills) |

450450| Skill [synced from claude.ai](#how-synced-skills-behave) | The skill's name on your claude.ai account, prefixed with `anthropic-skills:` | Account skill `deploy` → `/anthropic-skills:deploy`, or `/deploy` while no other command uses that name |

451451

452452In a plugin skill, the frontmatter `name` replaces the directory name in the last segment of the command, so `my-plugin/skills/review/SKILL.md` with `name: fancy` becomes `/my-plugin:fancy`. The bare `/fancy` also invokes the skill unless another command already uses that name. If the `name` you write already starts with the plugin's own prefix, Claude Code doesn't add the prefix again on v2.1.246 or later. For example, `name: my-plugin:fancy` still becomes `/my-plugin:fancy`. From v2.1.216 through v2.1.245, Claude Code doubled the prefix when the `name` already carried it.

453453

454In [non-interactive sessions](/docs/en/headless.md), the names `help` and `feedback` aren't reserved for their terminal-only built-in commands, so a plugin skill with one of those names keeps its bare command there. Every other terminal-only built-in's name, such as `/login`, stays reserved even though the command can't run in those sessions.

454In [non-interactive sessions](https://code.claude.com/docs/en/headless.md), the names `help` and `feedback` aren't reserved for their terminal-only built-in commands, so a plugin skill with one of those names keeps its bare command there. Every other terminal-only built-in's name, such as `/login`, stays reserved even though the command can't run in those sessions.

455455

456456For a plugin-root `SKILL.md`, there is no skill directory to take the name from, so `name` supplies the whole final segment. Without a `name` field, Claude Code falls back to the plugin's directory name.

457457

from line 467

467467

468468A custom command or skill doesn't load when Claude Code refuses its directory or file name. Rename that folder or file to remove the characters. A skill still loads when these characters are only in a plugin skill folder's name or in its frontmatter `name`:

469469

470* **Folder in a plugin's `skills/` directory or its manifest's [`skills` paths](/docs/en/plugins/components#skills)**: you don't need to rename the folder. These characters become hyphens in the skill's command name, so type the command with the hyphens.

470* **Folder in a plugin's `skills/` directory or its manifest's [`skills` paths](https://code.claude.com/docs/en/plugins/components#skills)**: you don't need to rename the folder. These characters become hyphens in the skill's command name, so type the command with the hyphens.

471471* **Frontmatter `name`**: the `/` menu doesn't show the `name` value and typing it doesn't invoke the skill. Edit the `name:` line to remove the characters.

472472

473To find out which name Claude Code refused, start it with [`claude --debug`](/docs/en/cli-reference#cli-flags) from your shell and search the [debug log](/docs/en/debug-your-config.md) for `[names]`. In an interactive session, a [startup notice](/docs/en/errors.md#skill-or-command-name-refused) also tells you that names were refused. After a rename or a `name:` edit, restart the session, unless the file is in a directory Claude Code [watches for changes](#live-change-detection).

473To find out which name Claude Code refused, start it with [`claude --debug`](https://code.claude.com/docs/en/cli-reference#cli-flags) from your shell and search the [debug log](https://code.claude.com/docs/en/debug-your-config.md) for `[names]`. In an interactive session, a [startup notice](https://code.claude.com/docs/en/errors.md#skill-or-command-name-refused) also tells you that names were refused. After a rename or a `name:` edit, restart the session, unless the file is in a directory Claude Code [watches for changes](#live-change-detection).

474474

475475#### Available string substitutions

476476

from line 485

485485| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |

486486| `${CLAUDE_EFFORT}` | The current effort level: `low`, `medium`, `high`, `xhigh`, or `max`. Use this to adapt skill instructions to the active effort setting. |

487487| `${CLAUDE_SKILL_DIR}` | The directory containing the skill's `SKILL.md` file. For plugin skills, this is the skill's subdirectory within the plugin, not the plugin root. Use this in bash injection commands to reference scripts or files bundled with the skill, regardless of the current working directory. |

488| `${CLAUDE_PROJECT_DIR}` | The project root directory. This is the same path [hooks](/docs/en/hooks.md#reference-scripts-by-path) and MCP servers receive as `CLAUDE_PROJECT_DIR`. Use this to reference project-local scripts or files, such as `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`, independent of where the skill is installed. |

489| `${CLAUDE_PLUGIN_ROOT}` | The plugin's installation directory. Substituted only in plugin skills. Use this to reference scripts or files bundled anywhere in the plugin, including resources shared between the plugin's skills. See [plugin environment variables](/docs/en/plugins/manifest-reference.md#environment-variables). |

490| `${CLAUDE_PLUGIN_DATA}` | The plugin's [persistent data directory](/docs/en/plugins/components.md#path-variables-and-persistent-data), which survives plugin updates. Substituted only in plugin skills. Use this to reference installed dependencies, generated files, or caches that must outlive an update. |

488| `${CLAUDE_PROJECT_DIR}` | The project root directory. This is the same path [hooks](https://code.claude.com/docs/en/hooks.md#reference-scripts-by-path) and MCP servers receive as `CLAUDE_PROJECT_DIR`. Use this to reference project-local scripts or files, such as `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`, independent of where the skill is installed. |

489| `${CLAUDE_PLUGIN_ROOT}` | The plugin's installation directory. Substituted only in plugin skills. Use this to reference scripts or files bundled anywhere in the plugin, including resources shared between the plugin's skills. See [plugin environment variables](https://code.claude.com/docs/en/plugins/manifest-reference.md#environment-variables). |

490| `${CLAUDE_PLUGIN_DATA}` | The plugin's [persistent data directory](https://code.claude.com/docs/en/plugins/components.md#path-variables-and-persistent-data), which survives plugin updates. Substituted only in plugin skills. Use this to reference installed dependencies, generated files, or caches that must outlive an update. |

491491

492492Claude Code substitutes `${CLAUDE_SKILL_DIR}` and `${CLAUDE_PROJECT_DIR}` in two places: the skill's markdown content, and Bash rules in the [`allowed-tools`](#frontmatter-reference) frontmatter. In a plugin skill, Claude Code substitutes `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}` in the same two places. Using the same variable in both places lets a skill run a bundled script without a permission prompt. The following skill shows the pattern:

493493

from line 587

587587

588588> [!NOTE]

589589>

590> In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked. [Subagents with preloaded skills](/docs/en/sub-agents.md#preload-skills-into-subagents) work differently: the full skill content is injected at startup.

590> In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked. [Subagents with preloaded skills](https://code.claude.com/docs/en/sub-agents.md#preload-skills-into-subagents) work differently: the full skill content is injected at startup.

591591

592592#### Where you write the skill's name

593593

from line 606

606606

607607When Claude re-invokes a skill whose rendered content is identical to the copy already in context, Claude Code adds a short note that the skill is already loaded rather than a second copy of the content. When the rendered content differs, because the arguments changed or a [dynamic context](#inject-dynamic-context) command produced new output, Claude Code appends the full content again.

608608

609[Auto-compaction](/docs/en/how-claude-code-works.md#when-context-fills-up) carries invoked skills forward within a token budget. When the conversation is summarized to free context, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens. Claude Code fills this budget starting from the most recently invoked skill, so older skills can be dropped entirely after compaction if you have invoked many in one session.

609[Auto-compaction](https://code.claude.com/docs/en/how-claude-code-works.md#when-context-fills-up) carries invoked skills forward within a token budget. When the conversation is summarized to free context, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens. Claude Code fills this budget starting from the most recently invoked skill, so older skills can be dropped entirely after compaction if you have invoked many in one session.

610610

611611If Claude stops following a skill partway through a session, see [Claude stops following a skill](#claude-stops-following-a-skill).

612612

613613### Pre-approve tools for a skill

614614

615The `allowed-tools` field grants permission for the listed tools during the turn that invokes the skill, so Claude can use them without prompting you for approval. The grant clears when you send your next message, even though the skill content [stays in context](#skill-content-lifecycle); invoking the skill again re-applies it for that turn. It does not restrict which tools are available: every tool remains callable, and your [permission settings](/docs/en/permissions.md) still govern tools that are not listed. To pre-approve tools for the whole session rather than a single turn, add allow rules to those permission settings instead.

615The `allowed-tools` field grants permission for the listed tools during the turn that invokes the skill, so Claude can use them without prompting you for approval. The grant clears when you send your next message, even though the skill content [stays in context](#skill-content-lifecycle); invoking the skill again re-applies it for that turn. It does not restrict which tools are available: every tool remains callable, and your [permission settings](https://code.claude.com/docs/en/permissions.md) still govern tools that are not listed. To pre-approve tools for the whole session rather than a single turn, add allow rules to those permission settings instead.

616616

617617Workspace trust doesn't gate this field. Claude Code applies a project skill's `allowed-tools` even in a `-p` run in a folder you've never trusted. A skill can grant itself broad tool access, so review the `allowed-tools` of skills checked into a repository before you run Claude Code there. To withhold the field from repository skills across your organization, see [When only managed permission rules apply](#when-only-managed-permission-rules-apply).

618618

from line 627

627627---

628628```

629629

630To remove tools from Claude's available pool while a skill is active, list them in `disallowed-tools` in the skill's frontmatter. The restriction clears when you send your next message. Like deny rules, the field can't remove [`EndConversation`](/docs/en/tools-reference#endconversation-tool-behavior) while any other tool remains. To block tools across all skills and prompts, add deny rules in your [permission settings](/docs/en/permissions.md).

630To remove tools from Claude's available pool while a skill is active, list them in `disallowed-tools` in the skill's frontmatter. The restriction clears when you send your next message. Like deny rules, the field can't remove [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior) while any other tool remains. To block tools across all skills and prompts, add deny rules in your [permission settings](https://code.claude.com/docs/en/permissions.md).

631631

632632#### When managed settings lock hooks to plugins

633633

634When your organization's managed settings list `hooks` in `strictPluginOnlyCustomization`, a personal or project skill whose frontmatter declares `hooks` loses its `allowed-tools` pre-approval, apart from the [skills that keep it](/docs/en/settings-reference.md#strictpluginonlycustomization-hooks).

634When your organization's managed settings list `hooks` in `strictPluginOnlyCustomization`, a personal or project skill whose frontmatter declares `hooks` loses its `allowed-tools` pre-approval, apart from the [skills that keep it](https://code.claude.com/docs/en/settings-reference.md#strictpluginonlycustomization-hooks).

635635

636* **Check**: type `/status` in a Claude Code session. If `/status` shows [`Enterprise managed settings`](/docs/en/settings#check-what-your-organization-enforces), ask your administrator whether `strictPluginOnlyCustomization` lists `hooks`.

637* **Fix**: remove `hooks` from the skill's frontmatter, because its hooks don't run under that setting. To keep them, [move the skill into a plugin](/docs/en/hooks.md#limits-on-skill-hooks) that you install from a marketplace.

636* **Check**: type `/status` in a Claude Code session. If `/status` shows [`Enterprise managed settings`](https://code.claude.com/docs/en/settings#check-what-your-organization-enforces), ask your administrator whether `strictPluginOnlyCustomization` lists `hooks`.

637* **Fix**: remove `hooks` from the skill's frontmatter, because its hooks don't run under that setting. To keep them, [move the skill into a plugin](https://code.claude.com/docs/en/hooks.md#limits-on-skill-hooks) that you install from a marketplace.

638638

639639#### When only managed permission rules apply

640640

641When your organization sets `allowManagedPermissionRulesOnly` in managed settings, Claude Code ignores `allowed-tools` in project and personal skills and in the [other sources the setting's entry lists](/docs/en/settings-reference.md#allowmanagedpermissionrulesonly). This requires Claude Code v2.1.282 or later.

641When your organization sets `allowManagedPermissionRulesOnly` in managed settings, Claude Code ignores `allowed-tools` in project and personal skills and in the [other sources the setting's entry lists](https://code.claude.com/docs/en/settings-reference.md#allowmanagedpermissionrulesonly). This requires Claude Code v2.1.282 or later.

642642

643643The tools an affected skill lists go through your organization's managed rules and the normal permission prompt instead. Run `/status` to list each skill whose `allowed-tools` Claude Code has ignored so far in the session. An injected command in the skill that no managed rule allows follows [Permission checks on injected commands](#permission-checks-on-injected-commands).

644644

from line 696

696696

697697When you type at the Claude Code prompt in your terminal, you can stack several skills at the start of one message. Through the Agent SDK or `claude -p`, Claude Code loads only the first skill, with the rest of the line as its arguments. At the terminal prompt, typing `/write-tests /fix-issue 123` loads both skills and passes the trailing text `123` as `$ARGUMENTS` to each of them.

698698

699Claude 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. If you stack 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 start with another command, such as `/loop`, expansion ends there. That token and everything after it become the argument text for every expanded skill.

699Claude 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. If you stack a skill that runs as a [forked subagent](#run-skills-in-a-subagent), such as [`/code-review`](https://code.claude.com/docs/en/code-review-local), or one whose arguments may start with another command, such as `/loop`, expansion ends there. That token and everything after it become the argument text for every expanded skill.

700700

701701## Advanced patterns

702702

from line 738

738738```

739739````

740740

741To disable this behavior for skills and custom commands from user, project, plugin, or [additional-directory](#skills-from-additional-directories) sources, set `"disableSkillShellExecution": true` in [settings](/docs/en/settings.md). Each command is replaced with `[shell command execution disabled by policy]` instead of being run. Bundled and managed skills are not affected. This setting is most useful in [managed settings](/docs/en/managed-settings.md), where users cannot override it.

741To disable this behavior for skills and custom commands from user, project, plugin, or [additional-directory](#skills-from-additional-directories) sources, set `"disableSkillShellExecution": true` in [settings](https://code.claude.com/docs/en/settings.md). Each command is replaced with `[shell command execution disabled by policy]` instead of being run. Bundled and managed skills are not affected. This setting is most useful in [managed settings](https://code.claude.com/docs/en/managed-settings.md), where users cannot override it.

742742

743743Claude Code never runs these commands on your machine when they appear in skills [synced from your claude.ai account](#how-synced-skills-behave), regardless of this setting. This restriction requires Claude Code v2.1.228 or later. [How Claude Code handles the body of a synced skill](#how-claude-code-handles-the-body-of-a-synced-skill) says what Claude receives in place of the command in each kind of session.

744744

745745> [!TIP]

746746>

747> To request deeper reasoning when a skill runs, include `ultrathink` anywhere in the skill content. See [Use ultrathink for one-off deep reasoning](/docs/en/model-config.md#use-ultrathink-for-one-off-deep-reasoning).

747> To request deeper reasoning when a skill runs, include `ultrathink` anywhere in the skill content. See [Use ultrathink for one-off deep reasoning](https://code.claude.com/docs/en/model-config.md#use-ultrathink-for-one-off-deep-reasoning).

748748

749749#### How injected commands run

750750

751751Claude Code picks the tool that runs a skill's injected commands from the `shell` key in the skill's frontmatter and your environment. Every combination runs the commands through the Bash tool or the PowerShell tool, except one that fails the invocation outright:

752752

753* `shell: powershell`, with the [PowerShell tool](/docs/en/tools-reference.md#powershell-tool) enabled: the commands run through the PowerShell tool.

753* `shell: powershell`, with the [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) enabled: the commands run through the PowerShell tool.

754754* `shell: bash` when bash isn't available: the invocation fails before any command runs. This happens on Windows without Git Bash. Claude Code shows ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``.

755755* Any other combination: the commands run through the Bash tool when bash is available. When it isn't, they run through the PowerShell tool.

756756

from line 758

758758

759759* **Working directory**: Claude Code runs each command in the session shell's current working directory. That directory moves when Claude runs `cd`. Use [`${CLAUDE_SKILL_DIR}` or `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions) in paths that must resolve the same way every time.

760760* **stderr**: with the default `bash` shell, Claude Code merges stderr into stdout. Anything the command writes to stderr appears in the injected text.

761* **Timeout**: each command runs under the Bash tool's default 2-minute [timeout](/docs/en/tools-reference.md#timeout-and-output-limits). When the Bash tool [moves a timed-out command to the background](/docs/en/tools-reference.md#foreground-commands-that-move-to-the-background), the skill still renders. The injected text reports the move and names the background task and the file collecting the command's output. When the command is one the Bash tool never auto-backgrounds, Claude Code kills it at the timeout. That failure [aborts the invocation](#when-an-injected-command-fails).

762* **Output size**: output past the Bash tool's inline ceiling arrives as a file path plus a short preview, not truncated text. [Output limits](/docs/en/tools-reference.md#output-limits) covers the ceiling and how to adjust each boundary.

761* **Timeout**: each command runs under the Bash tool's default 2-minute [timeout](https://code.claude.com/docs/en/tools-reference.md#timeout-and-output-limits). When the Bash tool [moves a timed-out command to the background](https://code.claude.com/docs/en/tools-reference.md#foreground-commands-that-move-to-the-background), the skill still renders. The injected text reports the move and names the background task and the file collecting the command's output. When the command is one the Bash tool never auto-backgrounds, Claude Code kills it at the timeout. That failure [aborts the invocation](#when-an-injected-command-fails).

762* **Output size**: output past the Bash tool's inline ceiling arrives as a file path plus a short preview, not truncated text. [Output limits](https://code.claude.com/docs/en/tools-reference.md#output-limits) covers the ceiling and how to adjust each boundary.

763763

764The PowerShell tool applies the same timeout, backgrounding, and output-ceiling behavior to the commands it runs. See the [PowerShell tool](/docs/en/tools-reference.md#powershell-tool) section for its specifics.

764The PowerShell tool applies the same timeout, backgrounding, and output-ceiling behavior to the commands it runs. See the [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) section for its specifics.

765765

766766#### When an injected command fails

767767

768768A failed command aborts the entire skill invocation, not just its own placeholder. Claude never sees the skill content for that invocation. The abort shows `Shell command failed for pattern "..."`. The error message includes the command's output.

769769

770With the default `bash` shell, any non-zero exit code counts as a failure. One carveout applies: Claude Code treats exit code 1 from [search and comparison commands](/docs/en/tools-reference.md#output-limits) as a normal result and injects their output. Exit codes of 2 or higher fail even for those commands.

770With the default `bash` shell, any non-zero exit code counts as a failure. One carveout applies: Claude Code treats exit code 1 from [search and comparison commands](https://code.claude.com/docs/en/tools-reference.md#output-limits) as a normal result and injects their output. Exit codes of 2 or higher fail even for those commands.

771771

772772Which commands get the carveout depends on the shell:

773773

774* Default `bash` shell: the commands listed under [Output limits](/docs/en/tools-reference.md#output-limits)

775* `shell: powershell`, when the PowerShell tool is enabled: a [different set](/docs/en/tools-reference.md#exit-code-1-from-searches-and-git-diff-in-powershell) that includes `grep` and `git diff` but not `find` or `diff`

774* Default `bash` shell: the commands listed under [Output limits](https://code.claude.com/docs/en/tools-reference.md#output-limits)

775* `shell: powershell`, when the PowerShell tool is enabled: a [different set](https://code.claude.com/docs/en/tools-reference.md#exit-code-1-from-searches-and-git-diff-in-powershell) that includes `grep` and `git diff` but not `find` or `diff`

776776

777777With 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.

778778

779779#### Control characters in injected commands

780780

781`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.md#no-shell-command-was-run).

782782

783783#### Permission checks on injected commands

784784

785Injected commands never prompt for permission while the skill renders. Claude Code checks each one against your [permission rules](/docs/en/permissions.md) first. A command a deny rule matches aborts the invocation with `Shell command permission check failed for pattern "..."`.

785Injected commands never prompt for permission while the skill renders. Claude Code checks each one against your [permission rules](https://code.claude.com/docs/en/permissions.md) first. A command a deny rule matches aborts the invocation with `Shell command permission check failed for pattern "..."`.

786786

787Outside [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), when a command's permission check returns anything other than allow, Claude Code aborts the invocation with the same error. This includes a rule that would normally ask you. To keep an unmatched command from aborting here, pre-approve it with [`allowed-tools`](#pre-approve-tools-for-a-skill). If your organization restricts permission rules to managed settings, see [When only managed permission rules apply](#when-only-managed-permission-rules-apply). Deny and ask rules still override `allowed-tools`. See [Manage permissions](/docs/en/permissions.md#manage-permissions).

787Outside [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), when a command's permission check returns anything other than allow, Claude Code aborts the invocation with the same error. This includes a rule that would normally ask you. To keep an unmatched command from aborting here, pre-approve it with [`allowed-tools`](#pre-approve-tools-for-a-skill). If your organization restricts permission rules to managed settings, see [When only managed permission rules apply](#when-only-managed-permission-rules-apply). Deny and ask rules still override `allowed-tools`. See [Manage permissions](https://code.claude.com/docs/en/permissions.md#manage-permissions).

788788

789In auto mode, a command that would otherwise need your approval doesn't abort the invocation. The skill loads with an instruction telling Claude to run the command first, and Claude's own call then goes through [auto mode's usual checks](/docs/en/permission-modes.md#how-the-classifier-evaluates-actions). The invocation still aborts in a [forked skill](#run-skills-in-a-subagent) that sets `agent`, and in a session where Claude doesn't have the [shell tool that runs injected commands](#how-injected-commands-run).

789In auto mode, a command that would otherwise need your approval doesn't abort the invocation. The skill loads with an instruction telling Claude to run the command first, and Claude's own call then goes through [auto mode's usual checks](https://code.claude.com/docs/en/permission-modes.md#how-the-classifier-evaluates-actions). The invocation still aborts in a [forked skill](#run-skills-in-a-subagent) that sets `agent`, and in a session where Claude doesn't have the [shell tool that runs injected commands](#how-injected-commands-run).

790790

791791### Run skills in a subagent

792792

from line 794

794794

795795> [!NOTE]

796796>

797> Despite the name, a skill with `context: fork` doesn't run in a [fork of the current conversation](/docs/en/sub-agents.md#fork-the-current-conversation), which would hand the subagent everything you've discussed so far. When the task depends on that history, fork the conversation instead of using `context: fork`.

797> Despite the name, a skill with `context: fork` doesn't run in a [fork of the current conversation](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation), which would hand the subagent everything you've discussed so far. When the task depends on that history, fork the conversation instead of using `context: fork`.

798798

799The forked subagent runs in the [background](/docs/en/sub-agents.md#run-subagents-in-foreground-or-background): you keep working while it runs, and its result arrives in your conversation when it completes. Set `background: false` in the frontmatter to instead wait for the result in the turn that invoked the skill. Before v2.1.218, forked skills always blocked the turn until they finished.

799The forked subagent runs in the [background](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background): you keep working while it runs, and its result arrives in your conversation when it completes. Set `background: false` in the frontmatter to instead wait for the result in the turn that invoked the skill. Before v2.1.218, forked skills always blocked the turn until they finished.

800800

801801Claude Code also waits for the result, even when the skill doesn't set `background: false`, in cases like these:

802802

803803* In non-interactive mode, with the `-p` flag or the Agent SDK

804* When you set [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/en/env-vars) to `1`, which also turns off other background task features

804* When you set [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/en/env-vars) to `1`, which also turns off other background task features

805805* When you invoke a forked skill while an earlier invocation of the same skill is still running

806* When a [session-scoped scheduled task](/docs/en/scheduled-tasks.md) fires with the skill as its prompt

806* When a [session-scoped scheduled task](https://code.claude.com/docs/en/scheduled-tasks.md) fires with the skill as its prompt

807807

808When an agent in a [dynamic workflow](/docs/en/workflows.md) invokes a forked skill, that agent waits for and receives the result, even when the skill doesn't set `background: false`. Before v2.1.295, when the skill ran in the background, that agent didn't wait for it. The skill's result then arrived in your main conversation instead of reaching the agent.

808When an agent in a [dynamic workflow](https://code.claude.com/docs/en/workflows.md) invokes a forked skill, that agent waits for and receives the result, even when the skill doesn't set `background: false`. Before v2.1.295, when the skill ran in the background, that agent didn't wait for it. The skill's result then arrived in your main conversation instead of reaching the agent.

809809

810A backgrounded fork also runs with the [narrower tool set that applies to background subagents](/docs/en/sub-agents.md#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.

810A backgrounded fork also runs with the [narrower tool set that applies to background subagents](https://code.claude.com/docs/en/sub-agents.md#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.

811811

812A forked skill that runs in the background applies its edits outside your session's [checkpoints](/docs/en/checkpointing.md#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.

812A forked skill that runs in the background applies its edits outside your session's [checkpoints](https://code.claude.com/docs/en/checkpointing.md#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.

813813

814814> [!WARNING]

815815>

816816> `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.

817817

818Skills and [subagents](/docs/en/sub-agents.md) work together in two directions:

818Skills and [subagents](https://code.claude.com/docs/en/sub-agents.md) work together in two directions:

819819

821821| :- | :- | :- | :- |

823| Subagent with `skills` field | Subagent's markdown body | Claude's delegation message | Preloaded skills + CLAUDE.md, per the subagent's [startup context](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup) |

824824

825With `context: fork`, you write the task in your skill and pick an agent type to execute it. The built-in Explore and Plan agents [start without CLAUDE.md and git status](/docs/en/sub-agents.md#what-loads-at-startup) to keep their context small. Put everything the task needs in your SKILL.md. A forked skill using `agent: Explore` starts with that content and the agent's own system prompt, and none of your CLAUDE.md files.

825With `context: fork`, you write the task in your skill and pick an agent type to execute it. The built-in Explore and Plan agents [start without CLAUDE.md and git status](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup) to keep their context small. Put everything the task needs in your SKILL.md. A forked skill using `agent: Explore` starts with that content and the agent's own system prompt, and none of your CLAUDE.md files.

826826

827For the inverse, where you define a custom subagent that uses skills as reference material, see [Subagents](/docs/en/sub-agents.md#preload-skills-into-subagents).

827For the inverse, where you define a custom subagent that uses skills as reference material, see [Subagents](https://code.claude.com/docs/en/sub-agents.md#preload-skills-into-subagents).

828828

829829#### Example: Research skill using Explore agent

830830

from line 856

856856

857857### Restrict Claude's skill access

858858

859By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Skills that define [`allowed-tools`](#pre-approve-tools-for-a-skill) grant Claude access to those tools without per-use approval during the turn that invokes the skill; the grant clears when you send your next message. Your [permission settings](/docs/en/permissions.md) still govern baseline approval behavior for all other tools. A few built-in commands are also available through the Skill tool, including `/init` and `/security-review`. Other built-in commands such as `/compact` are not.

859By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Skills that define [`allowed-tools`](#pre-approve-tools-for-a-skill) grant Claude access to those tools without per-use approval during the turn that invokes the skill; the grant clears when you send your next message. Your [permission settings](https://code.claude.com/docs/en/permissions.md) still govern baseline approval behavior for all other tools. A few built-in commands are also available through the Skill tool, including `/init` and `/security-review`. Other built-in commands such as `/compact` are not.

860860

861861Three ways to control which skills Claude can invoke:

862862

from line 867

867867Skill

868868```

869869

870**Allow or deny specific skills** using [permission rules](/docs/en/permissions.md):

870**Allow or deny specific skills** using [permission rules](https://code.claude.com/docs/en/permissions.md):

871871

872872```text theme={null}

873873# Allow only specific skills

from line 888

888888| An unqualified name | `Skill(deploy)` | A [nested skill](#where-skills-live) listed as `apps/web:deploy` |

889889| A [skill synced from claude.ai](#how-synced-skills-behave) | `Skill(anthropic-skills:deploy)` | That skill when Claude Desktop delivers it to a session as a plugin |

890890| The plugin form of a synced skill | `Skill(deploy:deploy)` | The synced skill |

891| A skill in the [parameter form](/docs/en/permissions.md#match-by-input-parameter) | `Skill(skill:deploy)` | The skill whichever of its names Claude calls it by, including its alias and display name |

891| A skill in the [parameter form](https://code.claude.com/docs/en/permissions.md#match-by-input-parameter) | `Skill(skill:deploy)` | The skill whichever of its names Claude calls it by, including its alias and display name |

892892

893893Before v2.1.260, Claude Code didn't block a nested skill listed under its qualified name when the deny rule named only the unqualified name.

894894

from line 906

906906

907907### Override skill visibility from settings

908908

909The `skillOverrides` setting controls skill visibility from your [settings](/docs/en/settings.md) instead of the skill's own frontmatter. Use it for skills whose SKILL.md you don't want to edit, such as ones checked into a shared project repo. The `/skills` menu writes it for you: highlight a skill and press `Space` to cycle states, then `Esc` to save to `.claude/settings.local.json`.

909The `skillOverrides` setting controls skill visibility from your [settings](https://code.claude.com/docs/en/settings.md) instead of the skill's own frontmatter. Use it for skills whose SKILL.md you don't want to edit, such as ones checked into a shared project repo. The `/skills` menu writes it for you: highlight a skill and press `Space` to cycle states, then `Esc` to save to `.claude/settings.local.json`.

910910

911911Each key is a skill name and each value is one of four states:

912912

from line 919

919919

920920The `/skills` menu labels the `"user-invocable-only"` state `user-only`.

921921

922`"off"` also hides the skill from the command lists advertised to [Remote Control](/docs/en/remote-control.md) clients and to [Agent SDK](/docs/en/agent-sdk/skills.md#discover-available-commands) callers, in addition to the terminal `/` menu. Invoking a hidden skill by its full name returns the `skillOverrides` error instead of running it.

922`"off"` also hides the skill from the command lists advertised to [Remote Control](https://code.claude.com/docs/en/remote-control.md) clients and to [Agent SDK](https://code.claude.com/docs/en/agent-sdk/skills.md#discover-available-commands) callers, in addition to the terminal `/` menu. Invoking a hidden skill by its full name returns the `skillOverrides` error instead of running it.

923923

924924A skill that is absent from `skillOverrides` is treated as `"on"`. The example below collapses one skill to its name and turns another off entirely:

925925

from line 932

932932}

933933```

934934

935Some bundled skills have aliases, such as `checkup` for `/doctor`. If you set a `skillOverrides` entry under an alias in [managed settings](/docs/en/managed-settings.md) or in a file you pass with the `--settings` flag, Claude Code applies it to the skill behind the alias. You can only restrict a skill further through an alias, never make it more visible, and if you also set an entry under the skill's own name in managed settings, that entry takes precedence. Before v2.1.260, Claude Code didn't apply an entry under an alias to the skill in any settings source.

935Some bundled skills have aliases, such as `checkup` for `/doctor`. If you set a `skillOverrides` entry under an alias in [managed settings](https://code.claude.com/docs/en/managed-settings.md) or in a file you pass with the `--settings` flag, Claude Code applies it to the skill behind the alias. You can only restrict a skill further through an alias, never make it more visible, and if you also set an entry under the skill's own name in managed settings, that entry takes precedence. Before v2.1.260, Claude Code didn't apply an entry under an alias to the skill in any settings source.

936936

937937In user, project, and local settings, Claude Code matches entries against skill names only. If you set an entry for `review` there, it applies to a skill named `review`, not to the bundled `/code-review` through its `/review` alias.

938938

from line 940

940940

941941### Find unused skills

942942

943Every skill in the [skill listing](#skill-descriptions-are-cut-short) adds to your context on every turn, whether or not Claude ever uses it. Run `/skill-doctor` to see what each of your skills costs and how often it gets used, so you can decide which ones to turn off. In an interactive session, the report opens in the `/plugin` manager's **Stats** tab. In [non-interactive mode](/docs/en/headless.md) with `-p`, Claude Code prints it as text.

943Every skill in the [skill listing](#skill-descriptions-are-cut-short) adds to your context on every turn, whether or not Claude ever uses it. Run `/skill-doctor` to see what each of your skills costs and how often it gets used, so you can decide which ones to turn off. In an interactive session, the report opens in the `/plugin` manager's **Stats** tab. In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with `-p`, Claude Code prints it as text.

944944

945945The report covers the skills in your session other than bundled skills and enterprise skills. It flags skills in the listing that have never been invoked and says where to turn them off. Of the skills it tells you where to turn off, start with the ones that have the highest context cost. The report also lists plugins you haven't used recently.

946946

947`/skill-doctor` requires Claude Code v2.1.252 or later and isn't available in sessions that skip [feature-flag fetching](/docs/en/env-vars.md#features-that-need-feature-flag-fetching). If you run `/skill-doctor` over [Remote Control](/docs/en/remote-control.md) from your phone or browser, Claude Code replies [`Skill usage reports are not available on this connection.`](/docs/en/errors#skill-usage-reports-are-not-available-on-this-connection) instead. Run `/skill-doctor` in the terminal on the machine where the session is running.

947`/skill-doctor` requires Claude Code v2.1.252 or later and isn't available in sessions that skip [feature-flag fetching](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching). If you run `/skill-doctor` over [Remote Control](https://code.claude.com/docs/en/remote-control.md) from your phone or browser, Claude Code replies [`Skill usage reports are not available on this connection.`](https://code.claude.com/docs/en/errors#skill-usage-reports-are-not-available-on-this-connection) instead. Run `/skill-doctor` in the terminal on the machine where the session is running.

948948

949949## Evaluate and iterate on a skill

950950

from line 955

955955How you turn the skill off for the second run depends on where it comes from:

956956

957957* **Personal or project skill**: set it to `"off"` in [`skillOverrides`](#override-skill-visibility-from-settings).

958* **Skill that a plugin provides**: `skillOverrides` doesn't apply to plugin skills. Use [`claude plugin eval`](/docs/en/plugin-evals#the-no-plugin-baseline) instead, which repeats each run with no plugin loaded.

958* **Skill that a plugin provides**: `skillOverrides` doesn't apply to plugin skills. Use [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals#the-no-plugin-baseline) instead, which repeats each run with no plugin loaded.

959959

960Two tools automate the baseline comparison. For a skill that ships in a [plugin](/docs/en/plugins/overview.md), [`claude plugin eval`](/docs/en/plugin-evals) runs each prompt in an isolated session with and without the plugin, scores it with graders you define or that it writes for you, and exits non-zero below a threshold so you can gate CI on it. For iterating on a single skill inside a Claude Code conversation, the skill-creator plugin below runs a similar loop with its own `evals/evals.json` format. The two formats aren't interchangeable.

960Two tools automate the baseline comparison. For a skill that ships in a [plugin](https://code.claude.com/docs/en/plugins/overview.md), [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals) runs each prompt in an isolated session with and without the plugin, scores it with graders you define or that it writes for you, and exits non-zero below a threshold so you can gate CI on it. For iterating on a single skill inside a Claude Code conversation, the skill-creator plugin below runs a similar loop with its own `evals/evals.json` format. The two formats aren't interchangeable.

961961

962962### Run evals with skill-creator

963963

964The [`skill-creator` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator) automates the comparison loop inside Claude Code. In the VS Code extension or the desktop app, install it from the official marketplace by following [Install a plugin](/docs/en/plugins/install.md#install-a-plugin). In a terminal, start Claude Code by running `claude`, then enter this at its prompt:

964The [`skill-creator` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator) automates the comparison loop inside Claude Code. In the VS Code extension or the desktop app, install it from the official marketplace by following [Install a plugin](https://code.claude.com/docs/en/plugins/install.md#install-a-plugin). In a terminal, start Claude Code by running `claude`, then enter this at its prompt:

965965

966966```text theme={null}

967967/plugin install skill-creator@claude-plugins-official

from line 970

970970If the install fails, match the message Claude Code reports:

971971

972972* `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.

973* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](/docs/en/plugins/troubleshooting.md#plugin-not-found-in-marketplace).

973* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-not-found-in-marketplace).

974974

975975If the install summary reports `Run /reload-plugins to apply.`, Claude Code then runs that reload for you. If the reload warns that your next message would re-read the conversation, run `/reload-plugins --force` to make the plugin's skills available in the current session. Then ask Claude to evaluate an existing skill, for example `evaluate my summarize-changes skill with skill-creator`. The plugin walks you through writing test cases and runs the loop:

976976

977977* **Test cases**: stores prompts, input files, and expected behavior in `evals/evals.json` inside the skill directory

978* **Isolated runs**: spawns a [subagent](/docs/en/sub-agents.md) per test case so each run starts with a clean context, and records token count and duration

978* **Isolated runs**: spawns a [subagent](https://code.claude.com/docs/en/sub-agents.md) per test case so each run starts with a clean context, and records token count and duration

979979* **Grading**: checks each assertion against the output and writes pass or fail with evidence to `grading.json`

980980* **Benchmark**: aggregates pass rate, time, and tokens for with-skill versus without-skill into `benchmark.json` so you can compare the pass-rate improvement against the token and time overhead

981981* **Version comparison**: runs a blind A/B between two versions of the skill so you can confirm an edit is an improvement before committing it

from line 989

989989Skills can be distributed at different scopes depending on your audience:

990990

991991* **Project skills**: Commit `.claude/skills/` to version control

992* **Plugins**: Create a `skills/` directory in your [plugin](/docs/en/plugins/overview.md)

993* **Managed**: Deploy organization-wide through [managed settings](/docs/en/managed-settings.md)

992* **Plugins**: Create a `skills/` directory in your [plugin](https://code.claude.com/docs/en/plugins/overview.md)

993* **Managed**: Deploy organization-wide through [managed settings](https://code.claude.com/docs/en/managed-settings.md)

994994

995995### Generate visual output

996996

from line 1194

119411943. Try rephrasing your request to match the description more closely

119511954. Invoke it directly with `/skill-name` if the skill is user-invocable

119611965. If `/skill-name` isn't recognized either, check whether Claude Code [refused the skill's name](#characters-a-skill-name-cant-hold)

11976. If the skill sets `paths`, check that the files Claude reads, edits, or writes are inside Claude's current working directory. The skill doesn't activate for files outside it, such as those in a sibling git worktree, even one you added with `/add-dir`. To have the skill activate for those files, start Claude Code in that worktree or [move the session there with `/cd`](/docs/en/permissions#move-the-session-to-another-directory).

11976. If the skill sets `paths`, check that the files Claude reads, edits, or writes are inside Claude's current working directory. The skill doesn't activate for files outside it, such as those in a sibling git worktree, even one you added with `/add-dir`. To have the skill activate for those files, start Claude Code in that worktree or [move the session there with `/cd`](https://code.claude.com/docs/en/permissions#move-the-session-to-another-directory).

11981198

11991199If the frontmatter YAML is malformed, Claude Code loads the skill body with empty metadata, so `/skill-name` still works but Claude can't match against your `description`. Run with `--debug` to see the parse error.

12001200

1201If the skill ships in a plugin, you can measure how often it triggers across realistic prompts rather than checking one at a time: write an eval case with a [`tool_used: Skill` grader](/docs/en/plugin-evals#create-your-first-eval-suite) and run it with `claude plugin eval` after each description change.

1201If the skill ships in a plugin, you can measure how often it triggers across realistic prompts rather than checking one at a time: write an eval case with a [`tool_used: Skill` grader](https://code.claude.com/docs/en/plugin-evals#create-your-first-eval-suite) and run it with `claude plugin eval` after each description change.

12021202

1203To find `SKILL.md` files whose frontmatter doesn't parse, run [`claude plugin validate`](/docs/en/plugins/cli-reference#validate-a-directory) on the skills directory, for example `claude plugin validate .claude/skills` for project skills or `claude plugin validate ~/.claude/skills` for personal skills. Requires Claude Code v2.1.233 or later.

1203To find `SKILL.md` files whose frontmatter doesn't parse, run [`claude plugin validate`](https://code.claude.com/docs/en/plugins/cli-reference#validate-a-directory) on the skills directory, for example `claude plugin validate .claude/skills` for project skills or `claude plugin validate ~/.claude/skills` for personal skills. Requires Claude Code v2.1.233 or later.

12041204

12051205### Skill triggers too often

12061206

from line 1213

12131213

12141214If Claude follows a skill in its first response and stops following it later, start with whichever of these cases matches:

12151215

1216* **Claude skipped a rule that must hold every time**: move the rule into a [hook](/docs/en/hooks-guide.md). Claude Code runs a hook every time its event occurs, such as before each file edit, whether or not Claude is following the skill. To keep the rule with the skill, define the hook in the skill's [`hooks` frontmatter](/docs/en/hooks#hooks-in-skills-and-agents). That hook applies from the time the skill is invoked until the session ends.

1216* **Claude skipped a rule that must hold every time**: move the rule into a [hook](https://code.claude.com/docs/en/hooks-guide.md). Claude Code runs a hook every time its event occurs, such as before each file edit, whether or not Claude is following the skill. To keep the rule with the skill, define the hook in the skill's [`hooks` frontmatter](https://code.claude.com/docs/en/hooks#hooks-in-skills-and-agents). That hook applies from the time the skill is invoked until the session ends.

12171217* **Claude skipped guidance it should apply with judgment**: word the guidance so it applies to the whole task, for example "Run the tests after every edit" rather than "Run the tests". Claude Code adds the skill's content to the conversation when the skill is invoked and [doesn't re-read the file](#skill-content-lifecycle) on later turns.

1218* **The conversation was compacted**: invoke the skill again to restore its full content. After [compaction](/docs/en/how-claude-code-works.md#when-context-fills-up), Claude Code [can keep only the start of an invoked skill](#skill-content-lifecycle), so put the most important instructions near the top of `SKILL.md`.

1218* **The conversation was compacted**: invoke the skill again to restore its full content. After [compaction](https://code.claude.com/docs/en/how-claude-code-works.md#when-context-fills-up), Claude Code [can keep only the start of an invoked skill](#skill-content-lifecycle), so put the most important instructions near the top of `SKILL.md`.

12191219

12201220### Skill descriptions are cut short

12211221

12221222Claude Code loads a listing of skill names and descriptions into context so Claude knows what's available. The listing always contains every skill name, but if you have many skills, Claude Code drops some descriptions to fit the listing's character budget, which removes the keywords Claude needs to match your request. The budget scales at 1% of the model's context window. When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least, so the skills you use most keep their full text.

12231223

1224Run `/doctor` for an estimate of the listing's context cost and its biggest contributors. To find skills worth turning off, run [`/skill-doctor`](#find-unused-skills). When the listing exceeds its budget, Claude Code also writes a warning to the debug log, visible with [`--debug`](/docs/en/cli-reference#cli-flags).

12251225

12261226The Skills row in `/context` reports the size of the listing after the budget is applied, so it matches what the model receives. Before v2.1.196, the row counted the full text of every description and could show a value several times larger than the configured budget.

12271227

1228To raise the budget, set the [`skillListingBudgetFraction`](/docs/en/settings-reference#skilllistingbudgetfraction) setting (for example, `0.02` = 2%) or the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable to a fixed character count. To free budget for other skills, set low-priority entries to `"name-only"` in [`skillOverrides`](#override-skill-visibility-from-settings) so they list without a description. You can also trim the `description` and `when_to_use` text at the source: put the key use case first, since each entry's combined text is capped at 1,536 characters regardless of budget. The cap is configurable with [`skillListingMaxDescChars`](/docs/en/settings-reference#skilllistingmaxdescchars).

1228To raise the budget, set the [`skillListingBudgetFraction`](https://code.claude.com/docs/en/settings-reference#skilllistingbudgetfraction) setting (for example, `0.02` = 2%) or the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable to a fixed character count. To free budget for other skills, set low-priority entries to `"name-only"` in [`skillOverrides`](#override-skill-visibility-from-settings) so they list without a description. You can also trim the `description` and `when_to_use` text at the source: put the key use case first, since each entry's combined text is capped at 1,536 characters regardless of budget. The cap is configurable with [`skillListingMaxDescChars`](https://code.claude.com/docs/en/settings-reference#skilllistingmaxdescchars).

12291229

12301230### Personal skills disappeared

12311231

from line 1233

12331233

12341234Before v2.1.280, a file named `manifest.json` in `~/.claude/skills/` caused Claude Code to move the skill folders that file listed into a timestamped folder under `~/.claude/skills/.trash/`, and those skills stopped loading.

12351235

1236To restore a skill, move its folder from the timestamped folder back into `~/.claude/skills/`. Do this before the [retention sweep](/docs/en/claude-directory.md#cleaned-up-automatically) deletes trash entries, by default 30 days after they were moved to the trash.

1236To restore a skill, move its folder from the timestamped folder back into `~/.claude/skills/`. Do this before the [retention sweep](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically) deletes trash entries, by default 30 days after they were moved to the trash.

12371237

12381238## Related resources

12391239

1240* **[Debug your configuration](/docs/en/debug-your-config.md)**: diagnose why a skill isn't appearing or triggering

1240* **[Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md)**: diagnose why a skill isn't appearing or triggering

12411241* **[Evaluating skill output quality](https://agentskills.io/skill-creation/evaluating-skills)**: the eval file format and iteration workflow on agentskills.io

12421242* **[Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)**: writing guidance that applies across Claude products

1243* **[Subagents](/docs/en/sub-agents.md)**: delegate tasks to specialized agents

1244* **[Plugins](/docs/en/plugins/overview.md)**: package and distribute skills with other extensions

1245* **[Hooks](/docs/en/hooks.md)**: automate workflows around tool events

1246* **[Memory](/docs/en/memory.md)**: manage CLAUDE.md files for persistent context

1247* **[Commands](/docs/en/commands.md)**: reference for built-in commands and bundled skills

1248* **[Permissions](/docs/en/permissions.md)**: control tool and skill access

1243* **[Subagents](https://code.claude.com/docs/en/sub-agents.md)**: delegate tasks to specialized agents

1244* **[Plugins](https://code.claude.com/docs/en/plugins/overview.md)**: package and distribute skills with other extensions

1245* **[Hooks](https://code.claude.com/docs/en/hooks.md)**: automate workflows around tool events

1246* **[Memory](https://code.claude.com/docs/en/memory.md)**: manage CLAUDE.md files for persistent context

1247* **[Commands](https://code.claude.com/docs/en/commands.md)**: reference for built-in commands and bundled skills

1248* **[Permissions](https://code.claude.com/docs/en/permissions.md)**: control tool and skill access

12491249* **[Claude Tag skills](https://claude.com/docs/claude-tag/admins/skills-repo)**: project skills committed to a repo also load when that repo is used in a Claude Tag channel

12501250

slack Changed · +6 / -6 lines

from line 29

2929| :- | :- |

3030| Claude Plan | Pro or Max |

3131| Slack workspace | Not connected to [Claude Tag](https://claude.com/docs/claude-tag/overview) by any organization. If @Claude replies with the [retirement notice](#the-legacy-claude-in-slack-bot-is-retired), the workspace is connected |

32| Cloud sessions | [Cloud sessions](/docs/en/claude-code-on-the-web.md) are enabled for your account |

32| Cloud sessions | [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) are enabled for your account |

3333| GitHub Account | Connected at [claude.ai/code](https://claude.ai/code) with at least one repository authenticated |

3434| Slack Authentication | Your Slack account linked to your Claude account via the Claude app |

3535

from line 151

151151**At claude.ai/code**: The complete Claude Code session with full conversation history, all code changes, and file operations. Sessions stay in your Claude Code history at [claude.ai/code](https://claude.ai/code), where you can continue past sessions, reference them, or create pull requests.

152152

153153For Enterprise and Team accounts, sessions created from Claude in Slack are

154automatically visible to the organization. See [cloud session sharing](/docs/en/claude-code-on-the-web.md#share-sessions)

154automatically visible to the organization. See [cloud session sharing](https://code.claude.com/docs/en/claude-code-on-the-web.md#share-sessions)

155155for more details.

156156

157157## Best practices

from line 188

188188

189189### "Claude Code is not enabled for your account"

190190

191This error means your Claude account has no cloud environment yet. Sign in at [claude.ai/code](https://claude.ai/code) once with the same account you connected to Slack and finish [web onboarding](/docs/en/web-quickstart.md#connect-github), which creates your default cloud environment or asks you to create it. The error clears on your next mention. Each user must do this individually.

191This error means your Claude account has no cloud environment yet. Sign in at [claude.ai/code](https://claude.ai/code) once with the same account you connected to Slack and finish [web onboarding](https://code.claude.com/docs/en/web-quickstart.md#connect-github), which creates your default cloud environment or asks you to create it. The error clears on your next mention. Each user must do this individually.

192192

193193### Sessions not starting

194194

from line 200

200200

201201This entry applies to workspaces using [Claude Tag](https://claude.com/docs/claude-tag/overview), where Claude works in channels as your organization's shared identity, not as any member's account. If you created the channel's cloud environment at [claude.ai/code](https://claude.ai/code), it belongs to your personal account, and Claude can't start channel sessions in a personal environment. Claude Code fails the session immediately, and retrying doesn't help.

202202

203If you're an Owner and the environment is your own, [share it with the organization](/docs/en/cloud-environments.md#organization-shared-environments) from the environment selector. Otherwise, an Owner recreates it as an organization-shared environment from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings).

203If you're an Owner and the environment is your own, [share it with the organization](https://code.claude.com/docs/en/cloud-environments.md#organization-shared-environments) from the environment selector. Otherwise, an Owner recreates it as an organization-shared environment from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings).

204204

205205You can apply it in two ways:

206206

from line 229

229229

230230* **GitHub only**: repositories must be on GitHub.

231231* **One PR at a time**: each session can create one pull request.

232* **Cloud session access required**: users need access to [cloud sessions](/docs/en/claude-code-on-the-web.md).

232* **Cloud session access required**: users need access to [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md).

233233

234234## Related resources

235235

236> **[Claude Code in the cloud](/docs/en/claude-code-on-the-web.md)**

236> **[Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md)**

237237>

238238> Learn more about cloud sessions

239239

statusline Changed · +30 / -30 lines

from line 11

1111* Work across multiple sessions and need to distinguish them

1212* Want git branch and status always visible

1313

14The status line renders in its own row above the built-in footer badges and does not replace them. With a custom status line configured, Claude Code stops showing most of the footer's keyboard hints, including `esc to interrupt`, the `? for shortcuts` fallback, and the `hold space to speak` [voice dictation](/docs/en/voice-dictation.md) hint. To add clickable link badges to the footer when an ID appears in the conversation, without writing a script, configure [`footerLinksRegexes`](/docs/en/settings-reference#footerlinksregexes) instead.

14The status line renders in its own row above the built-in footer badges and does not replace them. With a custom status line configured, Claude Code stops showing most of the footer's keyboard hints, including `esc to interrupt`, the `? for shortcuts` fallback, and the `hold space to speak` [voice dictation](https://code.claude.com/docs/en/voice-dictation.md) hint. To add clickable link badges to the footer when an ID appears in the conversation, without writing a script, configure [`footerLinksRegexes`](https://code.claude.com/docs/en/settings-reference#footerlinksregexes) instead.

1515

1616Here's an example of a [multi-line status line](#display-multiple-lines) that displays git info on the first line and a color-coded context bar on the second.

1717

from line 35

3535

3636### Manually configure a status line

3737

38Add a `statusLine` field to your user settings (`~/.claude/settings.json`, where `~` is your home directory) or [project settings](/docs/en/settings.md#where-settings-live). Set `type` to `"command"` and point `command` to a script path or an inline shell command. For a full walkthrough of creating a script, see [Build a status line step by step](#build-a-status-line-step-by-step).

38Add a `statusLine` field to your user settings (`~/.claude/settings.json`, where `~` is your home directory) or [project settings](https://code.claude.com/docs/en/settings.md#where-settings-live). Set `type` to `"command"` and point `command` to a script path or an inline shell command. For a full walkthrough of creating a script, see [Build a status line step by step](#build-a-status-line-step-by-step).

3939

4040```json theme={null}

4141{

from line 171

171171| `cwd`, `workspace.current_dir` | Current working directory. Both fields contain the same value; `workspace.current_dir` is preferred for consistency with `workspace.project_dir`. |

172172| `workspace.project_dir` | Directory where Claude Code was launched, which may differ from `cwd` if the working directory changes during a session |

173173| `workspace.added_dirs` | Additional directories added via `/add-dir` or `--add-dir`. Empty array if none have been added |

174| `workspace.git_worktree` | Git worktree name when the current directory is inside a linked worktree created with `git worktree add`. Absent in the main working tree. Populated for any git worktree, unlike `worktree.*`, which is present only while the session is in a [worktree session](/docs/en/worktrees.md) |

175175| `workspace.repo.host`, `workspace.repo.owner`, `workspace.repo.name` | Repository identity parsed from the `origin` remote, for example, `"github.com"`, `"anthropics"`, `"claude-code"`. Absent outside a git repository or when no `origin` remote is configured. For a gitlab.com project nested in subgroups, `owner` is the full namespace path with slashes, such as `"group/subgroup"`. Before v2.1.260, `workspace.repo` was absent for these projects |

176| `cost.total_cost_usd` | Estimated session cost in USD, computed client-side at list price unless a [`modelPricing`](/docs/en/settings-reference#modelpricing) table is in effect. May differ from your actual bill. Resets to \$0 when `/clear` starts a new session |

176| `cost.total_cost_usd` | Estimated session cost in USD, computed client-side at list price unless a [`modelPricing`](https://code.claude.com/docs/en/settings-reference#modelpricing) table is in effect. May differ from your actual bill. Resets to \$0 when `/clear` starts a new session |

177177| `cost.total_duration_ms` | Total wall-clock time the session has been running, in milliseconds. Accumulates across resumes and doesn't include time while the session isn't running |

178178| `cost.total_api_duration_ms` | Total time spent waiting for API responses in milliseconds |

179179| `cost.total_lines_added`, `cost.total_lines_removed` | Lines of code changed |

from line 183

183183| `context_window.remaining_percentage` | Pre-calculated percentage of context window remaining |

184184| `context_window.current_usage` | Token counts from the last API call, described in [context window fields](#context-window-fields) |

185185| `exceeds_200k_tokens` | Whether the total token count (input, cache, and output tokens combined) from the most recent API response exceeds 200k. This is a fixed threshold regardless of actual context window size. |

186| `fast_mode` | Whether [fast mode](/docs/en/fast-mode.md) is enabled for the session |

186| `fast_mode` | Whether [fast mode](https://code.claude.com/docs/en/fast-mode.md) is enabled for the session |

187187| `effort.level` | Current reasoning effort (`low`, `medium`, `high`, `xhigh`, or `max`). Reflects the live session value, including mid-session `/effort` changes. Absent when the current model does not support the effort parameter |

188188| `thinking.enabled` | Whether extended thinking is enabled for the session |

189189| `rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage` | Percentage of the 5-hour or 7-day rate limit consumed, from 0 to 100 |

from line 190

190190| `rate_limits.five_hour.resets_at`, `rate_limits.seven_day.resets_at` | Unix epoch seconds when the 5-hour or 7-day rate limit window resets |

191191| `rate_limits.spend_limit.used_percentage`, `rate_limits.spend_limit.resets_at` | Behind a Claude apps gateway, how much of your spend limit you have used and when its period resets. See [spend limit fields](#spend-limit-fields). Requires Claude Code v2.1.251 or later |

192192| `rate_limits.spend_limit.used_usd`, `rate_limits.spend_limit.limit_usd`, `rate_limits.spend_limit.period` | Your estimated spend and your limit in US dollars, and the limit's period. These fields can be absent. See [spend limit fields](#spend-limit-fields). Requires v2.1.284 or later on both Claude Code and the gateway |

193| `prompt_cache` | The session's [prompt cache](/docs/en/prompt-caching.md) statistics for the main conversation: hit ratio, misses, and whether the cache is warm. See [prompt cache fields](#prompt-cache-fields) for every field. Absent until the main conversation's first API response. Requires Claude Code v2.1.251 or later |

193| `prompt_cache` | The session's [prompt cache](https://code.claude.com/docs/en/prompt-caching.md) statistics for the main conversation: hit ratio, misses, and whether the cache is warm. See [prompt cache fields](#prompt-cache-fields) for every field. Absent until the main conversation's first API response. Requires Claude Code v2.1.251 or later |

194194| `session_id` | Unique session identifier |

195| `session_name` | Session name. Uses the custom name set with the `--name` flag or `/rename` when one exists, otherwise the AI-generated session title. The [default display name](/docs/en/sessions.md#name-your-sessions), such as `my-app-3f`, doesn't populate this field. Absent when the session has neither a custom name nor an AI-generated title |

196| `prompt_id` | UUID identifying the user prompt currently being processed. Matches the [`prompt.id` attribute on OpenTelemetry events](/docs/en/monitoring-usage#event-correlation-attributes). Absent until the first user input |

195| `session_name` | Session name. Uses the custom name set with the `--name` flag or `/rename` when one exists, otherwise the AI-generated session title. The [default display name](https://code.claude.com/docs/en/sessions.md#name-your-sessions), such as `my-app-3f`, doesn't populate this field. Absent when the session has neither a custom name nor an AI-generated title |

196| `prompt_id` | UUID identifying the user prompt currently being processed. Matches the [`prompt.id` attribute on OpenTelemetry events](https://code.claude.com/docs/en/monitoring-usage#event-correlation-attributes). Absent until the first user input |

197197| `transcript_path` | Path to conversation transcript file |

198198| `version` | Claude Code version |

199199| `output_style.name` | Name of the current output style |

200| `vim.mode` | Current vim mode (`NORMAL`, `INSERT`, `VISUAL`, or `VISUAL LINE`) when [vim mode](/docs/en/interactive-mode.md#vim-editor-mode) is enabled |

200| `vim.mode` | Current vim mode (`NORMAL`, `INSERT`, `VISUAL`, or `VISUAL LINE`) when [vim mode](https://code.claude.com/docs/en/interactive-mode.md#vim-editor-mode) is enabled |

201201| `agent.name` | Agent name when running with the `--agent` flag or agent settings configured |

202| `pr.number`, `pr.url` | Open pull request for the current branch. Mirrors the PR badge in the footer. In a repository with a GitLab remote, Claude Code fills these fields from the branch's open [merge request](/docs/en/interactive-mode.md#gitlab-merge-requests) instead, so `pr.number` is the merge request number. Merge request data requires Claude Code v2.1.234 or later. Absent when not in a git repository, until a pull request or merge request is found, or once it merges or closes |

202| `pr.number`, `pr.url` | Open pull request for the current branch. Mirrors the PR badge in the footer. In a repository with a GitLab remote, Claude Code fills these fields from the branch's open [merge request](https://code.claude.com/docs/en/interactive-mode.md#gitlab-merge-requests) instead, so `pr.number` is the merge request number. Merge request data requires Claude Code v2.1.234 or later. Absent when not in a git repository, until a pull request or merge request is found, or once it merges or closes |

203203| `pr.review_state` | Review status of the open PR: `approved`, `pending`, `changes_requested`, or `draft`. May be independently absent even when `pr` is present |

204| `pr.kind` | `mr` when `pr` describes a [GitLab merge request](/docs/en/interactive-mode.md#gitlab-merge-requests). Absent for GitHub pull requests, so scripts written before this field keep working. For a merge request, Claude Code sets `review_state` to `approved` when GitLab reports it mergeable, `pending` for any other open state, and `draft` for a draft. Requires Claude Code v2.1.234 or later |

205| `worktree.name` | Name of the active worktree. Present only while the session is in a [worktree session](/docs/en/worktrees.md) |

204| `pr.kind` | `mr` when `pr` describes a [GitLab merge request](https://code.claude.com/docs/en/interactive-mode.md#gitlab-merge-requests). Absent for GitHub pull requests, so scripts written before this field keep working. For a merge request, Claude Code sets `review_state` to `approved` when GitLab reports it mergeable, `pending` for any other open state, and `draft` for a draft. Requires Claude Code v2.1.234 or later |

205| `worktree.name` | Name of the active worktree. Present only while the session is in a [worktree session](https://code.claude.com/docs/en/worktrees.md) |

206206| `worktree.path` | Absolute path to the worktree directory |

207207| `worktree.branch` | Git branch name for the worktree (for example, `"worktree-my-feature"`). Absent for hook-based worktrees |

208208| `worktree.original_cwd` | The directory Claude was in before entering the worktree |

from line 336

336336> * `vim`: appears only when vim mode is enabled

337337> * `agent`: appears only when running with the `--agent` flag or agent settings configured

338338> * `pr`: appears only while an open PR or GitLab merge request is found for the current branch, and is removed once it merges or closes. `pr.review_state` and `pr.kind` may be independently absent

339> * `worktree`: appears only while the session is in a [worktree session](/docs/en/worktrees.md). When present, `branch` and `original_branch` may also be absent for hook-based worktrees

339> * `worktree`: appears only while the session is in a [worktree session](https://code.claude.com/docs/en/worktrees.md). When present, `branch` and `original_branch` may also be absent for hook-based worktrees

340340> * `rate_limits`: appears only for claude.ai Pro and Max subscribers, or behind a Claude apps gateway that sets a spend limit for you, and only after the first API response in the session. Each window (`five_hour`, `seven_day`, `spend_limit`) may be independently absent, and Claude Code drops a window once its `resets_at` time passes. Use `jq -r '.rate_limits.five_hour.used_percentage // empty'` to handle absence gracefully.

341341> * `prompt_cache`: appears after the main conversation's first API response. See [prompt cache fields](#prompt-cache-fields)

342342>

from line 361

361361* `cache_creation_input_tokens`: tokens written to cache

362362* `cache_read_input_tokens`: tokens read from cache

363363

364For what the cache fields mean and how they're billed, see [check cache performance](/docs/en/prompt-caching.md#check-cache-performance).

364For what the cache fields mean and how they're billed, see [check cache performance](https://code.claude.com/docs/en/prompt-caching.md#check-cache-performance).

365365

366366The `used_percentage` field is calculated from input tokens only: `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. It does not include `output_tokens`.

367367

from line 371

371371

372372### Spend limit fields

373373

374Behind a [Claude apps gateway with spend limits](/docs/en/claude-apps-gateway-spend-limits.md#usage-warnings-in-claude-code), the `rate_limits.spend_limit` object describes the spend limit that applies to you. It appears after the session's first API response and requires Claude Code v2.1.251 or later. Your script receives its fields on separate schedules:

374Behind a [Claude apps gateway with spend limits](https://code.claude.com/docs/en/claude-apps-gateway-spend-limits.md#usage-warnings-in-claude-code), the `rate_limits.spend_limit` object describes the spend limit that applies to you. It appears after the session's first API response and requires Claude Code v2.1.251 or later. Your script receives its fields on separate schedules:

375375

376376* `used_percentage` and `resets_at`: come with every response, so they are present whenever `spend_limit` is. `used_percentage` runs from 0 to 100, or above 100 once you exceed the limit, and `resets_at` is the Unix epoch seconds when the limit's period resets.

377* `used_usd`, `limit_usd`, and `period`: your estimated spend so far and your limit in US dollars, and the period the limit covers, one of `daily`, `weekly`, or `monthly`. The gateway [computes `used_usd` from token counts](/docs/en/claude-apps-gateway-spend-limits#how-requests-are-priced), so it's an estimate and not a billed amount. Claude Code reads them from the gateway in a separate request, about every five minutes while you send requests. The dollar amounts can be about five minutes older than `used_percentage`, so the two may briefly disagree. Requires v2.1.284 or later on both Claude Code and the gateway.

377* `used_usd`, `limit_usd`, and `period`: your estimated spend so far and your limit in US dollars, and the period the limit covers, one of `daily`, `weekly`, or `monthly`. The gateway [computes `used_usd` from token counts](https://code.claude.com/docs/en/claude-apps-gateway-spend-limits#how-requests-are-priced), so it's an estimate and not a billed amount. Claude Code reads them from the gateway in a separate request, about every five minutes while you send requests. The dollar amounts can be about five minutes older than `used_percentage`, so the two may briefly disagree. Requires v2.1.284 or later on both Claude Code and the gateway.

378378

379379Treat `used_usd`, `limit_usd`, and `period` as optional even when `spend_limit` is present. Your script receives the percentage before them, and they stay absent if you set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, which turns that request off. Read each with a fallback in your script, such as `jq -r '.rate_limits.spend_limit.used_usd // empty'`.

380380

381381### Prompt cache fields

382382

383The `prompt_cache` object summarizes how the session's main conversation is using the [prompt cache](/docs/en/prompt-caching.md). Claude Code computes it from the cache token counts in the API's responses, so it works on every provider.

383The `prompt_cache` object summarizes how the session's main conversation is using the [prompt cache](https://code.claude.com/docs/en/prompt-caching.md). Claude Code computes it from the cache token counts in the API's responses, so it works on every provider.

384384

385385The object appears after the main conversation's first API response. Claude Code doesn't count subagent requests in these statistics. Requires Claude Code v2.1.251 or later.

386386

from line 390

390390| - | - |

391391| `warm` | Whether the cached prefix is still within its TTL. `false` when the last response reported no cache tokens, even while `caching_observed` is `true` |

392392| `caching_observed` | Whether any response this session reported cache tokens. `false` means prompt caching is off, or your provider or gateway doesn't report it |

393| `ttl` | [Cache lifetime](/docs/en/prompt-caching.md#cache-lifetime) of the current cached prefix: `"5m"` or `"1h"` |

393| `ttl` | [Cache lifetime](https://code.claude.com/docs/en/prompt-caching.md#cache-lifetime) of the current cached prefix: `"5m"` or `"1h"` |

394394| `expires_at` | When the cached prefix leaves its TTL and goes cold, in epoch seconds. `null` when the last response reported no cache tokens |

395395| `requests` | API requests recorded for the main conversation this session |

396396| `misses` | Requests that re-processed content the cache already held: more than 5% and at least 2,000 tokens of what the request could have read from cache, with no compaction or tool-result clearing to explain the shortfall in cache reads |

from line 403

403403| `miss_causes` | How many of this session's diagnosed misses had each cause, keyed by the same cause names as `last_miss_cause`. Requires Claude Code v2.1.260 or later |

404404| `recache_tokens_if_cold` | Tokens the next request re-caches if the cache has gone cold by then. `null` right after a compaction or a clearing of old tool results, until the next request records the rewritten conversation's size |

405405

406Claude Code shows the same statistics in the terminal, on the [`/usage` command's `Prompt cache (main)` line](/docs/en/costs#prompt-cache-statistics).

406Claude Code shows the same statistics in the terminal, on the [`/usage` command's `Prompt cache (main)` line](https://code.claude.com/docs/en/costs#prompt-cache-statistics).

407407

408408#### Last miss cause

409409

from line 1083

10831083

10841084## Subagent status lines

10851085

1086The `subagentStatusLine` setting renders a custom row body for each [subagent](/docs/en/sub-agents.md) shown in the agent panel below the prompt. Use it to replace the default `name · description · token count` row with your own formatting.

1086The `subagentStatusLine` setting renders a custom row body for each [subagent](https://code.claude.com/docs/en/sub-agents.md) shown in the agent panel below the prompt. Use it to replace the default `name · description · token count` row with your own formatting.

10871087

10881088```json theme={null}

10891089{

from line 1094

10941094}

10951095```

10961096

1097The command runs once per refresh tick and receives all visible subagent rows as a single JSON object on stdin. The input includes the [base hook fields](/docs/en/hooks.md#common-input-fields), a `columns` field with the usable row width, and a `tasks` array with one entry per row, described in [Task fields](#task-fields).

1097The command runs once per refresh tick and receives all visible subagent rows as a single JSON object on stdin. The input includes the [base hook fields](https://code.claude.com/docs/en/hooks.md#common-input-fields), a `columns` field with the usable row width, and a `tasks` array with one entry per row, described in [Task fields](#task-fields).

10981098

10991099Write one JSON line to stdout per row you want to override, in the form `{"id": "<task id>", "content": "<row body>"}`. The `content` string is rendered as-is, including ANSI colors and OSC 8 hyperlinks. Omit a task's `id` to keep the default rendering for that row; emit an empty `content` string to hide it.

11001100

1101The same trust, `disableAllHooks`, and [`allowManagedHooksOnly`](/docs/en/settings-reference#allowmanagedhooksonly) gates that apply to `statusLine` apply here. Plugins can ship a default `subagentStatusLine` in their [`settings.json`](/docs/en/plugins/manifest-reference#standard-layout), but unlike hooks, plugin values don't run under `allowManagedHooksOnly` even when the plugin is force-enabled in managed settings `enabledPlugins`.

1101The same trust, `disableAllHooks`, and [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) gates that apply to `statusLine` apply here. Plugins can ship a default `subagentStatusLine` in their [`settings.json`](https://code.claude.com/docs/en/plugins/manifest-reference#standard-layout), but unlike hooks, plugin values don't run under `allowManagedHooksOnly` even when the plugin is force-enabled in managed settings `enabledPlugins`.

11021102

11031103### Task fields

11041104

from line 1107

11071107| Field | Type | Description |

11081108| :- | :- | :- |

11091109| `id` | string | Identifier of the task. Echo it as `id` in the line you write back for this row |

1110| `name` | string, optional | Name the subagent is [addressed by](/docs/en/sub-agents.md#subagent-names), when it has one |

1110| `name` | string, optional | Name the subagent is [addressed by](https://code.claude.com/docs/en/sub-agents.md#subagent-names), when it has one |

11111111| `type` | string | Kind of task: `local_agent` |

1112| `agentType` | string | Subagent type the task runs as, such as the built-in [`Explore`](/docs/en/sub-agents#built-in-subagents) or a custom `code-reviewer`. Holds the same value that hooks receive as [`agent_type`](/docs/en/hooks#subagentstart). Requires Claude Code v2.1.293 or later |

1112| `agentType` | string | Subagent type the task runs as, such as the built-in [`Explore`](https://code.claude.com/docs/en/sub-agents#built-in-subagents) or a custom `code-reviewer`. Holds the same value that hooks receive as [`agent_type`](https://code.claude.com/docs/en/hooks#subagentstart). Requires Claude Code v2.1.293 or later |

11131113| `status` | string | State of the task, such as `running`, `completed`, `failed`, or `killed` |

11141114| `description` | string | Short description of the task, such as the one Claude gave when it spawned the subagent |

11151115| `label` | string | Short progress summary of the task when Claude Code has one, otherwise the same text as `description` |

11161116| `startTime` | number | When the task started, in milliseconds since the Unix epoch |

11171117| `model` | string, optional | ID of the resolved model the task runs on. Omitted until the model is resolved |

1118| `effort` | string or number, optional | Reasoning effort set for the subagent in its [definition frontmatter](/docs/en/sub-agents.md#supported-frontmatter-fields) or on the individual invocation: `low`, `medium`, `high`, `xhigh`, `max`, or a numeric token budget. This is the configured value, and the effort Claude Code applies can differ when the model doesn't support that level. Omitted when no effort is set |

1118| `effort` | string or number, optional | Reasoning effort set for the subagent in its [definition frontmatter](https://code.claude.com/docs/en/sub-agents.md#supported-frontmatter-fields) or on the individual invocation: `low`, `medium`, `high`, `xhigh`, `max`, or a numeric token budget. This is the configured value, and the effort Claude Code applies can differ when the model doesn't support that level. Omitted when no effort is set |

11191119| `contextWindowSize` | number, optional | Context window of `model` in tokens, computed the same way as the main status line's [`context_window.context_window_size`](#context-window-fields), so you can render a per-row percentage from `tokenCount`. Omitted when `model` is |

11201120| `tokenCount` | number | Running token count of the subagent, the figure the default row shows |

11211121| `tokenSamples` | array of numbers | Up to the last 16 `tokenCount` readings, one per refresh tick, oldest first and ending with the current one |

from line 1141

11411141* Check that your script outputs to stdout, not stderr

11421142* Run your script manually to verify it produces output

11431143* On Windows with Git Bash installed, backslashes in the `command` path are likely being consumed as escape characters before the script runs. Use forward slashes in the path. See [Windows configuration](#windows-configuration).

1144* If `disableAllHooks` is `true` outside managed settings after [settings precedence](/docs/en/hooks.md#disable-or-remove-hooks) applies, Claude Code runs only a `statusLine` from managed settings, and with no managed `statusLine` the status line is disabled. Remove the setting, or set it to `false` in the file that sets it, to re-enable. See [`disableAllHooks`](/docs/en/settings-reference#disableallhooks).

1145* If your organization sets `allowManagedHooksOnly` in managed settings, your custom status line disappears without warning: you can only get a status line from a `statusLine` value in those managed settings. See [what runs under `allowManagedHooksOnly`](/docs/en/settings-reference#what-runs-under-allowmanagedhooksonly) for the full behavior, and ask your administrator whether this setting applies to you.

1144* If `disableAllHooks` is `true` outside managed settings after [settings precedence](https://code.claude.com/docs/en/hooks.md#disable-or-remove-hooks) applies, Claude Code runs only a `statusLine` from managed settings, and with no managed `statusLine` the status line is disabled. Remove the setting, or set it to `false` in the file that sets it, to re-enable. See [`disableAllHooks`](https://code.claude.com/docs/en/settings-reference#disableallhooks).

1145* If your organization sets `allowManagedHooksOnly` in managed settings, your custom status line disappears without warning: you can only get a status line from a `statusLine` value in those managed settings. See [what runs under `allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#what-runs-under-allowmanagedhooksonly) for the full behavior, and ask your administrator whether this setting applies to you.

11461146* Run `claude --debug` to log your script's stderr on every status line invocation, and its exit code on the first invocation in a session

11471147* Ask Claude to read your settings file and execute the `statusLine` command directly to surface errors

11481148

from line 1186

11861186

11871187### Workspace trust required

11881188

1189Until you accept the workspace trust dialog, the status line stays blank. Because `statusLine` executes a shell command, Claude Code runs it under the same [workspace trust rule as hooks in settings files](/docs/en/permissions.md#what-runs-before-you-trust-a-folder). Accepting the dialog for the folder, or for a parent directory whose trust extends to it, is enough.

1189Until you accept the workspace trust dialog, the status line stays blank. Because `statusLine` executes a shell command, Claude Code runs it under the same [workspace trust rule as hooks in settings files](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder). Accepting the dialog for the folder, or for a parent directory whose trust extends to it, is enough.

11901190

11911191Until then, `claude --debug` logs `Status line command skipped: workspace trust not accepted`. Restart Claude Code and accept the trust dialog to enable it.

11921192

from line 1201

12011201

12021202### Notifications share the status line row

12031203

1204Outside [fullscreen rendering](/docs/en/fullscreen.md), Claude Code shows notifications on the same row as your status line. In fullscreen rendering, Claude Code gives notifications a row of their own.

1204Outside [fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md), Claude Code shows notifications on the same row as your status line. In fullscreen rendering, Claude Code gives notifications a row of their own.

12051205

12061206* System notifications like MCP server errors and auto-updates display on the right side of the row. Transient notifications such as the context-low warning also cycle through this area.

1207* Enabling verbose mode adds a token counter to this area, showing the size of your context as the last API response reported it, not the [per-turn count beside the spinner](/docs/en/costs.md#read-the-token-count-beside-the-spinner)

1207* Enabling verbose mode adds a token counter to this area, showing the size of your context as the last API response reported it, not the [per-turn count beside the spinner](https://code.claude.com/docs/en/costs.md#read-the-token-count-beside-the-spinner)

12081208* On narrow terminals, these notifications may truncate your status line output

12091209

sub-agents Changed · +167 / -167 lines

from line 4

55Subagents are specialized AI assistants that handle specific types of tasks. Use one when a side task would flood your main conversation with search results, logs, or file contents you won't reference again: the subagent does that work in its own context and returns only the summary. Define a custom subagent when you keep spawning the same kind of worker with the same instructions.

7Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. It also sends its own requests, which count toward the same [usage limits](/docs/en/costs.md#plan-usage-breakdown) as your main conversation. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns results. To see the context savings in practice, the [context window visualization](/docs/en/context-window.md) walks through a session where a subagent handles research in its own separate window.

7Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. It also sends its own requests, which count toward the same [usage limits](https://code.claude.com/docs/en/costs.md#plan-usage-breakdown) as your main conversation. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns results. To see the context savings in practice, the [context window visualization](https://code.claude.com/docs/en/context-window.md) walks through a session where a subagent handles research in its own separate window.

99> [!NOTE]

1010>

11> Subagents work within a single session. To run many independent sessions in parallel and monitor them from one place, see [background agents](/docs/en/agent-view.md). For separate sessions that pass messages to each other, see [cross-session messaging](/docs/en/cross-session-messaging.md). For a coordinated team of sessions Claude spawns and supervises, see [agent teams](/docs/en/agent-teams.md).

11> Subagents work within a single session. To run many independent sessions in parallel and monitor them from one place, see [background agents](https://code.claude.com/docs/en/agent-view.md). For separate sessions that pass messages to each other, see [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md). For a coordinated team of sessions Claude spawns and supervises, see [agent teams](https://code.claude.com/docs/en/agent-teams.md).

1212

1313Subagents help you:

1414

from line 20

2020

2121Claude uses each subagent's description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it.

2222

23Those descriptions take up context, so keep them short. When the combined descriptions of your subagents, except the built-in ones, exceed 15,000 tokens, Claude Code shows a [warning at startup with the total token count](/docs/en/errors.md#agent-descriptions-are-over-the-15000-token-limit). Trim the `description` fields of your subagents, and move detail into each subagent's system prompt, which only loads when that subagent runs.

23Those descriptions take up context, so keep them short. When the combined descriptions of your subagents, except the built-in ones, exceed 15,000 tokens, Claude Code shows a [warning at startup with the total token count](https://code.claude.com/docs/en/errors.md#agent-descriptions-are-over-the-15000-token-limit). Trim the `description` fields of your subagents, and move detail into each subagent's system prompt, which only loads when that subagent runs.

2424

2525## Built-in subagents

2626

from line 33

3333A fast, read-only agent optimized for searching and analyzing codebases.

3434

3535* **Model**: the main conversation's model. When the main conversation runs Fable, Explore's model depends on how you connect:

36 * With a Claude subscription, an Anthropic Console account, or an [LLM gateway](/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`, Explore runs on the Opus model that the [`opus` alias](/docs/en/model-config#model-aliases) resolves to.

37 * On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](/docs/en/claude-platform-on-aws.md), or a [Claude apps gateway](/docs/en/claude-apps-gateway), Explore stays on the main conversation's model.

36 * With a Claude subscription, an Anthropic Console account, or an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`, Explore runs on the Opus model that the [`opus` alias](https://code.claude.com/docs/en/model-config#model-aliases) resolves to.

37 * On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), or a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway), Explore stays on the main conversation's model.

3838* **Tools**: read-only tools; Write and Edit are denied

3939* **Purpose**: file discovery, code search, codebase exploration

4040

from line 46

4646

4747**Plan**

4848

49A research agent used during [plan mode](/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.

49A research agent used during [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.

5050

5151* **Model**: inherits from the main conversation, unless you set `CLAUDE_CODE_SUBAGENT_MODEL` and [force it onto every subagent](#run-every-subagent-on-one-model)

5252* **Tools**: read-only tools; Write and Edit are denied

from line 70

7070

7171| Agent | Model | When Claude uses it |

7272| :- | :- | :- |

73| claude | None of its own; follows the [model order](#choose-a-model) when Claude spawns it as a subagent | When a task doesn't fit a more specialized agent. A catch-all with every tool [available to subagents](#available-tools). Also the default agent for a dispatched [background session](/docs/en/agent-view.md); [which permission mode it starts in](/docs/en/agent-view.md#permission-mode-model-and-effort) depends on how the session was started |

73| claude | None of its own; follows the [model order](#choose-a-model) when Claude spawns it as a subagent | When a task doesn't fit a more specialized agent. A catch-all with every tool [available to subagents](#available-tools). Also the default agent for a dispatched [background session](https://code.claude.com/docs/en/agent-view.md); [which permission mode it starts in](https://code.claude.com/docs/en/agent-view.md#permission-mode-model-and-effort) depends on how the session was started |

7474| statusline-setup | Sonnet | When you run `/statusline` to configure your status line |

7575| claude-code-guide | Haiku | When you ask questions about Claude Code features |

7676

from line 77

7777Built-in subagents are registered by default in interactive sessions. To restrict them:

7878

7979* To block a specific built-in type, add it to `permissions.deny` as shown in [Disable specific subagents](#disable-specific-subagents).

80* To prevent Claude from delegating to any subagent, deny the `Agent` tool itself with [`permissions.deny`](/docs/en/permissions#tool-specific-permission-rules).

81* To remove only the built-in `Explore` and `Plan` subagents, set [`CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`](/docs/en/env-vars). Claude reads and explores files directly instead of delegating to them. Requires Claude Code v2.1.198 or later.

82* In [non-interactive mode](/docs/en/headless.md) and the [Agent SDK](/docs/en/agent-sdk/overview.md), set [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/docs/en/env-vars) to remove all built-in types and supply only your own.

80* To prevent Claude from delegating to any subagent, deny the `Agent` tool itself with [`permissions.deny`](https://code.claude.com/docs/en/permissions#tool-specific-permission-rules).

81* To remove only the built-in `Explore` and `Plan` subagents, set [`CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`](https://code.claude.com/docs/en/env-vars). Claude reads and explores files directly instead of delegating to them. Requires Claude Code v2.1.198 or later.

82* In [non-interactive mode](https://code.claude.com/docs/en/headless.md) and the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md), set [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](https://code.claude.com/docs/en/env-vars) to remove all built-in types and supply only your own.

8383

84An Agent tool call that omits `subagent_type` fails with [`subagent_type is required`](/docs/en/errors#subagent-type-is-required) when the session has no `general-purpose` subagent to fall back on.

84An Agent tool call that omits `subagent_type` fails with [`subagent_type is required`](https://code.claude.com/docs/en/errors#subagent-type-is-required) when the session has no `general-purpose` subagent to fall back on.

8585

8686Beyond these built-in subagents, you can create your own with custom prompts, tool restrictions, permission modes, hooks, and skills. The following sections show how to get started and customize subagents.

8787

from line 153

153153

155155| :- | :- | :- | :- |

161161

162162**Project subagents** (`.claude/agents/`) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively.

163163

164164Project subagents are discovered by walking up from the current working directory, so every `.claude/agents/` between there and the repository root is scanned. When more than one of these nested directories defines the same `name`, Claude Code uses the definition closest to the working directory.

165165

166When you add a directory with `--add-dir` or `/add-dir`, Claude Code also loads its `.claude/agents/` folder, alongside your project subagents. See [Additional directories](/docs/en/permissions.md#additional-directories-grant-file-access-not-configuration) for which other configuration types load from `--add-dir`. To share subagents across projects without `--add-dir`, use `~/.claude/agents/` or a [plugin](/docs/en/plugins/overview.md).

166When you add a directory with `--add-dir` or `/add-dir`, Claude Code also loads its `.claude/agents/` folder, alongside your project subagents. See [Additional directories](https://code.claude.com/docs/en/permissions.md#additional-directories-grant-file-access-not-configuration) for which other configuration types load from `--add-dir`. To share subagents across projects without `--add-dir`, use `~/.claude/agents/` or a [plugin](https://code.claude.com/docs/en/plugins/overview.md).

167167

168168**User subagents** (`~/.claude/agents/`) are personal subagents available in all your projects.

169169

170170Claude Code scans `.claude/agents/` and `~/.claude/agents/` recursively, so you can organize definitions into subfolders such as `agents/review/` or `agents/research/`. The subdirectory path doesn't affect how a subagent is identified or invoked, because identity comes only from the `name` frontmatter field.

171171

172Keep `name` values unique across the whole tree: if two files under the same `.claude/agents/` directory, including its subfolders, declare the same name, Claude Code loads only one of them, chosen by filesystem read order rather than a documented precedence. Across nested project directories, the definition closest to the working directory wins, as described above. The [`/doctor`](/docs/en/commands#all-commands) setup checkup reports files in the same directory that share a name and proposes renaming or removing all but one.

172Keep `name` values unique across the whole tree: if two files under the same `.claude/agents/` directory, including its subfolders, declare the same name, Claude Code loads only one of them, chosen by filesystem read order rather than a documented precedence. Across nested project directories, the definition closest to the working directory wins, as described above. The [`/doctor`](https://code.claude.com/docs/en/commands#all-commands) setup checkup reports files in the same directory that share a name and proposes renaming or removing all but one.

173173

174174Plugin `agents/` directories are also scanned recursively. Unlike project and user scopes, a subfolder inside a plugin's `agents/` directory becomes part of the [scoped identifier](#invoke-subagents-explicitly): a file at `agents/review/security.md` in plugin `my-plugin` registers as `my-plugin:review:security`.

175175

from line 211

211211'@

212212```

213213

214In [non-interactive mode](/docs/en/headless.md), `--agents` also accepts the path to a JSON file holding the same object, for definitions too large to pass on the command line. For example, `claude -p --agents ./agents.json "Review my changes"` reads the definitions from that file. In an interactive session, Claude Code refuses a file path. The file form requires Claude Code v2.1.281 or later.

214In [non-interactive mode](https://code.claude.com/docs/en/headless.md), `--agents` also accepts the path to a JSON file holding the same object, for definitions too large to pass on the command line. For example, `claude -p --agents ./agents.json "Review my changes"` reads the definitions from that file. In an interactive session, Claude Code refuses a file path. The file form requires Claude Code v2.1.281 or later.

215215

216216Each top-level key in the JSON is an agent's name, and its value is that agent's definition. Don't start a name with `-`. A definition takes these fields:

217217

from line 219

219219* **[Frontmatter fields](#supported-frontmatter-fields)**: `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `autoCompactWindow`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `omitClaudeMd`, and `isolation`.

220220* **Ignored fields**: `color` and `experimental` aren't accepted here and are ignored rather than rejected.

221221

222For what Claude Code does with a value it can't load, and the flags and environment variable that skip that check, see [`Invalid --agents configuration`](/docs/en/errors#invalid-agents-configuration).

222For what Claude Code does with a value it can't load, and the flags and environment variable that skip that check, see [`Invalid --agents configuration`](https://code.claude.com/docs/en/errors#invalid-agents-configuration).

223223

224**Managed subagents** are deployed by organization administrators. Place markdown files in `.claude/agents/` inside the [managed settings directory](/docs/en/managed-settings.md#delivery-mechanisms), using the same frontmatter format as project and user subagents. Managed definitions take precedence over project and user subagents with the same name.

224**Managed subagents** are deployed by organization administrators. Place markdown files in `.claude/agents/` inside the [managed settings directory](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms), using the same frontmatter format as project and user subagents. Managed definitions take precedence over project and user subagents with the same name.

225225

226**Plugin subagents** come from [plugins](/docs/en/plugins/overview.md) you've installed. They load automatically alongside your custom subagents and appear in the @-mention typeahead under their scoped name. See the [plugin components reference](/docs/en/plugins/components.md#agents) for details on creating plugin subagents.

226**Plugin subagents** come from [plugins](https://code.claude.com/docs/en/plugins/overview.md) you've installed. They load automatically alongside your custom subagents and appear in the @-mention typeahead under their scoped name. See the [plugin components reference](https://code.claude.com/docs/en/plugins/components.md#agents) for details on creating plugin subagents.

227227

228228> [!NOTE]

229229>

230> For security reasons, plugin subagents don't support the `hooks`, `mcpServers`, or `permissionMode` frontmatter fields. These fields are ignored when loading agents from a plugin. If you need them, copy the agent file into `.claude/agents/` or `~/.claude/agents/`. You can also add rules to [`permissions.allow`](/docs/en/settings-reference#permissions-allow) in `settings.json` or `settings.local.json`, but these rules apply to the entire session, not only the plugin subagent.

230> For security reasons, plugin subagents don't support the `hooks`, `mcpServers`, or `permissionMode` frontmatter fields. These fields are ignored when loading agents from a plugin. If you need them, copy the agent file into `.claude/agents/` or `~/.claude/agents/`. You can also add rules to [`permissions.allow`](https://code.claude.com/docs/en/settings-reference#permissions-allow) in `settings.json` or `settings.local.json`, but these rules apply to the entire session, not only the plugin subagent.

231231>

232> If you're the plugin's author, ship the hooks in the plugin's [`hooks/hooks.json`](/docs/en/plugins/components#hooks) and the MCP servers in its [`.mcp.json`](/docs/en/plugins/components#mcp-servers) instead. They apply whenever the plugin is enabled rather than only inside the subagent.

232> If you're the plugin's author, ship the hooks in the plugin's [`hooks/hooks.json`](https://code.claude.com/docs/en/plugins/components#hooks) and the MCP servers in its [`.mcp.json`](https://code.claude.com/docs/en/plugins/components#mcp-servers) instead. They apply whenever the plugin is enabled rather than only inside the subagent.

233233

234You can also reuse a subagent definition as an [agent team](/docs/en/agent-teams.md) teammate: name the subagent type when you ask Claude to spawn the teammate, and Claude Code applies parts of that definition to it. [Use subagent definitions for teammates](/docs/en/agent-teams.md#use-subagent-definitions-for-teammates) says which scopes and which parts apply in each display mode.

234You can also reuse a subagent definition as an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate: name the subagent type when you ask Claude to spawn the teammate, and Claude Code applies parts of that definition to it. [Use subagent definitions for teammates](https://code.claude.com/docs/en/agent-teams.md#use-subagent-definitions-for-teammates) says which scopes and which parts apply in each display mode.

235235

236236### Write subagent files

237237

from line 261

261261

262262The frontmatter defines the subagent's metadata and configuration. The body becomes the system prompt that guides the subagent's behavior. Subagents receive only this system prompt plus basic environment details like the working directory, not the Claude Code system prompt.

263263

264In [non-interactive mode](/docs/en/headless.md), pass [`--append-subagent-system-prompt`](/docs/en/cli-reference#cli-flags) to append your text to the end of every subagent's system prompt, nested subagents included, apart from a [forked subagent](#fork-the-current-conversation), which reuses the conversation's own prompt. Requires Claude Code v2.1.205 or later. If your text is too long to pass on the command line, save it to a file and pass the path with `--append-subagent-system-prompt-file` instead. The file flag requires Claude Code v2.1.261 or later.

264In [non-interactive mode](https://code.claude.com/docs/en/headless.md), pass [`--append-subagent-system-prompt`](https://code.claude.com/docs/en/cli-reference#cli-flags) to append your text to the end of every subagent's system prompt, nested subagents included, apart from a [forked subagent](#fork-the-current-conversation), which reuses the conversation's own prompt. Requires Claude Code v2.1.205 or later. If your text is too long to pass on the command line, save it to a file and pass the path with `--append-subagent-system-prompt-file` instead. The file flag requires Claude Code v2.1.261 or later.

265265

266266A subagent starts in the main conversation's current working directory. Within a subagent, `cd` commands don't persist between Bash or PowerShell tool calls and don't affect the main conversation's working directory. To give the subagent an isolated copy of the repository instead, set [`isolation: worktree`](#supported-frontmatter-fields).

267267

268268A subagent with `isolation: worktree` runs its Bash and PowerShell commands inside its worktree. A command whose working directory resolves to your main checkout instead, for example because the worktree directory was removed while the subagent was running, fails with an error.

269269

270This working-directory check covers the whole repository containing the directory you launched Claude Code from. When your session runs in a linked [worktree](/docs/en/worktrees.md) of its own, the check also covers the main checkout that worktree is linked from.

270This working-directory check covers the whole repository containing the directory you launched Claude Code from. When your session runs in a linked [worktree](https://code.claude.com/docs/en/worktrees.md) of its own, the check also covers the main checkout that worktree is linked from.

271271

272272For Bash commands, Claude Code also checks the command itself in two ways:

273273

from line 274

274274* It blocks a command that redirects git into the main checkout.

275275* It refuses a command when it can't verify from the command text that any git the command runs stays inside the worktree, for example when the command name is computed at runtime.

276276

277The redirect vectors and the shape rules are listed under [How Claude Code enforces isolation](/docs/en/worktrees.md#how-claude-code-enforces-isolation). PowerShell commands get only the working-directory check.

277The redirect vectors and the shape rules are listed under [How Claude Code enforces isolation](https://code.claude.com/docs/en/worktrees.md#how-claude-code-enforces-isolation). PowerShell commands get only the working-directory check.

278278

279[Monitor](/docs/en/tools-reference.md#monitor-tool) commands go through the same working-directory and command-content checks as Bash commands.

279[Monitor](https://code.claude.com/docs/en/tools-reference.md#monitor-tool) commands go through the same working-directory and command-content checks as Bash commands.

280280

281When the main conversation itself runs isolated in a worktree, Claude Code applies the same checks to the session and to every subagent it spawns, including subagents without `isolation: worktree`; see [How Claude Code enforces isolation](/docs/en/worktrees.md#how-claude-code-enforces-isolation).

281When the main conversation itself runs isolated in a worktree, Claude Code applies the same checks to the session and to every subagent it spawns, including subagents without `isolation: worktree`; see [How Claude Code enforces isolation](https://code.claude.com/docs/en/worktrees.md#how-claude-code-enforces-isolation).

282282

283283### Frontmatter reference

284284

285Configure a subagent with YAML [frontmatter](/docs/en/glossary.md#frontmatter) between `---` markers at the top of its file, and write its system prompt as Markdown after the closing `---`. Only `name` and `description` are required.

285Configure a subagent with YAML [frontmatter](https://code.claude.com/docs/en/glossary.md#frontmatter) between `---` markers at the top of its file, and write its system prompt as Markdown after the closing `---`. Only `name` and `description` are required.

286286

287287Multi-word field names use camelCase, such as `maxTurns` and `disallowedTools`, and must match the table exactly: Claude Code ignores a field it doesn't recognize without reporting an error.

288288

289* To find a misspelled field in a subagent that loaded, run [`claude --debug`](/docs/en/cli-reference#cli-flags) in your shell and search the debug log at `~/.claude/debug/<session-id>.txt` for `does not recognize or apply`. The debug log names up to five top-level fields in the subagent's file that Claude Code doesn't recognize, with the likely intended name when a supported field is close. Requires Claude Code v2.1.296 or later.

289* To find a misspelled field in a subagent that loaded, run [`claude --debug`](https://code.claude.com/docs/en/cli-reference#cli-flags) in your shell and search the debug log at `~/.claude/debug/<session-id>.txt` for `does not recognize or apply`. The debug log names up to five top-level fields in the subagent's file that Claude Code doesn't recognize, with the likely intended name when a supported field is close. Requires Claude Code v2.1.296 or later.

290290* To find out why a subagent file didn't load, see [Subagent files Claude Code skips](#subagent-files-claude-code-skips).

291291

292292| Field | Required | Description |

293293| :- | :- | :- |

294| `name` | Yes | Unique identifier of at most 256 characters, such as `code-reviewer` or `reviewer-v2`. [Hooks](/docs/en/hooks.md#subagentstart) receive this value as `agent_type`. The filename doesn't have to match. Names can't contain `:`, which is reserved for [plugin-scoped identifiers](/docs/en/plugins/overview.md) such as `my-plugin:reviewer` |

294| `name` | Yes | Unique identifier of at most 256 characters, such as `code-reviewer` or `reviewer-v2`. [Hooks](https://code.claude.com/docs/en/hooks.md#subagentstart) receive this value as `agent_type`. The filename doesn't have to match. Names can't contain `:`, which is reserved for [plugin-scoped identifiers](https://code.claude.com/docs/en/plugins/overview.md) such as `my-plugin:reviewer` |

295295| `description` | Yes | When Claude should delegate to this subagent |

296| `tools` | No | [Tools](#available-tools) the subagent can use, as a comma-separated string such as `Read, Grep, Bash` or a YAML list. Inherits every tool available to subagents if omitted. If no entry in the list resolves to a tool, the subagent usually [fails to launch](/docs/en/errors.md#agent-would-be-spawned-with-zero-tools) with an error naming the entries. To preload Skills into context, use the `skills` field rather than listing `Skill` here |

296| `tools` | No | [Tools](#available-tools) the subagent can use, as a comma-separated string such as `Read, Grep, Bash` or a YAML list. Inherits every tool available to subagents if omitted. If no entry in the list resolves to a tool, the subagent usually [fails to launch](https://code.claude.com/docs/en/errors.md#agent-would-be-spawned-with-zero-tools) with an error naming the entries. To preload Skills into context, use the `skills` field rather than listing `Skill` here |

297297| `disallowedTools` | No | Tools to deny, removed from inherited or specified list. Same format as `tools`. An entry with a specifier, such as `Bash(git push *)`, still [removes the whole tool](#restrict-which-tools-a-subagent-can-use) |

298298| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, `fable`, a full model ID such as `claude-opus-5-5`, or `inherit`. When you omit it, Claude Code picks the model in the [subagent model order](#choose-a-model) |

299299| `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, or `manual` as an alias for `default`. Ignored for [plugin subagents](#choose-the-subagent-scope) |

300300| `maxTurns` | No | Maximum number of agentic turns before the subagent stops. When the subagent reaches the limit, Claude Code returns its output marked as partial, and Claude can [resume it](#resume-subagents) to continue. The partial marking requires Claude Code v2.1.246 or later |

301301| `autoCompactWindow` | No | Lower the [auto-compact window](#subagent-auto-compact-window) for this subagent to a token count from `100000` to `1000000`. Requires Claude Code v2.1.296 or later |

302| `skills` | No | [Skills](/docs/en/skills.md) to preload into the subagent's context at startup. The full skill content is injected, not only the description. Subagents can still invoke unlisted project, user, and plugin skills through the Skill tool |

303| `mcpServers` | No | [MCP servers](/docs/en/mcp.md) available to this subagent. Each entry is either a server name referencing an already-configured server (e.g., `"slack"`) or an inline definition with the server name as key and a full [MCP server config](/docs/en/mcp.md#installing-mcp-servers) as value. Ignored for [plugin subagents](#choose-the-subagent-scope) |

302| `skills` | No | [Skills](https://code.claude.com/docs/en/skills.md) to preload into the subagent's context at startup. The full skill content is injected, not only the description. Subagents can still invoke unlisted project, user, and plugin skills through the Skill tool |

303| `mcpServers` | No | [MCP servers](https://code.claude.com/docs/en/mcp.md) available to this subagent. Each entry is either a server name referencing an already-configured server (e.g., `"slack"`) or an inline definition with the server name as key and a full [MCP server config](https://code.claude.com/docs/en/mcp.md#installing-mcp-servers) as value. Ignored for [plugin subagents](#choose-the-subagent-scope) |

304304| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent. Ignored for [plugin subagents](#choose-the-subagent-scope) |

305305| `memory` | No | [Persistent memory scope](#enable-persistent-memory): `user`, `project`, or `local`. Enables cross-session learning |

306306| `background` | No | Set to `true` to keep this subagent in the background even when Claude asks to wait for it. By default, subagents Claude spawns from the main conversation already [start in the background](#run-subagents-in-foreground-or-background) |

307| `omitClaudeMd` | No | Set to `true` to start this subagent without the user, project, and local CLAUDE.md files in its [initial context](#what-loads-at-startup); [managed policy files](/docs/en/memory.md#how-claude-md-files-load) still load, except for [managed subagents](#choose-the-subagent-scope). Use it for subagents that take everything they need from the delegation prompt. Ignored when the agent runs as the main session agent via `--agent` or the `agent` setting. Requires Claude Code v2.1.271 or later |

308| `effort` | No | Effort level when this subagent is active. Overrides the session effort level, but not the [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/en/env-vars#variables) environment variable. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model. See [Choose an effort level](#choose-an-effort-level) |

309| `isolation` | No | Set to `worktree` to run the subagent in a temporary [git worktree](/docs/en/worktrees.md), giving it an isolated copy of the repository branched by default from your [default branch](/docs/en/worktrees.md#choose-the-base-branch) rather than the parent session's `HEAD`. The worktree is automatically cleaned up if the subagent makes no changes |

307| `omitClaudeMd` | No | Set to `true` to start this subagent without the user, project, and local CLAUDE.md files in its [initial context](#what-loads-at-startup); [managed policy files](https://code.claude.com/docs/en/memory.md#how-claude-md-files-load) still load, except for [managed subagents](#choose-the-subagent-scope). Use it for subagents that take everything they need from the delegation prompt. Ignored when the agent runs as the main session agent via `--agent` or the `agent` setting. Requires Claude Code v2.1.271 or later |

308| `effort` | No | Effort level when this subagent is active. Overrides the session effort level, but not the [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/en/env-vars#variables) environment variable. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model. See [Choose an effort level](#choose-an-effort-level) |

309| `isolation` | No | Set to `worktree` to run the subagent in a temporary [git worktree](https://code.claude.com/docs/en/worktrees.md), giving it an isolated copy of the repository branched by default from your [default branch](https://code.claude.com/docs/en/worktrees.md#choose-the-base-branch) rather than the parent session's `HEAD`. The worktree is automatically cleaned up if the subagent makes no changes |

310310| `color` | No | Display color for the subagent in the task list and transcript. Accepts `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan` |

311| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent` or the `agent` setting). [Commands](/docs/en/commands.md) and [skills](/docs/en/skills.md) are processed. Prepended to any user-provided prompt. Ignored for [plugin subagents](#choose-the-subagent-scope) |

312| `experimental` | No | Map of experimental options. Set its `cacheTtl` key to `5m` or `1h` to choose the [prompt cache lifetime](/docs/en/prompt-caching.md#choose-the-ttl-yourself) for this subagent's requests, at the frontmatter's place in the [cache lifetime precedence](/docs/en/prompt-caching.md#choose-the-ttl-yourself). Claude Code ignores any other value, ignores `1h` while your Claude subscription is using usage credits, and reads the field only from subagent files. Requires Claude Code v2.1.248 or later |

311| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent` or the `agent` setting). [Commands](https://code.claude.com/docs/en/commands.md) and [skills](https://code.claude.com/docs/en/skills.md) are processed. Prepended to any user-provided prompt. Ignored for [plugin subagents](#choose-the-subagent-scope) |

312| `experimental` | No | Map of experimental options. Set its `cacheTtl` key to `5m` or `1h` to choose the [prompt cache lifetime](https://code.claude.com/docs/en/prompt-caching.md#choose-the-ttl-yourself) for this subagent's requests, at the frontmatter's place in the [cache lifetime precedence](https://code.claude.com/docs/en/prompt-caching.md#choose-the-ttl-yourself). Claude Code ignores any other value, ignores `1h` while your Claude subscription is using usage credits, and reads the field only from subagent files. Requires Claude Code v2.1.248 or later |

313313

314314Write `cacheTtl` inside the `experimental` map, not at the top level of the frontmatter.

315315

from line 334

334334

335335To see the debug log, run Claude Code with `--debug`.

336336

337A [plugin subagent](/docs/en/plugins/components.md#agents) whose frontmatter has no `name` or doesn't parse still loads, under its filename.

337A [plugin subagent](https://code.claude.com/docs/en/plugins/components.md#agents) whose frontmatter has no `name` or doesn't parse still loads, under its filename.

338338

339339##### Check an `agents` directory before a session

340340

341To find files in an `agents` directory whose frontmatter doesn't parse, run `claude plugin validate` against the directory, for example `.claude/agents` or `~/.claude/agents`. Claude Code checks only [the directory you name](/docs/en/plugins/cli-reference.md#validate-a-directory), and doesn't flag a file whose frontmatter parses but has no `name`. Requires Claude Code v2.1.233 or later.

341To find files in an `agents` directory whose frontmatter doesn't parse, run `claude plugin validate` against the directory, for example `.claude/agents` or `~/.claude/agents`. Claude Code checks only [the directory you name](https://code.claude.com/docs/en/plugins/cli-reference.md#validate-a-directory), and doesn't flag a file whose frontmatter parses but has no `name`. Requires Claude Code v2.1.233 or later.

342342

343343### Choose a model

344344

from line 352

352352

3533531. The per-invocation `model` parameter

3543542. The subagent definition's `model` frontmatter, where `inherit` selects the main conversation's model

3553. The [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables) environment variable, when you set it to a model alias or model ID

3553. The [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables) environment variable, when you set it to a model alias or model ID

3563564. The main conversation's model

357357

358If an installed [mod](/docs/en/plugins/mods/overview.md) sets a model in its [`agent.spawn`](/docs/en/plugins/mods/reference#subagents) hook, Claude Code uses that model in place of the per-invocation parameter.

358If an installed [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) sets a model in its [`agent.spawn`](https://code.claude.com/docs/en/plugins/mods/reference#subagents) hook, Claude Code uses that model in place of the per-invocation parameter.

359359

360In two cases, a family alias such as `opus` in the per-invocation parameter or the frontmatter resolves to the main conversation's model instead of the [version the alias points to](/docs/en/model-config.md#model-aliases):

361361

362* **The main conversation's model belongs to that family**: the subagent runs on the main conversation's exact model, including any `[1m]` suffix, so it gets the same [extended context](/docs/en/model-config.md#extended-context) window as the main conversation.

363* **Claude Code can't tell the main conversation's model family, on [a provider other than the Anthropic API](/docs/en/third-party-integrations.md)**: this can happen with an [application inference profile ARN](/docs/en/amazon-bedrock.md#iam-configuration) on Amazon Bedrock that Claude Code hasn't resolved to a backing model. This case covers only the `opus` alias, and doesn't apply when you set [`ANTHROPIC_DEFAULT_OPUS_MODEL`](/docs/en/model-config#environment-variables), since `opus` then resolves to the model you set.

362* **The main conversation's model belongs to that family**: the subagent runs on the main conversation's exact model, including any `[1m]` suffix, so it gets the same [extended context](https://code.claude.com/docs/en/model-config.md#extended-context) window as the main conversation.

363* **Claude Code can't tell the main conversation's model family, on [a provider other than the Anthropic API](https://code.claude.com/docs/en/third-party-integrations.md)**: this can happen with an [application inference profile ARN](https://code.claude.com/docs/en/amazon-bedrock.md#iam-configuration) on Amazon Bedrock that Claude Code hasn't resolved to a backing model. This case covers only the `opus` alias, and doesn't apply when you set [`ANTHROPIC_DEFAULT_OPUS_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables), since `opus` then resolves to the model you set.

364364

365365An alias in `CLAUDE_CODE_SUBAGENT_MODEL` always resolves to the version the alias points to, even when it names the main conversation's family. Setting the variable to `inherit` is the same as leaving it unset.

366366

from line 368

368368

369369Before v2.1.251, `CLAUDE_CODE_SUBAGENT_MODEL` came first in this order and overrode both the per-invocation parameter and the frontmatter, including `model: inherit`.

370370

371Claude Code checks the per-invocation parameter, frontmatter, and environment variable values against your organization's [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist. For a blocked value, it substitutes another model:

371Claude Code checks the per-invocation parameter, frontmatter, and environment variable values against your organization's [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) allowlist. For a blocked value, it substitutes another model:

372372

373* When the blocked value is a family alias such as `opus`, Claude Code runs the subagent on the newest version of that family the allowlist permits, following the same [substitution rules and provider scope](/docs/en/model-config.md#restrict-model-selection) as `/model`. Before v2.1.222, Claude Code ran the subagent on the inherited model for a blocked family alias as well.

373* When the blocked value is a family alias such as `opus`, Claude Code runs the subagent on the newest version of that family the allowlist permits, following the same [substitution rules and provider scope](https://code.claude.com/docs/en/model-config.md#restrict-model-selection) as `/model`. Before v2.1.222, Claude Code ran the subagent on the inherited model for a blocked family alias as well.

374374* For any other blocked value, on providers where that substitution doesn't operate, or when the allowlist permits no version of the family, Claude Code runs the subagent on the inherited model instead. If you set `CLAUDE_CODE_SUBAGENT_MODEL`, Claude Code tries that model first, under these same rules.

375375

376376In interactive sessions, Claude Code shows a warning naming the requested model and the model the subagent runs on, for either substitution.

377377

378To check which model a subagent is running on, run [`/tasks`](/docs/en/commands). Claude Code names the model on the subagent's row, and adds the [effort level](/docs/en/model-config.md#adjust-effort-level) set for that subagent, if any. Requires Claude Code v2.1.242 or later.

378To check which model a subagent is running on, run [`/tasks`](https://code.claude.com/docs/en/commands). Claude Code names the model on the subagent's row, and adds the [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) set for that subagent, if any. Requires Claude Code v2.1.242 or later.

379379

380380A per-invocation `model` parameter also applies when the subagent is [resumed or sent a follow-up message](#resume-subagents), so the subagent stays on that model.

381381

382As of v2.1.198, subagents also inherit the main conversation's [extended thinking](/docs/en/model-config.md#extended-thinking) configuration: if thinking is on in your session, it's on for the subagent, and if it's off, it stays off. There is no per-subagent thinking setting. Before v2.1.198, subagents ran with extended thinking disabled regardless of the main conversation's setting.

382As of v2.1.198, subagents also inherit the main conversation's [extended thinking](https://code.claude.com/docs/en/model-config.md#extended-thinking) configuration: if thinking is on in your session, it's on for the subagent, and if it's off, it stays off. There is no per-subagent thinking setting. Before v2.1.198, subagents ran with extended thinking disabled regardless of the main conversation's setting.

383383

384384#### Run every subagent on one model

385385

386`CLAUDE_CODE_SUBAGENT_MODEL` is a default, so a subagent's definition or a model Claude passes still takes precedence over it. To apply one model to every subagent, [teammate](/docs/en/agent-teams.md#specify-teammates-and-models), and [workflow agent](/docs/en/workflows.md), also set `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` to `1`. Requires Claude Code v2.1.257 or later.

386`CLAUDE_CODE_SUBAGENT_MODEL` is a default, so a subagent's definition or a model Claude passes still takes precedence over it. To apply one model to every subagent, [teammate](https://code.claude.com/docs/en/agent-teams.md#specify-teammates-and-models), and [workflow agent](https://code.claude.com/docs/en/workflows.md), also set `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` to `1`. Requires Claude Code v2.1.257 or later.

387387

388388* If you set both variables, subagents run on the model in `CLAUDE_CODE_SUBAGENT_MODEL`.

389389* If you set only `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, subagents run on the main conversation's model, except that the built-in Explore subagent runs on the [model listed for it under Built-in subagents](#built-in-subagents).

390390

391For example, to run every subagent on Haiku, set both variables in the `env` block of a [settings file](/docs/en/settings.md):

391For example, to run every subagent on Haiku, set both variables in the `env` block of a [settings file](https://code.claude.com/docs/en/settings.md):

392392

393393```json theme={null}

394394{

from line 399

399399}

400400```

401401

402To check that the setting took effect, run [`/tasks`](/docs/en/commands) while a subagent is running. The subagent's row shows the model it runs on.

402To check that the setting took effect, run [`/tasks`](https://code.claude.com/docs/en/commands) while a subagent is running. The subagent's row shows the model it runs on.

403403

404While `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is [on](/docs/en/env-vars.md), Claude Code ignores the `model` field in subagent definitions, and Claude can't pass a model when it starts a subagent. These subagents still run on the main conversation's model:

404While `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is [on](https://code.claude.com/docs/en/env-vars.md), Claude Code ignores the `model` field in subagent definitions, and Claude can't pass a model when it starts a subagent. These subagents still run on the main conversation's model:

405405

406406* A [fork](#fork-the-current-conversation)

407* A [skill that runs in a subagent](/docs/en/skills.md#run-skills-in-a-subagent) with `model: inherit`

407* A [skill that runs in a subagent](https://code.claude.com/docs/en/skills.md#run-skills-in-a-subagent) with `model: inherit`

408408

409409### Choose an effort level

410410

411To run a subagent at its own [effort level](/docs/en/model-config.md#adjust-effort-level), set the [`effort`](#supported-frontmatter-fields) field in its definition.

411To run a subagent at its own [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level), set the [`effort`](#supported-frontmatter-fields) field in its definition.

412412

413When you ask Claude to run a non-fork subagent at a specific effort level, it can also pass an `effort` parameter for that invocation. The parameter overrides the `effort` field and stays in effect when the subagent is [resumed](#resume-subagents). The [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/en/env-vars#variables) environment variable takes precedence over both. The per-invocation parameter requires Claude Code v2.1.292 or later.

413When you ask Claude to run a non-fork subagent at a specific effort level, it can also pass an `effort` parameter for that invocation. The parameter overrides the `effort` field and stays in effect when the subagent is [resumed](#resume-subagents). The [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/en/env-vars#variables) environment variable takes precedence over both. The per-invocation parameter requires Claude Code v2.1.292 or later.

414414

415415### Control subagent capabilities

416416

from line 418

418418

419419#### Available tools

420420

421Subagents inherit the [built-in tools](/docs/en/tools-reference.md) and MCP tools available in the main conversation, narrowed by two filters: the first removes a short list of tools from every subagent, and the second reduces the built-in tool set for subagents that run in the [background](#run-subagents-in-foreground-or-background), which is the default. On macOS, Linux, and WSL, a subagent can also receive the Glob and Grep tools when the main conversation doesn't have them, as described under [Glob tool behavior](/docs/en/tools-reference.md#glob-tool-behavior). [Forks](#fork-the-current-conversation) skip both filters and receive the main conversation's exact tool pool. The first filter removes these tools, even when listed in the `tools` field:

421Subagents inherit the [built-in tools](https://code.claude.com/docs/en/tools-reference.md) and MCP tools available in the main conversation, narrowed by two filters: the first removes a short list of tools from every subagent, and the second reduces the built-in tool set for subagents that run in the [background](#run-subagents-in-foreground-or-background), which is the default. On macOS, Linux, and WSL, a subagent can also receive the Glob and Grep tools when the main conversation doesn't have them, as described under [Glob tool behavior](https://code.claude.com/docs/en/tools-reference.md#glob-tool-behavior). [Forks](#fork-the-current-conversation) skip both filters and receive the main conversation's exact tool pool. The first filter removes these tools, even when listed in the `tools` field:

422422

423423* `Agent`, when the subagent is at the [depth limit](#let-subagents-spawn-their-own-subagents); in a [fork](#fork-the-current-conversation) the tool stays listed but returns an error instead of spawning

424424* `AskUserQuestion`

425* `EndConversation`, which can end only the main conversation; see [EndConversation tool behavior](/docs/en/tools-reference.md#endconversation-tool-behavior)

425* `EndConversation`, which can end only the main conversation; see [EndConversation tool behavior](https://code.claude.com/docs/en/tools-reference.md#endconversation-tool-behavior)

426426* `EnterPlanMode`

427427* `ExitPlanMode`, unless the subagent's [`permissionMode`](#permission-modes) is `plan`

428428* `ScheduleWakeup`

from line 429

429429* `WaitForMcpServers`

430430* `Workflow`

431431

432The second filter applies to subagents running in the background. Apart from `Agent` and `ExitPlanMode`, which follow the first filter's conditions wherever the subagent runs, a background subagent keeps every MCP tool but only these built-in tools: `Read`, `Grep`, `Glob`, `LSP`, `Bash`, `PowerShell`, `Edit`, `Write`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`, `Skill`, `ToolSearch`, `EnterWorktree`, `ExitWorktree`, `Monitor`, `TaskStop`, `SendMessage`, and `Artifact`, plus [`SubagentHandback`](/docs/en/tools-reference) for a subagent that reports through it. Claude Code removes every other built-in tool from a background subagent, whether inherited or listed in the `tools` field, so the same definition can resolve to different tools in the foreground and the background. The removal reports no error unless it leaves the `tools` list [resolving to nothing](/docs/en/errors.md#agent-would-be-spawned-with-zero-tools).

432The second filter applies to subagents running in the background. Apart from `Agent` and `ExitPlanMode`, which follow the first filter's conditions wherever the subagent runs, a background subagent keeps every MCP tool but only these built-in tools: `Read`, `Grep`, `Glob`, `LSP`, `Bash`, `PowerShell`, `Edit`, `Write`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`, `Skill`, `ToolSearch`, `EnterWorktree`, `ExitWorktree`, `Monitor`, `TaskStop`, `SendMessage`, and `Artifact`, plus [`SubagentHandback`](https://code.claude.com/docs/en/tools-reference) for a subagent that reports through it. Claude Code removes every other built-in tool from a background subagent, whether inherited or listed in the `tools` field, so the same definition can resolve to different tools in the foreground and the background. The removal reports no error unless it leaves the `tools` list [resolving to nothing](https://code.claude.com/docs/en/errors.md#agent-would-be-spawned-with-zero-tools).

433433

434434Before v2.1.280, background subagents couldn't use `LSP`.

435435

436[`ListAgents`](/docs/en/cross-session-messaging) follows these filters like any built-in tool: a foreground subagent inherits it in sessions where cross-session messaging is enabled, and a background subagent doesn't keep it.

436[`ListAgents`](https://code.claude.com/docs/en/cross-session-messaging) follows these filters like any built-in tool: a foreground subagent inherits it in sessions where cross-session messaging is enabled, and a background subagent doesn't keep it.

437437

438Teammates in [agent teams](/docs/en/agent-teams.md) additionally keep the task tools and cron tools: `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `CronCreate`, `CronDelete`, and `CronList`. In a [session without the Task tools](/docs/en/tools-reference.md#task-tool-availability), Claude Code doesn't provide the task tools to subagents either, even when the subagent runs a different model. An in-process teammate follows your session the same way. To find out whether a split-pane teammate has the task tools, see [Task tool availability](/docs/en/tools-reference.md#task-tool-availability).

438Teammates in [agent teams](https://code.claude.com/docs/en/agent-teams.md) additionally keep the task tools and cron tools: `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `CronCreate`, `CronDelete`, and `CronList`. In a [session without the Task tools](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability), Claude Code doesn't provide the task tools to subagents either, even when the subagent runs a different model. An in-process teammate follows your session the same way. To find out whether a split-pane teammate has the task tools, see [Task tool availability](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability).

439439

440440#### Restrict which tools a subagent can use

441441

from line 461

461461---

462462```

463463

464When nothing in the `tools` list resolves to a tool, for example because every entry is misspelled or names a tool that isn't available to subagents, Claude Code usually refuses to launch the subagent and the Agent tool returns an error naming the unresolved entries; see [Agent would be spawned with zero tools](/docs/en/errors.md#agent-would-be-spawned-with-zero-tools) for the message and how to fix each entry.

464When nothing in the `tools` list resolves to a tool, for example because every entry is misspelled or names a tool that isn't available to subagents, Claude Code usually refuses to launch the subagent and the Agent tool returns an error naming the unresolved entries; see [Agent would be spawned with zero tools](https://code.claude.com/docs/en/errors.md#agent-would-be-spawned-with-zero-tools) for the message and how to fix each entry.

465465

466466The `tools` and `disallowedTools` fields also take entries for a whole MCP server:

467467

from line 481

481481---

482482```

483483

484A `disallowedTools` entry with a specifier, such as `Bash(git push *)`, still removes the whole tool from the subagent, not only the matching commands. To keep Bash and block specific commands, add a [Bash deny rule](/docs/en/permissions.md#bash) such as `Bash(git push *)` to `permissions.deny` in your settings. The rule applies to the main conversation and to subagents.

484A `disallowedTools` entry with a specifier, such as `Bash(git push *)`, still removes the whole tool from the subagent, not only the matching commands. To keep Bash and block specific commands, add a [Bash deny rule](https://code.claude.com/docs/en/permissions.md#bash) such as `Bash(git push *)` to `permissions.deny` in your settings. The rule applies to the main conversation and to subagents.

485485

486486##### MCP server names that contain a double underscore

487487

488488If a subagent gets none of the tools from an MCP server whose name contains `__`, such as `reports__v2`, check the subagent's `mcp__` entries:

489489

490* **In `tools`**: write `mcp__` followed by the [server's whole name](/docs/en/permissions.md#mcp) and `__*`, as in `mcp__reports__v2__*`. Without the trailing `__*`, `mcp__reports__v2` matches none of that server's tools.

490* **In `tools`**: write `mcp__` followed by the [server's whole name](https://code.claude.com/docs/en/permissions.md#mcp) and `__*`, as in `mcp__reports__v2__*`. Without the trailing `__*`, `mcp__reports__v2` matches none of that server's tools.

491491* **In `disallowedTools`**: look for `mcp__reports` or `mcp__reports__*`, the entries that withhold a server named `reports`. With either entry, the subagent loses every `reports__v2` tool as well, because those tool names also begin with `mcp__reports__`. To withhold only the `reports` server's tools, list them one by one instead, such as `mcp__reports__run_query`.

492492

493493#### Restrict which subagents can be spawned

from line 520

520520

521521#### Scope MCP servers to a subagent

522522

523Use the `mcpServers` field to give a subagent access to [MCP](/docs/en/mcp.md) servers that aren't available in the main conversation. Inline servers defined here are connected when the subagent starts, subject to the [trust rule for the agent file's folder](#inline-server-trust), and disconnected when it finishes. String references share the parent session's connection.

523Use the `mcpServers` field to give a subagent access to [MCP](https://code.claude.com/docs/en/mcp.md) servers that aren't available in the main conversation. Inline servers defined here are connected when the subagent starts, subject to the [trust rule for the agent file's folder](#inline-server-trust), and disconnected when it finishes. String references share the parent session's connection.

524524

525525> [!NOTE]

526526>

from line 529

529529> * As a subagent, spawned through the Agent tool or an @-mention

530530> * As the main session, launched with [`--agent`](#invoke-subagents-explicitly) or the `agent` setting

531531>

532> When the agent is the main session, inline server definitions connect at startup alongside servers from [`.mcp.json`](/docs/en/mcp) and settings files, under the same [trust rule for the agent file's folder](#inline-server-trust). In `/mcp`, a remote (HTTP or SSE) server you've used before can show the [`cached` status](/docs/en/mcp#managing-your-servers) instead; Claude Code connects it when Claude first calls one of its tools.

532> When the agent is the main session, inline server definitions connect at startup alongside servers from [`.mcp.json`](https://code.claude.com/docs/en/mcp) and settings files, under the same [trust rule for the agent file's folder](#inline-server-trust). In `/mcp`, a remote (HTTP or SSE) server you've used before can show the [`cached` status](https://code.claude.com/docs/en/mcp#managing-your-servers) instead; Claude Code connects it when Claude first calls one of its tools.

533533

534534Each entry in the list is either an inline server definition or a string referencing an MCP server already configured in your session:

535535

from line 556

556556

557557The MCP restrictions that apply to the main session also cover servers declared in subagent frontmatter:

558558

559* [`--strict-mcp-config`](/docs/en/cli-reference) and [`--bare`](/docs/en/cli-reference)

560* [Enterprise managed MCP configuration](/docs/en/managed-mcp.md)

561* [`allowedMcpServers` and `deniedMcpServers` policies](/docs/en/managed-mcp#policy-based-control-with-allowlists-and-denylists)

559* [`--strict-mcp-config`](https://code.claude.com/docs/en/cli-reference) and [`--bare`](https://code.claude.com/docs/en/cli-reference)

560* [Enterprise managed MCP configuration](https://code.claude.com/docs/en/managed-mcp.md)

561* [`allowedMcpServers` and `deniedMcpServers` policies](https://code.claude.com/docs/en/managed-mcp#policy-based-control-with-allowlists-and-denylists)

562562

563563When one of these blocks a server, Claude Code skips it and shows a warning naming the blocked servers.

564564

from line 566

566566

567567#### Trust required for inline MCP servers

568568

569Claude Code loads an [inline MCP server](#scope-mcp-servers-to-a-subagent) from an agent file in your project's `.claude/agents/` directory, or in an `--add-dir` directory's `.claude/agents/`, only after you [trust the folder the agent file came from](/docs/en/permissions.md#what-runs-before-you-trust-a-folder). Before v2.1.238, Claude Code loaded these servers without checking trust.

569Claude Code loads an [inline MCP server](#scope-mcp-servers-to-a-subagent) from an agent file in your project's `.claude/agents/` directory, or in an `--add-dir` directory's `.claude/agents/`, only after you [trust the folder the agent file came from](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder). Before v2.1.238, Claude Code loaded these servers without checking trust.

570570

571* **Trust that doesn't count**: a parent folder's trust, and the automatic trust a `-p` or SDK session gets for [hooks in settings files](/docs/en/permissions.md#what-runs-before-you-trust-a-folder)

571* **Trust that doesn't count**: a parent folder's trust, and the automatic trust a `-p` or SDK session gets for [hooks in settings files](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder)

572572* **Until then**: Claude Code skips every inline server in that agent file and writes the exact `projects["<path>"].hasTrustDialogAccepted` key for `~/.claude.json` to the debug log

573573* **`--add-dir` directories**: a directory outside your trusted workspace's repository needs its own trust entry, since its `.claude/agents/` files don't inherit your workspace's trust

574574

from line 579

579579

580580#### Permission modes

581581

582Set `permissionMode` to choose the permission mode a subagent runs in. Use the modes' config values, so Manual mode is `default`. If you leave it unset, the subagent inherits the main conversation's [permission mode](/docs/en/permission-modes.md).

583583

584584The main conversation's permission mode decides whether Claude Code uses the value you set:

585585

586* When the main conversation is in `bypassPermissions`, `acceptEdits`, or [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), the subagent runs in that same mode and Claude Code ignores the `permissionMode` you set. Under auto mode, the classifier evaluates the subagent's tool calls with the main conversation's block and allow rules. When the subagent finishes, the classifier also reviews its work and its final report before the report is delivered, as [How auto mode handles subagents](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) describes.

587* When the main conversation is in `plan` mode, the subagent stays in plan mode whichever `permissionMode` you set, unless it runs as an [agent team teammate](#subagent-names) under the [agent teams rules](/docs/en/agent-teams.md#have-teammates-plan-before-implementing). If you set `dontAsk`, the subagent also doesn't prompt you: an action that plan mode would ask you to approve is denied instead.

586* When the main conversation is in `bypassPermissions`, `acceptEdits`, or [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), the subagent runs in that same mode and Claude Code ignores the `permissionMode` you set. Under auto mode, the classifier evaluates the subagent's tool calls with the main conversation's block and allow rules. When the subagent finishes, the classifier also reviews its work and its final report before the report is delivered, as [How auto mode handles subagents](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) describes.

587* When the main conversation is in `plan` mode, the subagent stays in plan mode whichever `permissionMode` you set, unless it runs as an [agent team teammate](#subagent-names) under the [agent teams rules](https://code.claude.com/docs/en/agent-teams.md#have-teammates-plan-before-implementing). If you set `dontAsk`, the subagent also doesn't prompt you: an action that plan mode would ask you to approve is denied instead.

588588* When the main conversation is in `default` or `dontAsk` mode, the subagent runs in the permission mode you set. It keeps the main conversation's permission mode instead in these cases:

589589 * You set `bypassPermissions`. The `bypassPermissions` exception requires Claude Code v2.1.267 or later.

590 * You set `auto` and [auto mode isn't available](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) to the subagent, such as when a settings file sets [`disableAutoMode`](/docs/en/settings-reference#disableautomode) or the subagent's model doesn't support auto mode.

590 * You set `auto` and [auto mode isn't available](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) to the subagent, such as when a settings file sets [`disableAutoMode`](https://code.claude.com/docs/en/settings-reference#disableautomode) or the subagent's model doesn't support auto mode.

591591

592592`permissionMode` accepts these values, and `manual` as an alias for `default`:

593593

from line 595

595595| :- | :- |

596596| `default` | Manual mode: prompts for permission |

597597| `acceptEdits` | Auto-accept file edits and common filesystem commands for paths in the working directory or `additionalDirectories` |

598| `auto` | [Auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode): a background classifier reviews commands and protected-directory writes |

599| `dontAsk` | Auto-denies calls that would prompt, though a [mod](/docs/en/plugins/mods/overview.md) you installed can still approve [some of those calls](/docs/en/permissions.md#precedence-among-rules-hooks-and-mods). Explicitly allowed tools still work. `AskUserQuestion`, MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool), [reads from network paths](/docs/en/permissions.md#network-paths), and connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) in sessions where that setting reaches Claude Code are denied even if you've allowed them |

600| `bypassPermissions` | [Skip permission prompts](/docs/en/permission-modes.md#skip-all-checks-with-bypasspermissions-mode). A subagent runs in this mode only when the main conversation does |

598| `auto` | [Auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode): a background classifier reviews commands and protected-directory writes |

599| `dontAsk` | Auto-denies calls that would prompt, though a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) you installed can still approve [some of those calls](https://code.claude.com/docs/en/permissions.md#precedence-among-rules-hooks-and-mods). Explicitly allowed tools still work. `AskUserQuestion`, MCP tools marked [`requiresUserInteraction`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool), [reads from network paths](https://code.claude.com/docs/en/permissions.md#network-paths), and connector tools [your organization set to `ask`](https://code.claude.com/docs/en/mcp#organization-controls-on-connector-tools) in sessions where that setting reaches Claude Code are denied even if you've allowed them |

600| `bypassPermissions` | [Skip permission prompts](https://code.claude.com/docs/en/permission-modes.md#skip-all-checks-with-bypasspermissions-mode). A subagent runs in this mode only when the main conversation does |

601601| `plan` | Plan mode (read-only exploration) |

602602

603603#### Preload skills into subagents

from line 618

618618

619619The full content of each listed skill is injected into the subagent's context at startup, up to the first 32 distinct names in the list. This field controls which skills are preloaded, not which skills the subagent can access: without it, the subagent can still discover and invoke project, user, and plugin skills through the Skill tool during execution. To prevent a subagent from invoking skills entirely, omit `Skill` from the [`tools`](#available-tools) list or add it to `disallowedTools`.

620620

621You can't preload skills that set [`disable-model-invocation: true`](/docs/en/skills#control-who-invokes-a-skill), since preloading draws from the same set of skills Claude can invoke. This includes the bundled `/verify` skill, which Claude can't run on its own.

621You can't preload skills that set [`disable-model-invocation: true`](https://code.claude.com/docs/en/skills#control-who-invokes-a-skill), since preloading draws from the same set of skills Claude can invoke. This includes the bundled `/verify` skill, which Claude can't run on its own.

622622

623623If a listed skill is missing or disabled, for example by your organization's policy, Claude Code skips it and logs a warning to the debug log.

624624

625625> [!NOTE]

626626>

627> This is the inverse of [running a skill in a subagent](/docs/en/skills.md#run-skills-in-a-subagent). With `skills` in a subagent, the subagent controls the system prompt and loads skill content. With `context: fork` in a skill, the skill content is injected into the agent you specify. In both cases the subagent starts without your conversation history.

627> This is the inverse of [running a skill in a subagent](https://code.claude.com/docs/en/skills.md#run-skills-in-a-subagent). With `skills` in a subagent, the subagent controls the system prompt and loads skill content. With `context: fork` in a skill, the skill content is injected into the agent you specify. In both cases the subagent starts without your conversation history.

628628

629629#### Enable persistent memory

630630

from line 649

649649| `project` | `.claude/agent-memory/<name-of-agent>/` | the subagent's knowledge is project-specific and shareable via version control |

650650| `local` | `.claude/agent-memory-local/<name-of-agent>/` | the subagent's knowledge is project-specific but shouldn't be checked into version control |

651651

652Subagent memory is part of [auto memory](/docs/en/memory.md#auto-memory): if you turn auto memory off, with the `autoMemoryEnabled` setting or `CLAUDE_CODE_DISABLE_AUTO_MEMORY`, the `memory` field has no effect and the subagent launches without the memory instructions or the memory tool access described below.

652Subagent memory is part of [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory): if you turn auto memory off, with the `autoMemoryEnabled` setting or `CLAUDE_CODE_DISABLE_AUTO_MEMORY`, the `memory` field has no effect and the subagent launches without the memory instructions or the memory tool access described below.

653653

654654When memory is enabled:

655655

from line 691

691691---

692692```

693693

694Claude Code [passes hook input as JSON](/docs/en/hooks.md#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the Bash command, and [exits with code 2](/docs/en/hooks.md#exit-code-2-behavior-per-event) to block write operations:

694Claude Code [passes hook input as JSON](https://code.claude.com/docs/en/hooks.md#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the Bash command, and [exits with code 2](https://code.claude.com/docs/en/hooks.md#exit-code-2-behavior-per-event) to block write operations:

695695

696696```bash theme={null}

697697#!/bin/bash

from line 717

717717

718718To test the rule, ask the subagent to run an `UPDATE` statement: the script exits with code 2, Claude Code blocks the command, and the subagent sees the `Blocked: Only SELECT queries are allowed` message.

719719

720See [Hook input](/docs/en/hooks.md#pretooluse-input) for the complete input schema and [exit codes](/docs/en/hooks.md#exit-code-output) for how exit codes affect behavior. On Windows, write hook scripts in PowerShell and add `shell: powershell` to the hook entry as shown in [running hooks in PowerShell](/docs/en/hooks.md#windows-powershell-tool).

720See [Hook input](https://code.claude.com/docs/en/hooks.md#pretooluse-input) for the complete input schema and [exit codes](https://code.claude.com/docs/en/hooks.md#exit-code-output) for how exit codes affect behavior. On Windows, write hook scripts in PowerShell and add `shell: powershell` to the hook entry as shown in [running hooks in PowerShell](https://code.claude.com/docs/en/hooks.md#windows-powershell-tool).

721721

722722#### Disable specific subagents

723723

724You can prevent Claude from using specific subagents by adding them to the `deny` array in your [settings](/docs/en/settings-reference.md#permission-settings). Use the format `Agent(subagent-name)` where `subagent-name` matches the subagent's name field.

724You can prevent Claude from using specific subagents by adding them to the `deny` array in your [settings](https://code.claude.com/docs/en/settings-reference.md#permission-settings). Use the format `Agent(subagent-name)` where `subagent-name` matches the subagent's name field.

725725

726726```json theme={null}

727727{

from line 737

737737claude --disallowedTools "Agent(Explore)"

738738```

739739

740See [Permissions documentation](/docs/en/permissions.md#tool-specific-permission-rules) for more details on permission rules.

740See [Permissions documentation](https://code.claude.com/docs/en/permissions.md#tool-specific-permission-rules) for more details on permission rules.

741741

742742### Define hooks for subagents

743743

744Subagents can define [hooks](/docs/en/hooks.md) that run during the subagent's lifecycle. There are two ways to configure hooks:

744Subagents can define [hooks](https://code.claude.com/docs/en/hooks.md) that run during the subagent's lifecycle. There are two ways to configure hooks:

745745

746746* **In the subagent's frontmatter**: define hooks that run only while that subagent is active

747747* **In `settings.json`**: define session-wide hooks that also fire inside subagents. Tool events such as `PreToolUse` and `PostToolUse` fire for the subagent's tool calls the same way they do in the main conversation, and `SubagentStart` and `SubagentStop` fire when a subagent starts or finishes

748748

749Hooks from [settings files, managed policy settings, and plugins](/docs/en/hooks.md#hook-locations) all apply inside subagents, so a `PreToolUse` hook in `settings.json` also runs before every tool a subagent uses.

749Hooks from [settings files, managed policy settings, and plugins](https://code.claude.com/docs/en/hooks.md#hook-locations) all apply inside subagents, so a `PreToolUse` hook in `settings.json` also runs before every tool a subagent uses.

750750

751751#### Hooks in subagent frontmatter

752752

from line 754

754754

755755> [!NOTE]

756756>

757> Frontmatter hooks fire when the agent is spawned as a subagent through the Agent tool or an @-mention, and when the agent runs as the main session via [`--agent`](#invoke-subagents-explicitly) or the `agent` setting. In the main-session case they run alongside any hooks defined in [`settings.json`](/docs/en/hooks).

758758

759To let a project-level subagent's frontmatter hooks run, accept the [workspace trust dialog](/docs/en/permissions.md#project-allow-rules-and-workspace-trust) for the folder that contains the agent file. Hooks from user-level subagents in `~/.claude/agents/` and from definitions you pass with `--agents` run without this step. If you added a folder with `--add-dir` from outside your trusted workspace's repository, trust that folder separately: its `.claude/agents/` hooks don't inherit the workspace's grant.

759To let a project-level subagent's frontmatter hooks run, accept the [workspace trust dialog](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust) for the folder that contains the agent file. Hooks from user-level subagents in `~/.claude/agents/` and from definitions you pass with `--agents` run without this step. If you added a folder with `--add-dir` from outside your trusted workspace's repository, trust that folder separately: its `.claude/agents/` hooks don't inherit the workspace's grant.

760760

761Until you trust the folder, the subagent still runs, but Claude Code skips its frontmatter hooks and logs an error to the debug log explaining how to trust the folder. This is a stricter rule than the one for hooks in settings files: trusting a parent folder isn't enough, and a `-p` session doesn't count as trusted. [What runs before you trust a folder](/docs/en/permissions.md#what-runs-before-you-trust-a-folder) compares the two. Before v2.1.218, frontmatter hooks could run from folders you hadn't trusted, including in non-interactive sessions.

761Until you trust the folder, the subagent still runs, but Claude Code skips its frontmatter hooks and logs an error to the debug log explaining how to trust the folder. This is a stricter rule than the one for hooks in settings files: trusting a parent folder isn't enough, and a `-p` session doesn't count as trusted. [What runs before you trust a folder](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) compares the two. Before v2.1.218, frontmatter hooks could run from folders you hadn't trusted, including in non-interactive sessions.

762762

763All [hook events](/docs/en/hooks.md#hook-events) are supported. The most common events for subagents are:

763All [hook events](https://code.claude.com/docs/en/hooks.md#hook-events) are supported. The most common events for subagents are:

764764

765765| Event | Matcher input | When it fires |

766766| :- | :- | :- |

from line 799

799799| `SubagentStart` | Agent type name | When a subagent begins execution |

800800| `SubagentStop` | Agent type name | When a subagent completes |

801801

802Both events support matchers to target specific agent types by name. The matcher value is the agent's frontmatter `name` for project-level and user-level subagents, or the plugin-scoped identifier such as `my-plugin:db-agent` for [plugin subagents](/docs/en/plugins/components.md#agents). A scoped name contains a colon, so it is evaluated as an [unanchored regular expression](/docs/en/hooks.md#matcher-patterns); anchor it with `^` and `$`, as in `^my-plugin:db-agent$`, to match only that agent.

802Both events support matchers to target specific agent types by name. The matcher value is the agent's frontmatter `name` for project-level and user-level subagents, or the plugin-scoped identifier such as `my-plugin:db-agent` for [plugin subagents](https://code.claude.com/docs/en/plugins/components.md#agents). A scoped name contains a colon, so it is evaluated as an [unanchored regular expression](https://code.claude.com/docs/en/hooks.md#matcher-patterns); anchor it with `^` and `$`, as in `^my-plugin:db-agent$`, to match only that agent.

803803

804804This example runs a setup script only when the `db-agent` subagent starts, and a cleanup script when any subagent stops:

805805

from line 825

825825}

826826```

827827

828See [Hooks](/docs/en/hooks.md) for the complete hook configuration format.

828See [Hooks](https://code.claude.com/docs/en/hooks.md) for the complete hook configuration format.

829829

830830## Work with subagents

831831

from line 833

833833

834834Claude automatically delegates tasks based on the task description in your request, the `description` field in subagent configurations, and current context. To encourage proactive delegation, include phrases like "use proactively" in your subagent's description field.

835835

836Keep descriptions brief: Claude Code shows a startup warning when your subagents' combined descriptions pass [the 15,000-token limit](/docs/en/errors.md#agent-descriptions-are-over-the-15000-token-limit), and still loads every subagent.

836Keep descriptions brief: Claude Code shows a startup warning when your subagents' combined descriptions pass [the 15,000-token limit](https://code.claude.com/docs/en/errors.md#agent-descriptions-are-over-the-15000-token-limit), and still loads every subagent.

837837

838If the subagent ships in a [plugin](/docs/en/plugins/overview.md), you can measure how reliably Claude delegates to it across realistic prompts instead of checking one at a time: [`claude plugin eval`](/docs/en/plugin-evals) runs each prompt with and without the plugin and scores the results.

838If the subagent ships in a [plugin](https://code.claude.com/docs/en/plugins/overview.md), you can measure how reliably Claude delegates to it across realistic prompts instead of checking one at a time: [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals) runs each prompt with and without the plugin and scores the results.

839839

840840### Invoke subagents explicitly

841841

from line 860

860860

861861Your full message still goes to Claude, which writes the subagent's task prompt based on what you asked. The @-mention controls which subagent Claude invokes, not what prompt it receives.

862862

863Subagents provided by an enabled [plugin](/docs/en/plugins/overview.md) appear in the typeahead under their scoped name, such as `my-plugin:code-reviewer` or `my-plugin:review:security` when the plugin [organizes agents into subfolders](#choose-the-subagent-scope). Named background subagents currently running in the session also appear in the typeahead, showing their status next to the name.

863Subagents provided by an enabled [plugin](https://code.claude.com/docs/en/plugins/overview.md) appear in the typeahead under their scoped name, such as `my-plugin:code-reviewer` or `my-plugin:review:security` when the plugin [organizes agents into subfolders](#choose-the-subagent-scope). Named background subagents currently running in the session also appear in the typeahead, showing their status next to the name.

864864

865865You can also type the mention manually without using the picker: `@agent-<name>` for local subagents, or `@agent-` followed by the scoped name for plugin subagents, for example `@agent-my-plugin:code-reviewer`. While you type this form the typeahead shows file matches rather than agents. The agent mention still resolves when you submit.

866866

867**Run the whole session as a subagent.** Pass [`--agent <name>`](/docs/en/cli-reference) to start a session where the main thread itself takes on that subagent's tool restrictions and model:

867**Run the whole session as a subagent.** Pass [`--agent <name>`](https://code.claude.com/docs/en/cli-reference) to start a session where the main thread itself takes on that subagent's tool restrictions and model:

868868

869869```bash theme={null}

870870claude --agent code-reviewer

871871```

872872

873Unless the agent's [prompt is empty](#choose-the-subagent-scope), a custom subagent's system prompt replaces the default Claude Code system prompt entirely, the same way [`--system-prompt`](/docs/en/cli-reference) does. `CLAUDE.md` files and project memory still load through the normal message flow, even when the agent's definition sets [`omitClaudeMd`](#supported-frontmatter-fields). If you run the session with `-p` as a custom agent that has its own prompt, it also starts without the [git status snapshot](/docs/en/settings-reference.md#includegitinstructions).

873Unless the agent's [prompt is empty](#choose-the-subagent-scope), a custom subagent's system prompt replaces the default Claude Code system prompt entirely, the same way [`--system-prompt`](https://code.claude.com/docs/en/cli-reference) does. `CLAUDE.md` files and project memory still load through the normal message flow, even when the agent's definition sets [`omitClaudeMd`](#supported-frontmatter-fields). If you run the session with `-p` as a custom agent that has its own prompt, it also starts without the [git status snapshot](https://code.claude.com/docs/en/settings-reference.md#includegitinstructions).

874874

875875The agent name appears as `@<name>` in the startup header so you can confirm it's active.

876876

877This works with built-in and custom subagents, and the choice persists when you resume the session: Claude Code restores the agent's tool restrictions and model along with the conversation. If the agent no longer exists when you resume, the session continues with the default tools and shows a [warning naming the agent](/docs/en/errors.md#session-agent-no-longer-available). For the system prompt in either case, see [System prompt flags in resumed conversations](/docs/en/cli-reference.md#system-prompt-flags-in-resumed-conversations).

877This works with built-in and custom subagents, and the choice persists when you resume the session: Claude Code restores the agent's tool restrictions and model along with the conversation. If the agent no longer exists when you resume, the session continues with the default tools and shows a [warning naming the agent](https://code.claude.com/docs/en/errors.md#session-agent-no-longer-available). For the system prompt in either case, see [System prompt flags in resumed conversations](https://code.claude.com/docs/en/cli-reference.md#system-prompt-flags-in-resumed-conversations).

878878

879879For a plugin-provided subagent, you can pass only the agent name and Claude Code finds it:

880880

from line 914

914914* **`claude -p` and the Agent SDK**: Claude can wait, on its own judgment or when you ask.

915915* **Interactive terminal session, VS Code, and desktop app sessions on your machine**: to let Claude wait for a subagent, [turn off fork mode](#let-claude-wait-for-a-subagent), which is [on by default](#turn-fork-mode-on-or-off).

916916

917For a skill with `context: fork`, Claude Code follows the rules in [Run skills in a subagent](/docs/en/skills.md#run-skills-in-a-subagent) instead, whether or not fork mode is on.

917For a skill with `context: fork`, Claude Code follows the rules in [Run skills in a subagent](https://code.claude.com/docs/en/skills.md#run-skills-in-a-subagent) instead, whether or not fork mode is on.

918918

919919#### Let Claude wait for a subagent

920920

9211. Turn [fork mode](#turn-fork-mode-on-or-off) off by setting `CLAUDE_CODE_FORK_SUBAGENT` to `0`, for example in [`settings.json`](/docs/en/settings):

9211. Turn [fork mode](#turn-fork-mode-on-or-off) off by setting `CLAUDE_CODE_FORK_SUBAGENT` to `0`, for example in [`settings.json`](https://code.claude.com/docs/en/settings):

922922

923923 ```json theme={null}

924924 {

from line 932

932932

9339333. Ask Claude to wait when you need a result first, for example "run the reviewer subagent and wait for its report".

934934

935To keep working while Claude waits, press **Ctrl+B** in the terminal or click [**Run in background**](/docs/en/vs-code.md#move-a-running-command-or-subagent-to-the-background) in VS Code.

935To keep working while Claude waits, press **Ctrl+B** in the terminal or click [**Run in background**](https://code.claude.com/docs/en/vs-code.md#move-a-running-command-or-subagent-to-the-background) in VS Code.

936936

937If you set the [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/en/env-vars) environment variable to `1` instead of turning fork mode off, Claude waits for every subagent. Background commands are off too, and **Ctrl+B** doesn't move anything to the background.

937If you set the [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/en/env-vars) environment variable to `1` instead of turning fork mode off, Claude waits for every subagent. Background commands are off too, and **Ctrl+B** doesn't move anything to the background.

938938

939939#### Tools, permissions, and results of background subagents

940940

from line 942

942942

943943Background subagents surface every permission prompt in your main session. When you answer one of those prompts with a choice that lasts beyond that one tool call, such as a grant that lasts for the rest of the session, Claude Code applies your answer to the whole session, including your main conversation.

944944

945A background subagent can leave a background [Bash or PowerShell command](/docs/en/tools-reference.md#background-commands) [running past the end of its turn](/docs/en/interactive-mode.md#how-backgrounding-works). When that command ends, Claude Code sends the subagent a notification.

945A background subagent can leave a background [Bash or PowerShell command](https://code.claude.com/docs/en/tools-reference.md#background-commands) [running past the end of its turn](https://code.claude.com/docs/en/interactive-mode.md#how-backgrounding-works). When that command ends, Claude Code sends the subagent a notification.

946946

947947A background subagent's results reach Claude as a completion notification in a later turn. Claude waits for that notification before reporting the subagent's results, and if you ask about progress first, it reports that the subagent is still running.

948948

from line 950

950950

951951Claude Code clears a background subagent's row from the subagent panel below the prompt input in one of two ways, depending on how the subagent ended:

952952

953* When a subagent finishes successfully, Claude Code removes its row immediately and, except in [screen reader mode](/docs/en/accessibility.md), shows `/tasks to see subagents` in the footer for 30 seconds. During those 30 seconds, run [`/tasks`](/docs/en/commands) and press `Enter` on the subagent to open its transcript. Before v2.1.232, Claude Code kept the row for 30 seconds after the subagent finished, the same as a failed one, and showed no footer hint.

953* When a subagent finishes successfully, Claude Code removes its row immediately and, except in [screen reader mode](https://code.claude.com/docs/en/accessibility.md), shows `/tasks to see subagents` in the footer for 30 seconds. During those 30 seconds, run [`/tasks`](https://code.claude.com/docs/en/commands) and press `Enter` on the subagent to open its transcript. Before v2.1.232, Claude Code kept the row for 30 seconds after the subagent finished, the same as a failed one, and showed no footer hint.

954954* When a subagent fails or you stop it, Claude Code keeps its row for 30 seconds. To clear the row sooner, select it and press `x`.

955955

956A background subagent that completes stays listed in [`/tasks`](/docs/en/commands), marked done and sorted below running work, for the same 30 seconds as the footer hint. Its detail view stays open when the subagent finishes. Subagents that fail or that you stop leave the list. Before v2.1.208, a completed subagent left the list the moment it finished and its detail view closed.

956A background subagent that completes stays listed in [`/tasks`](https://code.claude.com/docs/en/commands), marked done and sorted below running work, for the same 30 seconds as the footer hint. Its detail view stays open when the subagent finishes. Subagents that fail or that you stop leave the list. Before v2.1.208, a completed subagent left the list the moment it finished and its detail view closed.

957957

958958### Subagent names

959959

960If you start a session with [agent teams](/docs/en/agent-teams.md#enable-agent-teams) enabled, Claude can give a subagent a name by passing a `name` parameter on the Agent tool call. It may do so on its own, without asking you first. The name makes the subagent addressable: Claude can [message or resume it by name](#resume-subagents) after it finishes.

960If you start a session with [agent teams](https://code.claude.com/docs/en/agent-teams.md#enable-agent-teams) enabled, Claude can give a subagent a name by passing a `name` parameter on the Agent tool call. It may do so on its own, without asking you first. The name makes the subagent addressable: Claude can [message or resume it by name](#resume-subagents) after it finishes.

961961

962In an interactive session with [agent teams](/docs/en/agent-teams.md) enabled, a subagent that Claude spawns from the main conversation with a `name` launches as a teammate instead, unless the call is a [fork](#fork-the-current-conversation) or passes `isolation` on the call itself. An `isolation` value in the subagent's frontmatter doesn't prevent it, and the teammate then runs in the main session's working directory. See [How Claude starts agent teams](/docs/en/agent-teams.md#how-claude-starts-agent-teams).

962In an interactive session with [agent teams](https://code.claude.com/docs/en/agent-teams.md) enabled, a subagent that Claude spawns from the main conversation with a `name` launches as a teammate instead, unless the call is a [fork](#fork-the-current-conversation) or passes `isolation` on the call itself. An `isolation` value in the subagent's frontmatter doesn't prevent it, and the teammate then runs in the main session's working directory. See [How Claude starts agent teams](https://code.claude.com/docs/en/agent-teams.md#how-claude-starts-agent-teams).

963963

964964### API errors in subagents

965965

966When something [cuts off a subagent's response mid-stream](/docs/en/errors.md#the-response-above-may-be-incomplete), and the partial response contains text but no tool calls, Claude Code prompts the subagent to continue rather than ending the run. This happens in interactive sessions too. The run ends on the error only once those continuations are used up.

966When something [cuts off a subagent's response mid-stream](https://code.claude.com/docs/en/errors.md#the-response-above-may-be-incomplete), and the partial response contains text but no tool calls, Claude Code prompts the subagent to continue rather than ending the run. This happens in interactive sessions too. The run ends on the error only once those continuations are used up.

967967

968968A subagent whose run ends on an API error, such as a usage limit or a repeated server error, reports that failure back to Claude. What Claude receives depends on where the subagent ran:

969969

970* **Foreground**: if a rate limit, overload, or server error cuts off a subagent that already produced text output, the Agent tool returns that partial output with a note that the subagent was cut off and didn't finish its task. A subagent that produced nothing, or whose only output was tool calls, fails with [`Agent terminated early due to an API error`](/docs/en/errors#agent-terminated-early-due-to-an-api-error), followed by the error detail.

970* **Foreground**: if a rate limit, overload, or server error cuts off a subagent that already produced text output, the Agent tool returns that partial output with a note that the subagent was cut off and didn't finish its task. A subagent that produced nothing, or whose only output was tool calls, fails with [`Agent terminated early due to an API error`](https://code.claude.com/docs/en/errors#agent-terminated-early-due-to-an-api-error), followed by the error detail.

971971* **Background**: the subagent is marked failed, and the message Claude receives when it ends names the API error and includes the subagent's last output, so partial work isn't lost.

972972

973973If a subagent's report opens with the following line, the subagent finished on a fallback model:

from line 976

976976⚠ This agent switched to <model> because its earlier model could not be used.

977977```

978978

979When you configure a [fallback model chain](/docs/en/model-config.md#fallback-model-chains) and a subagent encounters a failure the chain covers, such as its model being unavailable, Claude Code switches the subagent to the first model in the chain that accepts the request. The subagent keeps working instead of ending on the error.

979When you configure a [fallback model chain](https://code.claude.com/docs/en/model-config.md#fallback-model-chains) and a subagent encounters a failure the chain covers, such as its model being unavailable, Claude Code switches the subagent to the first model in the chain that accepts the request. The subagent keeps working instead of ending on the error.

980980

981981Once the underlying API error clears, ask Claude to retry the task or [resume the subagent](#resume-subagents).

982982

from line 987

987987* **Backslash insertion**: the scan inserts a backslash into text that imitates Claude Code's own output, such as a `<system-reminder>` tag or a line starting with `Human:` or `Assistant:`, so the imitation reads as ordinary text instead of being mistaken for part of the conversation.

988988* **Marker line**: the scan prepends a line starting with `[harness: subagent output matched instruction-shaped pattern(s):` when the report imitates a tag like `<system-reminder>` or mentions permission settings such as `bypassPermissions` or `--dangerously-skip-permissions`. Permission-setting mentions get the marker line, but the text itself stays as written.

989989

990The scan doesn't judge whether content is malicious, and it doesn't change what an instruction in a report can do: a tool call the report leads Claude to make still goes through the session's [permission checks](/docs/en/permissions.md) and [sandboxing](/docs/en/sandboxing.md). It isn't a substitute for [restricting what a subagent can reach](#control-subagent-capabilities).

990The scan doesn't judge whether content is malicious, and it doesn't change what an instruction in a report can do: a tool call the report leads Claude to make still goes through the session's [permission checks](https://code.claude.com/docs/en/permissions.md) and [sandboxing](https://code.claude.com/docs/en/sandboxing.md). It isn't a substitute for [restricting what a subagent can reach](#control-subagent-capabilities).

991991

992992A report that returns to Claude as the subagent's result also arrives under a header marking it as subagent output. The header states that instructions or approval claims inside the report are the subagent's words and carry no authority from you.

993993

from line 1017

10171017>

10181018> When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context, and each subagent spends tokens of its own while it runs.

10191019

1020For work that needs to keep running in parallel or won't fit in one context window, run it in [separate sessions](/docs/en/agents.md) and let Claude [pass findings between them](/docs/en/cross-session-messaging.md).

1020For work that needs to keep running in parallel or won't fit in one context window, run it in [separate sessions](https://code.claude.com/docs/en/agents.md) and let Claude [pass findings between them](https://code.claude.com/docs/en/cross-session-messaging.md).

10211021

10221022#### Chain subagents

10231023

from line 1042

10421042* You want to enforce specific tool restrictions or permissions

10431043* The work is self-contained and can return a summary

10441044

1045Consider [Skills](/docs/en/skills.md) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.

1045Consider [Skills](https://code.claude.com/docs/en/skills.md) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.

10461046

1047For a question about something already in your conversation, use [`/btw`](/docs/en/interactive-mode#side-questions-with-%2Fbtw) instead of a subagent. It sees your full context but has no tool access, and the answer isn't added to history.

1047For a question about something already in your conversation, use [`/btw`](https://code.claude.com/docs/en/interactive-mode#side-questions-with-%2Fbtw) instead of a subagent. It sees your full context but has no tool access, and the answer isn't added to history.

10481048

10491049### Let subagents spawn their own subagents

10501050

from line 1055

10551055* **Interactive terminal session**: only the top-level subagent's summary returns to you, because a subagent that launches background subagents waits for their results before it finishes.

10561056* **`claude -p` and the Agent SDK**: the spawning subagent waits while [fork mode](#turn-fork-mode-on-or-off) is on. If you turn fork mode off, nested subagents start in the [background](#run-subagents-in-foreground-or-background) instead. The spawning subagent doesn't wait for a background nested subagent, which reports to your main conversation if it outlasts the spawning subagent.

10571057

1058To change the limit, set [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/en/env-vars) to the number of subagent layers you want below your main conversation. For example, this entry in [`settings.json`](/docs/en/settings) caps nesting at two layers:

1058To change the limit, set [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](https://code.claude.com/docs/en/env-vars) to the number of subagent layers you want below your main conversation. For example, this entry in [`settings.json`](https://code.claude.com/docs/en/settings) caps nesting at two layers:

10591059

10601060```json theme={null}

10611061{

from line 1082

10821082

10831083Two limits control subagent use, each with its own variable: this one stops Claude from spawning more subagents while too many are running, and the [depth limit](#let-subagents-spawn-their-own-subagents) caps how deeply subagents nest. There's no limit on the total number of subagents Claude can spawn over a session.

10841084

1085By default, when 20 subagents are running in a session, spawning another with the Agent tool fails with `Concurrent subagent limit reached`, and the error tells Claude not to retry. Spawning succeeds again when the running count drops below the limit. To change the limit, set [`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`](/docs/en/env-vars) to any positive whole number. Sessions with [ultracode](/docs/en/model-config.md#adjust-effort-level) active are exempt: the limit isn't enforced there. Requires Claude Code v2.1.217 or later.

1085By default, when 20 subagents are running in a session, spawning another with the Agent tool fails with `Concurrent subagent limit reached`, and the error tells Claude not to retry. Spawning succeeds again when the running count drops below the limit. To change the limit, set [`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`](https://code.claude.com/docs/en/env-vars) to any positive whole number. Sessions with [ultracode](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) active are exempt: the limit isn't enforced there. Requires Claude Code v2.1.217 or later.

10861086

10871087The limit blocks only subagents Claude spawns with the Agent tool, but other runs occupy the same slots:

10881088

from line 1089

10891089* An in-session fork you start with [`/subtask`](#fork-the-current-conversation) takes a slot while it runs and is never blocked by the limit.

10901090* [Resuming a subagent](#resume-subagents) that already finished takes a fresh slot without checking the limit, so resumes can push the running count past it.

10911091

1092Agents that other features run, such as [workflow](/docs/en/workflows.md) agents and [agent team](/docs/en/agent-teams.md) teammates, follow their own limits instead.

1092Agents that other features run, such as [workflow](https://code.claude.com/docs/en/workflows.md) agents and [agent team](https://code.claude.com/docs/en/agent-teams.md) teammates, follow their own limits instead.

10931093

10941094### Manage subagent context

10951095

from line 1101

11011101

11021102* **System prompt**: the agent's own prompt plus environment details that Claude Code appends, not the Claude Code system prompt. Custom subagents define theirs in the [markdown body](#write-subagent-files) or `prompt` field. Built-in agents have predefined prompts.

11031103* **Task message**: the delegation prompt Claude writes when it hands off the work.

1104* **CLAUDE.md files**: every level of the [CLAUDE.md hierarchy](/docs/en/memory.md#how-claude-md-files-load) the main conversation loads, including `~/.claude/CLAUDE.md`, project rules, `CLAUDE.local.md`, managed policy files, and any [`AGENTS.md` files](/docs/en/memory#agents-md) loaded as project instructions. The built-in Explore and Plan agents skip this. A subagent whose definition sets [`omitClaudeMd`](#supported-frontmatter-fields) loads only the managed policy files, or none at all when the definition comes from [managed settings](#choose-the-subagent-scope).

1105* **Git status**: a snapshot Claude Code reads from your repository when the subagent starts. For a subagent in [its own worktree](/docs/en/worktrees.md#isolate-subagents-with-worktrees) of that repository, the snapshot shows the worktree's branch, status, and recent commits. Absent outside a Git repository or whenever the snapshot is turned off; see [`includeGitInstructions`](/docs/en/settings-reference#includegitinstructions). Explore and Plan skip it regardless.

1104* **CLAUDE.md files**: every level of the [CLAUDE.md hierarchy](https://code.claude.com/docs/en/memory.md#how-claude-md-files-load) the main conversation loads, including `~/.claude/CLAUDE.md`, project rules, `CLAUDE.local.md`, managed policy files, and any [`AGENTS.md` files](https://code.claude.com/docs/en/memory#agents-md) loaded as project instructions. The built-in Explore and Plan agents skip this. A subagent whose definition sets [`omitClaudeMd`](#supported-frontmatter-fields) loads only the managed policy files, or none at all when the definition comes from [managed settings](#choose-the-subagent-scope).

1105* **Git status**: a snapshot Claude Code reads from your repository when the subagent starts. For a subagent in [its own worktree](https://code.claude.com/docs/en/worktrees.md#isolate-subagents-with-worktrees) of that repository, the snapshot shows the worktree's branch, status, and recent commits. Absent outside a Git repository or whenever the snapshot is turned off; see [`includeGitInstructions`](https://code.claude.com/docs/en/settings-reference#includegitinstructions). Explore and Plan skip it regardless.

11061106* **Preloaded skills**: full content of any skill named in the agent's [`skills` field](#preload-skills-into-subagents). Built-in agents don't preload skills.

1107* **Sibling roster**: a [system reminder](/docs/en/glossary.md#system-reminder) listing `main` and every other named agent in the session, each a valid `to` value for [`SendMessage`](#resume-subagents). The roster appears only when the subagent's tools include `SendMessage` and at least one other agent has a name, whether Claude named it when spawning it or it runs as an [agent team](/docs/en/agent-teams.md) teammate. It is a snapshot taken when the subagent starts, so agents named later don't appear.

1107* **Sibling roster**: a [system reminder](https://code.claude.com/docs/en/glossary.md#system-reminder) listing `main` and every other named agent in the session, each a valid `to` value for [`SendMessage`](#resume-subagents). The roster appears only when the subagent's tools include `SendMessage` and at least one other agent has a name, whether Claude named it when spawning it or it runs as an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate. It is a snapshot taken when the subagent starts, so agents named later don't appear.

11081108

1109To launch one of your own subagents without the user, project, and local CLAUDE.md files, set [`omitClaudeMd: true`](#supported-frontmatter-fields) in its frontmatter or `--agents` JSON. For Explore, Plan, and subagents with `omitClaudeMd`, a subdirectory's `CLAUDE.md` and matching [path-scoped rules](/docs/en/memory.md#path-specific-rules) still [load](/docs/en/memory.md#how-claude-md-files-load) when the subagent works with files there.

1109To launch one of your own subagents without the user, project, and local CLAUDE.md files, set [`omitClaudeMd: true`](#supported-frontmatter-fields) in its frontmatter or `--agents` JSON. For Explore, Plan, and subagents with `omitClaudeMd`, a subdirectory's `CLAUDE.md` and matching [path-scoped rules](https://code.claude.com/docs/en/memory.md#path-specific-rules) still [load](https://code.claude.com/docs/en/memory.md#how-claude-md-files-load) when the subagent works with files there.

11101110

11111111The main conversation still has your full CLAUDE.md when it reads these subagents' results, so most rules don't need to reach the subagent itself. If a rule must, such as "ignore the `vendor/` directory," restate it in the prompt you give Claude when delegating.

11121112

from line 1114

11141114

11151115Some main-conversation state never reaches a non-fork subagent:

11161116

1117* **Output style**: a subagent runs its own system prompt, so your [output style](/docs/en/output-styles.md) doesn't shape its responses, except in a [fork](#fork-the-current-conversation).

1118* **Auto memory**: the main conversation's [auto memory](/docs/en/memory.md#auto-memory) isn't loaded. To give a subagent persistent memory of its own, use the [`memory` field](#enable-persistent-memory).

1117* **Output style**: a subagent runs its own system prompt, so your [output style](https://code.claude.com/docs/en/output-styles.md) doesn't shape its responses, except in a [fork](#fork-the-current-conversation).

1118* **Auto memory**: the main conversation's [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) isn't loaded. To give a subagent persistent memory of its own, use the [`memory` field](#enable-persistent-memory).

11191119* **Context window size**: a subagent's context window is sized by its own model, not the parent's. Delegating to a model with a smaller window gives that subagent the smaller window.

11201120

11211121#### Resume subagents

from line 1128

11281128* The built-in Explore and Plan agents are one-shot and return no agent ID, so Claude can't resume them. Use `general-purpose` or a custom subagent when you need to continue the work.

11291129* When a subagent stops at its [`maxTurns`](#supported-frontmatter-fields) limit, Claude Code marks the returned output as partial, and Claude can resume the subagent to continue its work.

11301130

1131Claude uses the `SendMessage` tool with the agent's ID or name as the `to` field to resume it. `SendMessage` doesn't require [agent teams](/docs/en/agent-teams.md) to be enabled; only structured team-protocol messages such as `shutdown_request` and `plan_approval_response` do. Beyond subagents and teammates, in sessions where cross-session messaging is enabled, Claude can use the same tool to message [your other Claude Code sessions](/docs/en/cross-session-messaging.md), on this machine or [beyond it](/docs/en/cross-session-messaging.md#message-sessions-on-other-machines).

1131Claude uses the `SendMessage` tool with the agent's ID or name as the `to` field to resume it. `SendMessage` doesn't require [agent teams](https://code.claude.com/docs/en/agent-teams.md) to be enabled; only structured team-protocol messages such as `shutdown_request` and `plan_approval_response` do. Beyond subagents and teammates, in sessions where cross-session messaging is enabled, Claude can use the same tool to message [your other Claude Code sessions](https://code.claude.com/docs/en/cross-session-messaging.md), on this machine or [beyond it](https://code.claude.com/docs/en/cross-session-messaging.md#message-sessions-on-other-machines).

11321132

11331133To resume a subagent, ask Claude to continue the previous work:

11341134

from line 1140

11401140[Claude resumes the subagent with full context from previous conversation]

11411141```

11421142

1143When Claude sends a completed subagent a message with the `SendMessage` tool, the subagent resumes in the background without a new `Agent` invocation. The same applies to a subagent that Claude stopped with the `TaskStop` tool, once its stopped run has exited. The resumed run keeps the [tool set from where the subagent first ran](#run-subagents-in-foreground-or-background) and can keep reading the [prompt cache the original run warmed](/docs/en/prompt-caching.md#subagents-and-the-cache).

1143When Claude sends a completed subagent a message with the `SendMessage` tool, the subagent resumes in the background without a new `Agent` invocation. The same applies to a subagent that Claude stopped with the `TaskStop` tool, once its stopped run has exited. The resumed run keeps the [tool set from where the subagent first ran](#run-subagents-in-foreground-or-background) and can keep reading the [prompt cache the original run warmed](https://code.claude.com/docs/en/prompt-caching.md#subagents-and-the-cache).

11441144

11451145A subagent that has the `SendMessage` tool can send that message too. In an interactive session, the resumed agent then reports back to the subagent that resumed it, not to your main conversation. That subagent waits for the result before finishing its own work. When a subagent messages an agent it reports to, such as its own launcher, Claude Code resumes that agent without redirecting its results.

11461146

from line 1160

11601160

11611161* **Main conversation compaction**: when the main conversation compacts, subagent transcripts are unaffected. They're stored in separate files.

11621162* **Session persistence**: subagent transcripts persist within their session. You can [resume a subagent](#resume-subagents) after restarting Claude Code by resuming the same session.

1163* **Automatic cleanup**: Claude Code deletes subagent transcripts after the `cleanupPeriodDays` retention period, 30 days by default, following the [retention sweep rules](/docs/en/claude-directory.md#cleaned-up-automatically).

1163* **Automatic cleanup**: Claude Code deletes subagent transcripts after the `cleanupPeriodDays` retention period, 30 days by default, following the [retention sweep rules](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically).

11641164

11651165##### Message a subagent by name after a restart

11661166

11671167> [!NOTE]

11681168>

1169> For a subagent that launched as a teammate, see the [agent team limitations](/docs/en/agent-teams.md#limitations) instead.

1169> For a subagent that launched as a teammate, see the [agent team limitations](https://code.claude.com/docs/en/agent-teams.md#limitations) instead.

11701170

1171If Claude can't message a subagent by name after you restart Claude Code and resume the session, give Claude the subagent's agent ID instead. Names Claude gave from the main conversation since its last [compaction](/docs/en/context-window.md#what-survives-compaction) survive the restart. A name from before that compaction doesn't. To find the ID for a name, look for that name in the `agent-{agentId}.meta.json` files in `~/.claude/projects/{project}/{sessionId}/subagents/`.

1171If Claude can't message a subagent by name after you restart Claude Code and resume the session, give Claude the subagent's agent ID instead. Names Claude gave from the main conversation since its last [compaction](https://code.claude.com/docs/en/context-window.md#what-survives-compaction) survive the restart. A name from before that compaction doesn't. To find the ID for a name, look for that name in the `agent-{agentId}.meta.json` files in `~/.claude/projects/{project}/{sessionId}/subagents/`.

11721172

11731173After one message by ID, the subagent's name works again, unless a newer agent has taken that name. Before v2.1.299, no name survived a restart, and a send by name was refused even when the agent ID still worked.

11741174

11751175#### Auto-compaction

11761176

1177Subagents support automatic compaction. Compaction triggers as the subagent's own context window fills, and `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` applies to subagents as well. See [environment variables](/docs/en/env-vars.md) for when the override takes effect.

1177Subagents support automatic compaction. Compaction triggers as the subagent's own context window fills, and `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` applies to subagents as well. See [environment variables](https://code.claude.com/docs/en/env-vars.md) for when the override takes effect.

11781178

11791179Compaction events are logged in subagent transcript files:

11801180

from line 1193

11931193

11941194##### Set the auto-compact window for one subagent

11951195

1196To make one subagent compact earlier than it otherwise would, set `autoCompactWindow` in its [frontmatter](#supported-frontmatter-fields) to a token count from `100000` to `1000000`. If you set [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/en/env-vars#variables), the subagent uses that variable's window instead and the field has no effect, unless Claude Code [ignores the variable's value](/docs/en/model-config.md#claude_code_auto_compact_window-values). Requires Claude Code v2.1.296 or later.

1196To make one subagent compact earlier than it otherwise would, set `autoCompactWindow` in its [frontmatter](#supported-frontmatter-fields) to a token count from `100000` to `1000000`. If you set [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](https://code.claude.com/docs/en/env-vars#variables), the subagent uses that variable's window instead and the field has no effect, unless Claude Code [ignores the variable's value](https://code.claude.com/docs/en/model-config.md#claude_code_auto_compact_window-values). Requires Claude Code v2.1.296 or later.

11971197

11981198This frontmatter sets `autoCompactWindow` to 200,000 tokens for a subagent that reads long log files:

11991199

from line 1209

12091209

12101210If the value is in range and you still see no change, check for these causes:

12111211

1212* **The value isn't below the [auto-compact window](/docs/en/model-config.md#context-window-and-auto-compaction) the subagent would otherwise inherit**: to compact earlier, set a value below that window.

1213* **You run the whole session as this subagent with `--agent` or the `agent` setting**: the field has no effect there. To set the session's window, see [Set the auto-compact window](/docs/en/model-config.md#set-the-auto-compact-window).

1212* **The value isn't below the [auto-compact window](https://code.claude.com/docs/en/model-config.md#context-window-and-auto-compaction) the subagent would otherwise inherit**: to compact earlier, set a value below that window.

1213* **You run the whole session as this subagent with `--agent` or the `agent` setting**: the field has no effect there. To set the session's window, see [Set the auto-compact window](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window).

12141214

12151215## Fork the current conversation

12161216

12171217> [!NOTE]

12181218>

1219> When [agent view is turned off](/docs/en/agent-view.md#turn-off-agent-view), `/subtask` isn't available and `/fork` starts the forked subagent instead; otherwise `/fork` copies the whole session into a new [background session](/docs/en/agent-view.md#from-inside-a-session).

1219> When [agent view is turned off](https://code.claude.com/docs/en/agent-view.md#turn-off-agent-view), `/subtask` isn't available and `/fork` starts the forked subagent instead; otherwise `/fork` copies the whole session into a new [background session](https://code.claude.com/docs/en/agent-view.md#from-inside-a-session).

12201220

12211221A fork is a subagent that inherits the entire conversation so far instead of starting fresh. This drops the input isolation that subagents otherwise provide: a fork sees the same system prompt, tools, model, and message history as the main session, so you can hand it a side task without re-explaining the situation. The fork's own tool calls still stay out of your conversation and only its final result comes back, so your main context window stays clean. Use a fork when any other subagent would need too much background to be useful, or when you want to try several approaches in parallel from the same starting point.

12221222

from line 1245

12451245| `x` | Stop the selected fork if it's running, or dismiss its row if it's no longer running. On the main session row, or on the row of the fork whose transcript you opened with `Enter`, `x` types into the prompt instead |

12461246| `Esc` | Return focus to the prompt input |

12471247

1248With a fork's or subagent's transcript open, follow-up messages and [skills](/docs/en/skills.md) go to that agent, and built-in commands go to your main conversation, with these safeguards:

1248With a fork's or subagent's transcript open, follow-up messages and [skills](https://code.claude.com/docs/en/skills.md) go to that agent, and built-in commands go to your main conversation, with these safeguards:

12491249

12501250* `/compact`, `/clear`, and `/rewind` act on the main conversation, so Claude Code asks you to confirm before running one of them from this view.

12511251* `/model` and `/fast` set the main conversation's model and fast mode, not the viewed agent's, so they don't run from this view. A notice tells you why.

12521252

1253To have the viewed agent read your message before the work it's waiting on finishes, send it with [`Ctrl+Enter` or `Ctrl+X Ctrl+S`](/docs/en/keybindings#chat-actions). Any shell command or subagent the agent is waiting on that can move to the [background](/docs/en/tools-reference.md#background-commands) moves there and keeps running. When the agent is writing a response, or waiting on work that can't move to the background, it keeps going and reads your message once that finishes. Requires Claude Code v2.1.286 or later.

1253To have the viewed agent read your message before the work it's waiting on finishes, send it with [`Ctrl+Enter` or `Ctrl+X Ctrl+S`](https://code.claude.com/docs/en/keybindings#chat-actions). Any shell command or subagent the agent is waiting on that can move to the [background](https://code.claude.com/docs/en/tools-reference.md#background-commands) moves there and keeps running. When the agent is writing a response, or waiting on work that can't move to the background, it keeps going and reads your message once that finishes. Requires Claude Code v2.1.286 or later.

12541254

12551255### How forks differ from other subagents

12561256

from line 1263

12631263| Model | Same as main session | From the subagent's `model` field |

12641264| Prompt cache | Shared with main session | Separate cache |

12651265

1266Because a fork's system prompt and tool definitions are identical to the parent, its first request reuses the parent's [prompt cache](/docs/en/prompt-caching.md#subagents-and-the-cache). Because of that reuse, a fork costs less than a fresh subagent for tasks that need the same context.

1266Because a fork's system prompt and tool definitions are identical to the parent, its first request reuses the parent's [prompt cache](https://code.claude.com/docs/en/prompt-caching.md#subagents-and-the-cache). Because of that reuse, a fork costs less than a fresh subagent for tasks that need the same context.

12671267

12681268When Claude spawns a fork through the Agent tool, it can pass `isolation: "worktree"` so the fork's file edits are written to a separate git worktree instead of your checkout. A fork can't spawn further forks.

12691269

from line 1427

14271427You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

14281428```

14291429

1430Claude Code [passes hook input as JSON](/docs/en/hooks.md#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the command being executed, and checks it against a list of SQL write operations. If a write operation is detected, the script [exits with code 2](/docs/en/hooks.md#exit-code-2-behavior-per-event) to block execution and returns an error message to Claude via stderr.

1430Claude Code [passes hook input as JSON](https://code.claude.com/docs/en/hooks.md#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the command being executed, and checks it against a list of SQL write operations. If a write operation is detected, the script [exits with code 2](https://code.claude.com/docs/en/hooks.md#exit-code-2-behavior-per-event) to block execution and returns an error message to Claude via stderr.

14311431

14321432Create the validation script anywhere in your project. The path must match the `command` field in your hook configuration:

14331433

from line 1460

14601460chmod +x ./scripts/validate-readonly-query.sh

14611461```

14621462

1463On Windows, write the validation script in PowerShell and add `shell: powershell` to the hook entry. See [running hooks in PowerShell](/docs/en/hooks.md#windows-powershell-tool).

1463On Windows, write the validation script in PowerShell and add `shell: powershell` to the hook entry. See [running hooks in PowerShell](https://code.claude.com/docs/en/hooks.md#windows-powershell-tool).

14641464

1465The hook receives JSON via stdin with the Bash command in `tool_input.command`. Exit code 2 blocks the operation and feeds the error message back to Claude. See [Hooks](/docs/en/hooks.md#exit-code-output) for details on exit codes and [Hook input](/docs/en/hooks.md#pretooluse-input) for the complete input schema.

1465The hook receives JSON via stdin with the Bash command in `tool_input.command`. Exit code 2 blocks the operation and feeds the error message back to Claude. See [Hooks](https://code.claude.com/docs/en/hooks.md#exit-code-output) for details on exit codes and [Hook input](https://code.claude.com/docs/en/hooks.md#pretooluse-input) for the complete input schema.

14661466

14671467The system prompt tells the subagent to refuse write requests, so the hook is a backstop: if the subagent attempts a write anyway, Claude Code blocks the command and the subagent sees the `Blocked: Write operations not allowed. Use SELECT queries only.` message.

14681468

from line 1470

14701470

14711471Now that you understand subagents, explore these related features:

14721472

1473* [Distribute subagents with plugins](/docs/en/plugins/components.md#agents) to share subagents across teams or projects

1474* [Run Claude Code programmatically](/docs/en/headless.md) with the Agent SDK for CI/CD and automation

1475* [Use MCP servers](/docs/en/mcp.md) to give subagents access to external tools and data

1473* [Distribute subagents with plugins](https://code.claude.com/docs/en/plugins/components.md#agents) to share subagents across teams or projects

1474* [Run Claude Code programmatically](https://code.claude.com/docs/en/headless.md) with the Agent SDK for CI/CD and automation

1475* [Use MCP servers](https://code.claude.com/docs/en/mcp.md) to give subagents access to external tools and data

14761476

terminal-config Changed · +48 / -48 lines

from line 12

1212* [Display flickers or scrollback jumps](#switch-to-fullscreen-rendering)

1313* [You want Vim keys in the prompt](#edit-prompts-with-vim-keybindings)

1414

15This page is about getting your terminal to send the right signals to Claude Code. To change which keys Claude Code itself responds to, see [keybindings](/docs/en/keybindings.md) instead.

15This page is about getting your terminal to send the right signals to Claude Code. To change which keys Claude Code itself responds to, see [keybindings](https://code.claude.com/docs/en/keybindings.md) instead.

1616

1717## Enter multiline prompts

1818

from line 29

2929

3030For VS Code, Cursor, Devin Desktop, Alacritty before 0.16, and Zed, `/terminal-setup` writes a Shift+Enter keybinding into the terminal's configuration file. On the first run you see a confirmation such as `Installed VSCode terminal Shift+Enter key binding`. Existing bindings are left in place; if you see a message such as `VSCode terminal Shift+Enter key binding already configured`, no change was made. Run `/terminal-setup` directly in the host terminal rather than inside tmux or screen, since it needs to write to the host terminal's configuration.

3131

32In VS Code, Cursor, and Devin Desktop, `/terminal-setup` also updates two editor settings: it sets `terminal.integrated.gpuAcceleration` to `"off"` to prevent garbled text in the integrated terminal, and it sets `terminal.integrated.mouseWheelScrollSensitivity` for smoother scrolling in [fullscreen mode](/docs/en/fullscreen.md). To undo the GPU acceleration change, set it back to `"auto"` and reload the editor window.

32In VS Code, Cursor, and Devin Desktop, `/terminal-setup` also updates two editor settings: it sets `terminal.integrated.gpuAcceleration` to `"off"` to prevent garbled text in the integrated terminal, and it sets `terminal.integrated.mouseWheelScrollSensitivity` for smoother scrolling in [fullscreen mode](https://code.claude.com/docs/en/fullscreen.md). To undo the GPU acceleration change, set it back to `"auto"` and reload the editor window.

3333

3434In Zed, `/terminal-setup` updates your `keymap.json` in place:

3535

3636* If the keymap already has bindings and none of them is a Terminal `shift-enter`, Claude Code first backs it up to a copy in the same directory, such as `keymap.json.1a2b3c4d.bak`, then merges the Shift+Enter binding into your keymap, keeping your other keybindings and comments

37* If Claude Code can't read or parse the keymap, can't back it up, or can't verify the merged result, it [leaves the file unchanged and prints the keybinding block to add yourself](/docs/en/errors.md#terminal-setup-left-your-zed-keymap-unchanged)

37* If Claude Code can't read or parse the keymap, can't back it up, or can't verify the merged result, it [leaves the file unchanged and prints the keybinding block to add yourself](https://code.claude.com/docs/en/errors.md#terminal-setup-left-your-zed-keymap-unchanged)

3838

3939If you are running inside tmux, Shift+Enter also requires the [tmux configuration below](#configure-tmux) even when the outer terminal supports it.

4040

41To bind newline to a different key, or to swap behavior so Enter inserts a newline and Shift+Enter submits, map the `chat:newline` and `chat:submit` actions in your [keybindings file](/docs/en/keybindings.md).

4242

4343## Enable Option key shortcuts on macOS

4444

from line 50

5050

5151If you accepted Claude Code's first-run terminal setup prompt, this is already done. That prompt runs `/terminal-setup` for you, which enables Option as Meta and turns off the audible bell in your Apple Terminal profile.

5252

53In [screen reader mode](/docs/en/accessibility.md), `/terminal-setup` leaves the bell setting unchanged so the terminal bell stays audible. If an earlier run turned the bell off, turn it back on under Settings → Profiles → Advanced → "Audible bell".

53In [screen reader mode](https://code.claude.com/docs/en/accessibility.md), `/terminal-setup` leaves the bell setting unchanged so the terminal bell stays audible. If an earlier run turned the bell off, turn it back on under Settings → Profiles → Advanced → "Audible bell".

5454

5555**iTerm2**

5656

from line 66

6666

6767## Get a terminal bell or notification

6868

69When Claude finishes a task or pauses for a permission prompt, and you appear to be away from the terminal, it fires a notification event. See [when each notification type fires](/docs/en/hooks.md#notification) for the exact timing. Surfacing this as a terminal bell or desktop notification lets you switch to other work while a long task runs.

69When Claude finishes a task or pauses for a permission prompt, and you appear to be away from the terminal, it fires a notification event. See [when each notification type fires](https://code.claude.com/docs/en/hooks.md#notification) for the exact timing. Surfacing this as a terminal bell or desktop notification lets you switch to other work while a long task runs.

7070

71By default Claude Code sends a desktop notification only in Ghostty, Kitty, and iTerm2. In other terminals, set [`preferredNotifChannel`](/docs/en/settings-reference#preferrednotifchannel) to `"terminal_bell"` to ring the terminal bell instead, or configure a [Notification hook](#play-a-sound-with-a-notification-hook) for a custom sound or command. The following settings entry turns on the terminal bell:

71By default Claude Code sends a desktop notification only in Ghostty, Kitty, and iTerm2. In other terminals, set [`preferredNotifChannel`](https://code.claude.com/docs/en/settings-reference#preferrednotifchannel) to `"terminal_bell"` to ring the terminal bell instead, or configure a [Notification hook](#play-a-sound-with-a-notification-hook) for a custom sound or command. The following settings entry turns on the terminal bell:

7272

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

7474{

from line 90

9090

9191### Play a sound with a Notification hook

9292

93In any terminal you can configure a [Notification hook](/docs/en/hooks-guide.md#get-notified-when-claude-needs-input) to play a sound or run a custom command when Claude needs your attention. Hooks run alongside the built-in notification rather than replacing it, so terminals that do not receive a desktop notification, such as Warp or the VS Code integrated terminal, can use a hook or set `preferredNotifChannel` to `"terminal_bell"` instead.

93In any terminal you can configure a [Notification hook](https://code.claude.com/docs/en/hooks-guide.md#get-notified-when-claude-needs-input) to play a sound or run a custom command when Claude needs your attention. Hooks run alongside the built-in notification rather than replacing it, so terminals that do not receive a desktop notification, such as Warp or the VS Code integrated terminal, can use a hook or set `preferredNotifChannel` to `"terminal_bell"` instead.

9494

9595The example below plays a system sound on macOS. The linked guide has desktop notification commands for macOS, Linux, and Windows.

9696

from line 114

114114

115115* **Claude Code version**: status reporting requires Claude Code v2.1.295 or later. Run `claude --version` in your shell to check.

116116* **tmux**: inside tmux, Claude Code checks tmux for support instead of your terminal, and [`allow-passthrough`](#configure-tmux) has no effect on that. Start the session outside tmux.

117* **Background session**: a [background session](/docs/en/agent-view.md) doesn't report its status to your terminal, even while you're attached to it. Agent view shows its status instead.

118* **[`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`](/docs/en/env-vars#variables)**: if you set this variable to `1`, Claude Code doesn't check for support or report status. Unset it.

117* **Background session**: a [background session](https://code.claude.com/docs/en/agent-view.md) doesn't report its status to your terminal, even while you're attached to it. Agent view shows its status instead.

118* **[`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`](https://code.claude.com/docs/en/env-vars#variables)**: if you set this variable to `1`, Claude Code doesn't check for support or report status. Unset it.

119119

120120## Configure tmux

121121

122When Claude Code runs inside tmux, by default Shift+Enter submits instead of inserting a newline, and desktop notifications and the [progress bar](/docs/en/settings-reference.md#terminalprogressbarenabled) never reach the outer terminal. Add these lines to `~/.tmux.conf`, then run `tmux source-file ~/.tmux.conf` to apply them to the running server:

122When Claude Code runs inside tmux, by default Shift+Enter submits instead of inserting a newline, and desktop notifications and the [progress bar](https://code.claude.com/docs/en/settings-reference.md#terminalprogressbarenabled) never reach the outer terminal. Add these lines to `~/.tmux.conf`, then run `tmux source-file ~/.tmux.conf` to apply them to the running server:

123123

124124```bash ~/.tmux.conf theme={null}

125125set -g allow-passthrough on

from line 131

131131

132132## Fix Backspace deleting a whole word on Windows

133133

134On Windows, Claude Code reads a Backspace that arrives as `^H` as Ctrl+Backspace, which [deletes the previous word](/docs/en/interactive-mode.md#text-editing), except when `TERM_PROGRAM` is `mintty` or `TERM` is `cygwin`. On macOS and Linux, Claude Code reads it as plain Backspace.

134On Windows, Claude Code reads a Backspace that arrives as `^H` as Ctrl+Backspace, which [deletes the previous word](https://code.claude.com/docs/en/interactive-mode.md#text-editing), except when `TERM_PROGRAM` is `mintty` or `TERM` is `cygwin`. On macOS and Linux, Claude Code reads it as plain Backspace.

135135

136If each press of Backspace deletes a whole word, your terminal sends `^H` for plain Backspace. Set [`CLAUDE_CODE_BS_AS_CTRL_BACKSPACE=0`](/docs/en/env-vars). Backspace and Ctrl+H then erase one character each. If Ctrl+Backspace erases only one character on macOS or Linux because your terminal sends `^H` for it, set the variable to `1` instead.

136If each press of Backspace deletes a whole word, your terminal sends `^H` for plain Backspace. Set [`CLAUDE_CODE_BS_AS_CTRL_BACKSPACE=0`](https://code.claude.com/docs/en/env-vars). Backspace and Ctrl+H then erase one character each. If Ctrl+Backspace erases only one character on macOS or Linux because your terminal sends `^H` for it, set the variable to `1` instead.

137137

138138## Match the color theme

139139

140140Use the `/theme` command, or the theme picker in `/config`, to choose a Claude Code theme that matches your terminal. Selecting the auto option detects your terminal's light or dark background, so the theme follows OS appearance changes whenever your terminal does. Claude Code does not control the terminal's own color scheme, which is set by the terminal application.

141141

142To customize what appears at the bottom of the interface, configure a [custom status line](/docs/en/statusline.md) that shows the current model, working directory, git branch, or other context.

142To customize what appears at the bottom of the interface, configure a [custom status line](https://code.claude.com/docs/en/statusline.md) that shows the current model, working directory, git branch, or other context.

143143

144144### Create a custom theme

145145

146In addition to the built-in presets, `/theme` lists any custom themes you have defined and any themes contributed by installed [plugins](/docs/en/plugins/components.md#themes-and-output-styles). Select **New custom theme…** at the end of the list to create one interactively: you name the theme, then pick individual color tokens to override. Press `Ctrl+E` while a custom theme is highlighted to edit it.

146In addition to the built-in presets, `/theme` lists any custom themes you have defined and any themes contributed by installed [plugins](https://code.claude.com/docs/en/plugins/components.md#themes-and-output-styles). Select **New custom theme…** at the end of the list to create one interactively: you name the theme, then pick individual color tokens to override. Press `Ctrl+E` while a custom theme is highlighted to edit it.

147147

148148Each custom theme is a JSON file in `~/.claude/themes/`. The filename without the `.json` extension is the theme's slug, and selecting the theme stores `custom:<slug>` as your theme preference. The file has three optional fields:

149149

from line 229

229229> | `bashBorder` | Input box border when entering a `!` shell command |

230230> | `ide` | IDE connection indicator |

231231> | `fastMode` | Fast mode indicator |

232> | `effortUltra` | The `ultracode` tag on the input box border while [ultracode](/docs/en/model-config.md#adjust-effort-level) is on. Your override of this color takes effect on Claude Code v2.1.239 or later |

232> | `effortUltra` | The `ultracode` tag on the input box border while [ultracode](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) is on. Your override of this color takes effect on Claude Code v2.1.239 or later |

233233>

234234> #### Diff rendering

235235>

from line 246

246246>

247247> #### Fullscreen mode

248248>

249> Claude Code uses `userMessageBackgroundHover`, `selectionBg`, and `composerSidebarBackground` only in [fullscreen rendering mode](/docs/en/fullscreen.md). It paints `userMessageBackground`, `bashMessageBackgroundColor`, and `memoryBackgroundColor` in both the default and fullscreen renderers.

249> Claude Code uses `userMessageBackgroundHover`, `selectionBg`, and `composerSidebarBackground` only in [fullscreen rendering mode](https://code.claude.com/docs/en/fullscreen.md). It paints `userMessageBackground`, `bashMessageBackgroundColor`, and `memoryBackgroundColor` in both the default and fullscreen renderers.

250250>

251251> | Token | Controls |

252252> | :- | :- |

from line 255

255255> | `bashMessageBackgroundColor` | Background behind `!` shell command entries in the transcript |

256256> | `memoryBackgroundColor` | Background behind `#` memory entries in the transcript |

257257> | `selectionBg` | Background of text selected with the mouse |

258> | `composerSidebarBackground` | Background of the panel beside the conversation, such as the [diff panel](/docs/en/fullscreen.md#watch-your-changes-in-the-diff-panel) or a [mod's pane](/docs/en/plugins/mods/interface.md) |

258> | `composerSidebarBackground` | Background of the panel beside the conversation, such as the [diff panel](https://code.claude.com/docs/en/fullscreen.md#watch-your-changes-in-the-diff-panel) or a [mod's pane](https://code.claude.com/docs/en/plugins/mods/interface.md) |

259259>

260260> #### Usage meter and speaker labels

261261>

from line 279

279279> * `inactive` and `inactiveShimmer`

280280> * `fastMode` and `fastModeShimmer`

281281>

282> Each [subagent](/docs/en/sub-agents.md) and parallel task is shown in one of eight named colors so you can tell them apart in the transcript. The token names follow the pattern `<color>_FOR_SUBAGENTS_ONLY`, where `<color>` is `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan`. Override these to change what each named color looks like. For example, a subagent with `color: blue` in its definition is drawn using the `blue_FOR_SUBAGENTS_ONLY` value.

282> Each [subagent](https://code.claude.com/docs/en/sub-agents.md) and parallel task is shown in one of eight named colors so you can tell them apart in the transcript. The token names follow the pattern `<color>_FOR_SUBAGENTS_ONLY`, where `<color>` is `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan`. Override these to change what each named color looks like. For example, a subagent with `color: blue` in its definition is drawn using the `blue_FOR_SUBAGENTS_ONLY` value.

283283>

284> Claude Code renders the [`ultrathink`](/docs/en/model-config#use-ultrathink-for-one-off-deep-reasoning) keyword in the prompt input with a seven-color rainbow gradient. The token names follow the pattern `rainbow_<color>` and `rainbow_<color>_shimmer`, where `<color>` is `red`, `orange`, `yellow`, `green`, `blue`, `indigo`, or `violet`.

284> Claude Code renders the [`ultrathink`](https://code.claude.com/docs/en/model-config#use-ultrathink-for-one-off-deep-reasoning) keyword in the prompt input with a seven-color rainbow gradient. The token names follow the pattern `rainbow_<color>` and `rainbow_<color>_shimmer`, where `<color>` is `red`, `orange`, `yellow`, `green`, `blue`, `indigo`, or `violet`.

285285

286286## Switch to fullscreen rendering

287287

288In [screen reader mode](/docs/en/accessibility.md), this section doesn't apply. Claude Code always renders as plain scrolling text except in attached [background sessions](/docs/en/agent-view.md), and if you run `/tui fullscreen` in any other session, Claude Code prints an explanation instead of switching.

288In [screen reader mode](https://code.claude.com/docs/en/accessibility.md), this section doesn't apply. Claude Code always renders as plain scrolling text except in attached [background sessions](https://code.claude.com/docs/en/agent-view.md), and if you run `/tui fullscreen` in any other session, Claude Code prints an explanation instead of switching.

289289

290If the display flickers or the scroll position jumps while Claude is working, switch to [fullscreen rendering mode](/docs/en/fullscreen.md). In this mode you scroll with the mouse or PageUp inside Claude Code rather than with your terminal's native scrollback; see the [fullscreen page](/docs/en/fullscreen.md#search-and-review-the-conversation) for how to search and copy.

290If the display flickers or the scroll position jumps while Claude is working, switch to [fullscreen rendering mode](https://code.claude.com/docs/en/fullscreen.md). In this mode you scroll with the mouse or PageUp inside Claude Code rather than with your terminal's native scrollback; see the [fullscreen page](https://code.claude.com/docs/en/fullscreen.md#search-and-review-the-conversation) for how to search and copy.

291291

292If flicker is the only problem and your terminal supports synchronized output but isn't auto-detected, such as Emacs `eat`, set [`CLAUDE_CODE_FORCE_SYNC_OUTPUT=1`](/docs/en/env-vars) to stop the flicker without changing renderers.

292If flicker is the only problem and your terminal supports synchronized output but isn't auto-detected, such as Emacs `eat`, set [`CLAUDE_CODE_FORCE_SYNC_OUTPUT=1`](https://code.claude.com/docs/en/env-vars) to stop the flicker without changing renderers.

293293

294Run `/tui fullscreen` to switch and save the preference. Your conversation relaunches intact and future sessions start in fullscreen unless a [fullscreen start fails](/docs/en/fullscreen.md#fullscreen-renderer-didnt-finish-starting). You can also set the `CLAUDE_CODE_NO_FLICKER` environment variable before starting Claude Code:

294Run `/tui fullscreen` to switch and save the preference. Your conversation relaunches intact and future sessions start in fullscreen unless a [fullscreen start fails](https://code.claude.com/docs/en/fullscreen.md#fullscreen-renderer-didnt-finish-starting). You can also set the `CLAUDE_CODE_NO_FLICKER` environment variable before starting Claude Code:

295295

296296```bash Bash and Zsh theme={null}

297297CLAUDE_CODE_NO_FLICKER=1 claude

from line 311

311311

312312## Cap response width in wide terminals

313313

314In a wide terminal, each line of prose in Claude's responses runs the full width of the window. To wrap the prose at a set number of columns instead, set [`maxProseWidth`](/docs/en/settings-reference#maxprosewidth) in your settings.

314In a wide terminal, each line of prose in Claude's responses runs the full width of the window. To wrap the prose at a set number of columns instead, set [`maxProseWidth`](https://code.claude.com/docs/en/settings-reference#maxprosewidth) in your settings.

315315

316316## Paste large content

317317

318318When you paste more than 800 characters or more than three lines into the prompt, Claude Code collapses the input to a placeholder such as `[Pasted text #1 +120 lines]` so the input box stays usable, and still sends the full content when you submit. For very large inputs such as entire files or long logs, write the content to a file and ask Claude to read it instead of pasting. The conversation transcript stays readable and Claude can refer to the file by path in later turns. The VS Code integrated terminal can also drop characters from very large pastes before they reach Claude Code, so use a file there.

319319

320If the paste carries [invisible Unicode characters](/docs/en/interactive-mode.md#invisible-characters-in-prompts), Claude Code removes them when you press Enter and puts the cleaned prompt back in the input box for you to send with another Enter.

320If the paste carries [invisible Unicode characters](https://code.claude.com/docs/en/interactive-mode.md#invisible-characters-in-prompts), Claude Code removes them when you press Enter and puts the cleaned prompt back in the input box for you to send with another Enter.

321321

322322### How Claude treats pasted text

323323

324When you submit, Claude sees the content behind each `[Pasted text #N]` placeholder marked as text you pasted from somewhere else rather than typed. Claude is told that a paste can contain instructions you didn't write, and to follow instructions inside it only where the message you typed asks it to. In sessions that don't [fetch feature flags](/docs/en/env-vars.md#features-that-need-feature-flag-fetching), pastes aren't marked.

324When you submit, Claude sees the content behind each `[Pasted text #N]` placeholder marked as text you pasted from somewhere else rather than typed. Claude is told that a paste can contain instructions you didn't write, and to follow instructions inside it only where the message you typed asks it to. In sessions that don't [fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), pastes aren't marked.

325325

326326### Delete and restore a collapsed paste

327327

328When you delete with a word or line shortcut such as `Ctrl+W` or `Ctrl+K`, or with a vim delete through an `f`/`t` motion such as `df]`, and the deleted range reaches inside a `[Pasted text #N]` placeholder, Claude Code removes the placeholder whole. To restore it, paste the deletion back with [`Ctrl+Y`](/docs/en/interactive-mode#text-editing) after a word or line shortcut, or with [`p` in NORMAL mode](/docs/en/interactive-mode#editing-normal-mode) after a vim delete.

328When you delete with a word or line shortcut such as `Ctrl+W` or `Ctrl+K`, or with a vim delete through an `f`/`t` motion such as `df]`, and the deleted range reaches inside a `[Pasted text #N]` placeholder, Claude Code removes the placeholder whole. To restore it, paste the deletion back with [`Ctrl+Y`](https://code.claude.com/docs/en/interactive-mode#text-editing) after a word or line shortcut, or with [`p` in NORMAL mode](https://code.claude.com/docs/en/interactive-mode#editing-normal-mode) after a vim delete.

329329

330330### Recall a prompt that had pasted text

331331

332Claude Code keeps the content behind each `[Pasted text #N]` placeholder under `~/.claude/paste-cache/`, so when you recall a prompt from [command history](/docs/en/interactive-mode.md#command-history) and resubmit it, the full pasted content is sent again, including in a later session.

332Claude Code keeps the content behind each `[Pasted text #N]` placeholder under `~/.claude/paste-cache/`, so when you recall a prompt from [command history](https://code.claude.com/docs/en/interactive-mode.md#command-history) and resubmit it, the full pasted content is sent again, including in a later session.

333333

334Cache files older than [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) are deleted under the [retention sweep rules](/docs/en/claude-directory.md#cleaned-up-automatically), so a recalled prompt can reference pasted text that no longer exists. When you submit such a prompt, Claude Code never sends the literal `[Pasted text #N]` string, and shows a notification naming the missing paste:

334Cache files older than [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) are deleted under the [retention sweep rules](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically), so a recalled prompt can reference pasted text that no longer exists. When you submit such a prompt, Claude Code never sends the literal `[Pasted text #N]` string, and shows a notification naming the missing paste:

335335

336336* In a plain prompt with text remaining, Claude Code removes the placeholder and sends the remaining text.

337* In a [shell mode](/docs/en/interactive-mode.md#shell-mode-with-prefix) command or a `/` command, where the removal would change what runs, and in any prompt the removal leaves empty, Claude Code cancels the submission and keeps the original text in the input, with the placeholder still in it. Delete the placeholder or edit the command, then resubmit.

337* In a [shell mode](https://code.claude.com/docs/en/interactive-mode.md#shell-mode-with-prefix) command or a `/` command, where the removal would change what runs, and in any prompt the removal leaves empty, Claude Code cancels the submission and keeps the original text in the input, with the placeholder still in it. Delete the placeholder or edit the command, then resubmit.

338338

339339## Edit prompts with Vim keybindings

340340

341Claude Code includes a Vim-style editing mode for the prompt input. Enable it through `/config` → Editor mode, or by setting [`editorMode`](/docs/en/settings-reference#editormode) to `"vim"` in `~/.claude/settings.json`. Set Editor mode back to `normal` to turn it off.

341Claude Code includes a Vim-style editing mode for the prompt input. Enable it through `/config` → Editor mode, or by setting [`editorMode`](https://code.claude.com/docs/en/settings-reference#editormode) to `"vim"` in `~/.claude/settings.json`. Set Editor mode back to `normal` to turn it off.

342342

343Vim mode supports a subset of NORMAL- and VISUAL-mode motions and operators, such as `hjkl` navigation, `v`/`V` selection, and `d`/`c`/`y` with text objects. See the [Vim editor mode reference](/docs/en/interactive-mode.md#vim-editor-mode) for the full key table.

343Vim mode supports a subset of NORMAL- and VISUAL-mode motions and operators, such as `hjkl` navigation, `v`/`V` selection, and `d`/`c`/`y` with text objects. See the [Vim editor mode reference](https://code.claude.com/docs/en/interactive-mode.md#vim-editor-mode) for the full key table.

344344

345Vim motions aren't remappable through the keybindings file. To map a two-key INSERT-mode sequence such as `jj` to Escape, set [`vimInsertModeRemaps`](/docs/en/interactive-mode#remap-insert-mode-key-sequences) in your user settings.

345Vim motions aren't remappable through the keybindings file. To map a two-key INSERT-mode sequence such as `jj` to Escape, set [`vimInsertModeRemaps`](https://code.claude.com/docs/en/interactive-mode#remap-insert-mode-key-sequences) in your user settings.

346346

347347Pressing Enter still submits your prompt in INSERT mode, unlike standard Vim. Use `o` or `O` in NORMAL mode, or Ctrl+J, to insert a newline instead.

348348

349349## Related resources

350350

351* [Interactive mode](/docs/en/interactive-mode.md): full keyboard shortcut reference and the Vim key table

352* [Keybindings](/docs/en/keybindings.md): remap any Claude Code shortcut, including Enter and Shift+Enter

353* [Fullscreen rendering](/docs/en/fullscreen.md): details on scrolling, search, and copy in fullscreen mode

354* [Hooks guide](/docs/en/hooks-guide.md): more Notification hook examples for Linux and Windows

355* [Troubleshooting](/docs/en/troubleshooting.md): fixes for issues outside terminal configuration

351* [Interactive mode](https://code.claude.com/docs/en/interactive-mode.md): full keyboard shortcut reference and the Vim key table

352* [Keybindings](https://code.claude.com/docs/en/keybindings.md): remap any Claude Code shortcut, including Enter and Shift+Enter

353* [Fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md): details on scrolling, search, and copy in fullscreen mode

354* [Hooks guide](https://code.claude.com/docs/en/hooks-guide.md): more Notification hook examples for Linux and Windows

355* [Troubleshooting](https://code.claude.com/docs/en/troubleshooting.md): fixes for issues outside terminal configuration

356356

third-party-integrations Changed · +23 / -23 lines

from line 13

1313

1414For most organizations, Claude for Teams or Claude for Enterprise provides the best experience. Team members get access to both Claude Code and Claude on the web with a single subscription, centralized billing, and no infrastructure setup required.

1515

16**Claude for Teams** is self-service and includes collaboration features, admin tools, SSO, billing management, and [server-managed settings](/docs/en/server-managed-settings.md) for organization-wide Claude Code configuration. Best for smaller teams that need to get started quickly.

16**Claude for Teams** is self-service and includes collaboration features, admin tools, SSO, billing management, and [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) for organization-wide Claude Code configuration. Best for smaller teams that need to get started quickly.

1717

1818**Claude for Enterprise** adds domain capture, role-based permissions, and compliance API access. Best for larger organizations with security and compliance requirements.

1919

2020Learn more about [Team plans](https://support.claude.com/en/articles/9266767-what-is-the-team-plan) and [Enterprise plans](https://support.claude.com/en/articles/9797531-what-is-the-enterprise-plan).

2121

22The deployment options compared below cover where model inference runs. To run Claude Code [cloud sessions](/docs/en/claude-code-on-the-web.md) on compute your organization operates, see [self-hosted environments](/docs/en/self-hosted-environments).

22The deployment options compared below cover where model inference runs. To run Claude Code [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) on compute your organization operates, see [self-hosted environments](https://code.claude.com/docs/en/self-hosted-environments).

2323

2424If your organization has specific infrastructure requirements, compare the options below:

2525

from line 81

8181 <tr>

8282 <td>Authentication</td>

8383 <td>claude.ai SSO or email</td>

84 <td>API key or a [Console sign-in without one](/docs/en/authentication.md#sign-in-without-an-api-key)</td>

84 <td>API key or a [Console sign-in without one](https://code.claude.com/docs/en/authentication.md#sign-in-without-an-api-key)</td>

8585 <td>API key or AWS credentials</td>

8686 <td>API key or AWS credentials</td>

8787 <td>GCP credentials</td>

from line 120

120120 </tbody>

121121</table>

122122

123For a feature-by-feature breakdown of what's available on each option, see [Feature availability](/docs/en/feature-availability.md).

123For a feature-by-feature breakdown of what's available on each option, see [Feature availability](https://code.claude.com/docs/en/feature-availability.md).

124124

125125Select a deployment option to view setup instructions:

126126

127* [Claude for Teams or Enterprise](/docs/en/authentication.md#claude-for-teams-or-enterprise)

128* [Anthropic Console](/docs/en/authentication.md#claude-console-authentication)

129* [Claude apps gateway](/docs/en/claude-apps-gateway), a self-hosted gateway that adds IdP sign-in in front of Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry, or the Anthropic API

130* [Amazon Bedrock](/docs/en/amazon-bedrock.md)

131* [Claude Platform on AWS](/docs/en/claude-platform-on-aws.md)

132* [Google Cloud's Agent Platform](/docs/en/google-vertex-ai.md)

133* [Microsoft Foundry](/docs/en/microsoft-foundry.md)

127* [Claude for Teams or Enterprise](https://code.claude.com/docs/en/authentication.md#claude-for-teams-or-enterprise)

128* [Anthropic Console](https://code.claude.com/docs/en/authentication.md#claude-console-authentication)

129* [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway), a self-hosted gateway that adds IdP sign-in in front of Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry, or the Anthropic API

130* [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md)

131* [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md)

132* [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md)

133* [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md)

134134

135135For Amazon Bedrock and Google Vertex AI, you can also run `claude` and select **3rd-party platform** at the login prompt to launch an interactive setup wizard.

136136

from line 138

138138

139139Most organizations can use a cloud provider directly without additional configuration. However, you may need to configure a corporate proxy or LLM gateway if your organization has specific network or management requirements. These are different configurations that can be used together:

140140

141* **Corporate proxy**: Routes traffic through an HTTP/HTTPS proxy. Use this if your organization requires all outbound traffic to pass through a proxy server for security monitoring, compliance, or network policy enforcement. Configure with the `HTTPS_PROXY` or `HTTP_PROXY` environment variables. Learn more in [Enterprise network configuration](/docs/en/network-config.md).

142* **LLM Gateway**: A service that sits between Claude Code and the cloud provider to handle authentication and routing. Use this if you need centralized usage tracking across teams, custom rate limiting or budgets, or centralized authentication management. Configure with the `ANTHROPIC_BASE_URL`, `ANTHROPIC_BEDROCK_BASE_URL`, `ANTHROPIC_AWS_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL`, or `ANTHROPIC_FOUNDRY_BASE_URL` environment variables. Learn more in [LLM gateways](/docs/en/llm-gateway).

143143

144For the per-provider environment variables that route Amazon Bedrock, Microsoft Foundry, or Google Cloud's Agent Platform through an LLM gateway, see [route to a cloud provider through a gateway](/docs/en/llm-gateway-connect.md#route-to-a-cloud-provider-through-a-gateway). Run `/status` in Claude Code to verify which provider, base URL, and proxy a session is using.

144For the per-provider environment variables that route Amazon Bedrock, Microsoft Foundry, or Google Cloud's Agent Platform through an LLM gateway, see [route to a cloud provider through a gateway](https://code.claude.com/docs/en/llm-gateway-connect.md#route-to-a-cloud-provider-through-a-gateway). Run `/status` in Claude Code to verify which provider, base URL, and proxy a session is using.

145145

146If your organization uses [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek) (CMEK) and routes Claude Code through an LLM gateway or a custom `ANTHROPIC_BASE_URL`, CMEK doesn't apply to Claude Code's operational telemetry on those sessions. To turn telemetry off for every developer, deliver `DISABLE_TELEMETRY` through managed settings as shown in [Turn telemetry off for your organization](/docs/en/managed-settings.md#turn-telemetry-off-for-your-organization).

146If your organization uses [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek) (CMEK) and routes Claude Code through an LLM gateway or a custom `ANTHROPIC_BASE_URL`, CMEK doesn't apply to Claude Code's operational telemetry on those sessions. To turn telemetry off for every developer, deliver `DISABLE_TELEMETRY` through managed settings as shown in [Turn telemetry off for your organization](https://code.claude.com/docs/en/managed-settings.md#turn-telemetry-off-for-your-organization).

147147

148148## Best practices for organizations

149149

150150### Invest in documentation and memory

151151

152Invest in documentation so that Claude Code understands your codebase. Organizations can deploy CLAUDE.md files at multiple levels. See [where CLAUDE.md files can live](/docs/en/memory.md#choose-where-to-put-claude-md-files) and [how to deploy an organization-wide CLAUDE.md](/docs/en/memory.md#deploy-organization-wide-claude-md).

152Invest in documentation so that Claude Code understands your codebase. Organizations can deploy CLAUDE.md files at multiple levels. See [where CLAUDE.md files can live](https://code.claude.com/docs/en/memory.md#choose-where-to-put-claude-md-files) and [how to deploy an organization-wide CLAUDE.md](https://code.claude.com/docs/en/memory.md#deploy-organization-wide-claude-md).

153153

154154### Simplify deployment

155155

from line 161

161161

162162### Pin model versions for cloud providers

163163

164If you deploy through [Amazon Bedrock](/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai.md), [Microsoft Foundry](/docs/en/microsoft-foundry.md), or [Claude Platform on AWS](/docs/en/claude-platform-on-aws.md), pin specific model versions using `ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Without pinning, model aliases resolve to Claude Code's built-in default for that provider, which can lag the newest release and may not yet be enabled in your account. Pinning lets you control when your users move to a new model. See [Model configuration](/docs/en/model-config.md#pin-models-for-third-party-deployments) for what each provider does when the default is unavailable.

164If you deploy through [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md), or [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), pin specific model versions using `ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Without pinning, model aliases resolve to Claude Code's built-in default for that provider, which can lag the newest release and may not yet be enabled in your account. Pinning lets you control when your users move to a new model. See [Model configuration](https://code.claude.com/docs/en/model-config.md#pin-models-for-third-party-deployments) for what each provider does when the default is unavailable.

165165

166166### Configure security policies

167167

168Security teams can configure managed permissions for what Claude Code is and is not allowed to do, which cannot be overwritten by local configuration. [Learn more](/docs/en/security.md).

168Security teams can configure managed permissions for what Claude Code is and is not allowed to do, which cannot be overwritten by local configuration. [Learn more](https://code.claude.com/docs/en/security.md).

169169

170To limit which of these deployment options a managed machine may use, set [`allowedProviders`](/docs/en/settings-reference#allowedproviders) in managed settings. For example, `["bedrock"]` allows Amazon Bedrock and nothing else; a Bedrock fleet that also enables the Mantle endpoint lists `"mantle"` too. The entry says which endpoint variables also need a managed `env` pin. Requires Claude Code v2.1.285 or later.

170To limit which of these deployment options a managed machine may use, set [`allowedProviders`](https://code.claude.com/docs/en/settings-reference#allowedproviders) in managed settings. For example, `["bedrock"]` allows Amazon Bedrock and nothing else; a Bedrock fleet that also enables the Mantle endpoint lists `"mantle"` too. The entry says which endpoint variables also need a managed `env` pin. Requires Claude Code v2.1.285 or later.

171171

172172### Use MCP for integrations

173173

174MCP is a great way to give Claude Code more information, such as connecting to ticket management systems or error logs. Have one central team configure MCP servers and check a `.mcp.json` configuration into the codebase so that all users benefit. [Learn more](/docs/en/mcp.md).

175175

176176## Next steps

177177

178178Once you've chosen a deployment option and configured access for your team:

179179

1801. **Roll out to your team**: Share installation instructions and have team members [install Claude Code](/docs/en/setup.md) and authenticate with their credentials.

1812. **Set up shared configuration**: Create a [CLAUDE.md file](/docs/en/memory.md) in your repositories to help Claude Code understand your codebase and coding standards.

1823. **Configure permissions**: Review [security settings](/docs/en/security.md) to define what Claude Code can and cannot do in your environment.

1801. **Roll out to your team**: Share installation instructions and have team members [install Claude Code](https://code.claude.com/docs/en/setup.md) and authenticate with their credentials.

1812. **Set up shared configuration**: Create a [CLAUDE.md file](https://code.claude.com/docs/en/memory.md) in your repositories to help Claude Code understand your codebase and coding standards.

1823. **Configure permissions**: Review [security settings](https://code.claude.com/docs/en/security.md) to define what Claude Code can and cannot do in your environment.

183183

tools-reference Changed · +162 / -162 lines

from line 2

33> Complete reference for the tools Claude Code can use, including permission requirements and per-tool behavior.

5Claude Code has access to a set of built-in tools that help it understand and modify your codebase. The tool names are the exact strings you use in [permission rules](/docs/en/permissions.md#tool-specific-permission-rules), [subagent tool lists](/docs/en/sub-agents.md), and [hook matchers](/docs/en/hooks.md).

5Claude Code has access to a set of built-in tools that help it understand and modify your codebase. The tool names are the exact strings you use in [permission rules](https://code.claude.com/docs/en/permissions.md#tool-specific-permission-rules), [subagent tool lists](https://code.claude.com/docs/en/sub-agents.md), and [hook matchers](https://code.claude.com/docs/en/hooks.md).

7To control which tools Claude can use and when it asks first, configure [permission rules](/docs/en/permissions.md#tool-specific-permission-rules) in your settings, [hooks](/docs/en/hooks.md), or a [subagent's tool list](/docs/en/sub-agents.md#supported-frontmatter-fields). See [Configure tools with permission rules and hooks](#configure-tools-with-permission-rules-and-hooks) for each place that accepts a tool name.

7To control which tools Claude can use and when it asks first, configure [permission rules](https://code.claude.com/docs/en/permissions.md#tool-specific-permission-rules) in your settings, [hooks](https://code.claude.com/docs/en/hooks.md), or a [subagent's tool list](https://code.claude.com/docs/en/sub-agents.md#supported-frontmatter-fields). See [Configure tools with permission rules and hooks](#configure-tools-with-permission-rules-and-hooks) for each place that accepts a tool name.

9To add custom tools, connect an [MCP server](/docs/en/mcp.md). To extend Claude with reusable prompt-based workflows, write a [skill](/docs/en/skills.md), which runs through the existing `Skill` tool rather than adding a new tool entry.

9To add custom tools, connect an [MCP server](https://code.claude.com/docs/en/mcp.md). To extend Claude with reusable prompt-based workflows, write a [skill](https://code.claude.com/docs/en/skills.md), which runs through the existing `Skill` tool rather than adding a new tool entry.

1010

1111> [!NOTE]

1212>

13> In [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), a classifier decides most permission prompts instead of you. The `Permission required` column shows whether the tool prompts in [Manual mode](/docs/en/permission-modes.md) for paths inside the working directory. File-access tools marked No, including `Read`, `Grep`, and `Glob`, still prompt for paths outside the [working directory and additional directories](/docs/en/permissions.md#working-directories). `Bash` is marked Yes but runs a built-in set of [read-only commands](/docs/en/permissions.md#read-only-commands) without prompting.

13> In [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), a classifier decides most permission prompts instead of you. The `Permission required` column shows whether the tool prompts in [Manual mode](https://code.claude.com/docs/en/permission-modes.md) for paths inside the working directory. File-access tools marked No, including `Read`, `Grep`, and `Glob`, still prompt for paths outside the [working directory and additional directories](https://code.claude.com/docs/en/permissions.md#working-directories). `Bash` is marked Yes but runs a built-in set of [read-only commands](https://code.claude.com/docs/en/permissions.md#read-only-commands) without prompting.

1414

1515| Tool | Description | Permission required |

1616| :- | :- | :- |

17| `Agent` | Spawns a [subagent](/docs/en/sub-agents.md) with its own context window to handle a task. With [agent teams](/docs/en/agent-teams.md) enabled, a call that carries a `name` can launch a [teammate](/docs/en/agent-teams.md#how-claude-starts-agent-teams) instead. See [Agent tool behavior](#agent-tool-behavior) | No |

18| `Artifact` | Publishes an HTML or Markdown file as an [artifact](/docs/en/artifacts.md): a private, interactive page on claude.ai. You can share it with a public link, or inside your organization on Team and Enterprise plans, where public sharing requires an Owner to [enable it](/docs/en/artifacts.md#control-public-sharing). Requires a Pro, Max, Team, or Enterprise plan and `/login` authentication; see [Availability](/docs/en/artifacts.md#availability) | Yes |

17| `Agent` | Spawns a [subagent](https://code.claude.com/docs/en/sub-agents.md) with its own context window to handle a task. With [agent teams](https://code.claude.com/docs/en/agent-teams.md) enabled, a call that carries a `name` can launch a [teammate](https://code.claude.com/docs/en/agent-teams.md#how-claude-starts-agent-teams) instead. See [Agent tool behavior](#agent-tool-behavior) | No |

18| `Artifact` | Publishes an HTML or Markdown file as an [artifact](https://code.claude.com/docs/en/artifacts.md): a private, interactive page on claude.ai. You can share it with a public link, or inside your organization on Team and Enterprise plans, where public sharing requires an Owner to [enable it](https://code.claude.com/docs/en/artifacts.md#control-public-sharing). Requires a Pro, Max, Team, or Enterprise plan and `/login` authentication; see [Availability](https://code.claude.com/docs/en/artifacts.md#availability) | Yes |

1919| `AskUserQuestion` | Asks multiple-choice questions to gather requirements or clarify ambiguity. Questions stay open until you answer them by default. See [AskUserQuestion tool behavior](#askuserquestion-tool-behavior) | No |

2020| `Bash` | Executes shell commands in your environment. See [Bash tool behavior](#bash-tool-behavior) | Yes |

21| `CronCreate` | Schedules a recurring or one-shot prompt within the current session. Tasks are session-scoped and restored on `--resume` or `--continue` if unexpired. See [session-scoped scheduled tasks](/docs/en/scheduled-tasks.md) | No |

2222| `CronDelete` | Cancels a session-scoped scheduled task by ID | No |

2323| `CronList` | Lists all session-scoped scheduled tasks | No |

2424| `Edit` | Makes targeted edits to specific files. See [Edit tool behavior](#edit-tool-behavior) | Yes |

2525| `EndConversation` | Ends the session, in rare cases of sustained abusive input or when you ask Claude to demonstrate the tool. See [EndConversation tool behavior](#endconversation-tool-behavior) | No |

2626| `EnterPlanMode` | Switches to plan mode to design an approach before coding | No |

27| `EnterWorktree` | Creates an isolated [git worktree](/docs/en/worktrees.md) and switches into it. Pass a `path` to switch into an existing worktree instead of creating a new one. On first entry the target may be a worktree of the current repository or, in a multi-repo workspace, of a repository nested inside it. Before v2.1.203, a nested repository's worktree was rejected. A `path` outside `.claude/worktrees/` prompts for your approval before entering, since it moves the session's working directory and write access to that location. New-worktree creation and paths under `.claude/worktrees/` don't prompt. Before v2.1.206, Claude entered paths outside `.claude/worktrees/` without a prompt. From within a worktree session, or from a subagent with a pinned working directory such as [`isolation: worktree`](/docs/en/sub-agents#supported-frontmatter-fields), only the `path` form is available and the target must be under `.claude/worktrees/` of the session's repository | Yes |

27| `EnterWorktree` | Creates an isolated [git worktree](https://code.claude.com/docs/en/worktrees.md) and switches into it. Pass a `path` to switch into an existing worktree instead of creating a new one. On first entry the target may be a worktree of the current repository or, in a multi-repo workspace, of a repository nested inside it. Before v2.1.203, a nested repository's worktree was rejected. A `path` outside `.claude/worktrees/` prompts for your approval before entering, since it moves the session's working directory and write access to that location. New-worktree creation and paths under `.claude/worktrees/` don't prompt. Before v2.1.206, Claude entered paths outside `.claude/worktrees/` without a prompt. From within a worktree session, or from a subagent with a pinned working directory such as [`isolation: worktree`](https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields), only the `path` form is available and the target must be under `.claude/worktrees/` of the session's repository | Yes |

2828| `ExitPlanMode` | Presents a plan for approval and exits plan mode | Yes |

29| `ExitWorktree` | Exits a worktree session and returns to the original directory. Not available to subagents that already run in their own working directory, such as with [`isolation: worktree`](/docs/en/sub-agents#supported-frontmatter-fields) | No |

29| `ExitWorktree` | Exits a worktree session and returns to the original directory. Not available to subagents that already run in their own working directory, such as with [`isolation: worktree`](https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields) | No |

3030| `Glob` | Finds files based on pattern matching. Absent by default on macOS, Linux, and WSL. See [Glob tool behavior](#glob-tool-behavior) | No |

3131| `Grep` | Searches for patterns in file contents. Absent by default on macOS, Linux, and WSL. See [Grep tool behavior](#grep-tool-behavior) | No |

32| `ListAgents` | Lists the agents Claude can message with `SendMessage`: subagents in the session, [agent team](/docs/en/agent-teams.md) teammates, your other local Claude Code sessions, and, while this session is connected to [Remote Control](/docs/en/remote-control.md), your [cloud sessions](/docs/en/claude-code-on-the-web.md) and your Remote Control sessions on other machines. Backs the `/list-agents` command. See [cross-session messaging](/docs/en/cross-session-messaging.md). Requires Claude Code v2.1.224 or later, and appears only in sessions where [cross-session messaging is enabled](/docs/en/cross-session-messaging.md#availability). Teammate rows and the first line showing this session's own name require v2.1.239 or later | No |

33| `ListMcpResourcesTool` | Lists resources exposed by connected [MCP servers](/docs/en/mcp.md), leaving out [MCP Apps UI resources](/docs/en/mcp.md#reference-mcp-resources), which are pages for a host application to render | No |

32| `ListAgents` | Lists the agents Claude can message with `SendMessage`: subagents in the session, [agent team](https://code.claude.com/docs/en/agent-teams.md) teammates, your other local Claude Code sessions, and, while this session is connected to [Remote Control](https://code.claude.com/docs/en/remote-control.md), your [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) and your Remote Control sessions on other machines. Backs the `/list-agents` command. See [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md). Requires Claude Code v2.1.224 or later, and appears only in sessions where [cross-session messaging is enabled](https://code.claude.com/docs/en/cross-session-messaging.md#availability). Teammate rows and the first line showing this session's own name require v2.1.239 or later | No |

33| `ListMcpResourcesTool` | Lists resources exposed by connected [MCP servers](https://code.claude.com/docs/en/mcp.md), leaving out [MCP Apps UI resources](https://code.claude.com/docs/en/mcp.md#reference-mcp-resources), which are pages for a host application to render | No |

3434| `LSP` | Code intelligence via language servers: jump to definitions, find references, report type errors and warnings. See [LSP tool behavior](#lsp-tool-behavior) | No |

3535| `Monitor` | Runs a command in the background and feeds each output line back to Claude, so it can react to log entries, file changes, or polled status mid-conversation. Can also open a WebSocket and treat each incoming message as an event. See [Monitor tool](#monitor-tool) | Yes |

3636| `NotebookEdit` | Modifies Jupyter notebook cells. See [NotebookEdit tool behavior](#notebookedit-tool-behavior) | Yes |

3737| `PowerShell` | Executes PowerShell commands natively. See [PowerShell tool](#powershell-tool) for availability | Yes |

38| `PushNotification` | Sends a desktop notification, and a phone push when [Remote Control](/docs/en/remote-control.md) is connected, so a long-running task or [session-scoped scheduled task](/docs/en/scheduled-tasks.md) can reach you when you step away. Push delivery runs through Anthropic-hosted infrastructure, which is not accessible from Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry | No |

38| `PushNotification` | Sends a desktop notification, and a phone push when [Remote Control](https://code.claude.com/docs/en/remote-control.md) is connected, so a long-running task or [session-scoped scheduled task](https://code.claude.com/docs/en/scheduled-tasks.md) can reach you when you step away. Push delivery runs through Anthropic-hosted infrastructure, which is not accessible from Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry | No |

3939| `Read` | Reads the contents of files. See [Read tool behavior](#read-tool-behavior) | No |

4040| `ReadMcpResourceTool` | Reads a specific MCP resource by URI | No |

41| `RemoteTrigger` | Creates, updates, runs, and lists [cloud scheduled tasks](/docs/en/routines.md), formerly routines, on claude.ai. Backs the `/schedule` command. The [`RemoteTrigger` input reference](/docs/en/agent-sdk/typescript#remotetrigger) documents every action and the organization policies that remove the tool. Cloud scheduled tasks live on claude.ai and require a Pro, Max, Team, or Enterprise plan. This tool is therefore not accessible from Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry | No |

41| `RemoteTrigger` | Creates, updates, runs, and lists [cloud scheduled tasks](https://code.claude.com/docs/en/routines.md), formerly routines, on claude.ai. Backs the `/schedule` command. The [`RemoteTrigger` input reference](https://code.claude.com/docs/en/agent-sdk/typescript#remotetrigger) documents every action and the organization policies that remove the tool. Cloud scheduled tasks live on claude.ai and require a Pro, Max, Team, or Enterprise plan. This tool is therefore not accessible from Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry | No |

4242| `ReportFindings` | Reports code-review findings as a structured list, with a file, summary, and failure scenario per finding, so Claude Code can render them instead of printing them as text. Claude calls it when active code-review instructions tell it to. A finding can also carry an optional `category` slug, such as `correctness` or `test-coverage`, shown next to the file location in the rendered list | No |

43| `ScheduleWakeup` | Reschedules the next iteration of a [self-paced `/loop`](/docs/en/scheduled-tasks#let-claude-choose-the-interval). Claude calls this at the end of each iteration to pick when the next one runs, between one minute and one hour out; you don't call it directly. To end the loop instead, Claude calls it with `stop: true`, which cancels the pending wakeup. The pending wakeup appears in `session_crons` in [Stop hook input](/docs/en/hooks.md#stop-input) | No |

43| `ScheduleWakeup` | Reschedules the next iteration of a [self-paced `/loop`](https://code.claude.com/docs/en/scheduled-tasks#let-claude-choose-the-interval). Claude calls this at the end of each iteration to pick when the next one runs, between one minute and one hour out; you don't call it directly. To end the loop instead, Claude calls it with `stop: true`, which cancels the pending wakeup. The pending wakeup appears in `session_crons` in [Stop hook input](https://code.claude.com/docs/en/hooks.md#stop-input) | No |

4444| `SendFeedback` | Drafts a feedback report about Claude Code, covering a product problem or Claude's own behavior in the session, and queues it on your machine for you to review. Claude Code sends nothing until you choose to send the draft. See [SendFeedback tool behavior](#sendfeedback-tool-behavior). Requires Claude Code v2.1.238 or later | No |

45| `SendMessage` | Sends a message to another agent: an [agent team](/docs/en/agent-teams.md) teammate, a [subagent it resumes](/docs/en/sub-agents.md#resume-subagents) by agent ID or name, or one of your other Claude Code sessions, on this machine or beyond it. Messaging other sessions requires Claude Code v2.1.224 or later. [Cross-session messaging](/docs/en/cross-session-messaging.md) covers which sessions Claude can reach, [what a message looks like when it arrives](/docs/en/cross-session-messaging.md#what-a-message-looks-like), and [how Claude gets a notice when another session goes idle](/docs/en/cross-session-messaging.md#get-a-notice-when-another-session-goes-idle). Claude can include an optional `summary` input, typically 5-10 words, that Claude Code shows as a one-line preview. When Claude omits it on a [plain-text message](/docs/en/cross-session-messaging.md#limitations), Claude Code uses the first line of the message as the summary. Claude Code truncates a summary longer than 200 characters with an ellipsis | No |

46| `SendUserFile` | Sends files from the session to you with an optional caption, so a generated report, diagram, screenshot, or built artifact reaches your device instead of only being mentioned in the transcript. The optional `display` input controls presentation: `render` opens the file inline in the client, `attach` shows a download card only, and when unset the client decides by file type. Available when a [Remote Control](/docs/en/remote-control.md) client is connected or in a [cloud session](/docs/en/claude-code-on-the-web.md). Delivery runs through Anthropic-hosted infrastructure, so the tool is not available on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry | No |

45| `SendMessage` | Sends a message to another agent: an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate, a [subagent it resumes](https://code.claude.com/docs/en/sub-agents.md#resume-subagents) by agent ID or name, or one of your other Claude Code sessions, on this machine or beyond it. Messaging other sessions requires Claude Code v2.1.224 or later. [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md) covers which sessions Claude can reach, [what a message looks like when it arrives](https://code.claude.com/docs/en/cross-session-messaging.md#what-a-message-looks-like), and [how Claude gets a notice when another session goes idle](https://code.claude.com/docs/en/cross-session-messaging.md#get-a-notice-when-another-session-goes-idle). Claude can include an optional `summary` input, typically 5-10 words, that Claude Code shows as a one-line preview. When Claude omits it on a [plain-text message](https://code.claude.com/docs/en/cross-session-messaging.md#limitations), Claude Code uses the first line of the message as the summary. Claude Code truncates a summary longer than 200 characters with an ellipsis | No |

46| `SendUserFile` | Sends files from the session to you with an optional caption, so a generated report, diagram, screenshot, or built artifact reaches your device instead of only being mentioned in the transcript. The optional `display` input controls presentation: `render` opens the file inline in the client, `attach` shows a download card only, and when unset the client decides by file type. Available when a [Remote Control](https://code.claude.com/docs/en/remote-control.md) client is connected or in a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md). Delivery runs through Anthropic-hosted infrastructure, so the tool is not available on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry | No |

4747| `ShareOnboardingGuide` | Uploads `ONBOARDING.md` and returns a share link teammates can open in Claude Code. Called from `/team-onboarding` after the guide is written. Available to claude.ai subscribers on Team and Enterprise plans | Yes |

48| `Skill` | Executes a [skill](/docs/en/skills.md#control-who-invokes-a-skill) within the main conversation | Yes |

49| `SubagentHandback` | Delivers a subagent's final report to whichever conversation receives that subagent's result. Provided only in [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), to subagents that the Agent tool runs locally other than [forks](/docs/en/sub-agents.md#fork-the-current-conversation), and available in the terminal CLI, IDE extensions, cloud sessions, and the Agent SDK; the classifier reviews the report before it's delivered. Requires Claude Code v2.1.271 or later | No |

48| `Skill` | Executes a [skill](https://code.claude.com/docs/en/skills.md#control-who-invokes-a-skill) within the main conversation | Yes |

49| `SubagentHandback` | Delivers a subagent's final report to whichever conversation receives that subagent's result. Provided only in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), to subagents that the Agent tool runs locally other than [forks](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation), and available in the terminal CLI, IDE extensions, cloud sessions, and the Agent SDK; the classifier reviews the report before it's delivered. Requires Claude Code v2.1.271 or later | No |

5050| `TaskCreate` | Creates a new task in the task list. Provided by default only on the models listed under [Task tool availability](#task-tool-availability), and on other models when you opt in | No |

5151| `TaskGet` | Retrieves full details for a specific task. Provided by default only on the models listed under [Task tool availability](#task-tool-availability), and on other models when you opt in | No |

5252| `TaskList` | Lists all tasks with their current status. Provided by default only on the models listed under [Task tool availability](#task-tool-availability), and on other models when you opt in | No |

53| `TaskOutput` | Removed in v2.1.277. Previously retrieved output from a background task; Claude reads a background task's [output file](/docs/en/interactive-mode.md#how-backgrounding-works) with `Read` instead | No |

54| `TaskStop` | Stops a running background task by ID. It also accepts an [agent-team teammate](/docs/en/agent-teams.md) or a named background agent by agent ID or name. When no task matches the ID, the error lists the running background agents by ID and description, including agents that another agent spawned | No |

53| `TaskOutput` | Removed in v2.1.277. Previously retrieved output from a background task; Claude reads a background task's [output file](https://code.claude.com/docs/en/interactive-mode.md#how-backgrounding-works) with `Read` instead | No |

54| `TaskStop` | Stops a running background task by ID. It also accepts an [agent-team teammate](https://code.claude.com/docs/en/agent-teams.md) or a named background agent by agent ID or name. When no task matches the ID, the error lists the running background agents by ID and description, including agents that another agent spawned | No |

5555| `TaskUpdate` | Updates task status, dependencies, details, or deletes tasks. Provided by default only on the models listed under [Task tool availability](#task-tool-availability), and on other models when you opt in | No |

5656| `TodoWrite` | Manages the session task checklist. Disabled by default in favor of `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate`. Set `CLAUDE_CODE_ENABLE_TASKS=0` to re-enable it in [sessions that have the task-tracking tools](#task-tool-availability) | No |

57| `ToolSearch` | Searches for and loads deferred tools when [tool search](/docs/en/mcp.md#scale-with-mcp-tool-search) is enabled | No |

58| `WaitForMcpServers` | Waits for one or more [MCP servers](/docs/en/mcp.md) that are still connecting in the background, so a request can use their tools without restarting the session. Claude calls it when a needed server isn't connected yet. Only appears when [tool search](/docs/en/mcp.md#scale-with-mcp-tool-search) is disabled, since `ToolSearch` handles the wait when it's enabled | No |

57| `ToolSearch` | Searches for and loads deferred tools when [tool search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search) is enabled | No |

58| `WaitForMcpServers` | Waits for one or more [MCP servers](https://code.claude.com/docs/en/mcp.md) that are still connecting in the background, so a request can use their tools without restarting the session. Claude calls it when a needed server isn't connected yet. Only appears when [tool search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search) is disabled, since `ToolSearch` handles the wait when it's enabled | No |

5959| `WebFetch` | Fetches content from a specified URL. See [WebFetch tool behavior](#webfetch-tool-behavior) | Yes |

6060| `WebSearch` | Performs web searches. See [WebSearch tool behavior](#websearch-tool-behavior) | Yes |

61| `Workflow` | Runs a [dynamic workflow](/docs/en/workflows.md): a script that orchestrates many subagents in the background and returns one consolidated result | Yes |

61| `Workflow` | Runs a [dynamic workflow](https://code.claude.com/docs/en/workflows.md): a script that orchestrates many subagents in the background and returns one consolidated result | Yes |

6262| `Write` | Creates or overwrites files. See [Write tool behavior](#write-tool-behavior) | Yes |

6363

6464## Configure tools with permission rules and hooks

from line 65

6565

6666For the most part, Claude decides when to use these tools and you don't need to name them yourself when interacting with Claude. You reference tool names directly when defining permissions and other configuration:

6767

68* in [`permissions.allow`](/docs/en/settings-reference#permissions-allow) and [`permissions.deny`](/docs/en/settings-reference#permissions-deny) in settings, and the `/permissions` interface

69* in the `--allowedTools` and `--disallowedTools` [CLI flags](/docs/en/cli-reference.md)

70* in the Agent SDK's [`allowedTools` and `disallowedTools`](/docs/en/agent-sdk/permissions#allow-and-deny-rules) options

71* in a [skill's `allowed-tools`](/docs/en/skills#frontmatter-reference) frontmatter

72* in a hook's [`if` condition](/docs/en/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field)

68* in [`permissions.allow`](https://code.claude.com/docs/en/settings-reference#permissions-allow) and [`permissions.deny`](https://code.claude.com/docs/en/settings-reference#permissions-deny) in settings, and the `/permissions` interface

69* in the `--allowedTools` and `--disallowedTools` [CLI flags](https://code.claude.com/docs/en/cli-reference.md)

70* in the Agent SDK's [`allowedTools` and `disallowedTools`](https://code.claude.com/docs/en/agent-sdk/permissions#allow-and-deny-rules) options

71* in a [skill's `allowed-tools`](https://code.claude.com/docs/en/skills#frontmatter-reference) frontmatter

72* in a hook's [`if` condition](https://code.claude.com/docs/en/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field)

7373

7474All of these accept the same rule format, `ToolName(specifier)`. The specifier depends on the tool, and several tools share a format:

7575

7676| Rule format | Applies to | Details |

7777| :- | :- | :- |

78| `Bash(npm run *)` | Bash, Monitor | [Command pattern matching](/docs/en/permissions.md#bash) |

79| `PowerShell(Get-ChildItem *)` | PowerShell | [Command pattern matching](/docs/en/permissions.md#powershell) |

80| `Read(~/secrets/**)` | Read, Grep, Glob, LSP | [Path pattern matching](/docs/en/permissions.md#read-and-edit) |

81| `Edit(/src/**)` | Edit, Write, NotebookEdit | [Path pattern matching](/docs/en/permissions.md#read-and-edit) |

82| `Skill(deploy *)` | Skill | [Skill name matching](/docs/en/skills.md#restrict-claude’s-skill-access) |

83| `Agent(Explore)` | Agent | [Subagent type matching](/docs/en/permissions.md#agent-subagents) |

84| `WebFetch(domain:example.com)` | WebFetch | [Domain matching](/docs/en/permissions.md#webfetch) |

78| `Bash(npm run *)` | Bash, Monitor | [Command pattern matching](https://code.claude.com/docs/en/permissions.md#bash) |

79| `PowerShell(Get-ChildItem *)` | PowerShell | [Command pattern matching](https://code.claude.com/docs/en/permissions.md#powershell) |

80| `Read(~/secrets/**)` | Read, Grep, Glob, LSP | [Path pattern matching](https://code.claude.com/docs/en/permissions.md#read-and-edit) |

81| `Edit(/src/**)` | Edit, Write, NotebookEdit | [Path pattern matching](https://code.claude.com/docs/en/permissions.md#read-and-edit) |

82| `Skill(deploy *)` | Skill | [Skill name matching](https://code.claude.com/docs/en/skills.md#restrict-claude’s-skill-access) |

83| `Agent(Explore)` | Agent | [Subagent type matching](https://code.claude.com/docs/en/permissions.md#agent-subagents) |

84| `WebFetch(domain:example.com)` | WebFetch | [Domain matching](https://code.claude.com/docs/en/permissions.md#webfetch) |

8585| `WebSearch` | WebSearch | No specifier; allow or deny the tool as a whole |

8686

8787Tools not listed here, such as `ExitPlanMode` or `ShareOnboardingGuide`, accept only the bare tool name with no specifier.

from line 88

8888

8989An `Edit(...)` allow rule also grants read access to the same path, so you don't need a matching `Read(...)` rule. A `Read(...)` deny rule also blocks the Edit and Write tools on the same path, including creating a new file there, because both tools change content Claude has to be able to read back. For the Write tool, the `Read` deny check requires Claude Code v2.1.228 or later.

9090

91Hook `matcher` fields use bare tool names, not the parenthesized rule format. See [matcher patterns](/docs/en/hooks.md#matcher-patterns) for the matching rules. For the field names each tool passes to `tool_input` in hooks, see the [PreToolUse input reference](/docs/en/hooks.md#pretooluse-input).

91Hook `matcher` fields use bare tool names, not the parenthesized rule format. See [matcher patterns](https://code.claude.com/docs/en/hooks.md#matcher-patterns) for the matching rules. For the field names each tool passes to `tool_input` in hooks, see the [PreToolUse input reference](https://code.claude.com/docs/en/hooks.md#pretooluse-input).

9292

9393## Agent tool behavior

9494

9595The Agent tool spawns a subagent in a separate context window. The subagent works through its task autonomously, then returns its result to the parent conversation. The parent doesn't see the subagent's intermediate tool calls or outputs, only that final result. The same tool can also launch a teammate or a fork:

9696

97* **Teammate**: with [agent teams](/docs/en/agent-teams.md) enabled, a call that carries a `name` can launch a [teammate](/docs/en/agent-teams.md#how-claude-starts-agent-teams) instead, which reports back through team messages rather than by returning a result

98* **Fork**: wherever [fork mode](/docs/en/sub-agents.md#turn-fork-mode-on-or-off) is on, the tool can launch a [forked subagent](/docs/en/sub-agents.md#fork-the-current-conversation), which inherits the full parent conversation instead of starting fresh

97* **Teammate**: with [agent teams](https://code.claude.com/docs/en/agent-teams.md) enabled, a call that carries a `name` can launch a [teammate](https://code.claude.com/docs/en/agent-teams.md#how-claude-starts-agent-teams) instead, which reports back through team messages rather than by returning a result

98* **Fork**: wherever [fork mode](https://code.claude.com/docs/en/sub-agents.md#turn-fork-mode-on-or-off) is on, the tool can launch a [forked subagent](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation), which inherits the full parent conversation instead of starting fresh

9999

100To cap how many turns a subagent runs, set `maxTurns` in the [subagent definition](/docs/en/sub-agents.md#supported-frontmatter-fields). When the subagent reaches the limit, Claude Code marks the returned result as partial output, and Claude can [resume the subagent](/docs/en/sub-agents.md#resume-subagents) to continue.

100To cap how many turns a subagent runs, set `maxTurns` in the [subagent definition](https://code.claude.com/docs/en/sub-agents.md#supported-frontmatter-fields). When the subagent reaches the limit, Claude Code marks the returned result as partial output, and Claude can [resume the subagent](https://code.claude.com/docs/en/sub-agents.md#resume-subagents) to continue.

101101

102Which tools a non-fork subagent can use depends on the `tools` and `disallowedTools` fields in the [subagent definition](/docs/en/sub-agents.md):

102Which tools a non-fork subagent can use depends on the `tools` and `disallowedTools` fields in the [subagent definition](https://code.claude.com/docs/en/sub-agents.md):

103103

104* **Neither field set**: the subagent inherits every [tool available to subagents](/docs/en/sub-agents.md#available-tools).

104* **Neither field set**: the subagent inherits every [tool available to subagents](https://code.claude.com/docs/en/sub-agents.md#available-tools).

105105* **`tools` only**: the subagent gets only the listed tools.

106106* **`disallowedTools` only**: the subagent gets every parent tool except the listed ones.

107107* **Both set**: `disallowedTools` takes precedence. A tool listed in both is removed.

108108

109In every case, the resolved set is limited to the [tools available to subagents](/docs/en/sub-agents.md#available-tools): a tool that isn't available to subagents is never granted, even when listed in `tools`. Where the conditions in the `SubagentHandback` tools-table entry hold, Claude Code also gives the subagent that tool, even if you leave it out of `tools` or list it in `disallowedTools`.

109In every case, the resolved set is limited to the [tools available to subagents](https://code.claude.com/docs/en/sub-agents.md#available-tools): a tool that isn't available to subagents is never granted, even when listed in `tools`. Where the conditions in the `SubagentHandback` tools-table entry hold, Claude Code also gives the subagent that tool, even if you leave it out of `tools` or list it in `disallowedTools`.

110110

111If every entry in a subagent's `tools` list fails to match a usable tool, the Agent tool usually returns an error naming the entries instead of launching the subagent; see [Agent would be spawned with zero tools](/docs/en/errors.md#agent-would-be-spawned-with-zero-tools) for the message and how to fix each entry.

111If every entry in a subagent's `tools` list fails to match a usable tool, the Agent tool usually returns an error naming the entries instead of launching the subagent; see [Agent would be spawned with zero tools](https://code.claude.com/docs/en/errors.md#agent-would-be-spawned-with-zero-tools) for the message and how to fix each entry.

112112

113113Launching the subagent doesn't itself prompt for permission. Claude Code checks the subagent's own tool calls against your permission rules as it runs.

114114

115Where you see a subagent's permission prompts depends on whether it runs in the foreground or the background. Claude Code runs subagents in the background by default, apart from the [cases that run in the foreground](/docs/en/sub-agents.md#run-subagents-in-foreground-or-background).

115Where you see a subagent's permission prompts depends on whether it runs in the foreground or the background. Claude Code runs subagents in the background by default, apart from the [cases that run in the foreground](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background).

116116

117117* **Foreground subagents** show the same permission prompts you would see in the main conversation, at the moment each tool call happens.

118118* **Background subagents** surface permission prompts in your main session. The prompt names which subagent is asking, and pressing Esc denies that one tool call without stopping the subagent.

119119

120To [limit what a subagent can reach](/docs/en/sub-agents.md#control-subagent-capabilities) in the first place, narrow its `tools` field, for example by leaving Bash off the list, or set deny rules in your settings.

120To [limit what a subagent can reach](https://code.claude.com/docs/en/sub-agents.md#control-subagent-capabilities) in the first place, narrow its `tools` field, for example by leaving Bash off the list, or set deny rules in your settings.

121121

122122## AskUserQuestion tool behavior

123123

from line 127

127127

128128### Question auto-continue timeout

129129

130Questions stay open until you answer them. If you want a question you leave unanswered to eventually close and let Claude continue without you, set the [`askUserQuestionTimeout`](/docs/en/settings-reference#askuserquestiontimeout) setting to `60s`, `5m`, or `10m`, either in your user `settings.json` or from the **Question auto-continue timeout** row in `/config`.

130Questions stay open until you answer them. If you want a question you leave unanswered to eventually close and let Claude continue without you, set the [`askUserQuestionTimeout`](https://code.claude.com/docs/en/settings-reference#askuserquestiontimeout) setting to `60s`, `5m`, or `10m`, either in your user `settings.json` or from the **Question auto-continue timeout** row in `/config`.

131131

132132After a question sits that long with no input, the dialog closes on its own: it submits any options you'd already selected and tells Claude you may be away from your keyboard, so Claude proceeds on its own judgment and can re-ask later. You see a countdown for the last 20 seconds. Press any key to restart the timer. While your terminal reports that its window is focused, the timer doesn't count down.

133133

134The timer never starts for a question Claude asks in a [background session](/docs/en/agent-view.md), in [screen reader mode](/docs/en/accessibility.md), or while the session is connected to [Remote Control](/docs/en/remote-control.md). Those questions wait until you answer them. The timeout applies only to `AskUserQuestion`'s multiple-choice questions; permission prompts, including plan approval, never auto-resolve on idle.

134The timer never starts for a question Claude asks in a [background session](https://code.claude.com/docs/en/agent-view.md), in [screen reader mode](https://code.claude.com/docs/en/accessibility.md), or while the session is connected to [Remote Control](https://code.claude.com/docs/en/remote-control.md). Those questions wait until you answer them. The timeout applies only to `AskUserQuestion`'s multiple-choice questions; permission prompts, including plan approval, never auto-resolve on idle.

135135

136136## Bash tool behavior

137137

from line 139

139139

140140### What persists between commands

141141

142* When Claude runs `cd` in the main session, the new working directory carries over to later Bash commands as long as it stays inside the project directory or an [additional working directory](/docs/en/permissions.md#working-directories) you added with `--add-dir`, `/add-dir`, or `additionalDirectories` in settings. This includes commands Claude runs in response to your later messages.

142* When Claude runs `cd` in the main session, the new working directory carries over to later Bash commands as long as it stays inside the project directory or an [additional working directory](https://code.claude.com/docs/en/permissions.md#working-directories) you added with `--add-dir`, `/add-dir`, or `additionalDirectories` in settings. This includes commands Claude runs in response to your later messages.

143143 * Subagent sessions never carry over working directory changes.

144144 * If `cd` lands outside those directories, Claude Code resets to the project directory and appends `Shell cwd was reset to <dir>` to the tool result.

145145 * To disable this carry-over so every Bash command starts in the project directory, set `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1`.

from line 146

146146* Environment variables don't persist. An `export` in one command won't be available in the next.

147147* Aliases and shell functions defined in your shell startup file are available. At session start, Claude Code sources `~/.zshrc`, `~/.bashrc`, or `~/.profile` depending on your shell, captures the resulting aliases, functions, and shell options, and applies them to every Bash command.

148148

149Activate your virtualenv or conda environment before launching Claude Code. To make environment variables persist across Bash commands, set [`CLAUDE_ENV_FILE`](/docs/en/env-vars) to a shell script before launching Claude Code, or use a [SessionStart hook](/docs/en/hooks.md#persist-environment-variables) to populate it dynamically.

149Activate your virtualenv or conda environment before launching Claude Code. To make environment variables persist across Bash commands, set [`CLAUDE_ENV_FILE`](https://code.claude.com/docs/en/env-vars) to a shell script before launching Claude Code, or use a [SessionStart hook](https://code.claude.com/docs/en/hooks.md#persist-environment-variables) to populate it dynamically.

150150

151151### Timeout and output limits

152152

153153Each command runs under a timeout, and Claude manages it: when it wants longer than the default for a command, it passes the `timeout` parameter with that call. You never set a per-command timeout.

154154

155Two [environment variables](/docs/en/env-vars.md) control what Claude gets for a command that runs in the foreground:

155Two [environment variables](https://code.claude.com/docs/en/env-vars.md) control what Claude gets for a command that runs in the foreground:

156156

157157* `BASH_DEFAULT_TIMEOUT_MS` — the default when Claude passes no timeout; two minutes out of the box

158158* `BASH_MAX_TIMEOUT_MS` — with the default, sets the ceiling that caps whatever Claude requests: the effective ceiling is the larger of the two, ten minutes out of the box

from line 170

170170

171171A command that exits 1 counts as a valid result for the Bash tool only when Claude Code recognizes exit code 1 as a benign outcome for that command: `grep`, `rg`, `egrep`, `fgrep`, `find`, `diff`, `test`, and `[`, plus `git diff` and `git grep`. Every other command that exits 1 counts as a failure, even when exit 1 is a benign informational outcome: no matches for `pgrep` and `jq -e`, files that differ for `cmp`.

172172

173[`BASH_MAX_OUTPUT_LENGTH`](/docs/en/env-vars) sets how many characters of output Claude Code reads back from the working file into a command's result: 30,000 by default, up to a hard ceiling of 150,000. Raise it when your commands routinely overflow that window, such as a verbose build or a full test-suite log. Raising it enlarges the read-back window, which is also the window a failing command's excerpt is cut from. It doesn't raise the inline ceilings: a valid result over the inline ceiling arrives as a file path plus preview regardless of this variable.

173[`BASH_MAX_OUTPUT_LENGTH`](https://code.claude.com/docs/en/env-vars) sets how many characters of output Claude Code reads back from the working file into a command's result: 30,000 by default, up to a hard ceiling of 150,000. Raise it when your commands routinely overflow that window, such as a verbose build or a full test-suite log. Raising it enlarges the read-back window, which is also the window a failing command's excerpt is cut from. It doesn't raise the inline ceilings: a valid result over the inline ceiling arrives as a file path plus preview regardless of this variable.

174174

175To change how much of a valid result Claude receives inline, set the [`bashOutputMaxChars`](/docs/en/settings-reference#bashoutputmaxchars) setting instead, up to 128,000 characters. It sizes the inline ceiling and the read-back window together, and Claude Code then ignores `BASH_MAX_OUTPUT_LENGTH`. Requires Claude Code v2.1.261 or later.

175To change how much of a valid result Claude receives inline, set the [`bashOutputMaxChars`](https://code.claude.com/docs/en/settings-reference#bashoutputmaxchars) setting instead, up to 128,000 characters. It sizes the inline ceiling and the read-back window together, and Claude Code then ignores `BASH_MAX_OUTPUT_LENGTH`. Requires Claude Code v2.1.261 or later.

176176

177177### Background commands

178178

from line 180

180180

181181#### When a background command stops

182182

183A command that a [foreground subagent](/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) started stops when that subagent's run ends, whether it finished, failed, or was interrupted. A command that the main conversation or a background subagent started keeps running after a final response, until it exits, is stopped, or reaches its [time limit](#time-limit-for-background-commands).

183A command that a [foreground subagent](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) started stops when that subagent's run ends, whether it finished, failed, or was interrupted. A command that the main conversation or a background subagent started keeps running after a final response, until it exits, is stopped, or reaches its [time limit](#time-limit-for-background-commands).

184184

185While a command that the main conversation started is still running, a run in non-interactive mode with the `-p` flag [stays open after its result](/docs/en/headless.md#background-tasks-at-exit) until that command exits or reaches its time limit. A command that a background subagent started is stopped when the run exits.

185While a command that the main conversation started is still running, a run in non-interactive mode with the `-p` flag [stays open after its result](https://code.claude.com/docs/en/headless.md#background-tasks-at-exit) until that command exits or reaches its time limit. A command that a background subagent started is stopped when the run exits.

186186

187187#### Time limit for background commands

188188

from line 195

195195* A command that Claude starts in the background gets 30 minutes, or the `timeout` Claude passes with `run_in_background`, up to a maximum of 2 hours

196196* A command that starts in the foreground and then moves to the background, for example at its timeout, gets 30 minutes from the move

197197

198In a run with the `-p` flag whose prompt you pass as text rather than with `--input-format stream-json`, both defaults are 10 minutes instead of 30, because the run [waits for background commands after its result](/docs/en/headless.md#background-tasks-at-exit).

199199

200200When a background command reaches its time limit, Claude Code stops it and tells Claude why, and Claude can start the command again with a longer `timeout` if the work still needs it. The stop notice reads `Background command "<description>" was stopped after reaching its background time limit`.

201201

202202#### Raise the time limit for background commands

203203

204Two [environment variables](/docs/en/env-vars.md) raise these limits, for Bash and PowerShell commands alike. Both take milliseconds, and neither can shorten a limit: a lower value leaves the defaults and the 2-hour maximum in place.

204Two [environment variables](https://code.claude.com/docs/en/env-vars.md) raise these limits, for Bash and PowerShell commands alike. Both take milliseconds, and neither can shorten a limit: a lower value leaves the defaults and the 2-hour maximum in place.

205205

206206* Set `BASH_DEFAULT_TIMEOUT_MS` above `1800000` to replace the 30-minute default with that value, both for commands Claude starts without a `timeout` and for moved commands. In a `-p` run whose prompt you pass as text, any value above `600000` replaces its 10-minute default

207207* Set `BASH_MAX_TIMEOUT_MS` above `7200000` to raise the 2-hour maximum to that value. Setting `BASH_DEFAULT_TIMEOUT_MS` above `7200000` raises the maximum the same way

from line 210

210210

211211When a foreground command reaches its timeout without finishing, Claude Code moves it to the background instead of stopping it, unless the command starts with `sleep`. A moved command's [time limit](#time-limit-for-background-commands) counts from the move, and a foreground subagent's moved command still stops when that subagent's run ends.

212212

213Setting [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/en/env-vars#variables) or running in [bare mode](/docs/en/headless.md#start-faster-with-bare-mode) disables auto-backgrounding, so a command that reaches its timeout stops instead.

213Setting [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](https://code.claude.com/docs/en/env-vars#variables) or running in [bare mode](https://code.claude.com/docs/en/headless.md#start-faster-with-bare-mode) disables auto-backgrounding, so a command that reaches its timeout stops instead.

214214

215215The result of a command moved to the background states what happened:

216216

from line 219

219219

220220### Memory limit on Linux and WSL

221221

222On Linux and WSL, set [`CLAUDE_CODE_TOOL_MEMORY_LIMIT`](/docs/en/env-vars#variables) to a size such as `4G` to cap the memory that Bash, PowerShell, and [Monitor](#monitor-tool) tool commands can use, so one runaway build can't take the memory the rest of the session needs. Requires Claude Code v2.1.233 or later. Before v2.1.246, Monitor tool commands ran outside the cap.

222On Linux and WSL, set [`CLAUDE_CODE_TOOL_MEMORY_LIMIT`](https://code.claude.com/docs/en/env-vars#variables) to a size such as `4G` to cap the memory that Bash, PowerShell, and [Monitor](#monitor-tool) tool commands can use, so one runaway build can't take the memory the rest of the session needs. Requires Claude Code v2.1.233 or later. Before v2.1.246, Monitor tool commands ran outside the cap.

223223

224224* Write the size as a number of bytes or with a `K`, `M`, `G`, or `T` suffix. Set `0`, `off`, `false`, `no`, or `none` to turn the cap off. Claude Code ignores any other value it can't read as a size, such as `4e9`.

225225* Claude Code counts all of a session's Bash, PowerShell, and Monitor commands against the one cap, not each command on its own.

from line 227

227227* After the first process Claude Code starts has turned the cap on, or has turned it off because of an off value or a failed cgroup setup, Claude Code holds that result until you relaunch. To apply a changed or removed value, or a fixed setup, launch `claude` again.

228228* When commands can't stay under the cap, the kernel kills a command, and nothing in its result names the cap.

229229

230Claude Code can also count other kinds of processes it starts against the same limit. Set [`CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE`](/docs/en/env-vars#variables) to a comma-separated list of the kinds to exempt from the cap; Claude Code applies the cap to every kind not on your list. Set it to `none` to cap every kind, or to `all-new` to cap only Bash, PowerShell, and Monitor tool commands. Requires Claude Code v2.1.246 or later. The kinds you can name:

230Claude Code can also count other kinds of processes it starts against the same limit. Set [`CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE`](https://code.claude.com/docs/en/env-vars#variables) to a comma-separated list of the kinds to exempt from the cap; Claude Code applies the cap to every kind not on your list. Set it to `none` to cap every kind, or to `all-new` to cap only Bash, PowerShell, and Monitor tool commands. Requires Claude Code v2.1.246 or later. The kinds you can name:

231231

232* `mcp`: local [MCP servers](/docs/en/mcp.md)

232* `mcp`: local [MCP servers](https://code.claude.com/docs/en/mcp.md)

233233* `lsp`: [language servers](#lsp-tool-behavior)

234* `hooks`: [hook](/docs/en/hooks.md) commands

235* `plugin`: commands that [plugins](/docs/en/plugins/overview.md) run

234* `hooks`: [hook](https://code.claude.com/docs/en/hooks.md) commands

235* `plugin`: commands that [plugins](https://code.claude.com/docs/en/plugins/overview.md) run

236236* `helper`: Claude Code's own helper commands, such as `git`

237* `agent`: child Claude Code processes, such as [agent teammates](/docs/en/agent-teams.md)

237* `agent`: child Claude Code processes, such as [agent teammates](https://code.claude.com/docs/en/agent-teams.md)

238238

239239Whatever you list, these rules apply:

240240

from line 246

246246

247247The Edit tool performs exact string replacement. It takes an `old_string` and a `new_string` and replaces the first with the second. It doesn't use regex or fuzzy matching.

248248

249These checks must pass for an edit to apply. Before any of them, a path matched by a [`Read` deny rule](/docs/en/permissions#tool-specific-permission-rules) is refused, including creating a new file there.

249These checks must pass for an edit to apply. Before any of them, a path matched by a [`Read` deny rule](https://code.claude.com/docs/en/permissions#tool-specific-permission-rules) is refused, including creating a new file there.

250250

251251* **Read-before-edit**: Claude reads the file in the current conversation before editing it, and a read cut short with a [`PARTIAL view` notice](#large-files) doesn't count. Claude Opus 4.6, Claude Haiku 4.5, and older models always require the read. Newer models can edit an unread file when reading it wouldn't need a permission prompt and the Read tool is available.

252252* **Match**: `old_string` must appear in the file exactly as written. A single character of whitespace or indentation difference is enough to miss.

from line 256

256256

257257Claude can also edit a file without a separate Read after it views the file with a Bash command such as `cat` or `grep`. Those commands are `cat`, `nl`, `bat`, `batcat`, `head`, `tail`, `sed -n 'X,Yp'`, `grep`, `egrep`, `fgrep`, and `rg`, each run on one file with no pipes or redirects. A search that prints no matches doesn't count as a read, nor does any command outside this list.

258258

259When Claude views a file this way, Claude Code also loads any [subdirectory `CLAUDE.md`](/docs/en/memory#how-claude-md-files-load) and [path-scoped rules](/docs/en/memory.md#path-specific-rules) that apply to that file. See [Read and Edit permission rules](/docs/en/permissions.md#read-and-edit) for which Bash commands your `Read` and `Edit` deny rules cover.

259When Claude views a file this way, Claude Code also loads any [subdirectory `CLAUDE.md`](https://code.claude.com/docs/en/memory#how-claude-md-files-load) and [path-scoped rules](https://code.claude.com/docs/en/memory.md#path-specific-rules) that apply to that file. See [Read and Edit permission rules](https://code.claude.com/docs/en/permissions.md#read-and-edit) for which Bash commands your `Read` and `Edit` deny rules cover.

260260

261261### Non-UTF-8 files

262262

263263Claude can't use [NotebookEdit](#notebookedit-tool-behavior) on a file that isn't valid UTF-8. The same goes for Edit, unless the file starts with a little-endian UTF-16 byte-order mark. When Claude tries, the tool refuses the change and leaves the file untouched. Refused files include non-ASCII text saved in a legacy encoding such as Windows-1252 or Shift-JIS, binary files, and UTF-8 with an invalid byte sequence.

264264

265The tools refuse because they save the whole file back as UTF-8, which would replace every byte they can't decode with the replacement character `U+FFFD`. Instead, the [error Claude receives](/docs/en/errors.md#file-is-not-valid-utf-8) tells it to make the change with a shell command that keeps the file's encoding, or to ask you about converting it to UTF-8 first.

265The tools refuse because they save the whole file back as UTF-8, which would replace every byte they can't decode with the replacement character `U+FFFD`. Instead, the [error Claude receives](https://code.claude.com/docs/en/errors.md#file-is-not-valid-utf-8) tells it to make the change with a shell command that keeps the file's encoding, or to ask you about converting it to UTF-8 first.

266266

267267Claude can still replace such a file with Write, unless the new content contains `U+FFFD`, the character Read shows Claude in place of bytes it can't decode. That guard stops Claude from writing back the garbled text it read. When Write does replace the file, it saves the new content as UTF-8, so the file's original encoding is lost.

268268

from line 277

277277

278278After Claude ends an interactive session, the session locks. New prompts and most commands return `Claude ended this conversation. Start a new session (or /clear) to continue.`, and only `/clear`, `/resume`, `/help`, `/exit`, and `/feedback` still run. Claude Code records the end in the session's transcript, so resuming an ended session restores the lock; the session's history isn't deleted.

279279

280Resuming an ended session in [non-interactive mode](/docs/en/headless.md) with the `-p` flag errors and exits with code 1, so a script doesn't read the ended run as a success.

280Resuming an ended session in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag errors and exits with code 1, so a script doesn't read the ended run as a success.

281281

282The tool never prompts for permission, and [PreToolUse hooks](/docs/en/hooks.md#pretooluse) don't run for it. While any other tool remains, you can't block it either: [deny and ask rules](/docs/en/permissions.md#tool-specific-permission-rules) naming `EndConversation` have no effect, and neither `--disallowedTools` nor a `--tools` list can remove it. The exemption is deliberate: the tool does nothing except end the conversation, never reading or modifying files or data, and a safeguard of this kind holds only if the session it applies to can't turn it off. When your deny rules remove every other tool and also match `EndConversation`, as `"*"` does, Claude Code removes it too rather than leaving it as the only tool, unless an allow rule names `EndConversation` explicitly. A deny list that removes every other tool without matching `EndConversation` leaves it in place.

282The tool never prompts for permission, and [PreToolUse hooks](https://code.claude.com/docs/en/hooks.md#pretooluse) don't run for it. While any other tool remains, you can't block it either: [deny and ask rules](https://code.claude.com/docs/en/permissions.md#tool-specific-permission-rules) naming `EndConversation` have no effect, and neither `--disallowedTools` nor a `--tools` list can remove it. The exemption is deliberate: the tool does nothing except end the conversation, never reading or modifying files or data, and a safeguard of this kind holds only if the session it applies to can't turn it off. When your deny rules remove every other tool and also match `EndConversation`, as `"*"` does, Claude Code removes it too rather than leaving it as the only tool, unless an allow rule names `EndConversation` explicitly. A deny list that removes every other tool without matching `EndConversation` leaves it in place.

283283

284[Subagents](/docs/en/sub-agents.md) never get the tool. Background tasks that share the main conversation's tool list see it, but calling it there ends nothing.

284[Subagents](https://code.claude.com/docs/en/sub-agents.md) never get the tool. Background tasks that share the main conversation's tool list see it, but calling it there ends nothing.

285285

286286The tool appears only when all of the following are true:

287287

288288* **Model**: the session's model is Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, or a later version of one of those families.

289* **Surface**: an interactive terminal session, including a `claude` session in an IDE's integrated terminal, which is how the [JetBrains plugin](/docs/en/jetbrains.md) runs it. Other surfaces don't include the tool, such as:

289* **Surface**: an interactive terminal session, including a `claude` session in an IDE's integrated terminal, which is how the [JetBrains plugin](https://code.claude.com/docs/en/jetbrains.md) runs it. Other surfaces don't include the tool, such as:

290290 * non-interactive `-p` runs

291 * sessions through the [Agent SDK](/docs/en/agent-sdk/overview.md) TypeScript and Python packages

292 * the [VS Code extension](/docs/en/vs-code.md) panel, which bundles its own CLI

293 * [GitHub Actions](/docs/en/github-actions.md)

294 * [cloud sessions](/docs/en/claude-code-on-the-web.md)

295* **Startup mode**: not a [`--bare`](/docs/en/headless#start-faster-with-bare-mode) session. Bare mode loads only shell and file tools, so the tool is never registered there.

296* **Provider**: not available on [Amazon Bedrock](/docs/en/amazon-bedrock.md), [Claude Platform on AWS](/docs/en/claude-platform-on-aws.md), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai.md), or [Microsoft Foundry](/docs/en/microsoft-foundry.md), or on sessions signed in through a [cloud gateway](/docs/en/claude-apps-gateway).

291 * sessions through the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) TypeScript and Python packages

292 * the [VS Code extension](https://code.claude.com/docs/en/vs-code.md) panel, which bundles its own CLI

293 * [GitHub Actions](https://code.claude.com/docs/en/github-actions.md)

294 * [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md)

295* **Startup mode**: not a [`--bare`](https://code.claude.com/docs/en/headless#start-faster-with-bare-mode) session. Bare mode loads only shell and file tools, so the tool is never registered there.

296* **Provider**: not available on [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md), or on sessions signed in through a [cloud gateway](https://code.claude.com/docs/en/claude-apps-gateway).

297297

298298## Glob tool behavior

299299

from line 301

301301

302302On macOS, Linux, and WSL, you get the Glob and Grep tools back in these cases:

303303

304* You name `Glob` or `Grep` in [`--tools` or `--allowedTools`](/docs/en/cli-reference#cli-flags) when you start the session, or in the equivalent [Agent SDK](/docs/en/agent-sdk/overview.md) options. With `--tools` you get the ones you list, and naming either tool in `--allowedTools` restores both. An allow rule in a settings file doesn't have this effect.

305* A permissions [deny rule](/docs/en/permissions.md#match-all-uses-of-a-tool), the `--disallowedTools` flag, or [`--restricted`](/docs/en/cli-reference#cli-flags) removes `Bash` from the session.

306* A [subagent](/docs/en/sub-agents.md#available-tools) lists `Glob` or `Grep` in its `tools` field and leaves out `Bash`. The listed tools come back for that subagent only, or for the whole session when it runs as the main session agent through [`--agent`](/docs/en/sub-agents#invoke-subagents-explicitly) or the `agent` setting.

304* You name `Glob` or `Grep` in [`--tools` or `--allowedTools`](https://code.claude.com/docs/en/cli-reference#cli-flags) when you start the session, or in the equivalent [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) options. With `--tools` you get the ones you list, and naming either tool in `--allowedTools` restores both. An allow rule in a settings file doesn't have this effect.

305* A permissions [deny rule](https://code.claude.com/docs/en/permissions.md#match-all-uses-of-a-tool), the `--disallowedTools` flag, or [`--restricted`](https://code.claude.com/docs/en/cli-reference#cli-flags) removes `Bash` from the session.

306* A [subagent](https://code.claude.com/docs/en/sub-agents.md#available-tools) lists `Glob` or `Grep` in its `tools` field and leaves out `Bash`. The listed tools come back for that subagent only, or for the whole session when it runs as the main session agent through [`--agent`](https://code.claude.com/docs/en/sub-agents#invoke-subagents-explicitly) or the `agent` setting.

307307

308308Glob supports standard glob syntax including `**` for recursive directory matching:

309309

from line 315

315315

316316Glob doesn't respect `.gitignore` by default, so it finds gitignored files alongside tracked ones. This differs from [Grep](#grep-tool-behavior), which skips gitignored files. To make Glob respect `.gitignore`, set `CLAUDE_CODE_GLOB_NO_IGNORE=false` before launching Claude Code.

317317

318Claude Code decides permission for a Glob call before it checks whether the search directory exists. It still runs the read-permission check for a missing `path` outside the [working directories](/docs/en/permissions.md#working-directories), so a permission prompt for a path doesn't mean the path exists.

318Claude Code decides permission for a Glob call before it checks whether the search directory exists. It still runs the read-permission check for a missing `path` outside the [working directories](https://code.claude.com/docs/en/permissions.md#working-directories), so a permission prompt for a path doesn't mean the path exists.

319319

320320A `pattern` or `path` value that contains a null byte returns an error asking Claude to remove it.

321321

from line 337

337337

338338Grep respects `.gitignore`, so gitignored files are skipped. To search a gitignored file, Claude passes its path directly.

339339

340Claude Code decides permission for a Grep call before it checks whether the search `path` exists. It still runs the read-permission check for a missing `path` outside the [working directories](/docs/en/permissions.md#working-directories), so a permission prompt for a path doesn't mean the path exists.

340Claude Code decides permission for a Grep call before it checks whether the search `path` exists. It still runs the read-permission check for a missing `path` outside the [working directories](https://code.claude.com/docs/en/permissions.md#working-directories), so a permission prompt for a path doesn't mean the path exists.

341341

342342## LSP tool behavior

343343

from line 351

351351* Find implementations of an interface

352352* Trace call hierarchies

353353

354Claude Code keeps the tool inactive until you install a [code intelligence plugin](/docs/en/plugins/code-intelligence.md) for your language. In [cloud sessions](/docs/en/claude-code-on-the-web.md), Claude Code doesn't start plugin language servers, so the LSP tool stays inactive there. Claude Code takes the language server's configuration from the plugin, and you install the server binary yourself.

354Claude Code keeps the tool inactive until you install a [code intelligence plugin](https://code.claude.com/docs/en/plugins/code-intelligence.md) for your language. In [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md), Claude Code doesn't start plugin language servers, so the LSP tool stays inactive there. Claude Code takes the language server's configuration from the plugin, and you install the server binary yourself.

355355

356356Claude Code returns an error result for each LSP call on a file whose language server it can't start.

357357

from line 369

369369

370370You keep working in the same session and Claude interjects when an event arrives.

371371

372Every watch Claude starts has a deadline: 5 minutes by default, at most 30 minutes, and at most 10 minutes in a [non-interactive](/docs/en/headless.md) run given a single prompt with `-p`.

372Every watch Claude starts has a deadline: 5 minutes by default, at most 30 minutes, and at most 10 minutes in a [non-interactive](https://code.claude.com/docs/en/headless.md) run given a single prompt with `-p`.

373373

374374At the deadline the watch ends. Claude gets one notice, so it can start the watch again if it's still needed.

375375

376Stop a monitor by asking Claude to cancel it or by ending the session. When you stop a [subagent](/docs/en/sub-agents.md) that started monitors, for example from `/tasks`, those monitors stop with it.

376Stop a monitor by asking Claude to cancel it or by ending the session. When you stop a [subagent](https://code.claude.com/docs/en/sub-agents.md) that started monitors, for example from `/tasks`, those monitors stop with it.

377377

378When Monitor runs a command, it uses the same [permission rules as Bash](/docs/en/permissions.md#tool-specific-permission-rules), so `allow` and `deny` patterns you have set for Bash apply here too. While [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) is active, Claude Code sets aside allow rules that name `Monitor` itself, along with the other [broad allow rules it drops](/docs/en/permission-modes.md#how-the-classifier-evaluates-actions), so the classifier reviews Monitor commands the same way it reviews Bash commands.

378When Monitor runs a command, it uses the same [permission rules as Bash](https://code.claude.com/docs/en/permissions.md#tool-specific-permission-rules), so `allow` and `deny` patterns you have set for Bash apply here too. While [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) is active, Claude Code sets aside allow rules that name `Monitor` itself, along with the other [broad allow rules it drops](https://code.claude.com/docs/en/permission-modes.md#how-the-classifier-evaluates-actions), so the classifier reviews Monitor commands the same way it reviews Bash commands.

379379

380380The [WebSocket source](#websocket-source) has its own approval prompt, which the classifier also decides in auto mode.

381381

382The tool is not available on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. It is also not available when `DISABLE_TELEMETRY` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set. On Windows, the tool is available only when [Git Bash](/docs/en/setup.md#set-up-on-windows) is installed.

383383

384Plugins can declare monitors that start automatically when the plugin is active, instead of asking Claude to start them. See [plugin monitors](/docs/en/plugins/components.md#monitors).

384Plugins can declare monitors that start automatically when the plugin is active, instead of asking Claude to start them. See [plugin monitors](https://code.claude.com/docs/en/plugins/components.md#monitors).

385385

386386### WebSocket source

387387

from line 401

401401

402402The `timeout_ms` deadline applies to a WebSocket watch too: the watch ends at the deadline, and `TaskStop` cancels it early.

403403

404Opening a WebSocket prompts for approval; in [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) the classifier decides instead. The prompt doesn't offer an option to skip future prompts for the same host.

404Opening a WebSocket prompts for approval; in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) the classifier decides instead. The prompt doesn't offer an option to skip future prompts for the same host.

405405

406Claude Code denies URLs that point at a private, link-local, or cloud-metadata address, including hostnames that resolve to one. It also denies hosts in `sandbox.network.deniedDomains`, and when [`allowManagedDomainsOnly`](/docs/en/settings-reference#sandbox-network-allowmanageddomainsonly) is set in managed settings, any host outside the managed allowlist.

406Claude Code denies URLs that point at a private, link-local, or cloud-metadata address, including hostnames that resolve to one. It also denies hosts in `sandbox.network.deniedDomains`, and when [`allowManagedDomainsOnly`](https://code.claude.com/docs/en/settings-reference#sandbox-network-allowmanageddomainsonly) is set in managed settings, any host outside the managed allowlist.

407407

408408## NotebookEdit tool behavior

409409

from line 427

427427* **Windows with Git Bash installed**: the tool is on by default for claude.ai and Console accounts; set `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` to enable it in Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry sessions, or `0` to turn it off.

428428* **Linux, macOS, and WSL**: the tool is opt-in.

429429

430Your [PreToolUse hooks](/docs/en/hooks.md#powershell) receive the tool's command string in `tool_input.command`, with the same fields as the Bash tool.

430Your [PreToolUse hooks](https://code.claude.com/docs/en/hooks.md#powershell) receive the tool's command string in `tool_input.command`, with the same fields as the Bash tool.

431431

432Match `Bash|PowerShell` in hooks that inspect shell commands; the [PowerShell hook input section](/docs/en/hooks.md#powershell) explains why matching `Bash` alone is not enough.

432Match `Bash|PowerShell` in hooks that inspect shell commands; the [PowerShell hook input section](https://code.claude.com/docs/en/hooks.md#powershell) explains why matching `Bash` alone is not enough.

433433

434434### Enable the PowerShell tool

435435

from line 451

451451

452452### Bash deny rules also turn off the PowerShell tool

453453

454On Windows with Git Bash installed, denying Bash also turns the PowerShell tool off for the session. This applies to scoped rules such as `Bash(git push *)` as well as a bare `Bash`, and to rules from one of your settings files or `--disallowedTools`. Claude Code does this because a `Bash` rule doesn't restrict the PowerShell tool, which has [its own permission rules](/docs/en/permissions.md#powershell). With PowerShell left on, Claude could run there what your rule denies in Bash.

454On Windows with Git Bash installed, denying Bash also turns the PowerShell tool off for the session. This applies to scoped rules such as `Bash(git push *)` as well as a bare `Bash`, and to rules from one of your settings files or `--disallowedTools`. Claude Code does this because a `Bash` rule doesn't restrict the PowerShell tool, which has [its own permission rules](https://code.claude.com/docs/en/permissions.md#powershell). With PowerShell left on, Claude could run there what your rule denies in Bash.

455455

456456To keep the PowerShell tool on alongside a Bash deny rule, do either of these:

457457

458458* Set `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` in your environment or in the `env` block of a settings file, as shown in [Enable the PowerShell tool](#enable-the-powershell-tool).

459* Add a scoped [`PowerShell` permission rule](/docs/en/permissions#powershell) to a settings file, such as a `PowerShell(git push *)` deny rule.

459* Add a scoped [`PowerShell` permission rule](https://code.claude.com/docs/en/permissions#powershell) to a settings file, such as a `PowerShell(git push *)` deny rule.

460460

461461Without one of these, a scoped Bash deny rule leaves the Bash tool available, and Claude Code turns PowerShell off without a warning. A rule that removes the whole Bash tool leaves Claude with no shell tool for the session.

462462

from line 464

464464

465465Three additional settings control where PowerShell is used:

466466

467* `"defaultShell": "powershell"` in [`settings.json`](/docs/en/settings-reference#all-settings): routes interactive `!` commands through PowerShell. Requires the PowerShell tool to be enabled.

468* `"shell": "powershell"` on individual [command hooks](/docs/en/hooks.md#command-hook-fields): runs that hook in PowerShell. Hooks spawn PowerShell directly, so this works regardless of `CLAUDE_CODE_USE_POWERSHELL_TOOL`.

469* `shell: powershell` in [skill frontmatter](/docs/en/skills.md#frontmatter-reference): runs `` !`command` `` blocks in PowerShell. Requires the PowerShell tool to be enabled.

467* `"defaultShell": "powershell"` in [`settings.json`](https://code.claude.com/docs/en/settings-reference#all-settings): routes interactive `!` commands through PowerShell. Requires the PowerShell tool to be enabled.

468* `"shell": "powershell"` on individual [command hooks](https://code.claude.com/docs/en/hooks.md#command-hook-fields): runs that hook in PowerShell. Hooks spawn PowerShell directly, so this works regardless of `CLAUDE_CODE_USE_POWERSHELL_TOOL`.

469* `shell: powershell` in [skill frontmatter](https://code.claude.com/docs/en/skills.md#frontmatter-reference): runs `` !`command` `` blocks in PowerShell. Requires the PowerShell tool to be enabled.

470470

471471PowerShell commands follow the [same main-session working-directory reset behavior](#what-persists-between-commands) as Bash commands, including the `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` environment variable.

472472

473PowerShell commands also receive the variables hooks persist through `CLAUDE_ENV_FILE`, under the conditions in [Persisted variables in PowerShell commands](/docs/en/hooks.md#persisted-variables-in-powershell-commands). Requires Claude Code v2.1.296 or later.

473PowerShell commands also receive the variables hooks persist through `CLAUDE_ENV_FILE`, under the conditions in [Persisted variables in PowerShell commands](https://code.claude.com/docs/en/hooks.md#persisted-variables-in-powershell-commands). Requires Claude Code v2.1.296 or later.

474474

475475### Exit code 1 from searches and `git diff` in PowerShell

476476

477477If a `grep` or `rg` search that matches nothing shows `Error: Exit code 1` when Claude runs it in the PowerShell tool, the search didn't fail. You don't need to do anything. The error can appear when the search is part of a longer command. For example, when `rg` exits with code 1, `rg foo | Out-Null` shows the error and `rg foo` doesn't.

478478

479The PowerShell tool can count exit code 1 as a normal result from `grep`, `rg`, `egrep`, `fgrep`, `findstr`, `git grep`, and `git diff`. The searches use exit code 1 to report no matches. From `git diff`, exit code 1 means the files differ. A command that shows the error when Claude runs it [counts as failed](/docs/en/skills.md#when-an-injected-command-fails) in a skill with `shell: powershell`.

479The PowerShell tool can count exit code 1 as a normal result from `grep`, `rg`, `egrep`, `fgrep`, `findstr`, `git grep`, and `git diff`. The searches use exit code 1 to report no matches. From `git diff`, exit code 1 means the files differ. A command that shows the error when Claude runs it [counts as failed](https://code.claude.com/docs/en/skills.md#when-an-injected-command-fails) in a skill with `shell: powershell`.

480480

481481### Windows encoding and exit codes

482482

from line 506

506506

507507 If Claude misses fine pixel-level detail in a large image, ask it to crop the region you care about, such as with ImageMagick via Bash, and then read the crop.

508508

509 Read refuses an image file larger than 128 MB with an error that tells Claude to resize the image or export a smaller copy, then read that copy. If Claude stops at the error instead of doing so, see [File is too large to read as an image](/docs/en/errors.md#file-is-too-large-to-read-as-an-image).

509 Read refuses an image file larger than 128 MB with an error that tells Claude to resize the image or export a smaller copy, then read that copy. If Claude stops at the error instead of doing so, see [File is too large to read as an image](https://code.claude.com/docs/en/errors.md#file-is-too-large-to-read-as-an-image).

510510* **PDFs**: Claude reads short `.pdf` files whole. For PDFs longer than 10 pages, it reads in ranges with a `pages` parameter, such as `"1-5"`, up to 20 pages at a time. Page-range reads render pages with `pdftoppm` from poppler-utils, so install it with `brew install poppler` on macOS or `apt-get install poppler-utils` on Debian and Ubuntu. On Windows and other platforms, install a poppler build that puts `pdftoppm` on your `PATH`. Without it, a page-range read fails with `pdftoppm is not installed`.

511511* **Jupyter notebooks**: `.ipynb` files return all cells with their outputs, including code, markdown, and visualizations. A notebook whose cells come to more than 256 KB, or more than the [token limit](#large-files), returns an error instead. Claude Code refuses to read a notebook file over 100 MB; the error tells Claude how to read a portion of the notebook instead, such as a slice of cells, with a shell command.

512512

513513Read only reads files, not directories. Claude lists directory contents with a shell command such as `ls`.

514514

515Read refuses a file whose extension it treats as binary, such as `.xlsx`, `.parquet`, `.heic`, or `.zip`. Claude keeps working after a refusal: the error suggests a skill for that file type if one is available, or else a shell command or script that reads the format. If you [`@`-mention](/docs/en/common-workflows#reference-files-and-directories) a file that Read refuses, Claude receives the file's path but not its contents.

515Read refuses a file whose extension it treats as binary, such as `.xlsx`, `.parquet`, `.heic`, or `.zip`. Claude keeps working after a refusal: the error suggests a skill for that file type if one is available, or else a shell command or script that reads the format. If you [`@`-mention](https://code.claude.com/docs/en/common-workflows#reference-files-and-directories) a file that Read refuses, Claude receives the file's path but not its contents.

516516

517517### Large files

518518

519Claude can read a text file larger than a single Read call returns. By default one call returns at most 25,000 tokens, or the value you set in [`CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS`](/docs/en/env-vars), and refuses a whole file over 256 KB, so Claude reads a larger file in pages with `offset` and `limit`. On Claude Code v2.1.296 or later it can instead read the whole file, or a long line range, in one call by setting `allow_large: true` when it needs to, for example because you asked for the entire file. That read is sized against the room left in the session's [context window](/docs/en/context-window.md) instead of the default limits. Images, PDFs, and notebooks keep their limits.

519Claude can read a text file larger than a single Read call returns. By default one call returns at most 25,000 tokens, or the value you set in [`CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS`](https://code.claude.com/docs/en/env-vars), and refuses a whole file over 256 KB, so Claude reads a larger file in pages with `offset` and `limit`. On Claude Code v2.1.296 or later it can instead read the whole file, or a long line range, in one call by setting `allow_large: true` when it needs to, for example because you asked for the entire file. That read is sized against the room left in the session's [context window](https://code.claude.com/docs/en/context-window.md) instead of the default limits. Images, PDFs, and notebooks keep their limits.

520520

521521What Claude receives when a read goes over the default limits:

522522

from line 536

536536

537537After Claude queues a draft, you see a card above your prompt with the draft's title. Press `1` to review the draft, press `2` twice to send it as written, or press `0` to dismiss it. A dismissed draft stays in your queue. After you dismiss a card, Claude Code asks whether to turn Claude-drafted feedback off. It stops asking once you've declined twice.

538538

539By default, you see at most three cards in a session; Anthropic can adjust that limit from the server without a release. After the limit, and whenever you set [`feedbackDrafts`](/docs/en/settings-reference#feedbackdrafts) to `quiet`, you see only a count of queued drafts in the prompt footer.

539By default, you see at most three cards in a session; Anthropic can adjust that limit from the server without a release. After the limit, and whenever you set [`feedbackDrafts`](https://code.claude.com/docs/en/settings-reference#feedbackdrafts) to `quiet`, you see only a count of queued drafts in the prompt footer.

540540

541541### Review and edit a draft

542542

from line 550

550550

551551### Send a draft

552552

553When you send a draft, Claude Code submits it the same way as a `/feedback` report, with the same [retention](/docs/en/data-usage.md#feedback-using-the-%2Ffeedback-command), and deletes the draft from your machine. When you send from the card, it shows `✓ Sent`; when you send from the queue, it closes with a receipt ID.

553When you send a draft, Claude Code submits it the same way as a `/feedback` report, with the same [retention](https://code.claude.com/docs/en/data-usage.md#feedback-using-the-%2Ffeedback-command), and deletes the draft from your machine. When you send from the card, it shows `✓ Sent`; when you send from the queue, it closes with a receipt ID.

554554

555555The report carries:

556556

from line 561

561561

562562Claude Code keeps your working directory in the local draft so it can find the transcript, and doesn't send the directory.

563563

564In [organizations with Zero Data Retention](/docs/en/zero-data-retention.md#features-disabled-under-zdr), and in organizations with the [HIPAA configuration](/docs/en/hipaa-setup.md) applied, Claude Code leaves the SendFeedback tool out of your sessions. If a session in an organization with Zero Data Retention still offers the tool, drafts stay on your machine, and sending fails with `Feedback collection is not available for organizations with custom data retention policies.`

564In [organizations with Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md#features-disabled-under-zdr), and in organizations with the [HIPAA configuration](https://code.claude.com/docs/en/hipaa-setup.md) applied, Claude Code leaves the SendFeedback tool out of your sessions. If a session in an organization with Zero Data Retention still offers the tool, drafts stay on your machine, and sending fails with `Feedback collection is not available for organizations with custom data retention policies.`

565565

566566### Discard or keep a draft

567567

568When you discard a draft, Claude Code deletes it from your machine. A draft you leave in the queue expires after 30 days, or after [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) when that's shorter. The queue holds 10 drafts across all your sessions, and when Claude queues an eleventh, Claude Code deletes the oldest. When you run `/exit` with drafts from the session still in the queue, Claude Code asks whether to review them or discard them before exiting.

568When you discard a draft, Claude Code deletes it from your machine. A draft you leave in the queue expires after 30 days, or after [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) when that's shorter. The queue holds 10 drafts across all your sessions, and when Claude queues an eleventh, Claude Code deletes the oldest. When you run `/exit` with drafts from the session still in the queue, Claude Code asks whether to review them or discard them before exiting.

569569

570570### Turn Claude-drafted feedback off

571571

572Set **Claude-drafted feedback** to `off` in `/config`, which writes the [`feedbackDrafts`](/docs/en/settings-reference#feedbackdrafts) setting, or set [`CLAUDE_CODE_SEND_FEEDBACK=0`](/docs/en/env-vars) for one session. With either, Claude can't queue drafts. To keep drafting on without cards, set `feedbackDrafts` to `quiet` instead. Administrators can set `feedbackDrafts` in [managed settings](/docs/en/managed-settings.md), which takes precedence over your own setting.

572Set **Claude-drafted feedback** to `off` in `/config`, which writes the [`feedbackDrafts`](https://code.claude.com/docs/en/settings-reference#feedbackdrafts) setting, or set [`CLAUDE_CODE_SEND_FEEDBACK=0`](https://code.claude.com/docs/en/env-vars) for one session. With either, Claude can't queue drafts. To keep drafting on without cards, set `feedbackDrafts` to `quiet` instead. Administrators can set `feedbackDrafts` in [managed settings](https://code.claude.com/docs/en/managed-settings.md), which takes precedence over your own setting.

573573

574574### Sessions without Claude-drafted feedback

575575

576576Claude Code includes the tool in interactive terminal sessions on your own machine that use the Claude API rather than a cloud provider. It leaves the tool out of:

577577

578* Non-interactive `-p` runs and [Agent SDK](/docs/en/agent-sdk/overview.md) sessions, which have no screen to review the queue on

579* [Cloud sessions](/docs/en/claude-code-on-the-web.md), which can't write to the queue on your machine

580* Sessions on [Amazon Bedrock](/docs/en/amazon-bedrock.md), [Claude Platform on AWS](/docs/en/claude-platform-on-aws.md), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai.md), or [Microsoft Foundry](/docs/en/microsoft-foundry.md)

581* Sessions where you set [`CLAUDE_CODE_SEND_FEEDBACK=0`](/docs/en/env-vars) or [`DISABLE_FEEDBACK_COMMAND=1`](/docs/en/env-vars), set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` to any non-empty value, or turned off [feature-flag fetching](/docs/en/env-vars.md#features-that-need-feature-flag-fetching)

582* Organizations that have turned off product feedback, [organizations with Zero Data Retention](/docs/en/zero-data-retention.md#features-disabled-under-zdr), and organizations with the [HIPAA configuration](/docs/en/hipaa-setup.md) applied

578* Non-interactive `-p` runs and [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) sessions, which have no screen to review the queue on

579* [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md), which can't write to the queue on your machine

580* Sessions on [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md)

581* Sessions where you set [`CLAUDE_CODE_SEND_FEEDBACK=0`](https://code.claude.com/docs/en/env-vars) or [`DISABLE_FEEDBACK_COMMAND=1`](https://code.claude.com/docs/en/env-vars), set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` to any non-empty value, or turned off [feature-flag fetching](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching)

582* Organizations that have turned off product feedback, [organizations with Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md#features-disabled-under-zdr), and organizations with the [HIPAA configuration](https://code.claude.com/docs/en/hipaa-setup.md) applied

583583

584584## Task tool availability

585585

586The task-tracking tools, `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`, and `TodoWrite`, are available by default only on Opus 4.7, Sonnet 4.6, Haiku 4.5, and earlier models. Wherever the tools are available, you get the four Task tools, or `TodoWrite` instead when you set [`CLAUDE_CODE_ENABLE_TASKS=0`](/docs/en/env-vars).

587587

588On every other model, Claude Code leaves the tools out unless you opt in. The same applies to a model ID Claude Code doesn't recognize, such as a custom model name served through an [LLM gateway](/docs/en/llm-gateway). On newer models, Claude keeps track of multi-step work without a written checklist, and the tools' definitions and reminders take up context. Without the tools, Claude adds nothing to the [task list](/docs/en/interactive-mode.md#task-list) while it works.

588On every other model, Claude Code leaves the tools out unless you opt in. The same applies to a model ID Claude Code doesn't recognize, such as a custom model name served through an [LLM gateway](https://code.claude.com/docs/en/llm-gateway). On newer models, Claude keeps track of multi-step work without a written checklist, and the tools' definitions and reminders take up context. Without the tools, Claude adds nothing to the [task list](https://code.claude.com/docs/en/interactive-mode.md#task-list) while it works.

589589

590590If you'd like to use these tools on a model that doesn't have them by default, do one of the following:

591591

592* Export [`CLAUDE_CODE_ENABLE_TODO_TOOLS=1`](/docs/en/env-vars) before you start Claude Code, for example `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude`. Claude Code then provides the same tools on every model and every provider

593* Name one of the tools in [`--allowedTools`](/docs/en/cli-reference#cli-flags), for example `claude --allowedTools TaskCreate`

594* List the tools in [`--tools`](/docs/en/cli-reference#cli-flags), which restricts the session's built-in tools to the ones it names. Include the tools you want alongside the other built-in tools you use

595* In the Agent SDK, the [`allowedTools` and `tools` options](/docs/en/agent-sdk/todo-tracking#model-availability) work the same way as the two flags

592* Export [`CLAUDE_CODE_ENABLE_TODO_TOOLS=1`](https://code.claude.com/docs/en/env-vars) before you start Claude Code, for example `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude`. Claude Code then provides the same tools on every model and every provider

593* Name one of the tools in [`--allowedTools`](https://code.claude.com/docs/en/cli-reference#cli-flags), for example `claude --allowedTools TaskCreate`

594* List the tools in [`--tools`](https://code.claude.com/docs/en/cli-reference#cli-flags), which restricts the session's built-in tools to the ones it names. Include the tools you want alongside the other built-in tools you use

595* In the Agent SDK, the [`allowedTools` and `tools` options](https://code.claude.com/docs/en/agent-sdk/todo-tracking#model-availability) work the same way as the two flags

596596

597In [background sessions](/docs/en/agent-view.md) and in [cloud sessions](/docs/en/claude-code-on-the-web.md), Claude Code provides the same tools on every model, listed or not.

597In [background sessions](https://code.claude.com/docs/en/agent-view.md) and in [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md), Claude Code provides the same tools on every model, listed or not.

598598

599599The default set described here applies in Claude Code v2.1.268 and later.

600600

601601### Task-tracking tools in subagents and agent teams

602602

603A subagent has the task-tracking tools only when your session has them, whatever model the subagent runs. An in-process [agent team](/docs/en/agent-teams.md) teammate has the task-tracking tools when your session does. A [split-pane](/docs/en/agent-teams.md#choose-a-display-mode) teammate is a separate Claude Code process that [inherits](/docs/en/agent-teams.md#permissions) your `--tools` list and deny rules, not `--allowedTools`, so check what you set:

603A subagent has the task-tracking tools only when your session has them, whatever model the subagent runs. An in-process [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate has the task-tracking tools when your session does. A [split-pane](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) teammate is a separate Claude Code process that [inherits](https://code.claude.com/docs/en/agent-teams.md#permissions) your `--tools` list and deny rules, not `--allowedTools`, so check what you set:

604604

605605* **No `--tools` list or deny rule, and `CLAUDE_CODE_ENABLE_TODO_TOOLS` unset for the teammate**: the teammate has the task-tracking tools its own model has by default.

606* **`CLAUDE_CODE_ENABLE_TODO_TOOLS` exported in your shell**: Claude Code passes the teammate a fixed set of environment variables that doesn't include the one you exported. To set it for the teammate too, start your session by running `claude --settings '{"env":{"CLAUDE_CODE_ENABLE_TODO_TOOLS":"1"}}'` in your shell. The teammate also gets your [`--settings`](/docs/en/settings#change-a-setting-for-one-session) value.

606* **`CLAUDE_CODE_ENABLE_TODO_TOOLS` exported in your shell**: Claude Code passes the teammate a fixed set of environment variables that doesn't include the one you exported. To set it for the teammate too, start your session by running `claude --settings '{"env":{"CLAUDE_CODE_ENABLE_TODO_TOOLS":"1"}}'` in your shell. The teammate also gets your [`--settings`](https://code.claude.com/docs/en/settings#change-a-setting-for-one-session) value.

607607* **`--tools` naming the task-tracking tools**: the teammate has them on any model.

608608* **A task-tracking tool missing from `--tools` or named in a deny rule**: the teammate lacks that tool.

609609

610Without the Task tools, an agent coordinates with its team through messages instead of the [shared task list](/docs/en/agent-teams.md#assign-and-claim-tasks).

610Without the Task tools, an agent coordinates with its team through messages instead of the [shared task list](https://code.claude.com/docs/en/agent-teams.md#assign-and-claim-tasks).

611611

612612## WebFetch tool behavior

613613

from line 617

617617

618618A few behaviors shape the response Claude receives:

619619

620* WebFetch refuses `localhost` and any other hostname without a dot, such as a bare intranet name, before making a request. The [error it returns](/docs/en/errors.md#webfetch-cannot-fetch-localhost) tells Claude to reach local servers with `curl` through Bash instead.

620* WebFetch refuses `localhost` and any other hostname without a dot, such as a bare intranet name, before making a request. The [error it returns](https://code.claude.com/docs/en/errors.md#webfetch-cannot-fetch-localhost) tells Claude to reach local servers with `curl` through Bash instead.

621621* HTTP URLs are automatically upgraded to HTTPS.

622622* WebFetch reads up to 100,000 characters of a page's content per call. On Claude Code v2.1.290 or later, the result for a longer page tells Claude how much went unread, so Claude can fetch the next part.

623* WebFetch caches each response for 15 minutes by default, so repeated fetches of the same URL return quickly. On Claude Code v2.1.233 or later, set [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/en/env-vars#variables) to change how long WebFetch keeps each response.

624* A page that hasn't finished downloading within five minutes, including any redirects WebFetch follows, fails with a deadline error. On Claude Code v2.1.268 or later, set [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/en/env-vars#variables) to change the limit, or to `0` to remove it.

623* WebFetch caches each response for 15 minutes by default, so repeated fetches of the same URL return quickly. On Claude Code v2.1.233 or later, set [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](https://code.claude.com/docs/en/env-vars#variables) to change how long WebFetch keeps each response.

624* A page that hasn't finished downloading within five minutes, including any redirects WebFetch follows, fails with a deadline error. On Claude Code v2.1.268 or later, set [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](https://code.claude.com/docs/en/env-vars#variables) to change the limit, or to `0` to remove it.

625625* When a URL redirects to a different host, WebFetch returns a text result that names the original URL and the redirect target instead of following it. Claude then fetches the new URL with a second WebFetch call.

626626* When the extraction step hits an overloaded API, Claude Code retries it with backoff; a fetch that still fails returns an error result.

627627

628In Manual and `acceptEdits` [permission modes](/docs/en/permission-modes.md), WebFetch prompts before fetching, except for domains your [permission rules](/docs/en/permissions.md#manage-permissions) already allow or deny and a built-in set of preapproved documentation domains that fetch without a prompt. Whatever your rules allow, a fetch also passes the [WebFetch domain safety check](/docs/en/data-usage.md#webfetch-domain-safety-check) first; that section covers what the check sends and the setting that skips it. The prompt offers three options:

628In Manual and `acceptEdits` [permission modes](https://code.claude.com/docs/en/permission-modes.md), WebFetch prompts before fetching, except for domains your [permission rules](https://code.claude.com/docs/en/permissions.md#manage-permissions) already allow or deny and a built-in set of preapproved documentation domains that fetch without a prompt. Whatever your rules allow, a fetch also passes the [WebFetch domain safety check](https://code.claude.com/docs/en/data-usage.md#webfetch-domain-safety-check) first; that section covers what the check sends and the setting that skips it. The prompt offers three options:

629629

630630* **Yes**: approves this fetch only. The next WebFetch call prompts again, even for the same domain.

631* **Yes, and don't ask again for `<domain>`**: approves the fetch and saves a `WebFetch(domain:...)` allow rule for that domain to `.claude/settings.local.json` for that repository. See [how saved approvals persist](/docs/en/permissions.md#permission-system). When your organization sets [`allowManagedPermissionRulesOnly`](/docs/en/permissions#managed-only-settings), Claude Code hides this option.

631* **Yes, and don't ask again for `<domain>`**: approves the fetch and saves a `WebFetch(domain:...)` allow rule for that domain to `.claude/settings.local.json` for that repository. See [how saved approvals persist](https://code.claude.com/docs/en/permissions.md#permission-system). When your organization sets [`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/en/permissions#managed-only-settings), Claude Code hides this option.

632632* **No, and tell Claude what to do differently**: rejects the fetch.

633633

634To allow a domain in advance without a prompt, add an allow rule like `WebFetch(domain:example.com)`; `WebFetch(domain:*)` allows every domain. The `auto` and `bypassPermissions` [permission modes](/docs/en/permissions.md#permission-modes) skip the prompt, except for a domain an explicit `ask` rule matches.

634To allow a domain in advance without a prompt, add an allow rule like `WebFetch(domain:example.com)`; `WebFetch(domain:*)` allows every domain. The `auto` and `bypassPermissions` [permission modes](https://code.claude.com/docs/en/permissions.md#permission-modes) skip the prompt, except for a domain an explicit `ask` rule matches.

635635

636636An explicit `WebFetch(domain:...)` rule in `deny`, `ask`, or `allow` takes precedence over the preapproved set, so you can block a preapproved domain or require a prompt for it.

637637

638When the URL is a claude.ai [artifact](/docs/en/artifacts.md) link, Claude Code can also ask for approval to read the artifact itself. For the cases where it asks, see [Read an artifact shared with you](/docs/en/artifacts.md#read-an-artifact-shared-with-you).

638When the URL is a claude.ai [artifact](https://code.claude.com/docs/en/artifacts.md) link, Claude Code can also ask for approval to read the artifact itself. For the cases where it asks, see [Read an artifact shared with you](https://code.claude.com/docs/en/artifacts.md#read-an-artifact-shared-with-you).

639639

640640WebFetch sets a `User-Agent` header beginning with `Claude-User`, and an `Accept` header that prefers Markdown over HTML so servers that support content negotiation can return Markdown directly.

641641

642Sandboxed commands don't inherit WebFetch's built-in set of preapproved documentation domains. To let a sandboxed command reach a domain without a prompt, add the domain to [`allowedDomains`](/docs/en/settings-reference#sandbox-network-alloweddomains) or allow it with a `WebFetch(domain:...)` rule, which the [sandbox also honors](/docs/en/sandboxing.md#network-isolation). WebFetch never reads the sandbox allowlist in return, so adding a domain to a sandbox or organization network allowlist doesn't stop WebFetch from prompting for it.

642Sandboxed commands don't inherit WebFetch's built-in set of preapproved documentation domains. To let a sandboxed command reach a domain without a prompt, add the domain to [`allowedDomains`](https://code.claude.com/docs/en/settings-reference#sandbox-network-alloweddomains) or allow it with a `WebFetch(domain:...)` rule, which the [sandbox also honors](https://code.claude.com/docs/en/sandboxing.md#network-isolation). WebFetch never reads the sandbox allowlist in return, so adding a domain to a sandbox or organization network allowlist doesn't stop WebFetch from prompting for it.

643643

644644### WebFetch availability

645645

646On Claude Code v2.1.285 or later, set [`CLAUDE_CODE_DISABLE_WEB_FETCH`](/docs/en/env-vars#variables) to `1` to turn WebFetch off.

646On Claude Code v2.1.285 or later, set [`CLAUDE_CODE_DISABLE_WEB_FETCH`](https://code.claude.com/docs/en/env-vars#variables) to `1` to turn WebFetch off.

647647

648If you sign in with a Team or Enterprise claude.ai account and don't connect through an [LLM gateway](/docs/en/llm-gateway), WebFetch also depends on your organization's policy, which Claude Code requests from `api.anthropic.com` when a session starts. The same goes for a session whose plan Claude Code can't determine, such as one running under a claude.ai token that another app supplied.

648If you sign in with a Team or Enterprise claude.ai account and don't connect through an [LLM gateway](https://code.claude.com/docs/en/llm-gateway), WebFetch also depends on your organization's policy, which Claude Code requests from `api.anthropic.com` when a session starts. The same goes for a session whose plan Claude Code can't determine, such as one running under a claude.ai token that another app supplied.

649649

650650If WebFetch is missing from a session, run `/status` in the session. If its `Organization policy` line reports that the policy didn't load and names web fetch among the features that wait for it, Claude Code is withholding WebFetch until it can confirm that your organization allows it. Outside a session, `claude doctor` makes its own request and prints the same line. Once a policy that allows WebFetch loads, the tool returns without a restart.

651651

from line 659

659659

660660WebSearch permission rules take no specifier. A bare `WebSearch` entry in `allow` or `deny` is the only form.

661661

662The search backend is not configurable. To search with a different provider, add an [MCP server](/docs/en/mcp.md) that exposes a search tool.

662The search backend is not configurable. To search with a different provider, add an [MCP server](https://code.claude.com/docs/en/mcp.md) that exposes a search tool.

663663

664664> [!NOTE]

665665>

666> WebSearch is available on the Claude API, [Claude Platform on AWS](/docs/en/claude-platform-on-aws.md), and Microsoft Foundry. On Google Cloud's Agent Platform it works with Opus 4, Sonnet 4, Haiku 4.5, and later models. Amazon Bedrock doesn't expose the server-side web search tool.

666> WebSearch is available on the Claude API, [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), and Microsoft Foundry. On Google Cloud's Agent Platform it works with Opus 4, Sonnet 4, Haiku 4.5, and later models. Amazon Bedrock doesn't expose the server-side web search tool.

667667

668668### Session search limit

669669

670An interactive terminal session has a limit of 200 WebSearch calls. Searches from the main conversation and from [subagents](/docs/en/sub-agents.md), such as a parallel research fan-out, count against the same limit.

670An interactive terminal session has a limit of 200 WebSearch calls. Searches from the main conversation and from [subagents](https://code.claude.com/docs/en/sub-agents.md), such as a parallel research fan-out, count against the same limit.

671671

672672While a session is at the limit, searches appear in the conversation as calls that did nothing. Claude gets a notice telling it to continue with the information already gathered, say so in its answer, and, if it needs more searches, ask you to raise the limit.

673673

674674To get more searches, raise the cap, wait for the limit to refill, or start a new conversation:

675675

676* **Raise the cap**: set the [`CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`](/docs/en/env-vars#variables) environment variable to a positive whole number, such as `500`. The cap can be raised but not turned off.

677* **Wait for the refill**: on Claude Code v2.1.290 or later, an interactive terminal session's limit refills at about 100 calls per hour. To change the rate, set [`CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR`](/docs/en/env-vars#variables) to a number of calls per hour, such as `50`.

678* **Start a new conversation**: running [`/clear`](/docs/en/commands#all-commands) at the Claude Code prompt also resets the count. If work that can still spawn subagents survives the clear, such as a running workflow, the count carries over instead.

676* **Raise the cap**: set the [`CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`](https://code.claude.com/docs/en/env-vars#variables) environment variable to a positive whole number, such as `500`. The cap can be raised but not turned off.

677* **Wait for the refill**: on Claude Code v2.1.290 or later, an interactive terminal session's limit refills at about 100 calls per hour. To change the rate, set [`CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR`](https://code.claude.com/docs/en/env-vars#variables) to a number of calls per hour, such as `50`.

678* **Start a new conversation**: running [`/clear`](https://code.claude.com/docs/en/commands#all-commands) at the Claude Code prompt also resets the count. If work that can still spawn subagents survives the clear, such as a running workflow, the count carries over instead.

679679

680In [non-interactive mode](/docs/en/headless.md) with `-p` and in the [Agent SDK](/docs/en/agent-sdk/overview.md), the limit applies per turn, not per session. A turn lasts from a message you send until Claude finishes responding. The limit resets when you send the next message after that or start a new `claude -p` run, even with [`--continue` or `--resume`](/docs/en/headless#continue-conversations). For more searches, raise [`CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`](/docs/en/env-vars#variables) or set a refill rate with [`CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR`](/docs/en/env-vars#variables).

680In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with `-p` and in the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md), the limit applies per turn, not per session. A turn lasts from a message you send until Claude finishes responding. The limit resets when you send the next message after that or start a new `claude -p` run, even with [`--continue` or `--resume`](https://code.claude.com/docs/en/headless#continue-conversations). For more searches, raise [`CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`](https://code.claude.com/docs/en/env-vars#variables) or set a refill rate with [`CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR`](https://code.claude.com/docs/en/env-vars#variables).

681681

682682## Write tool behavior

683683

from line 707

707707

708708> [!NOTE]

709709>

710> The [advisor tool](/docs/en/advisor.md) is a [server tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) that the API runs, rather than a tool that Claude Code implements. It has no name you can reference in permission rules or hook matchers.

710> The [advisor tool](https://code.claude.com/docs/en/advisor.md) is a [server tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) that the API runs, rather than a tool that Claude Code implements. It has no name you can reference in permission rules or hook matchers.

711711

712712## See also

713713

714* [MCP servers](/docs/en/mcp.md): add custom tools by connecting external servers

715* [Permissions](/docs/en/permissions.md): permission system, rule syntax, and tool-specific patterns

716* [Subagents](/docs/en/sub-agents.md): configure tool access for subagents

717* [Hooks](/docs/en/hooks-guide.md): run custom commands before or after tool execution

714* [MCP servers](https://code.claude.com/docs/en/mcp.md): add custom tools by connecting external servers

715* [Permissions](https://code.claude.com/docs/en/permissions.md): permission system, rule syntax, and tool-specific patterns

716* [Subagents](https://code.claude.com/docs/en/sub-agents.md): configure tool access for subagents

717* [Hooks](https://code.claude.com/docs/en/hooks-guide.md): run custom commands before or after tool execution

718718

troubleshoot-install Changed · +36 / -36 lines

from line 2

33> Fix command not found, PATH, permission, network, and authentication errors when installing or signing in to Claude Code.

5If installation fails or you can't sign in, find your error below. For runtime issues after Claude Code is working, see [Troubleshooting](/docs/en/troubleshooting.md). For configuration problems such as settings not applying or hooks not firing, see [Debug your configuration](/docs/en/debug-your-config.md).

5If installation fails or you can't sign in, find your error below. For runtime issues after Claude Code is working, see [Troubleshooting](https://code.claude.com/docs/en/troubleshooting.md). For configuration problems such as settings not applying or hooks not firing, see [Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md).

77## Find your error

from line 54

5454| `unable to get local issuer certificate` | [Configure corporate CA certificates](#tls-or-ssl-connection-errors) |

5555| `OAuth error` or `403 Forbidden` | [Fix authentication](#login-and-authentication) |

5656| `Claude Code access has not been granted for this account` | [Get a role that includes Claude Code](#claude-code-access-has-not-been-granted-for-this-account) |

57| `Unable to connect to Anthropic services` during setup | See [Unable to connect to Anthropic services](/docs/en/errors.md#unable-to-connect-to-anthropic-services) in the Error reference |

57| `Unable to connect to Anthropic services` during setup | See [Unable to connect to Anthropic services](https://code.claude.com/docs/en/errors.md#unable-to-connect-to-anthropic-services) in the Error reference |

5858| `Could not load the default credentials` or `Could not load credentials from any providers` | [Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry credentials](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

5959| `ChainedTokenCredential authentication failed` or `CredentialUnavailableError` | [Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry credentials](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

60| `API Error: 500`, `529 Overloaded`, `429`, or other 4xx and 5xx errors not listed above | See the [Error reference](/docs/en/errors.md) |

60| `API Error: 500`, `529 Overloaded`, `429`, or other 4xx and 5xx errors not listed above | See the [Error reference](https://code.claude.com/docs/en/errors.md) |

6161

6262If your issue isn't listed, work through the diagnostic checks below to narrow down the cause.

6363

6464> [!TIP]

6565>

66> If you'd rather skip the terminal entirely, the [Claude Code Desktop app](/docs/en/desktop-quickstart.md) lets you install and use Claude Code through a graphical interface. Download it for [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) or [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) and start coding without any command-line setup. On Linux, install the app with apt by following the [Linux install instructions](/docs/en/desktop-linux.md).

66> If you'd rather skip the terminal entirely, the [Claude Code Desktop app](https://code.claude.com/docs/en/desktop-quickstart.md) lets you install and use Claude Code through a graphical interface. Download it for [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) or [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) and start coding without any command-line setup. On Linux, install the app with apt by following the [Linux install instructions](https://code.claude.com/docs/en/desktop-linux.md).

6767

6868## Run diagnostic checks

6969

from line 124

124124

125125> [!NOTE]

126126>

127> The [VS Code extension](/docs/en/vs-code.md) does not place `claude` at this location. It bundles a private copy of the CLI inside the extension directory for its own chat panel and does not add it to PATH. If you have only installed the extension, `~/.local/bin/claude` will not exist. Run the [standalone install](/docs/en/setup.md) to use `claude` from a terminal, then continue below.

127> The [VS Code extension](https://code.claude.com/docs/en/vs-code.md) does not place `claude` at this location. It bundles a private copy of the CLI inside the extension directory for its own chat panel and does not add it to PATH. If you have only installed the extension, `~/.local/bin/claude` will not exist. Run the [standalone install](https://code.claude.com/docs/en/setup.md) to use `claude` from a terminal, then continue below.

128128

129129First check that the program is there at all, then check whether its folder is in your PATH. The PATH fix is permanent, so you apply it once. Pick your platform's tab and run its commands there: in your terminal on macOS and Linux, or in PowerShell or Command Prompt on Windows.

130130

from line 136

136136ls -la ~/.local/bin/claude

137137```

138138

139* **`No such file or directory`**: there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).

139* **`No such file or directory`**: there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).

140140* **A listing for the file**: the program is there. Check your PATH next.

141141

142142List your PATH entries and filter for the install folder:

from line 194

194194Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

195195```

196196

197* **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).

197* **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).

198198* **`True`**: the program is there. Check your PATH next.

199199

200200List your PATH entries and filter for the install folder:

from line 231

231231dir "%USERPROFILE%\.local\bin\claude.exe"

232232```

233233

234* **`File Not Found` or `The system cannot find the path specified.`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).

234* **`File Not Found` or `The system cannot find the path specified.`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).

235235* **A listing for `claude.exe`**: the program is there. Check your PATH next.

236236

237237List your PATH entries and filter for the install folder:

from line 270

270270ls -la ~/.local/bin/claude

271271```

272272

273A native install shows a symlink into `~/.local/share/claude/versions/`. A script or a symlink you created yourself at this path is a custom launcher, which [auto-update leaves in place](/docs/en/setup.md#auto-updates).

274274

275275If either `ls` command prints `No such file or directory`, that's not an error. It means nothing is installed at that location, so move on to the next check.

276276

from line 282

282282npm -g ls @anthropic-ai/claude-code 2>/dev/null

283283```

284284

285If `ls -la ~/.local/bin/claude` printed `No such file or directory`, there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](/docs/en/setup.md#install-claude-code). If `~/.local/bin/claude` exists but `which -a claude` didn't list it, the folder isn't in your PATH: see [Verify your PATH](#verify-your-path).

285If `ls -la ~/.local/bin/claude` printed `No such file or directory`, there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If `~/.local/bin/claude` exists but `which -a claude` didn't list it, the folder isn't in your PATH: see [Verify your PATH](#verify-your-path).

286286

287287**Windows PowerShell**

288288

from line 301

301301```

302302

303303* **`True`**: the native install is there. If `where.exe` found nothing, its folder isn't in your PATH: see [Verify your PATH](#verify-your-path).

304* **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](/docs/en/setup.md#install-claude-code).

304* **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code).

305305

306306If you find multiple installations, keep only one. The native install at `~/.local/bin/claude` on macOS/Linux or `%USERPROFILE%\.local\bin\claude.exe` on Windows is recommended. Remove the extras:

307307

from line 348

348348* `~/.local/share/claude/`: each version it downloads

349349* `~/.local/state/claude/`: its lock files

350350* `~/.cache/claude/`: staged downloads

351* [`~/.claude.json`](/docs/en/claude-directory): your global config file, where the installer records the install method

351* [`~/.claude.json`](https://code.claude.com/docs/en/claude-directory): your global config file, where the installer records the install method

352352

353If you set `XDG_DATA_HOME`, `XDG_STATE_HOME`, or `XDG_CACHE_HOME`, the install uses those in place of `~/.local/share`, `~/.local/state`, and `~/.cache`. If you set [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars), the global config file lives under that directory instead of your home directory.

353If you set `XDG_DATA_HOME`, `XDG_STATE_HOME`, or `XDG_CACHE_HOME`, the install uses those in place of `~/.local/share`, `~/.local/state`, and `~/.cache`. If you set [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars), the global config file lives under that directory instead of your home directory.

354354

355355Check whether the directories are writable:

356356

from line 384

384384Get-Command claude | Select-Object Source

385385```

386386

387On Linux, check for missing shared libraries. If `ldd` shows missing libraries, you may need to install system packages. On Alpine Linux and other musl-based distributions, see [Alpine Linux setup](/docs/en/setup.md#alpine-linux-and-musl-based-distributions).

387On Linux, check for missing shared libraries. If `ldd` shows missing libraries, you may need to install system packages. On Alpine Linux and other musl-based distributions, see [Alpine Linux setup](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions).

388388

389389```bash theme={null}

390390ldd "$(command -v claude)" | grep "not found"

from line 457

457457

4584581. **Retry after a few minutes**: the issue is often temporary. Wait and try the original command again.

459459

4602. **Use an alternative install method**: unlike a native install, a Homebrew or WinGet install [doesn't update itself by default](/docs/en/setup.md#auto-updates).

4602. **Use an alternative install method**: unlike a native install, a Homebrew or WinGet install [doesn't update itself by default](https://code.claude.com/docs/en/setup.md#auto-updates).

461461

462462 On macOS, install via Homebrew:

463463

from line 507

507507

508508The `curl ... | bash` command downloads the script and pipes it to Bash for execution. This error, and the related `curl: (23) Failure writing output to destination`, means Bash did not receive the complete script. Exit code 56 indicates the download itself was interrupted, and exit code 23 indicates curl could not write what it received to the pipe, usually because Bash exited early.

509509

510Test that you can reach `downloads.claude.ai` with the check in [Check network connectivity](#check-network-connectivity). If you reached the server, the original failure was likely intermittent; retry the install command. You can also [try an alternative install method](/docs/en/setup.md#install-claude-code).

511511

512512### Homebrew cask unavailable or outdated

513513

from line 518

518518brew install --cask claude-code

519519```

520520

521If Homebrew installs an older Claude Code version than you expect, the same stale index is usually the cause. The `claude-code` cask tracks the stable channel and is typically about one week behind the latest release; for the newest version run `brew install --cask claude-code@latest` instead. See [Configure release channel](/docs/en/setup.md#configure-release-channel) for the difference between the two casks.

521If Homebrew installs an older Claude Code version than you expect, the same stale index is usually the cause. The `claude-code` cask tracks the stable channel and is typically about one week behind the latest release; for the newest version run `brew install --cask claude-code@latest` instead. See [Configure release channel](https://code.claude.com/docs/en/setup.md#configure-release-channel) for the difference between the two casks.

522522

523523### `Cask 'claude-code@latest' is not installed`

524524

from line 626

626626

627627* Run `claude update` again. On an otherwise healthy network, the download usually succeeds on the next run. For the timed-out message, run it again from a faster or less throttled network.

628628* If your network requires a proxy, set `HTTPS_PROXY` before running the installer or `claude update`. See [Check network connectivity](#check-network-connectivity).

629* If a corporate proxy keeps closing the transfer, ask your network team to allow the full download from `downloads.claude.ai`. See [Network access requirements](/docs/en/network-config.md#network-access-requirements).

629* If a corporate proxy keeps closing the transfer, ask your network team to allow the full download from `downloads.claude.ai`. See [Network access requirements](https://code.claude.com/docs/en/network-config.md#network-access-requirements).

630630* Run `claude doctor` from your shell for installation diagnostics

631631

632632### Release verification failed for Claude Code

from line 716

716716 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

717717 ```

7187182. **Call the `.cmd` launcher instead**: `npm.cmd` and `claude.cmd` do the same job, and the policy doesn't cover them.

7193. **Use the [PowerShell installer](/docs/en/setup.md#install-claude-code)** instead of npm. It installs a binary rather than a `.ps1` script.

7193. **Use the [PowerShell installer](https://code.claude.com/docs/en/setup.md#install-claude-code)** instead of npm. It installs a binary rather than a `.ps1` script.

720720

721721### `The process cannot access the file` during Windows install

722722

from line 760

760760Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

761761```

762762

763Installing needs roughly 512 MB of free memory, and running Claude Code needs more. See the [system requirements](/docs/en/setup.md#system-requirements).

763Installing needs roughly 512 MB of free memory, and running Claude Code needs more. See the [system requirements](https://code.claude.com/docs/en/setup.md#system-requirements).

764764

765765**Solutions:**

766766

from line 817

817817

818818### `Raw mode is not supported` during install

819819

820When your organization's [server-managed settings](/docs/en/server-managed-settings.md) include changes that need [security approval](/docs/en/server-managed-settings.md#security-approval-dialogs), Claude Code versions before 2.1.246 try to show the approval dialog during `claude install`. The dialog needs a terminal on stdin. When the installer runs `claude install` from a pipe, as `curl -fsSL https://claude.ai/install.sh | bash` does, stdin is the pipe rather than a terminal, so the install fails with an error containing `Raw mode is not supported`.

820When your organization's [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) include changes that need [security approval](https://code.claude.com/docs/en/server-managed-settings.md#security-approval-dialogs), Claude Code versions before 2.1.246 try to show the approval dialog during `claude install`. The dialog needs a terminal on stdin. When the installer runs `claude install` from a pipe, as `curl -fsSL https://claude.ai/install.sh | bash` does, stdin is the pipe rather than a terminal, so the install fails with an error containing `Raw mode is not supported`.

821821

822Claude Code v2.1.246 and later don't show the dialog during `claude install` or `claude update`. The command runs with the settings you last approved, and Claude Code shows the dialog in your next interactive session. If your organization's startup configuration [waits for the settings fetch](/docs/en/server-managed-settings.md#enforce-fail-closed-startup), such as when it sets `forceRemoteSettingsRefresh`, the dialog still appears during these commands, and an install run from a pipe still fails.

822Claude Code v2.1.246 and later don't show the dialog during `claude install` or `claude update`. The command runs with the settings you last approved, and Claude Code shows the dialog in your next interactive session. If your organization's startup configuration [waits for the settings fetch](https://code.claude.com/docs/en/server-managed-settings.md#enforce-fail-closed-startup), such as when it sets `forceRemoteSettingsRefresh`, the dialog still appears during these commands, and an install run from a pipe still fails.

823823

824824In every other configuration, rerunning the installer gets past this error, because the script runs the latest release's `install` command even when you ask it to install an older version. Rerun the command for your platform:

825825

from line 847

847847ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish

848848```

849849

850Move the directory aside, or update to v2.1.214 or later. Since `claude update` hangs on the affected versions, update by rerunning the [install script](/docs/en/setup.md#install-claude-code) instead.

850Move the directory aside, or update to v2.1.214 or later. Since `claude update` hangs on the affected versions, update by rerunning the [install script](https://code.claude.com/docs/en/setup.md#install-claude-code) instead.

851851

852852### Claude Desktop overrides the `claude` command on Windows

853853

from line 857

857857

858858### Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

859859

860Git for Windows is optional. Claude Code uses the [PowerShell tool](/docs/en/tools-reference.md#powershell-tool) when Git Bash is absent, so this error means neither shell was found.

860Git for Windows is optional. Claude Code uses the [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) when Git Bash is absent, so this error means neither shell was found.

861861

862862**If PowerShell is missing from your PATH**, its default location is `C:\Windows\System32\WindowsPowerShell\v1.0\`. Add that directory to your `PATH`, or install [PowerShell 7](https://aka.ms/powershell), which provides `pwsh`.

863863

from line 870

870870

871871In step 2, Claude Code skips a `git` that sits in the folder you launched Claude Code from, or below it in a path that contains `node_modules` or a virtual-environment folder such as `.venv` or `env`, for example `C:\dev\env\myproject\Git` when you launched from `C:\dev\env\myproject`. This keeps Claude Code from running an executable that a project placed there. If your Git is in a location like that, point `CLAUDE_CODE_GIT_BASH_PATH` at it.

872872

873**To point Claude Code at a specific Git installation**, find it by running `where.exe git` in PowerShell, then set the `bin\bash.exe` path from that installation as `CLAUDE_CODE_GIT_BASH_PATH` in your [settings.json file](/docs/en/settings.md):

874874

875875```json theme={null}

876876{

from line 894

894894

895895If this prints `True`, your operating system is fine. Close the window, open `Windows PowerShell` without the x86 suffix, and run the install command again.

896896

897If this prints `False`, you are on a 32-bit edition of Windows. Claude Code requires a 64-bit operating system. See the [system requirements](/docs/en/setup.md#system-requirements).

897If this prints `False`, you are on a 32-bit edition of Windows. Claude Code requires a 64-bit operating system. See the [system requirements](https://code.claude.com/docs/en/setup.md#system-requirements).

898898

899899### Linux musl or glibc binary mismatch

900900

from line 920

920920 ```bash theme={null}

921921 apk add libgcc libstdc++ ripgrep

922922 ```

923 On Alpine, `ripgrep` is in the community repository. If `apk` reports that the package is missing, see [Alpine Linux setup](/docs/en/setup.md#alpine-linux-and-musl-based-distributions).

923 On Alpine, `ripgrep` is in the community repository. If `apk` reports that the package is missing, see [Alpine Linux setup](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions).

924924

925925### `Illegal instruction`

926926

from line 967

967967

968968Before the shell's message, Claude Code's runtime can print a crash report that includes `panic(main thread): Bus error at address` and `oh no: Bun has crashed. This indicates a bug in Bun, not your code.` When the executable became unreadable, the crash comes from the unreadable file, not from a bug in Bun. The report can also be missing, if the runtime couldn't read the code that prints it either.

969969

970Start a new session to continue. If Claude Code is installed on network storage, follow [Install on network storage](/docs/en/setup.md#install-on-network-storage) so upgrades don't remove a binary that running sessions still need.

970Start a new session to continue. If Claude Code is installed on network storage, follow [Install on network storage](https://code.claude.com/docs/en/setup.md#install-on-network-storage) so upgrades don't remove a binary that running sessions still need.

971971

972972### `Exec format error` on WSL1

973973

from line 991

991991

992992### npm install errors in WSL

993993

994These issues apply if you installed Claude Code with `npm install -g` inside WSL. If you used the [native installer](/docs/en/setup.md), skip this section.

994These issues apply if you installed Claude Code with `npm install -g` inside WSL. If you used the [native installer](https://code.claude.com/docs/en/setup.md), skip this section.

995995

996996**OS or platform detection issues.** If npm reports a platform mismatch during install, WSL is likely picking up the Windows `npm`. Run `npm config set os linux` first, then install with `npm install -g @anthropic-ai/claude-code --force`. Do not use `sudo`.

997997

from line 1054

10541054

10551055* **Optional dependencies are disabled.** Remove `--omit=optional` from your npm install command, `--no-optional` from pnpm, or `--ignore-optional` from yarn, and check that `.npmrc` does not set `optional=false`. Then reinstall. The native binary is delivered only as an optional dependency, so there is no JavaScript fallback if it is skipped, and running `install.cjs` again can't place a binary that was never downloaded.

10561056* **Install scripts are disabled.** `--ignore-scripts` and some pnpm configurations skip the postinstall step but still download the platform package. Run `node node_modules/@anthropic-ai/claude-code/install.cjs` as the message suggests, or reinstall without the flag. If postinstall can't run in your environment at all, `node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs` finds the downloaded package and launches it, at the cost of an extra Node process on each start. If the wrapper prints `Could not find native binary package` instead, the platform package was never downloaded, so fix the optional-dependencies cause above first.

1057* **Unsupported platform.** Prebuilt binaries are published for `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64`, and `win32-arm64`. Claude Code does not ship a binary for other platforms; see the [system requirements](/docs/en/setup.md#system-requirements). On FreeBSD, the installer reports the platform as unsupported. Before v2.1.205, it treated FreeBSD as Linux and downloaded a binary that couldn't run.

1057* **Unsupported platform.** Prebuilt binaries are published for `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64`, and `win32-arm64`. Claude Code does not ship a binary for other platforms; see the [system requirements](https://code.claude.com/docs/en/setup.md#system-requirements). On FreeBSD, the installer reports the platform as unsupported. Before v2.1.205, it treated FreeBSD as Linux and downloaded a binary that couldn't run.

10581058* **Corporate npm mirror is missing the platform packages.** Ensure your registry mirrors all eight `@anthropic-ai/claude-code-*` platform packages in addition to the meta package.

10591059

10601060### npm `ENOTEMPTY` error during update or reinstall

from line 1128

11281128

11291129* **Claude Pro/Max users**: verify your subscription is active at [claude.ai/settings](https://claude.ai/settings)

11301130* **Anthropic Console users**: confirm your account has the "Claude Code" or "Developer" role. Admins assign this on the Console's Members page at [platform.claude.com/settings/members](https://platform.claude.com/settings/members).

1131* **Behind a proxy**: corporate proxies can interfere with API requests. See [network configuration](/docs/en/network-config.md) for proxy setup.

1131* **Behind a proxy**: corporate proxies can interfere with API requests. See [network configuration](https://code.claude.com/docs/en/network-config.md) for proxy setup.

11321132

11331133### Claude Code access has not been granted for this account

11341134

from line 1143

11431143

11441144If you see `API Error: 400 ... "This organization has been disabled"` despite having an active Claude subscription, an `ANTHROPIC_API_KEY` environment variable is overriding your subscription. This commonly happens when an old API key from a previous employer or project is still set in your shell profile.

11451145

1146When `ANTHROPIC_API_KEY` is present and you have approved it, Claude Code uses that key instead of your subscription's OAuth credentials. In non-interactive mode with the `-p` flag, the key is always used when present. See [authentication precedence](/docs/en/authentication.md#authentication-precedence) for the full resolution order.

1146When `ANTHROPIC_API_KEY` is present and you have approved it, Claude Code uses that key instead of your subscription's OAuth credentials. In non-interactive mode with the `-p` flag, the key is always used when present. See [authentication precedence](https://code.claude.com/docs/en/authentication.md#authentication-precedence) for the full resolution order.

11471147

11481148To use your subscription instead, unset the environment variable and remove it from your shell profile:

11491149

from line 1190

11901190

11911191Run `/login` to re-authenticate. If this happens frequently, check that your system clock is accurate, as token validation depends on correct timestamps.

11921192

1193Parallel sessions on one machine share a saved login and coordinate its renewal so that only one process refreshes the token at a time. For what the other sessions do after you sign in again in one of them, see [Not logged in](/docs/en/errors.md#not-logged-in).

11941194

11951195Before v2.1.211, waking the machine from sleep could cause two sessions to renew with the same token, which revoked the saved login and prompted every open session to log in again at once.

11961196

from line 1242

12421242

12431243If credentials work in your terminal but not in the VS Code or JetBrains extension, the IDE process likely didn't inherit your shell environment. Set the provider environment variables in the IDE's own settings, or launch the IDE from a terminal where they're already exported.

12441244

1245See [Amazon Bedrock](/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai.md), or [Microsoft Foundry](/docs/en/microsoft-foundry.md) for full provider setup.

1245See [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md) for full provider setup.

12461246

12471247## Still stuck

12481248

troubleshooting Changed · +38 / -38 lines

from line 6

77| Symptom | Go to |

88| :- | :- |

9| `command not found`, install fails, PATH issues, `EACCES`, TLS errors | [Troubleshoot installation and login](/docs/en/troubleshoot-install.md) |

10| Update or install download fails with `The connection dropped while downloading the update` or `aborted` | [Troubleshoot installation and login](/docs/en/troubleshoot-install.md#the-connection-dropped-while-downloading-the-update) |

11| Update or install fails with `Release verification failed for Claude Code` | [Troubleshoot installation and login](/docs/en/troubleshoot-install.md#release-verification-failed) |

12| Session footer shows `Auto-update failed · Run claude doctor` in red | [Troubleshoot installation and login](/docs/en/troubleshoot-install.md#auto-update-failed) |

13| Login loops, OAuth errors, `403 Forbidden`, "organization disabled", Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry credentials | [Troubleshoot installation and login](/docs/en/troubleshoot-install.md#login-and-authentication) |

14| Settings not applying, hooks not firing, MCP servers not loading | [Debug your configuration](/docs/en/debug-your-config.md) |

15| Session started in auto mode, or Claude edits files and runs commands without asking | [Which mode a session starts in](/docs/en/permission-modes.md#which-mode-a-session-starts-in) |

16| After you update Claude Code or the Agent SDK, tool calls are denied in `claude -p` or SDK runs that don't pass `--permission-mode`, `permissionMode`, or `permission_mode` | [Tool calls denied in `claude -p` and Agent SDK runs](/docs/en/permission-modes#which-mode-a-non-interactive-run-starts-in) |

17| `API Error: 5xx`, `529 Overloaded`, `429`, request validation errors | [Error reference](/docs/en/errors.md) |

18| `model not found` or `you may not have access to it` | [Error reference](/docs/en/errors.md#theres-an-issue-with-the-selected-model) |

19| A command Claude runs fails with `Disk full:`, `Disk quota used up:`, `Nearly out of inodes:`, `The command was not started:`, `Your disk quota is full`, `is full (ENOSPC)`, or `Command output was lost` | [Error reference](/docs/en/errors.md#disk-quota-or-temp-filesystem-is-full) |

20| VS Code extension not connecting or detecting Claude | [VS Code integration](/docs/en/vs-code.md#fix-common-issues) |

21| `Claude Code process exited with code 1` in VS Code or an SDK app | [Error reference](/docs/en/errors.md#claude-code-process-exited-with-code-n) |

22| JetBrains plugin or IDE not detected | [JetBrains integration](/docs/en/jetbrains.md#troubleshooting) |

9| `command not found`, install fails, PATH issues, `EACCES`, TLS errors | [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install.md) |

10| Update or install download fails with `The connection dropped while downloading the update` or `aborted` | [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install.md#the-connection-dropped-while-downloading-the-update) |

11| Update or install fails with `Release verification failed for Claude Code` | [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install.md#release-verification-failed) |

12| Session footer shows `Auto-update failed · Run claude doctor` in red | [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install.md#auto-update-failed) |

13| Login loops, OAuth errors, `403 Forbidden`, "organization disabled", Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry credentials | [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install.md#login-and-authentication) |

14| Settings not applying, hooks not firing, MCP servers not loading | [Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md) |

15| Session started in auto mode, or Claude edits files and runs commands without asking | [Which mode a session starts in](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in) |

16| After you update Claude Code or the Agent SDK, tool calls are denied in `claude -p` or SDK runs that don't pass `--permission-mode`, `permissionMode`, or `permission_mode` | [Tool calls denied in `claude -p` and Agent SDK runs](https://code.claude.com/docs/en/permission-modes#which-mode-a-non-interactive-run-starts-in) |

17| `API Error: 5xx`, `529 Overloaded`, `429`, request validation errors | [Error reference](https://code.claude.com/docs/en/errors.md) |

18| `model not found` or `you may not have access to it` | [Error reference](https://code.claude.com/docs/en/errors.md#theres-an-issue-with-the-selected-model) |

19| A command Claude runs fails with `Disk full:`, `Disk quota used up:`, `Nearly out of inodes:`, `The command was not started:`, `Your disk quota is full`, `is full (ENOSPC)`, or `Command output was lost` | [Error reference](https://code.claude.com/docs/en/errors.md#disk-quota-or-temp-filesystem-is-full) |

20| VS Code extension not connecting or detecting Claude | [VS Code integration](https://code.claude.com/docs/en/vs-code.md#fix-common-issues) |

21| `Claude Code process exited with code 1` in VS Code or an SDK app | [Error reference](https://code.claude.com/docs/en/errors.md#claude-code-process-exited-with-code-n) |

22| JetBrains plugin or IDE not detected | [JetBrains integration](https://code.claude.com/docs/en/jetbrains.md#troubleshooting) |

2323| High CPU or memory, slow responses, hangs, search not finding files | [Performance and stability](#performance-and-stability) below |

2424

2525If you're not sure which applies, run `/doctor` inside Claude Code for an automated check of your installation, settings, extensions, and context usage; it proposes fixes it can apply after you confirm. If `claude` won't start at all, run `claude doctor` from your shell instead. Run `/mcp` to check MCP server status.

from line 35

35351. Use `/compact` regularly to reduce context size. If it returns `Not enough messages to compact.`, the conversation has too few turns to summarize; that can happen even with a full context when a single large paste filled it

36362. Close and restart Claude Code between major tasks

37373. Consider adding large build directories to your `.gitignore` file

384. Restart with [`claude --safe-mode`](/docs/en/cli-reference#cli-flags) to check whether a plugin, MCP server, or hook is the source. It disables all customizations for the session; if usage drops, see [Debug your configuration](/docs/en/debug-your-config.md#test-against-a-clean-configuration) to find which one

384. Restart with [`claude --safe-mode`](https://code.claude.com/docs/en/cli-reference#cli-flags) to check whether a plugin, MCP server, or hook is the source. It disables all customizations for the session; if usage drops, see [Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md#test-against-a-clean-configuration) to find which one

3939

40If a session's heap memory passes 2.5GB, a critical memory usage warning appears. To free the memory, restart Claude Code and run [`claude --continue`](/docs/en/cli-reference#cli-flags) to resume the conversation in a fresh process.

40If a session's heap memory passes 2.5GB, a critical memory usage warning appears. To free the memory, restart Claude Code and run [`claude --continue`](https://code.claude.com/docs/en/cli-reference#cli-flags) to resume the conversation in a fresh process.

4141

42Outside [fullscreen rendering](/docs/en/fullscreen.md), running `/compact` frees memory too. The warning disappears once memory use drops back below 2.5GB.

42Outside [fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md), running `/compact` frees memory too. The warning disappears once memory use drops back below 2.5GB.

4343

44If memory usage stays high after these steps, run `/heapdump` to write two files to `~/Desktop`: a JavaScript heap snapshot named `<session-id>.heapsnapshot` and a memory breakdown named `<session-id>-diagnostics.json`. Claude Code [hides the command from the command menu](/docs/en/commands.md#how-the-command-menu-matches-what-you-type); type it in full. On Linux without a Desktop folder, the files are written to your home directory.

44If memory usage stays high after these steps, run `/heapdump` to write two files to `~/Desktop`: a JavaScript heap snapshot named `<session-id>.heapsnapshot` and a memory breakdown named `<session-id>-diagnostics.json`. Claude Code [hides the command from the command menu](https://code.claude.com/docs/en/commands.md#how-the-command-menu-matches-what-you-type); type it in full. On Linux without a Desktop folder, the files are written to your home directory.

4545

4646> [!WARNING]

4747>

from line 58

5858

5959### Large tables are cut off in the terminal

6060

61A Markdown table with more than 200 rows renders its first 200 rows followed by a `… N more rows not shown` line. Only the display is capped: the full table stays in the conversation, and [`/copy`](/docs/en/commands) copies every row. For a table too large to read in the terminal, ask Claude to write it to a file instead. Before v2.1.208, Claude Code rendered every row, so resuming a session that contained a very large table could stall while it re-rendered.

61A Markdown table with more than 200 rows renders its first 200 rows followed by a `… N more rows not shown` line. Only the display is capped: the full table stays in the conversation, and [`/copy`](https://code.claude.com/docs/en/commands) copies every row. For a table too large to read in the terminal, ask Claude to write it to a file instead. Before v2.1.208, Claude Code rendered every row, so resuming a session that contained a very large table could stall while it re-rendered.

6262

6363### Auto-compaction stops with a thrashing error

6464

from line 68

6868

69691. Ask Claude to read the oversized file in smaller chunks, such as a specific line range or function, instead of the whole file

70702. Run `/compact` with a focus that drops the large output, for example `/compact keep only the plan and the diff`

713. Move the large-file work to a [subagent](/docs/en/sub-agents.md) so it runs in a separate context window

713. Move the large-file work to a [subagent](https://code.claude.com/docs/en/sub-agents.md) so it runs in a separate context window

72724. Run `/clear` if the earlier conversation is no longer needed

7373

74If the error comes back after a `/clear`, run [`/context`](/docs/en/debug-your-config) and compare the `Messages` row with the rows above it:

74If the error comes back after a `/clear`, run [`/context`](https://code.claude.com/docs/en/debug-your-config) and compare the `Messages` row with the rows above it:

7575

7676* **`Messages` is the largest row**: a file or tool output in the new conversation is refilling the window, so work through steps 1 to 3 again

77* **The other rows together are larger**: what loads at session start leaves too little room to work in, so [trim what loads at startup](/docs/en/errors.md#prompt-is-too-long)

77* **The other rows together are larger**: what loads at session start leaves too little room to work in, so [trim what loads at startup](https://code.claude.com/docs/en/errors.md#prompt-is-too-long)

7878

7979### Command hangs or freezes

8080

from line 87

8787

8888### Garbled or corrupted text in an editor's integrated terminal

8989

90If characters render as boxes, smears, or the wrong glyphs when running Claude Code in the VS Code, Cursor, or Devin Desktop integrated terminal, the terminal's GPU renderer is likely the cause. Run `/terminal-setup` inside Claude Code to set `terminal.integrated.gpuAcceleration` to `"off"`, or set it manually in your editor settings and reload the window. See [Terminal configuration](/docs/en/terminal-config.md) for the other settings `/terminal-setup` writes.

90If characters render as boxes, smears, or the wrong glyphs when running Claude Code in the VS Code, Cursor, or Devin Desktop integrated terminal, the terminal's GPU renderer is likely the cause. Run `/terminal-setup` inside Claude Code to set `terminal.integrated.gpuAcceleration` to `"off"`, or set it manually in your editor settings and reload the window. See [Terminal configuration](https://code.claude.com/docs/en/terminal-config.md) for the other settings `/terminal-setup` writes.

9191

9292### Stray `>0q` at startup or `>4m` after exit

9393

94These characters, printed by terminals built on a VTE library older than 0.53, are the ends of two Claude Code control sequences. To stop the text, [update Claude Code](/docs/en/setup.md#update-claude-code) to v2.1.301 or later, which skips both sequences when it identifies such a terminal.

94These characters, printed by terminals built on a VTE library older than 0.53, are the ends of two Claude Code control sequences. To stop the text, [update Claude Code](https://code.claude.com/docs/en/setup.md#update-claude-code) to v2.1.301 or later, which skips both sequences when it identifies such a terminal.

9595

9696If the text remains, print the VTE version from the terminal's shell:

9797

from line 103

103103

104104### Mouse wheel scrolls one line at a time in fullscreen rendering

105105

106In [fullscreen rendering](/docs/en/fullscreen.md), Claude Code scrolls the conversation itself rather than leaving it to your terminal. If each wheel notch moves fewer lines than you want, run `/scroll-speed` to raise the number of lines per notch and save it, or set the `CLAUDE_CODE_SCROLL_SPEED` environment variable, except in the JetBrains IDE terminal, where Claude Code applies its own scroll handling and neither takes effect. See [Mouse wheel scrolling](/docs/en/fullscreen.md#mouse-wheel-scrolling) for the values each accepts.

106In [fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md), Claude Code scrolls the conversation itself rather than leaving it to your terminal. If each wheel notch moves fewer lines than you want, run `/scroll-speed` to raise the number of lines per notch and save it, or set the `CLAUDE_CODE_SCROLL_SPEED` environment variable, except in the JetBrains IDE terminal, where Claude Code applies its own scroll handling and neither takes effect. See [Mouse wheel scrolling](https://code.claude.com/docs/en/fullscreen.md#mouse-wheel-scrolling) for the values each accepts.

107107

108108To move faster without changing the speed, press `PgUp` and `PgDn` to scroll half a screen at a time. To use your terminal's native scrollback instead, run `/tui default` to switch to the classic renderer.

109109

110110### Clipboard commands such as `pbcopy` fail inside the sandbox

111111

112When [sandboxing](/docs/en/sandboxing.md) is on, clipboard utilities such as `pbcopy`, `xclip`, and `wl-copy` can fail to reach the system clipboard from inside a sandboxed Bash command, leaving your clipboard unchanged after Claude pipes text to them.

112When [sandboxing](https://code.claude.com/docs/en/sandboxing.md) is on, clipboard utilities such as `pbcopy`, `xclip`, and `wl-copy` can fail to reach the system clipboard from inside a sandboxed Bash command, leaving your clipboard unchanged after Claude pipes text to them.

113113

114To put Claude's output on your clipboard, ask Claude to print the content in its response, then run [`/copy`](/docs/en/commands). `/copy` writes to the clipboard from the Claude Code process itself rather than from a sandboxed command, so sandboxing doesn't block it. It can copy a single code block instead of the whole response, and it also writes what it copied to a file and prints the path, which gives you a fallback when the clipboard write doesn't reach your terminal, for example over SSH.

114To put Claude's output on your clipboard, ask Claude to print the content in its response, then run [`/copy`](https://code.claude.com/docs/en/commands). `/copy` writes to the clipboard from the Claude Code process itself rather than from a sandboxed command, so sandboxing doesn't block it. It can copy a single code block instead of the whole response, and it also writes what it copied to a file and prints the path, which gives you a fallback when the clipboard write doesn't reach your terminal, for example over SSH.

115115

116When Claude pipes text to one of these tools, adding `pbcopy *`, `wl-copy *`, or `xclip *` to [`excludedCommands`](/docs/en/settings-reference#sandbox-excludedcommands) doesn't take that call out of the sandbox on its own.

116When Claude pipes text to one of these tools, adding `pbcopy *`, `wl-copy *`, or `xclip *` to [`excludedCommands`](https://code.claude.com/docs/en/settings-reference#sandbox-excludedcommands) doesn't take that call out of the sandbox on its own.

117117

118118### Copied text doesn't reach your local clipboard over SSH

119119

120When Claude Code runs on a remote machine over SSH, it can't run a clipboard tool on your local machine. Outside tmux, when you select text in [fullscreen rendering](/docs/en/fullscreen.md) or run `/copy`, Claude Code sends the text to your terminal as an OSC 52 escape sequence instead. Your terminal decides whether to put it on your clipboard. `/copy` reports `Copied to clipboard` whether or not the text arrived, and outside tmux the selection notice reads `sent N chars via OSC 52`.

120When Claude Code runs on a remote machine over SSH, it can't run a clipboard tool on your local machine. Outside tmux, when you select text in [fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md) or run `/copy`, Claude Code sends the text to your terminal as an OSC 52 escape sequence instead. Your terminal decides whether to put it on your clipboard. `/copy` reports `Copied to clipboard` whether or not the text arrived, and outside tmux the selection notice reads `sent N chars via OSC 52`.

121121

122122Some terminals don't act on OSC 52. iTerm2 ignores it until you turn on **Settings > General > Selection > Applications in terminal may access clipboard**, and macOS Terminal.app doesn't support it.

123123

124124To get the text without OSC 52:

125125

126* Hold your terminal's native-selection key while you drag, then copy with your terminal's usual shortcut, such as `Cmd+C`. The key is `Fn` in Terminal.app and `Option` in iTerm2. [Keep native text selection](/docs/en/fullscreen.md#keep-native-text-selection) lists it for other terminals.

127* Set [`CLAUDE_CODE_DISABLE_MOUSE=1`](/docs/en/env-vars) on the remote machine so your terminal handles selection for the whole session.

126* Hold your terminal's native-selection key while you drag, then copy with your terminal's usual shortcut, such as `Cmd+C`. The key is `Fn` in Terminal.app and `Option` in iTerm2. [Keep native text selection](https://code.claude.com/docs/en/fullscreen.md#keep-native-text-selection) lists it for other terminals.

127* Set [`CLAUDE_CODE_DISABLE_MOUSE=1`](https://code.claude.com/docs/en/env-vars) on the remote machine so your terminal handles selection for the whole session.

128128

129129### Search and discovery issues

130130

from line 148

148148apk add ripgrep

149149```

150150

151`ripgrep` is in Alpine's community repository. If `apk` reports that the package is missing, see [Alpine Linux setup](/docs/en/setup.md#alpine-linux-and-musl-based-distributions).

151`ripgrep` is in Alpine's community repository. If `apk` reports that the package is missing, see [Alpine Linux setup](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions).

152152

153153**Arch**

154154

from line 162

162162winget install BurntSushi.ripgrep.MSVC

163163```

164164

165Then set `USE_BUILTIN_RIPGREP` to `0`, either in your shell [environment](/docs/en/env-vars.md) or in the `env` block of your [`settings.json`](/docs/en/settings-reference#all-settings):

165Then set `USE_BUILTIN_RIPGREP` to `0`, either in your shell [environment](https://code.claude.com/docs/en/env-vars.md) or in the `env` block of your [`settings.json`](https://code.claude.com/docs/en/settings-reference#all-settings):

166166

167167```json theme={null}

168168{

ultrareview Changed · +15 / -15 lines

from line 6

66>

77> Ultrareview is a research preview feature. The feature, pricing, and availability may change based on feedback. The command is `/code-review ultra`. When ultrareview is available to your account, `/ultrareview` is an alias.

9Ultrareview is a deep code review that runs as a [cloud session](/docs/en/claude-code-on-the-web.md) on Anthropic's infrastructure. When you run `/code-review ultra`, Claude Code launches a fleet of reviewer agents in a cloud sandbox to find bugs in your branch or pull request.

9Ultrareview is a deep code review that runs as a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md) on Anthropic's infrastructure. When you run `/code-review ultra`, Claude Code launches a fleet of reviewer agents in a cloud sandbox to find bugs in your branch or pull request.

1010

1111Compared to a local `/code-review`, ultrareview offers:

1212

from line 14

1414* **Broader coverage**: a larger fleet of reviewer agents explores the change in parallel, which surfaces issues that a local review can miss

1515* **No local resource use**: the review runs entirely in a cloud sandbox, so your terminal stays free for other work while it runs

1616

17Ultrareview 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.md) 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`.

17Ultrareview 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](https://code.claude.com/docs/en/hipaa-setup.md) 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`.

1818

1919## Run ultrareview from the CLI

2020

from line 26

2626

2727Without arguments, ultrareview reviews the diff between your current branch and the default branch, including uncommitted and staged changes.

2828

29For a branch review, Claude Code bundles the repository state and uploads it to a cloud sandbox under the rules for [uploading a local repository to a cloud session](/docs/en/claude-code-on-the-web.md#send-local-repositories-without-github), which cover the size limits, the checkout requirements, and what happens to uncommitted changes in files named like credentials or keys, such as `.env` and `*.tfvars` files. When you [review a pull request](#review-a-pull-request), Claude Code uploads nothing from your machine.

29For a branch review, Claude Code bundles the repository state and uploads it to a cloud sandbox under the rules for [uploading a local repository to a cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md#send-local-repositories-without-github), which cover the size limits, the checkout requirements, and what happens to uncommitted changes in files named like credentials or keys, such as `.env` and `*.tfvars` files. When you [review a pull request](#review-a-pull-request), Claude Code uploads nothing from your machine.

3030

3131Before launching, Claude Code shows a confirmation dialog with the review scope, your remaining free runs, and the estimated cost; for a branch review, the scope includes the file and line count. After you confirm, the review continues in the background while you keep using your session.

3232

from line 54

5454

5555The command also accepts `#1234`, `PR 1234`, and pasted PR URLs; a pasted URL must point to the repository in your current directory.

5656

57PR mode needs a repository on `github.com`. For a repository on a [GitHub Enterprise Server](/docs/en/github-enterprise-server.md) instance, run `/code-review ultra` without a PR number to review your local branch instead.

57PR mode needs a repository on `github.com`. For a repository on a [GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server.md) instance, run `/code-review ultra` without a PR number to review your local branch instead.

5858

5959In PR mode, the cloud sandbox clones the pull request from `github.com` instead of uploading your working tree. It uses the GitHub account connected to your Claude account, so that account needs read access to the repository.

6060

61Run [`/web-setup`](/docs/en/web-quickstart#connect-from-your-terminal) to connect your GitHub CLI login to your Claude account.

61Run [`/web-setup`](https://code.claude.com/docs/en/web-quickstart#connect-from-your-terminal) to connect your GitHub CLI login to your Claude account.

6262

6363### Post findings to the pull request

6464

from line 69

6969* **Interactive**: in the launch dialog, select **Run and post the findings to the PR as me**. If you add `--post` to the command, as in `/code-review ultra 1234 --post`, Claude Code preselects that choice and still asks before launching.

7070* **Non-interactive**: run the [`claude ultrareview` subcommand](#run-ultrareview-non-interactively) with `--post`. You consent to the post by running the subcommand with the flag, so Claude Code posts without asking. In a `claude -p '/code-review ultra'` run, Claude Code exits before the findings arrive, so it posts nothing; use the subcommand instead.

7171

72Claude Code doesn't post from your machine. It sends the review's session ID to the Anthropic API, which posts the review's stored findings as the comment through the GitHub account you've connected to Claude. Posting requires the same claude.ai sign-in as the review itself, and it isn't available on third-party providers or when you set [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/en/env-vars).

7373

7474In an interactive session, Claude Code starts the post when the findings arrive, so keep the session open until the review finishes. Claude Code keeps the posting choice only in that session. If the session ends before the review finishes, Claude Code posts nothing, even if you resume the conversation later.

7575

from line 99

9999

100100Ultrareview checks the diff before any review work runs and tells you when it can't review it as-is:

101101

102* **Diff too large**: a branch review can include up to 500 changed files and 8,000 changed lines by default. The exact values can change, and the [refusal](/docs/en/errors.md#diff-is-too-large-for-ultrareview) names the ones in effect, the size of your diff, and the files with the most changed lines. Claude Code refuses a too-large pull request the same way, naming its file and line counts but not the per-file breakdown

102* **Diff too large**: a branch review can include up to 500 changed files and 8,000 changed lines by default. The exact values can change, and the [refusal](https://code.claude.com/docs/en/errors.md#diff-is-too-large-for-ultrareview) names the ones in effect, the size of your diff, and the files with the most changed lines. Claude Code refuses a too-large pull request the same way, naming its file and line counts but not the per-file breakdown

103103* **Nothing to review**: when the diff against the base is empty, ultrareview refuses and names the branch or commit it compared against and the case you're in, such as being on the base branch itself with nothing uncommitted, or a branch whose commits are all part of the base already. It also suggests the way out for that case, such as switching to the branch with your work, staging or committing local edits, or passing a different base

104104* **First commit**: a repository's first commit has nothing earlier to compare with, so ultrareview reviews every file in it after you confirm in the launch dialog. If you have untracked files, it refuses instead and tells you to `git add` the ones you want reviewed. The same size limits apply.

105105

from line 106

106106 A first commit is reviewed whole only after that confirmation, so the `claude ultrareview` subcommand and `claude -p` refuse it and point you to an interactive session instead. Requires Claude Code v2.1.277 or later

107107* **No merge base**: when your branch shares no history with the base branch, or the repository has no base branch to compare with, ultrareview reviews every tracked file in the repository instead. The fallback requires a full clone and applies the same size limits. It launches only when you confirm in the launch dialog or run the `claude ultrareview` subcommand yourself. In `claude -p` and anywhere else neither happens, ultrareview refuses, says the review would cover every file, and points you to an interactive session.

108108

109 On a checkout with no branches or other refs, such as a detached HEAD created by checking out `FETCH_HEAD` after fetching a URL, Claude Code [refuses the review](/docs/en/errors.md#your-checkout-has-no-branches) and suggests creating a branch first

109 On a checkout with no branches or other refs, such as a detached HEAD created by checking out `FETCH_HEAD` after fetching a URL, Claude Code [refuses the review](https://code.claude.com/docs/en/errors.md#your-checkout-has-no-branches) and suggests creating a branch first

110110

111111## Pricing and free runs

112112

from line 135

135135

136136Claude can also tell you that a review was stopped or that its session wasn't found:

137137

138* If the review's cloud session is stopped or [archived](/docs/en/claude-code-on-the-web.md#archive-sessions) on claude.ai before the review finishes, Claude tells you it was stopped.

138* If the review's cloud session is stopped or [archived](https://code.claude.com/docs/en/claude-code-on-the-web.md#archive-sessions) on claude.ai before the review finishes, Claude tells you it was stopped.

139139* If the review's cloud session was deleted, or you've signed in to a different Claude account or organization since launching it, Claude tells you the session wasn't found.

140140* If you switched accounts, the review may still finish under the account that started it. If the review is still running, sign back in as that account and resume the conversation with `claude --resume` to re-attach it.

141141

from line 182

182182* If the run fails, is stopped, or times out, the subcommand posts nothing.

183183* If the review completes but the comment isn't posted, Claude Code prints the reason to stderr, and the findings stay on stdout so you can post them by hand.

184184

185For automatic reviews on GitHub pull requests, [Code Review](/docs/en/code-review.md) integrates with your repository directly and posts findings as inline PR comments without a CLI step.

185For automatic reviews on GitHub pull requests, [Code Review](https://code.claude.com/docs/en/code-review.md) integrates with your repository directly and posts findings as inline PR comments without a CLI step.

186186

187187### Trust the folder before the review runs

188188

189When `claude ultrareview` asks `Trust <folder>? [y/N]`, answer `y` to [trust the folder](/docs/en/permissions.md#project-allow-rules-and-workspace-trust). Trust it only if you trust its code, because git and Claude Code can then run programs named in its git configuration and project settings.

189When `claude ultrareview` asks `Trust <folder>? [y/N]`, answer `y` to [trust the folder](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust). Trust it only if you trust its code, because git and Claude Code can then run programs named in its git configuration and project settings.

190190

191When it can't ask you, such as in a CI job or with output sent to a file, it exits with [`Error: Workspace not trusted`](/docs/en/errors#workspace-not-trusted-when-running-claude-ultrareview). Append `--trust-workspace` to trust the folder for that run:

191When it can't ask you, such as in a CI job or with output sent to a file, it exits with [`Error: Workspace not trusted`](https://code.claude.com/docs/en/errors#workspace-not-trusted-when-running-claude-ultrareview). Append `--trust-workspace` to trust the folder for that run:

192192

193193```bash theme={null}

194194claude ultrareview 1234 --trust-workspace

from line 213

213213

214214## Related resources

215215

216* [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web.md): learn how cloud sessions and cloud sandboxes work

217* [Manage costs effectively](/docs/en/costs.md): track usage and set spending limits

216* [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md): learn how cloud sessions and cloud sandboxes work

217* [Manage costs effectively](https://code.claude.com/docs/en/costs.md): track usage and set spending limits

218218

voice-dictation Changed · +17 / -17 lines

from line 4

55Speak your prompts instead of typing them in the Claude Code CLI. Your speech is transcribed live into the prompt input, so you can mix voice and typing in the same message. Enable dictation with `/voice`, then either hold a key while you speak or tap once to start and again to send.

7In [hold mode](#hold-to-record), dictation also works in [agent view](/docs/en/agent-view.md#peek-and-reply). Hold your push-to-talk key while the dispatch input or a peek-panel reply is focused to dictate to a background session.

7In [hold mode](#hold-to-record), dictation also works in [agent view](https://code.claude.com/docs/en/agent-view.md#peek-and-reply). Hold your push-to-talk key while the dispatch input or a peek-panel reply is focused to dictate to a background session.

99## Requirements

1010

from line 11

1111Voice dictation streams your recorded audio to Anthropic's servers for transcription. Audio is not processed locally. It needs all of the following:

1212

1313* **A Claude.ai account**: the speech-to-text service is only available when you authenticate with one, and is not available when Claude Code is configured to use an Anthropic API key directly, Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry.

14* **A local microphone**: voice dictation does not work in [cloud sessions](/docs/en/claude-code-on-the-web.md) or SSH sessions.

14* **A local microphone**: voice dictation does not work in [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) or SSH sessions.

1515* **WSLg, if you run Claude Code in WSL**: WSLg is included with WSL2 when installed from the Microsoft Store on Windows 10 or 11. If WSLg is not available, for example on WSL1, run Claude Code in native Windows instead.

1616

17Transcription does not consume Claude messages or tokens and does not count toward the limits shown in `/usage`. See [data usage](/docs/en/data-usage.md) for how Anthropic handles your data.

17Transcription does not consume Claude messages or tokens and does not count toward the limits shown in `/usage`. See [data usage](https://code.claude.com/docs/en/data-usage.md) for how Anthropic handles your data.

1818

1919Audio recording uses a built-in native module on macOS, Linux, and Windows. On Linux, if the native module cannot load, Claude Code falls back to `arecord` from ALSA utils or `rec` from SoX. If neither is available, `/voice` prints an install command for your package manager.

2020

21The Claude Code [VS Code extension](/docs/en/vs-code.md) also supports voice dictation with the same claude.ai account requirement. It is not available in VS Code Remote sessions, including SSH, Dev Containers, and Codespaces, because the microphone is on your local machine and the extension runs on the remote host.

21The Claude Code [VS Code extension](https://code.claude.com/docs/en/vs-code.md) also supports voice dictation with the same claude.ai account requirement. It is not available in VS Code Remote sessions, including SSH, Dev Containers, and Codespaces, because the microphone is on your local machine and the extension runs on the remote host.

2222

2323## Enable voice dictation

2424

from line 38

3838| `/voice tap` | Enable in [tap mode](#tap-to-record-and-send) |

3939| `/voice off` | Disable |

4040

41Voice dictation persists across sessions. Set it directly in your [user settings file](/docs/en/settings.md) instead of running `/voice`:

41Voice dictation persists across sessions. Set it directly in your [user settings file](https://code.claude.com/docs/en/settings.md) instead of running `/voice`:

4242

4343```json theme={null}

4444{

from line 49

4949}

5050```

5151

52For the first three sessions with voice dictation enabled, the input footer shows a `hold space to speak` hint when the prompt is empty. The hint reflects your current `voice:pushToTalk` binding and updates if you [rebind the dictation key](#rebind-the-dictation-key). The hint text is the same in both modes, and it does not appear if you have a [custom status line](/docs/en/statusline.md) configured.

5353

5454Transcription is tuned for coding vocabulary in both modes. Common development terms like `regex`, `OAuth`, `JSON`, and `localhost` are recognized correctly, and your current project name and git branch name are added as recognition hints automatically.

5555

from line 57

5757

5858Hold mode is push-to-talk: recording runs while you hold the key and stops when you release it. This is the default mode.

5959

60Hold `Space` to start recording. Claude Code detects a held key by watching for rapid key-repeat events from your terminal, so there is a brief warmup before recording begins. The footer shows `keep holding…` during warmup, then `listening…` once recording is active. While recording, the prompt cursor becomes a bar that rises and falls with your microphone level, unless you have [`prefersReducedMotion`](/docs/en/settings-reference#prefersreducedmotion) turned on.

60Hold `Space` to start recording. Claude Code detects a held key by watching for rapid key-repeat events from your terminal, so there is a brief warmup before recording begins. The footer shows `keep holding…` during warmup, then `listening…` once recording is active. While recording, the prompt cursor becomes a bar that rises and falls with your microphone level, unless you have [`prefersReducedMotion`](https://code.claude.com/docs/en/settings-reference#prefersreducedmotion) turned on.

6161

6262The first couple of key-repeat characters type into the input during warmup and are removed automatically when recording activates. A single `Space` tap still types a space, since hold detection only triggers on rapid repeat.

6363

64Holding or tapping `Space` starts dictation only where the keypress would otherwise type into the prompt. In the [transcript viewer](/docs/en/interactive-mode.md#transcript-viewer), `Space` pages through the conversation, and in [vim mode](/docs/en/interactive-mode.md#vim-editor-mode) outside INSERT it is a command. A [rebound modifier combination](#rebind-the-dictation-key) like `meta+k` never types text, so it starts dictation from those places too.

64Holding or tapping `Space` starts dictation only where the keypress would otherwise type into the prompt. In the [transcript viewer](https://code.claude.com/docs/en/interactive-mode.md#transcript-viewer), `Space` pages through the conversation, and in [vim mode](https://code.claude.com/docs/en/interactive-mode.md#vim-editor-mode) outside INSERT it is a command. A [rebound modifier combination](#rebind-the-dictation-key) like `meta+k` never types text, so it starts dictation from those places too.

6565

6666> [!TIP]

6767>

from line 95

9595

9696Both keys also cancel while a finished recording's transcript is still processing. A prompt you edited or submitted during processing stays as you left it.

9797

98Neither key does anything else in the press that cancels: `Esc` doesn't interrupt Claude's response, and `Ctrl+C` doesn't clear the prompt or count as the first of the [two presses that exit Claude Code](/docs/en/interactive-mode.md#general-controls).

9999

100100## Change the dictation language

101101

102Voice dictation uses the same [`language` setting](/docs/en/settings-reference#language) that controls Claude's response language. If that setting is empty, dictation defaults to English. In the VS Code extension, if `language` is empty, dictation uses VS Code's `accessibility.voice.speechLanguage` setting before defaulting to English.

102Voice dictation uses the same [`language` setting](https://code.claude.com/docs/en/settings-reference#language) that controls Claude's response language. If that setting is empty, dictation defaults to English. In the VS Code extension, if `language` is empty, dictation uses VS Code's `accessibility.voice.speechLanguage` setting before defaulting to English.

103103

104104> **Supported dictation languages**

105105>

from line 138

138138

139139## Rebind the dictation key

140140

141The dictation key is bound to `voice:pushToTalk` in the `Chat` context and defaults to `Space`. The same binding controls both hold and tap modes. Rebind it in [`~/.claude/keybindings.json`](/docs/en/keybindings):

142142

143143```json theme={null}

144144{

from line 158

158158

159159In hold mode, avoid binding a bare letter key like `v` since hold detection relies on key-repeat and the letter types into the prompt during warmup. Use `Space`, or use a modifier combination like `meta+k` to start recording on the first keypress with no warmup. Tap mode has no warmup, so most keys work.

160160

161Some keys are not delivered to terminal applications and can't be bound at all. For example, `Caps Lock` shows an error if you try to bind it. See [customize keyboard shortcuts](/docs/en/keybindings.md) for the full keybinding syntax and the list of reserved shortcuts.

161Some keys are not delivered to terminal applications and can't be bound at all. For example, `Caps Lock` shows an error if you try to bind it. See [customize keyboard shortcuts](https://code.claude.com/docs/en/keybindings.md) for the full keybinding syntax and the list of reserved shortcuts.

162162

163163## Troubleshooting

164164

from line 176

176176* **Tapping `Space` types a space instead of recording in tap mode**: the first tap only starts recording when the prompt input is empty. Clear the input first, or check that you are in tap mode by running `/voice tap`.

177177* **`No audio detected from microphone`**: recording started but captured silence. Confirm the correct input device is set as the system default and that its input level is not muted or near zero. On Windows, open Settings → System → Sound → Input and select your microphone. On macOS, open System Settings → Sound → Input.

178178* **`Voice connection failed`**: your recording never reached the transcription service because the connection failed. Check your network and try again. A recording that captures no audio reports `No audio detected from microphone` instead of this message. Before v2.1.200, a silent microphone could report a connection failure, which suggested a network problem when the actual issue was the input device.

179* **`Dictation error: WebSocket error:` followed by a certificate error such as `unable to get local issuer certificate`**: see [Dictation or the Web tab fails behind a TLS-inspecting proxy](/docs/en/vs-code.md#dictation-or-the-web-tab-fails-behind-a-tls-inspecting-proxy) on the VS Code page.

179* **`Dictation error: WebSocket error:` followed by a certificate error such as `unable to get local issuer certificate`**: see [Dictation or the Web tab fails behind a TLS-inspecting proxy](https://code.claude.com/docs/en/vs-code.md#dictation-or-the-web-tab-fails-behind-a-tls-inspecting-proxy) on the VS Code page.

180180* **`Voice stream error: WebSocket upgrade rejected with HTTP <status>`**: a server refused your connection with the HTTP status shown, so this isn't a network outage. A status in the 400 range usually means a stale sign-in, or a proxy or bot-protection service answering in place of the transcription service. Run `/login` to refresh your sign-in, and check for a VPN or proxy on your network path if the status persists. If you're still recording when the rejection arrives, Claude Code retries a status outside the 400 range once before showing this message; it doesn't retry a status in the 400 range. In v2.1.229 through v2.1.231, native builds didn't show this message: Claude Code kept recording, the hold-mode footer still showed `listening…`, and it reported `Voice connection failed` after you stopped recording.

181181* **`No speech detected`**: audio reached the transcription service but no words were recognized. Speak closer to the microphone, reduce background noise, and confirm your [dictation language](#change-the-dictation-language) matches the language you are speaking.

182182* **`Dictation stopped: no speech recognized for 15 seconds` or `Dictation stopped at its 2-minute limit`**: in the VS Code extension, a recording ends after 15 seconds with no recognized words, or two minutes after it starts. If you were speaking during those 15 seconds, try the fixes for `No speech detected`. Words already recognized stay in the prompt box and aren't sent. To add more, click the microphone button again.

from line 204

204204

205205## See also

206206

207* [Customize keyboard shortcuts](/docs/en/keybindings.md): rebind `voice:pushToTalk` and other CLI keyboard actions

208* [All settings](/docs/en/settings-reference.md#voice): the `voice`, `language`, and other settings keys

209* [Interactive mode](/docs/en/interactive-mode.md): keyboard shortcuts, input modes, and session controls

210* [Commands](/docs/en/commands.md): reference for `/voice`, `/config`, and all other commands

207* [Customize keyboard shortcuts](https://code.claude.com/docs/en/keybindings.md): rebind `voice:pushToTalk` and other CLI keyboard actions

208* [All settings](https://code.claude.com/docs/en/settings-reference.md#voice): the `voice`, `language`, and other settings keys

209* [Interactive mode](https://code.claude.com/docs/en/interactive-mode.md): keyboard shortcuts, input modes, and session controls

210* [Commands](https://code.claude.com/docs/en/commands.md): reference for `/voice`, `/config`, and all other commands

211211

vs-code Changed · +116 / -116 lines

from line 19

1919Before installing, make sure you have:

2020

2121* VS Code 1.94.0 or later

22* An Anthropic account: any paid Claude subscription (Pro, Max, Team, or Enterprise) or a Claude Console account works, and no API key is required. You'll [sign in](/docs/en/authentication.md#log-in-to-claude-code) with this account when you first open the extension. If you access Claude through a third-party provider like Amazon Bedrock or Google Cloud's Agent Platform, see [Use third-party providers](#use-third-party-providers) for setup instructions.

22* An Anthropic account: any paid Claude subscription (Pro, Max, Team, or Enterprise) or a Claude Console account works, and no API key is required. You'll [sign in](https://code.claude.com/docs/en/authentication.md#log-in-to-claude-code) with this account when you first open the extension. If you access Claude through a third-party provider like Amazon Bedrock or Google Cloud's Agent Platform, see [Use third-party providers](#use-third-party-providers) for setup instructions.

2323

2424> [!TIP]

2525>

26> The extension bundles its own copy of the CLI (command-line interface) for the chat panel. To run `claude` in VS Code's integrated terminal, you also need the [standalone CLI install](/docs/en/setup.md). See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.

26> The extension bundles its own copy of the CLI (command-line interface) for the chat panel. To run `claude` in VS Code's integrated terminal, you also need the [standalone CLI install](https://code.claude.com/docs/en/setup.md). See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.

2727

2828## Install the extension

2929

from line 39

3939Claude Code also runs in other editors and containers:

4040

4141* **Other VS Code forks**: the extension also installs in forks like Devin Desktop or Kiro. Search for "Claude Code" in the editor's Extensions view, or install from the [Open VSX registry](https://open-vsx.org/extension/Anthropic/claude-code).

42* **Editors that can't install the extension**: [install the CLI](/docs/en/quickstart.md) and run `claude` in the editor's integrated terminal instead. The CLI works in any terminal.

43* **Dev containers**: to run Claude Code inside a dev container, see [Development containers](/docs/en/devcontainer.md).

42* **Editors that can't install the extension**: [install the CLI](https://code.claude.com/docs/en/quickstart.md) and run `claude` in the editor's integrated terminal instead. The CLI works in any terminal.

43* **Dev containers**: to run Claude Code inside a dev container, see [Development containers](https://code.claude.com/docs/en/devcontainer.md).

4444

4545> [!NOTE]

4646>

from line 90

9090

9191**4. Review changes**

9292

93Check the [permission mode](/docs/en/permission-modes.md#which-mode-a-session-starts-in) shown at the bottom of the prompt box:

93Check the [permission mode](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in) shown at the bottom of the prompt box:

9494

95* In Auto or Edit automatically mode, Claude edits [most files](/docs/en/permission-modes.md#protected-paths) in your workspace without asking.

95* In Auto or Edit automatically mode, Claude edits [most files](https://code.claude.com/docs/en/permission-modes.md#protected-paths) in your workspace without asking.

9696* In Manual mode, when Claude wants to edit a file, it shows a side-by-side comparison of the original and proposed changes, then asks for permission. You can accept, reject, or tell Claude what to do instead. If you edit the proposed content directly in the diff view before accepting, Claude is told that you modified it so it doesn't assume the file matches its original proposal.

9797

9898 ![VS Code showing a diff of Claude's proposed changes with a permission prompt asking whether to make the edit](https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?fit=max\&auto=format\&n=FVYz38sRY-VuoGHA\&q=85\&s=e005f9b41c541c5c7c59c082f7c4841c)

from line 103

103103

104104The same actions are available at the cursor from the editor's context menu and from the Command Palette as **Claude Code: Accept Change at Cursor** and **Claude Code: Reject Change at Cursor**.

105105

106For more ideas on what you can do with Claude Code, see [Common workflows](/docs/en/common-workflows.md).

106For more ideas on what you can do with Claude Code, see [Common workflows](https://code.claude.com/docs/en/common-workflows.md).

107107

108108> [!TIP]

109109>

from line 113

113113

114114The prompt box supports several features:

115115

116* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch permission modes. With Claude Code v2.1.283 or later, Auto is the built-in starting permission mode, and on earlier versions only on Pro, Max, and Team plans. See [how the extension chooses the starting permission mode](/docs/en/permission-modes.md#switch-permission-modes) for what changes that, and every permission mode the indicator offers.

117 * **Auto**: a classifier reviews most actions instead of asking you. See [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) for what it reviews and blocks.

116* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch permission modes. With Claude Code v2.1.283 or later, Auto is the built-in starting permission mode, and on earlier versions only on Pro, Max, and Team plans. See [how the extension chooses the starting permission mode](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes) for what changes that, and every permission mode the indicator offers.

117 * **Auto**: a classifier reviews most actions instead of asking you. See [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) for what it reviews and blocks.

118118 * **Manual**: Claude asks permission before file edits and most shell commands.

119119 * **Plan**: Claude describes what it will do and waits for approval before making changes. VS Code automatically opens the plan as a full Markdown document where you can add inline comments to give feedback before Claude begins.

120120

from line 126

126126 * **Edit automatically**: Claude makes edits without asking.

127127* **Model**: select **Switch model…** from the command menu to change the model mid-session. You can also click the model name at the bottom of the prompt box to open the same picker. With Claude Code v2.1.284 or later, typing `/model` on its own in the prompt box opens the picker too.

128128

129 When the current model supports [effort levels](/docs/en/model-config.md#adjust-effort-level), the picker also shows an **Effort** row and the model name button shows the selected level. When you pick a level other than `max`, Claude Code saves it for the current model as your default, under [`modelSettings`](/docs/en/settings-reference#modelsettings) in your user settings; `max` applies to the current session only. The model name button and the **Effort** row require Claude Code v2.1.257 or later.

129 When the current model supports [effort levels](https://code.claude.com/docs/en/model-config.md#adjust-effort-level), the picker also shows an **Effort** row and the model name button shows the selected level. When you pick a level other than `max`, Claude Code saves it for the current model as your default, under [`modelSettings`](https://code.claude.com/docs/en/settings-reference#modelsettings) in your user settings; `max` applies to the current session only. The model name button and the **Effort** row require Claude Code v2.1.257 or later.

130130

131 When [dynamic workflows](/docs/en/workflows.md) are enabled and the current model supports it, an **Ultracode** switch appears under the **Effort** row. Turn it on to have Claude plan a [workflow](/docs/en/workflows.md#let-claude-decide-with-ultracode) for each substantive task in this session, at the selected effort level. While it's on, the model name button shows `· Ultracode` after the level. The switch requires Claude Code v2.1.284 or later.

131 When [dynamic workflows](https://code.claude.com/docs/en/workflows.md) are enabled and the current model supports it, an **Ultracode** switch appears under the **Effort** row. Turn it on to have Claude plan a [workflow](https://code.claude.com/docs/en/workflows.md#let-claude-decide-with-ultracode) for each substantive task in this session, at the selected effort level. While it's on, the model name button shows `· Ultracode` after the level. The switch requires Claude Code v2.1.284 or later.

132132* **Command menu**: click `/` or type `/` to open the command menu. Options include attaching files, switching models, and toggling extended thinking.

133133

134134 The Customize section includes entries such as MCP servers, commands, output styles, hooks, memory, instructions, permissions, and plugins. Items with a terminal icon open in the integrated terminal.

135135

136 * To browse commands such as `/usage` or [`/remote-control`](/docs/en/remote-control), select **Slash commands** in the Customize section. A dialog lists them with a filter box. Pick one to run it. Typing `/` in the prompt box still suggests commands inline. Requires Claude Code v2.1.257 or later.

136 * To browse commands such as `/usage` or [`/remote-control`](https://code.claude.com/docs/en/remote-control), select **Slash commands** in the Customize section. A dialog lists them with a filter box. Pick one to run it. Typing `/` in the prompt box still suggests commands inline. Requires Claude Code v2.1.257 or later.

137137

138 Typing `/skills` also opens this dialog. Each [skill](/docs/en/skills.md) row shows its [visibility](/docs/en/skills.md#override-skill-visibility-from-settings), such as **On** or **Name only**. Click the visibility to change it, except on rows marked **locked**, such as plugin skills. The `/skills` shortcut and the visibility controls require Claude Code v2.1.280 or later.

139 * Select **Output styles** in the Customize section to pick an [output style](/docs/en/output-styles.md), including your custom styles. Requires Claude Code v2.1.257 or later.

138 Typing `/skills` also opens this dialog. Each [skill](https://code.claude.com/docs/en/skills.md) row shows its [visibility](https://code.claude.com/docs/en/skills.md#override-skill-visibility-from-settings), such as **On** or **Name only**. Click the visibility to change it, except on rows marked **locked**, such as plugin skills. The `/skills` shortcut and the visibility controls require Claude Code v2.1.280 or later.

139 * Select **Output styles** in the Customize section to pick an [output style](https://code.claude.com/docs/en/output-styles.md), including your custom styles. Requires Claude Code v2.1.257 or later.

140140

141 To create a custom style instead, select **Build a custom style** from the **Output styles** menu. Claude Code writes the [style file](/docs/en/output-styles.md#create-a-custom-output-style) for you at the project or user level. Requires Claude Code v2.1.261 or later.

142 * Select **Hooks** in the Customize section to view the [hooks](/docs/en/hooks.md) loaded in the session, grouped by event. You can add, edit, or remove hooks saved in your user, project, and local settings files. Hooks from other sources, such as managed settings or plugins, are read-only. Requires Claude Code v2.1.269 or later.

143 * Select **Permissions** in the Customize section to view the session's [permission rules](/docs/en/permissions.md), grouped into Allow, Ask, and Deny. You can add rules to your user, project, or local settings and remove rules saved there. Rules from other sources, such as managed settings or approvals made for this session only, are read-only. Requires Claude Code v2.1.269 or later.

144 * Select **Memory** in the Customize section to turn [auto memory](/docs/en/memory.md#auto-memory) on or off. While it's on, you can also browse the memories Claude has saved and reveal the folders that store them in your file manager. Requires Claude Code v2.1.274 or later.

141 To create a custom style instead, select **Build a custom style** from the **Output styles** menu. Claude Code writes the [style file](https://code.claude.com/docs/en/output-styles.md#create-a-custom-output-style) for you at the project or user level. Requires Claude Code v2.1.261 or later.

142 * Select **Hooks** in the Customize section to view the [hooks](https://code.claude.com/docs/en/hooks.md) loaded in the session, grouped by event. You can add, edit, or remove hooks saved in your user, project, and local settings files. Hooks from other sources, such as managed settings or plugins, are read-only. Requires Claude Code v2.1.269 or later.

143 * Select **Permissions** in the Customize section to view the session's [permission rules](https://code.claude.com/docs/en/permissions.md), grouped into Allow, Ask, and Deny. You can add rules to your user, project, or local settings and remove rules saved there. Rules from other sources, such as managed settings or approvals made for this session only, are read-only. Requires Claude Code v2.1.269 or later.

144 * Select **Memory** in the Customize section to turn [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) on or off. While it's on, you can also browse the memories Claude has saved and reveal the folders that store them in your file manager. Requires Claude Code v2.1.274 or later.

145145

146146 Click a saved memory to read it in the dialog, where you can edit the text, delete the memory, or open its file in the editor. Viewing, editing, and deleting a memory in the dialog require Claude Code v2.1.275 or later.

147 * Select **Instructions** in the Customize section to edit the [CLAUDE.md files](/docs/en/memory.md#claude-md-files) Claude reads. Pick a file to open it in the editor. If the file doesn't exist yet, Claude Code creates it first. Requires Claude Code v2.1.274 or later.

147 * Select **Instructions** in the Customize section to edit the [CLAUDE.md files](https://code.claude.com/docs/en/memory.md#claude-md-files) Claude reads. Pick a file to open it in the editor. If the file doesn't exist yet, Claude Code creates it first. Requires Claude Code v2.1.274 or later.

148148 * Select **Status** in the Customize section, or type `/status`, to check the session's Claude Code version, account, model, and MCP server details. Requires Claude Code v2.1.280 or later.

149 * Select **Sandbox** in the Customize section, or type `/sandbox`, to see whether Claude's Bash commands run [sandboxed](/docs/en/sandboxing.md). You can switch the sandbox mode and add [excluded commands](/docs/en/settings-reference.md#sandbox-excludedcommands) there. Requires Claude Code v2.1.280 or later.

150 * Select **Claude in Chrome** in the Customize section, or type `/chrome`, to check and manage the [Claude in Chrome](/docs/en/chrome.md) connection. Both require signing in with a claude.ai account. Requires Claude Code v2.1.280 or later.

149 * Select **Sandbox** in the Customize section, or type `/sandbox`, to see whether Claude's Bash commands run [sandboxed](https://code.claude.com/docs/en/sandboxing.md). You can switch the sandbox mode and add [excluded commands](https://code.claude.com/docs/en/settings-reference.md#sandbox-excludedcommands) there. Requires Claude Code v2.1.280 or later.

150 * Select **Claude in Chrome** in the Customize section, or type `/chrome`, to check and manage the [Claude in Chrome](https://code.claude.com/docs/en/chrome.md) connection. Both require signing in with a claude.ai account. Requires Claude Code v2.1.280 or later.

151151 * Select **Export conversation** in the Context section, or type `/export`, to copy the conversation as plain text or save it to a file. Add a file name, such as `/export notes.txt`, to skip the dialog and choose where to save the file. Requires Claude Code v2.1.280 or later.

152 * The Settings section includes **Enable Remote Control for all sessions**, which sets [`remoteControlAtStartup`](/docs/en/settings-reference#remotecontrolatstartup) to control whether [new interactive sessions connect to Remote Control automatically](/docs/en/remote-control.md#enable-remote-control-for-all-sessions). Requires Claude Code v2.1.203 or later.

152 * The Settings section includes **Enable Remote Control for all sessions**, which sets [`remoteControlAtStartup`](https://code.claude.com/docs/en/settings-reference#remotecontrolatstartup) to control whether [new interactive sessions connect to Remote Control automatically](https://code.claude.com/docs/en/remote-control.md#enable-remote-control-for-all-sessions). Requires Claude Code v2.1.203 or later.

153153

154154 When you turn the toggle on or off in a VS Code window, the change isn't limited to sessions you start afterwards. It also applies to the sessions already open in that VS Code window. If you turn it off, the open sessions disconnect. With Claude Code v2.1.261 or later, the change also reaches sessions open in your other VS Code windows.

155155 * The Settings section also includes **Focus view**, which hides tool calls, tool results, and thinking behind expandable rows, leaving your prompts and Claude's responses. Toggle it there, with `Ctrl+Option+F` (Mac) / `Ctrl+Alt+F` (Windows/Linux), or from the Command Palette with **Claude Code: Toggle Focus view**. The change applies to every open session and persists across sessions. Requires Claude Code v2.1.221 or later.

156156

157 Claude's latest to-do list stays visible, and so does the text a pending question from Claude is asking about; this requires Claude Code v2.1.225 or later. While Claude runs [subagents](/docs/en/sub-agents.md), live progress rows with their latest activity appear under the tool-call group that started them. This requires Claude Code v2.1.269 or later.

157 Claude's latest to-do list stays visible, and so does the text a pending question from Claude is asking about; this requires Claude Code v2.1.225 or later. While Claude runs [subagents](https://code.claude.com/docs/en/sub-agents.md), live progress rows with their latest activity appear under the tool-call group that started them. This requires Claude Code v2.1.269 or later.

158158 * To sign out of your Anthropic account, select **Sign out** in the Settings section, or type `/logout`. On a [third-party provider](#use-third-party-providers), the menu doesn't offer either. Requires Claude Code v2.1.277 or later.

159159 * To report a bug, click **Report a problem** at the bottom of the menu, or type `/bug` or `/feedback` with an optional description that prefills the report. When you submit the report and you're signed in to Anthropic on a first-party connection, Claude Code sends it to Anthropic. Requires Claude Code v2.1.229 or later.

160160

161 On a third-party provider, or without Anthropic credentials, nothing is sent. The dialog says so before you write. Submitting saves the report as a [local archive under `~/.claude/feedback-bundles/`](/docs/en/data-usage#telemetry-services) with known API key and token patterns redacted. Saving the report on your computer requires Claude Code v2.1.284 or later.

161 On a third-party provider, or without Anthropic credentials, nothing is sent. The dialog says so before you write. Submitting saves the report as a [local archive under `~/.claude/feedback-bundles/`](https://code.claude.com/docs/en/data-usage#telemetry-services) with known API key and token patterns redacted. Saving the report on your computer requires Claude Code v2.1.284 or later.

162162

163163 After the report is saved, the confirmation names the file and includes a **Show folder** button. Send that file to your Anthropic account representative or attach it to a support request.

164164

165165 If your organization's policy turns product feedback off, **Report a problem** doesn't appear in the menu, and `/bug` and `/feedback` show a `Feedback is turned off by your organization's policy or this environment's settings.` notice instead of opening the report. With Claude Code v2.1.284 or later, if you set the `DISABLE_FEEDBACK_COMMAND` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` environment variable, feedback is also turned off and opening the report shows that notice instead.

166* **Side questions**: type `/btw` followed by a question to ask about your session [without adding to the conversation](/docs/en/interactive-mode.md#side-questions-with-%2Fbtw). The answer opens in a panel beside the chat, where you can ask follow-up questions. Requires Claude Code v2.1.227 or later.

166* **Side questions**: type `/btw` followed by a question to ask about your session [without adding to the conversation](https://code.claude.com/docs/en/interactive-mode.md#side-questions-with-%2Fbtw). The answer opens in a panel beside the chat, where you can ask follow-up questions. Requires Claude Code v2.1.227 or later.

167167

168 The thread survives window reloads. Claude Code keeps the newest 20 exchanges and expires stored threads on the [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) schedule, as long as Claude Code can [safely determine the retention period](/docs/en/claude-directory.md#cleaned-up-automatically). To clear a thread, click the trash icon in the panel.

168 The thread survives window reloads. Claude Code keeps the newest 20 exchanges and expires stored threads on the [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) schedule, as long as Claude Code can [safely determine the retention period](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically). To clear a thread, click the trash icon in the panel.

169169* **Copy a response**: hover over a response and click **Copy response** to copy it to your clipboard, or type `/copy` to copy the latest response. `/copy 2` copies the second-to-last. Requires Claude Code v2.1.277 or later.

170170* **Bookmarks**: hover over a response and click **Bookmark response** to save it, or click **Remove bookmark** on a saved response to remove it.

171171

172172 To review saved responses, open the Bookmarks panel. You can click the bookmark icon at the top of the Claude Code panel, select **Bookmarks** in the Context section of the command menu, or type `/bookmarks`. Requires Claude Code v2.1.286 or later.

173* **Files Claude sends you**: when the session is connected to [Remote Control](/docs/en/remote-control.md#start-a-remote-control-session) and Claude sends you files with the [`SendUserFile` tool](/docs/en/tools-reference), the conversation shows a row such as **Sent report.md, chart.png**. Click a file's name to open it in the editor. The row stays visible in Focus view. Requires Claude Code v2.1.295 or later.

173* **Files Claude sends you**: when the session is connected to [Remote Control](https://code.claude.com/docs/en/remote-control.md#start-a-remote-control-session) and Claude sends you files with the [`SendUserFile` tool](https://code.claude.com/docs/en/tools-reference), the conversation shows a row such as **Sent report.md, chart.png**. Click a file's name to open it in the editor. The row stays visible in Focus view. Requires Claude Code v2.1.295 or later.

174174

175 A file appears as a full path you can't click, such as `\\server\share\report.md`, when its path names a network host. Claude Code doesn't link that file because opening it would contact that host and, on Windows, [could send your Windows credentials to that host](/docs/en/permissions.md#read-only-commands).

176176* **Context indicator**: the prompt box shows how much of Claude's context window you're using. Claude automatically compacts when needed, or you can run `/compact` manually.

177* **Prompt cache clock**: a clock icon next to the context indicator estimates how much time the conversation's [prompt cache](/docs/en/prompt-caching.md) has left before it expires. It counts down from the cache's five-minute or one-hour [lifetime](/docs/en/prompt-caching.md#cache-lifetime), and each response that uses the cache restarts the countdown. Apart from compaction, the [actions that invalidate the cache](/docs/en/prompt-caching.md#actions-that-invalidate-the-cache) don't reset the clock, so it can still show minutes left after you switch models.

177* **Prompt cache clock**: a clock icon next to the context indicator estimates how much time the conversation's [prompt cache](https://code.claude.com/docs/en/prompt-caching.md) has left before it expires. It counts down from the cache's five-minute or one-hour [lifetime](https://code.claude.com/docs/en/prompt-caching.md#cache-lifetime), and each response that uses the cache restarts the countdown. Apart from compaction, the [actions that invalidate the cache](https://code.claude.com/docs/en/prompt-caching.md#actions-that-invalidate-the-cache) don't reset the clock, so it can still show minutes left after you switch models.

178178 * Until the countdown runs out, the icon shows the minutes left, such as **12m**.

179 * When the countdown runs out, the minutes disappear and the icon turns red, or your theme's error color, until the next response. The cache has likely expired, so expect a slower, more expensive response to your next message while the cache rebuilds. If the five-minute lifetime keeps running out between your messages, see [Choose the TTL yourself](/docs/en/prompt-caching.md#choose-the-ttl-yourself).

180 * Right after the conversation is [compacted](/docs/en/prompt-caching.md#compacting-the-conversation), the icon also turns red without minutes until the next response, because the cache doesn't cover the compacted conversation yet.

181* **Agent map**: when the conversation includes [subagents](/docs/en/sub-agents.md), an agent count such as **2 agents** appears at the bottom of the prompt box. Its dot shows whether any subagent is working or waiting for your permission.

179 * When the countdown runs out, the minutes disappear and the icon turns red, or your theme's error color, until the next response. The cache has likely expired, so expect a slower, more expensive response to your next message while the cache rebuilds. If the five-minute lifetime keeps running out between your messages, see [Choose the TTL yourself](https://code.claude.com/docs/en/prompt-caching.md#choose-the-ttl-yourself).

180 * Right after the conversation is [compacted](https://code.claude.com/docs/en/prompt-caching.md#compacting-the-conversation), the icon also turns red without minutes until the next response, because the cache doesn't cover the compacted conversation yet.

181* **Agent map**: when the conversation includes [subagents](https://code.claude.com/docs/en/sub-agents.md), an agent count such as **2 agents** appears at the bottom of the prompt box. Its dot shows whether any subagent is working or waiting for your permission.

182182

183183 Click the agent count to open the agent map, which draws the conversation's subagents as a tree under the main agent, each with its status, elapsed time, and token count. Click a subagent to see its prompt and tool calls, open its read-only transcript, or stop it while it runs. Requires Claude Code v2.1.269 or later.

184184

185 The map also lists the session's other [background tasks](/docs/en/tools-reference.md#background-commands), such as background shell commands and [monitors](/docs/en/tools-reference.md#monitor-tool), below the agents. Click a row to open the task's card and stop it there.

185 The map also lists the session's other [background tasks](https://code.claude.com/docs/en/tools-reference.md#background-commands), such as background shell commands and [monitors](https://code.claude.com/docs/en/tools-reference.md#monitor-tool), below the agents. Click a row to open the task's card and stop it there.

186186

187187 To open the map when no agent count is showing, such as when Claude has started a background shell but no subagents, type `/tasks` in the prompt box. Background tasks in the map and the typed `/tasks` require Claude Code v2.1.277 or later.

188188

189189 With Claude Code v2.1.286 or later, when you click **Stop** or press `Esc`, the current turn ends. Background agents keep running until they finish or you stop them from the map.

190* **Extended thinking**: lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). Claude's reasoning appears in the conversation as collapsed blocks: click a block to read it, or press `Ctrl+O` to expand or collapse every thinking block in the session. See [Extended thinking](/docs/en/model-config.md#extended-thinking) for details.

190* **Extended thinking**: lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). Claude's reasoning appears in the conversation as collapsed blocks: click a block to read it, or press `Ctrl+O` to expand or collapse every thinking block in the session. See [Extended thinking](https://code.claude.com/docs/en/model-config.md#extended-thinking) for details.

191191* **Multi-line input**: press `Shift+Enter` to add a new line without sending. This also works in the "Other" free-text input of question dialogs.

192192

193193### Reference files and folders

from line 199

199199What's in @src/components/ (include a trailing slash for folders)

200200```

201201

202For large PDFs, you can ask Claude to read specific pages instead of the whole file. Ask for a single page, a range like pages 1-10, or an open-ended range like page 3 onward. Reading specific pages requires [poppler-utils](/docs/en/tools-reference.md#read-tool-behavior) on the machine where Claude Code runs.

202For large PDFs, you can ask Claude to read specific pages instead of the whole file. Ask for a single page, a range like pages 1-10, or an open-ended range like page 3 onward. Reading specific pages requires [poppler-utils](https://code.claude.com/docs/en/tools-reference.md#read-tool-behavior) on the machine where Claude Code runs.

203203

204204When you select text in the editor, Claude can see your highlighted code automatically. The prompt box footer shows how many lines are selected. Press `Option+K` (Mac) / `Alt+K` (Windows/Linux) to insert an @-mention with the file path and line numbers, for example `@app.ts#5-10`. Click the **X** on the selection indicator to remove it so Claude doesn't receive the selection. The indicator comes back when you select other text.

205205

from line 224

224224

225225### Paste text

226226

227Text you paste stays visible in the prompt box, rather than collapsing to a placeholder as it does [in the terminal](/docs/en/terminal-config.md#paste-large-content). In sessions where Claude Code [marks pasted text](/docs/en/terminal-config.md#how-claude-treats-pasted-text), Claude still sees a large paste as text you pasted rather than typed.

227Text you paste stays visible in the prompt box, rather than collapsing to a placeholder as it does [in the terminal](https://code.claude.com/docs/en/terminal-config.md#paste-large-content). In sessions where Claude Code [marks pasted text](https://code.claude.com/docs/en/terminal-config.md#how-claude-treats-pasted-text), Claude still sees a large paste as text you pasted rather than typed.

228228

229Claude Code also removes [invisible Unicode characters](/docs/en/interactive-mode.md#invisible-characters-in-prompts) from text you paste into the prompt box and from anything else you send:

229Claude Code also removes [invisible Unicode characters](https://code.claude.com/docs/en/interactive-mode.md#invisible-characters-in-prompts) from text you paste into the prompt box and from anything else you send:

230230

231231* If a notice such as `Removed 3 invisible characters from the pasted text` appears when you paste, the text went in without those characters.

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

from line 246

246246

247247Click 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.

248248

249Click any conversation to resume it. If the conversation is already open in another tab of the current window, clicking it switches to that tab. When a notice says the conversation is still open somewhere else, see [how to continue it in this window](#the-conversation-is-still-open-somewhere-else). If the conversation opens with no messages showing, see [why a resumed conversation is blank at first](#a-resumed-conversation-is-blank-at-first). For more on resuming sessions, see [Manage sessions](/docs/en/sessions.md).

250250

251251* **Session titles**: new sessions receive AI-generated titles based on your first message.

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

253* **Conversations missing with [`claudeProcessWrapper`](#extension-settings) set**: update the extension to version 2.1.304 or later. The list then includes the conversations that were missing, along with sessions that `claude -p` or the [Agent SDK](/docs/en/agent-sdk/overview.md) started in this workspace.

253* **Conversations missing with [`claudeProcessWrapper`](#extension-settings) set**: update the extension to version 2.1.304 or later. The list then includes the conversations that were missing, along with sessions that `claude -p` or the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) started in this workspace.

254254

255255By default, a session with no activity for 14 days moves to **Archived sessions** automatically, unless it is open, unread, or in a [group](#organize-sessions-into-groups). Automatic archiving requires Claude Code v2.1.265 or later. To change the period or turn it off, open the [Archive Inactive Sessions setting](vscode://settings/claudeCode.archiveInactiveSessions) and select a number of days or **Never**.

256256

from line 263

263263

264264When the conversation you resume ended in plan mode, Claude Code restores plan mode. Requires Claude Code v2.1.246 or later. Claude Code doesn't restore it in these cases:

265265

266* The extension [chooses the starting permission mode](/docs/en/permission-modes.md#switch-permission-modes) from `claudeCode.initialPermissionMode` or a pick that carries over from an earlier conversation

266* The extension [chooses the starting permission mode](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes) from `claudeCode.initialPermissionMode` or a pick that carries over from an earlier conversation

267267* You have `claudeCode.claudeProcessWrapper` configured

268* A [deny rule](/docs/en/permissions.md#manage-permissions) removes the [`ExitPlanMode`](/docs/en/tools-reference) tool

268* A [deny rule](https://code.claude.com/docs/en/permissions.md#manage-permissions) removes the [`ExitPlanMode`](https://code.claude.com/docs/en/tools-reference) tool

269269

270270#### The conversation is still open somewhere else

271271

from line 284

284284

285285### Resume cloud sessions from claude.ai

286286

287If you run [cloud sessions](/docs/en/claude-code-on-the-web.md), you can resume them directly in VS Code. This requires signing in with **Claude.ai Subscription**, not Anthropic Console.

287If you run [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md), you can resume them directly in VS Code. This requires signing in with **Claude.ai Subscription**, not Anthropic Console.

288288

289289**1. Open session history**

290290

from line 304

304304>

305305> When you resume a cloud session, the extension downloads a copy of the conversation history; changes don't sync back to claude.ai.

306306

307The Web tab also lists your [Remote Control](/docs/en/remote-control.md) sessions. If you click one that ran in the folder you have open, the extension opens that local conversation instead of downloading a copy. The extension focuses the tab already showing it, if there is one. If the extension can't rule out that another Claude process has the conversation open, you get a downloaded copy instead.

307The Web tab also lists your [Remote Control](https://code.claude.com/docs/en/remote-control.md) sessions. If you click one that ran in the folder you have open, the extension opens that local conversation instead of downloading a copy. The extension focuses the tab already showing it, if there is one. If the extension can't rule out that another Claude process has the conversation open, you get a downloaded copy instead.

308308

309309If any part of a conversation fails to download, an error appears and no copy is saved. Select the session again to retry. If you select a session that has no conversation to download yet, an error tells you where to continue it instead.

310310

from line 317

317317 The dialog also breaks down what is contributing to your plan limits:

318318

319319 * **Recommendations**: suggested changes, one per row, such as `Trim ~/code/api/CLAUDE.md · 49k tokens per request`

320 * **Fix button**: to have Claude Code apply the recommendations it can, click the button under them, such as **Fix both**. To learn which rows the button acts on and what then happens in your session, see [Apply recommendations with the fix shortcut](/docs/en/costs.md#apply-recommendations-with-the-fix-shortcut). Requires Claude Code v2.1.305 or later.

320 * **Fix button**: to have Claude Code apply the recommendations it can, click the button under them, such as **Fix both**. To learn which rows the button acts on and what then happens in your session, see [Apply recommendations with the fix shortcut](https://code.claude.com/docs/en/costs.md#apply-recommendations-with-the-fix-shortcut). Requires Claude Code v2.1.305 or later.

321321

322 The button isn't shown while [Remote Control](/docs/en/remote-control.md) is connected. If a warning reads `The usage fix wasn’t fully sent. Open usage and try again.` after Remote Control connected, [disconnect Remote Control](/docs/en/remote-control.md#check-connection-status) before you try again.

322 The button isn't shown while [Remote Control](https://code.claude.com/docs/en/remote-control.md) is connected. If a warning reads `The usage fix wasn’t fully sent. Open usage and try again.` after Remote Control connected, [disconnect Remote Control](https://code.claude.com/docs/en/remote-control.md#check-connection-status) before you try again.

323323 * **Attribution**: tables of how much usage came from each skill, subagent, plugin, and MCP server

324324

325325 Use the Day and Week toggle to switch between the last 24 hours and the last 7 days. The figures are approximate and computed from local sessions on this machine, so usage from other devices or claude.ai is not included.

326* **Other sign-ins**: when plan limits don't apply to your sign-in, such as on a [third-party provider](#use-third-party-providers) or with an API key, the Usage section shows the session's own cost and token usage instead. The CLI's `/usage` shows the same totals in its [Session block](/docs/en/costs.md#track-your-costs). The sessions list in the Activity Bar also shows the active session's totals under its **Account & usage** header. Requires Claude Code v2.1.277 or later.

326* **Other sign-ins**: when plan limits don't apply to your sign-in, such as on a [third-party provider](#use-third-party-providers) or with an API key, the Usage section shows the session's own cost and token usage instead. The CLI's `/usage` shows the same totals in its [Session block](https://code.claude.com/docs/en/costs.md#track-your-costs). The sessions list in the Activity Bar also shows the active session's totals under its **Account & usage** header. Requires Claude Code v2.1.277 or later.

327327

328For more on tracking and reducing usage, see [Track your costs](/docs/en/costs.md#track-your-costs).

328For more on tracking and reducing usage, see [Track your costs](https://code.claude.com/docs/en/costs.md#track-your-costs).

329329

330330### Rewind with checkpoints

331331

from line 335

335335* **Rewind code to here**: revert file changes back to this point in the conversation while keeping the full conversation history

336336* **Fork conversation and rewind code**: start a new conversation branch and revert file changes to this point

337337

338For full details on how checkpoints work and their limitations, see [Checkpointing](/docs/en/checkpointing.md).

338For full details on how checkpoints work and their limitations, see [Checkpointing](https://code.claude.com/docs/en/checkpointing.md).

339339

340340## Customize your workflow

341341

from line 374

374374

375375To stop Claude from continuing an interrupted step after a reload, open the [Continue After Reload setting](vscode://settings/claudeCode.continueAfterReload) and uncheck it.

376376

377If you set [`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), it has no effect in the panel. That's because the extension removes those variables before it starts the panel's sessions.

377If you set [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](https://code.claude.com/docs/en/env-vars#variables) or any other `CLAUDE_CODE_RESUME_` variable in VS Code's environment or in the [`environmentVariables` setting](#extension-settings), it has no effect in the panel. That's because the extension removes those variables before it starts the panel's sessions.

378378

379379#### A conversation was not reopened

380380

from line 424

424424

425425## Manage plugins

426426

427The VS Code extension includes a graphical interface for installing and managing [plugins](/docs/en/plugins/overview.md). Type `/plugins` in the prompt box to open the **Manage plugins** interface.

427The VS Code extension includes a graphical interface for installing and managing [plugins](https://code.claude.com/docs/en/plugins/overview.md). Type `/plugins` in the prompt box to open the **Manage plugins** interface.

428428

429429### Install plugins

430430

from line 434

434434

435435* **Installed plugins** appear at the top with toggle switches to enable or disable them.

436436 * If you turn off a plugin that your project's shared `.claude/settings.json` turns on, the extension asks first: **Disable for me** turns it off only for you, while **Disable for everyone** changes the shared file.

437 * A plugin that failed to load shows a short reason on its row. Click the reason for what you can do about it, including copying the full error message to look up in [Troubleshoot plugins](/docs/en/plugins/troubleshooting.md).

438438* **Available plugins** from your configured marketplaces appear below

439439* Search to filter plugins by name or description

440440* Click **Install** on any available plugin

from line 445

445445* **Install for this project**: shared with project collaborators (project scope)

446446* **Install locally**: only for you, only in this repository (local scope)

447447

448Once the install finishes, a form asks for any of the plugin's [configuration options](/docs/en/plugins/components.md#user-configuration) that aren't set yet. To review or change the options later, click the gear icon on the plugin's row.

448Once the install finishes, a form asks for any of the plugin's [configuration options](https://code.claude.com/docs/en/plugins/components.md#user-configuration) that aren't set yet. To review or change the options later, click the gear icon on the plugin's row.

449449

450450Sensitive text fields are masked, and a secret you saved earlier shows **(unchanged)**. Leave the field blank to keep the saved value. After you save changes, the open sessions reload their plugins and the dialog shows **Restart Claude to apply plugin changes**.

451451

452452### Uninstall plugins

453453

454Each installed row names the [scope](/docs/en/plugins/install.md#choose-an-install-scope) it's installed at. To uninstall that installation, click the row's trash icon. A dimmed trash icon marks a row you can't uninstall from this workspace, such as a plugin your organization manages or one installed for another project.

454Each installed row names the [scope](https://code.claude.com/docs/en/plugins/install.md#choose-an-install-scope) it's installed at. To uninstall that installation, click the row's trash icon. A dimmed trash icon marks a row you can't uninstall from this workspace, such as a plugin your organization manages or one installed for another project.

455455

456456The extension asks first in two cases:

457457

458* **A plugin your project's shared `.claude/settings.json` turns on**: choose **Disable for me**, which keeps the plugin installed for your collaborators, or **Uninstall for everyone**, which removes the project's installation with [`--keep-data`](/docs/en/plugins/cli-reference#what-an-uninstall-deletes-and-keeps), so the plugin's saved data directory stays. If you already turned the plugin off for yourself, the trash icon removes your own installation without the question.

458* **A plugin your project's shared `.claude/settings.json` turns on**: choose **Disable for me**, which keeps the plugin installed for your collaborators, or **Uninstall for everyone**, which removes the project's installation with [`--keep-data`](https://code.claude.com/docs/en/plugins/cli-reference#what-an-uninstall-deletes-and-keeps), so the plugin's saved data directory stays. If you already turned the plugin off for yourself, the trash icon removes your own installation without the question.

459459* **Otherwise, the last installation of a plugin with saved data**: choose whether to keep or delete the data; **Keep** is the default

460460

461461### Share a plugin install link

from line 471

471471| Parameter | Description |

472472| - | - |

473473| `plugin` | The plugin's name as its marketplace lists it. Required. |

474| `marketplace` | The marketplace's [source](/docs/en/plugins/install.md#add-a-marketplace): a GitHub `owner/repo`, an `https://` URL, or a git SSH address such as `[email protected]:owner/repo.git`. Defaults to `anthropics/claude-plugins-official` when omitted. |

474| `marketplace` | The marketplace's [source](https://code.claude.com/docs/en/plugins/install.md#add-a-marketplace): a GitHub `owner/repo`, an `https://` URL, or a git SSH address such as `[email protected]:owner/repo.git`. Defaults to `anthropics/claude-plugins-official` when omitted. |

475475

476476The extension checks both values before it opens anything:

477477

from line 487

487487* **The plugin is already installed**: the dialog says so, and nothing changes.

488488* **A different marketplace with the same name is already added**: the dialog says the link's marketplace wasn't added, and nothing installs.

489489

490GitHub READMEs, issues, and some other Markdown hosts strip links whose scheme isn't `http` or `https`, so a `vscode://` link there renders as plain text. Put the URL in a code block on those hosts, as [The link renders as plain text instead of being clickable](/docs/en/deep-links.md#the-link-renders-as-plain-text-instead-of-being-clickable) describes for `claude-cli://` links.

490GitHub READMEs, issues, and some other Markdown hosts strip links whose scheme isn't `http` or `https`, so a `vscode://` link there renders as plain text. Put the URL in a code block on those hosts, as [The link renders as plain text instead of being clickable](https://code.claude.com/docs/en/deep-links.md#the-link-renders-as-plain-text-instead-of-being-clickable) describes for `claude-cli://` links.

491491

492492### Manage marketplaces

493493

from line 495

495495

496496* Enter a GitHub repo, URL, or local path to add a new marketplace

497497* Click the refresh icon to update a marketplace's plugin list

498* Click the trash icon to remove a marketplace. Removing it [uninstalls every plugin you installed from it](/docs/en/plugins/install.md#manage-marketplaces), so a confirmation names those plugins first

498* Click the trash icon to remove a marketplace. Removing it [uninstalls every plugin you installed from it](https://code.claude.com/docs/en/plugins/install.md#manage-marketplaces), so a confirmation names those plugins first

499499

500500Plugin changes you make in the dialog apply right away to the Claude Code sessions open in that VS Code window.

501501

from line 505

505505>

506506> The extension manages plugins by running the same commands as the CLI. Plugins and marketplaces you configure in the extension are also available in the CLI, and vice versa.

507507

508For more about the plugin system, see [Plugins](/docs/en/plugins/overview.md) and [Plugin marketplaces](/docs/en/plugins/overview.md).

508For more about the plugin system, see [Plugins](https://code.claude.com/docs/en/plugins/overview.md) and [Plugin marketplaces](https://code.claude.com/docs/en/plugins/overview.md).

509509

510510### Plugins that draw in the panel

511511

512A plugin that contains a [mod](/docs/en/plugins/mods/overview.md) can draw in the chat panel. Drawing requires extension version 2.1.299 or later. A session that [doesn't fetch feature flags](/docs/en/env-vars.md#features-that-need-feature-flag-fetching), such as one on Amazon Bedrock, needs 2.1.304 or later. From such a plugin you can see:

512A plugin that contains a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) can draw in the chat panel. Drawing requires extension version 2.1.299 or later. A session that [doesn't fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), such as one on Amazon Bedrock, needs 2.1.304 or later. From such a plugin you can see:

513513

514514* A pane beside the conversation or above the prompt box

515515* A toast or a status line above the prompt box

from line 539

539539

540540For more on working with the browser, see:

541541

542* [Enable Chrome by default](/docs/en/chrome.md#enable-chrome-by-default): have each session connect to your browser as it starts, without typing `@browser`

543* [Permission prompts in VS Code sessions](/docs/en/chrome.md#permission-prompts-in-vs-code-sessions): when Claude Code asks you before a browser action

544* [Use Claude Code with Chrome](/docs/en/chrome.md): setup instructions, the full list of capabilities, and troubleshooting

542* [Enable Chrome by default](https://code.claude.com/docs/en/chrome.md#enable-chrome-by-default): have each session connect to your browser as it starts, without typing `@browser`

543* [Permission prompts in VS Code sessions](https://code.claude.com/docs/en/chrome.md#permission-prompts-in-vs-code-sessions): when Claude Code asks you before a browser action

544* [Use Claude Code with Chrome](https://code.claude.com/docs/en/chrome.md): setup instructions, the full list of capabilities, and troubleshooting

545545

546546## Work with git

547547

548Claude Code integrates with git to help with version control workflows directly in VS Code. Ask Claude to commit changes, create pull requests, or work across branches. To start Claude in an isolated worktree with its own files and branch, see [Run parallel sessions with worktrees](/docs/en/worktrees.md).

549549

550550### Create commits and pull requests

551551

from line 565

565565

566566### Move a running command or subagent to the background

567567

568When a command or a [subagent](/docs/en/sub-agents.md) keeps Claude waiting longer than you want, click **Run in background** below its tool call in the conversation. Requires Claude Code v2.1.287 or later.

568When a command or a [subagent](https://code.claude.com/docs/en/sub-agents.md) keeps Claude waiting longer than you want, click **Run in background** below its tool call in the conversation. Requires Claude Code v2.1.287 or later.

569569

570* **Timing**: the action appears once a command has run for about two seconds, or as soon as Claude starts waiting for a [subagent](/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) it spawned from the main conversation.

571* **After you click**: Claude stops waiting and continues the turn. The command or subagent keeps running as a [background task](/docs/en/tools-reference.md#background-commands) that notifies Claude when done.

570* **Timing**: the action appears once a command has run for about two seconds, or as soon as Claude starts waiting for a [subagent](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) it spawned from the main conversation.

571* **After you click**: Claude stops waiting and continues the turn. The command or subagent keeps running as a [background task](https://code.claude.com/docs/en/tools-reference.md#background-commands) that notifies Claude when done.

572572

573573To check on the task or stop it in the meantime, type `/tasks` in the prompt box to open the [agent map](#use-the-prompt-box). A subagent keeps its place in the tree of agents there, and a command is listed below the agents with its [latest output on its card](#monitor-background-processes).

574574

from line 576

576576

577577By default in VS Code, subagents don't show this action. To see why for one subagent, open its card in the [agent map](#use-the-prompt-box) and read the `Spawned by` line:

578578

579* **`Spawned by the main agent`**: the subagent started in the background, so Claude isn't waiting for it and you don't need to do anything. To have Claude wait for subagents instead, see [Let Claude wait for a subagent](/docs/en/sub-agents.md#let-claude-wait-for-a-subagent).

580* **`Spawned by` names another subagent**: the action appears only for subagents the main agent spawned, not a [nested subagent](/docs/en/sub-agents.md#let-subagents-spawn-their-own-subagents) another subagent waits for. To end the nested subagent early, click **Stop agent** on its card. The waiting subagent then carries on without that result.

579* **`Spawned by the main agent`**: the subagent started in the background, so Claude isn't waiting for it and you don't need to do anything. To have Claude wait for subagents instead, see [Let Claude wait for a subagent](https://code.claude.com/docs/en/sub-agents.md#let-claude-wait-for-a-subagent).

580* **`Spawned by` names another subagent**: the action appears only for subagents the main agent spawned, not a [nested subagent](https://code.claude.com/docs/en/sub-agents.md#let-subagents-spawn-their-own-subagents) another subagent waits for. To end the nested subagent early, click **Stop agent** on its card. The waiting subagent then carries on without that result.

581581

582582### Monitor background processes

583583

584584Type `/tasks` in the prompt box to open the [agent map](#use-the-prompt-box), which lists the session's background tasks, such as a dev server Claude left running as a background shell command. Click a task to open its card, where you can stop it. Requires Claude Code v2.1.277 or later.

585585

586For a background shell command, or a [monitor](/docs/en/tools-reference.md#monitor-tool) that runs a command, the card also shows the command's latest output and refreshes it while the command runs.

586For a background shell command, or a [monitor](https://code.claude.com/docs/en/tools-reference.md#monitor-tool) that runs a command, the card also shows the command's latest output and refreshes it while the command runs.

587587

588588#### See a background subagent's tool calls

589589

from line 637

637637xdg-open "vscode://anthropic.claude-code/open"

638638```

639639

640The `xdg-open` command comes from the `xdg-utils` package. If the shell reports it isn't found, see [xdg-open is not found on Linux](/docs/en/deep-links.md#xdg-open-is-not-found-on-linux).

640The `xdg-open` command comes from the `xdg-utils` package. If the shell reports it isn't found, see [xdg-open is not found on Linux](https://code.claude.com/docs/en/deep-links.md#xdg-open-is-not-found-on-linux).

641641

642642**Windows**

643643

from line 658

658658| Parameter | Description |

659659| - | - |

660660| `prompt` | Text to pre-fill in the prompt box. Must be URL-encoded. The prompt is pre-filled but not submitted automatically. |

661| `session` | A session ID to resume instead of starting a new conversation. The session must belong to the workspace currently open in VS Code. If the session isn't found, a fresh conversation starts instead. If the session is already open in a tab, that tab is focused. To capture a session ID programmatically, see [Continue conversations](/docs/en/headless.md#continue-conversations). |

662662

663663For example, to open a tab pre-filled with "review my changes":

664664

from line 666

666666vscode://anthropic.claude-code/open?prompt=review%20my%20changes

667667```

668668

669The extension also handles `vscode://anthropic.claude-code/install-plugin`, which [opens the plugin dialog on one plugin](#share-a-plugin-install-link). To launch a terminal session instead of a VS Code tab, use the CLI's `claude-cli://` handler. See [Launch sessions from links](/docs/en/deep-links.md).

670670

671671## Configure settings

672672

from line 673

673673You configure the extension in two places, VS Code's extension settings and the Claude Code settings file:

674674

675675* **Extension settings** in VS Code: control the extension's behavior within VS Code. Open with `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux), then go to **Extensions > Claude Code**. You can also type `/` and select **General config…** to open settings.

676* **Claude Code settings** in `~/.claude/settings.json`: shared between the extension and CLI. Use it for allowed commands, environment variables, hooks, and MCP servers. With Claude Code v2.1.283 or later, it's also one input to the permission mode conversations start in, and on earlier versions only on Pro, Max, and Team plans. [Switch permission modes](/docs/en/permission-modes.md#switch-permission-modes) lists the order. See [Settings](/docs/en/settings.md) for details.

676* **Claude Code settings** in `~/.claude/settings.json`: shared between the extension and CLI. Use it for allowed commands, environment variables, hooks, and MCP servers. With Claude Code v2.1.283 or later, it's also one input to the permission mode conversations start in, and on earlier versions only on Pro, Max, and Team plans. [Switch permission modes](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes) lists the order. See [Settings](https://code.claude.com/docs/en/settings.md) for details.

677677

678678> [!TIP]

679679>

from line 686

686686| Setting | Default | Description |

687687| - | - | - |

688688| `useTerminal` | `false` | Launch Claude in terminal mode instead of graphical panel |

689| `initialPermissionMode` | - | Controls approval prompts for new conversations: `default`, `plan`, `acceptEdits`, or `bypassPermissions`. `manual` is an alias for `default` and selects the mode labeled **Manual** in the mode indicator. When you leave it unset, the extension chooses the starting permission mode as described in [Switch permission modes](/docs/en/permission-modes.md#switch-permission-modes). |

689| `initialPermissionMode` | - | Controls approval prompts for new conversations: `default`, `plan`, `acceptEdits`, or `bypassPermissions`. `manual` is an alias for `default` and selects the mode labeled **Manual** in the mode indicator. When you leave it unset, the extension chooses the starting permission mode as described in [Switch permission modes](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes). |

690690| `preferredLocation` | `panel` | Where Claude opens: `sidebar` (right) or `panel` (new tab) |

691691| `lockEditorGroups` | `true` | [Lock the editor groups Claude starts for its tabs](#choose-where-claude-lives), so files you open while a Claude tab is focused go to another group. When off, the extension never locks an editor group. Requires Claude Code v2.1.274 or later |

692692| `autosave` | `true` | Auto-save files before Claude reads or writes them |

from line 694

694694| `useCtrlEnterToSend` | `false` | Use Ctrl/Cmd+Enter instead of Enter to send prompts |

695695| `scrollToBottomOnSend` | `true` | Scroll the conversation to the bottom when you send a message. When off, the conversation stays where you left it. Requires Claude Code v2.1.275 or later |

696696| `showMessageTimestamps` | `true` | Show when each message was sent. A date line marks where the day changes. Requires Claude Code v2.1.284 or later. Before v2.1.290, the default was `false` |

697| `spinnerVerbs` | `{"mode": "append", "verbs": []}` | Set the verbs the conversation spinner rotates through while a turn runs, with the same `mode` and `verbs` fields as the CLI's [`spinnerVerbs`](/docs/en/settings-reference#spinnerverbs). |

698698| `enableNewConversationShortcut` | `false` | Enable Cmd/Ctrl+N to start a new conversation |

699699| `enableReopenClosedSessionShortcut` | `true` | Use Cmd/Ctrl+Shift+T to reopen the most recently closed Claude session tab. When the last closed tab wasn't a Claude session, the shortcut runs VS Code's normal reopen-closed-editor command instead. |

700700| `archiveInactiveSessions` | `14` | [Archive a session automatically](#resume-past-conversations) after this many days without activity: `1`, `2`, `7`, or `14`. Set `0` to turn it off. Requires Claude Code v2.1.265 or later |

from line 703

703703| `focusView` | `false` | Hide tool calls, tool results, and thinking behind expandable rows, leaving your prompts and Claude's responses. Claude's latest to-do list stays visible; this requires Claude Code v2.1.225 or later. You can also toggle Focus view from the command menu. Requires Claude Code v2.1.221 or later |

704704| `respectGitIgnore` | `true` | Exclude .gitignore patterns from file searches and from [selection context](#reference-files-and-folders) |

705705| `usePythonEnvironment` | `true` | Activate the workspace's Python environment when running Claude. Requires the Python extension. |

706| `environmentVariables` | `[]` | Set environment variables for the Claude process. Use Claude Code settings instead for shared config. A [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars) entry applies only when its value is an absolute path; the extension doesn't expand `~` and ignores a relative value. |

706| `environmentVariables` | `[]` | Set environment variables for the Claude process. Use Claude Code settings instead for shared config. A [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars) entry applies only when its value is an absolute path; the extension doesn't expand `~` and ignores a relative value. |

707707| `disableLoginPrompt` | `false` | Skip authentication prompts (for third-party provider setups) |

708708| `allowDangerouslySkipPermissions` | `false` | Adds Bypass permissions to the mode selector. Use it only in sandboxes with no internet access. |

709709| `claudeProcessWrapper` | - | Executable used to launch the Claude process. The bundled binary path is passed as an argument when present. Set this to a separately installed `claude` binary if the extension build doesn't include one for your platform. |

from line 722

722722

723723Follow the setup guide for your provider:

724724

725* [Claude Code on Amazon Bedrock](/docs/en/amazon-bedrock.md)

726* [Claude Code on Google Cloud's Agent Platform](/docs/en/google-vertex-ai.md)

727* [Claude Code on Microsoft Foundry](/docs/en/microsoft-foundry.md)

725* [Claude Code on Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md)

726* [Claude Code on Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md)

727* [Claude Code on Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md)

728728

729729These guides cover configuring your provider in `~/.claude/settings.json`, which ensures your settings are shared between the VS Code extension and the CLI.

730730

731On a third-party provider, the extension doesn't offer features that require a claude.ai account, such as plan usage bars, [voice dictation](/docs/en/voice-dictation.md), and the Web tab for [cloud sessions](#resume-cloud-sessions-from-claude-ai). For what the Account & usage dialog shows on these sign-ins, see [Check account and usage](#check-account-and-usage).

731On a third-party provider, the extension doesn't offer features that require a claude.ai account, such as plan usage bars, [voice dictation](https://code.claude.com/docs/en/voice-dictation.md), and the Web tab for [cloud sessions](#resume-cloud-sessions-from-claude-ai). For what the Account & usage dialog shows on these sign-ins, see [Check account and usage](#check-account-and-usage).

732732

733733A claude.ai sign-in left over from an earlier `/login` stays unused: the extension doesn't send it with any request.

734734

735735## Use a screen reader

736736

737The extension's chat panel works with screen readers. You don't need to turn anything on: the extension announces conversation activity for every user, with no visual change. This is separate from the CLI's opt-in [screen reader mode](/docs/en/accessibility.md), which adapts the terminal interface.

737The extension's chat panel works with screen readers. You don't need to turn anything on: the extension announces conversation activity for every user, with no visual change. This is separate from the CLI's opt-in [screen reader mode](https://code.claude.com/docs/en/accessibility.md), which adapts the terminal interface.

738738

739739Screen reader support in the chat panel requires Claude Code v2.1.236 or later.

740740

from line 742

742742

743743* **Claude's replies**: the extension announces each reply once, when it's complete, and stays silent while text streams in. Your screen reader reads code blocks as a line-count summary, reads links by their label, and reads tables cell by cell; the full reply stays readable in the transcript.

744744* **Permission requests and questions**: the extension announces a request when its permission prompt appears, naming the tool Claude wants to use. It announces in the same way when Claude asks you a question and when Claude finishes a plan and waits for your review.

745* **Status changes**: the extension announces when Claude starts working, when Claude is ready for your input, and when Claude Code starts compacting the conversation. If you send a prompt while the session's [SessionStart](/docs/en/hooks.md#sessionstart) hooks are still running, your screen reader also says "Running start-up hooks."

745* **Status changes**: the extension announces when Claude starts working, when Claude is ready for your input, and when Claude Code starts compacting the conversation. If you send a prompt while the session's [SessionStart](https://code.claude.com/docs/en/hooks.md#sessionstart) hooks are still running, your screen reader also says "Running start-up hooks."

746746* **Queued messages**: when you send a message while Claude is working, the extension announces "Message queued." for that message.

747* **Errors and model prompts**: the extension announces errors in the conversation, and announces when the [usage-credits consent prompt](/docs/en/model-config.md#fable-and-usage-credits) or the [flagged-request prompt](/docs/en/model-config.md#ask-before-switching) appears.

747* **Errors and model prompts**: the extension announces errors in the conversation, and announces when the [usage-credits consent prompt](https://code.claude.com/docs/en/model-config.md#fable-and-usage-credits) or the [flagged-request prompt](https://code.claude.com/docs/en/model-config.md#ask-before-switching) appears.

748748

749749While Claude works, your screen reader reads a text label in place of the progress spinner's animation.

750750

from line 770

770770

771771## VS Code extension vs. Claude Code CLI

772772

773Claude Code is available as both a VS Code extension (graphical panel) and a CLI (command-line interface in the terminal). Some features are only available in the CLI. If you need a CLI-only feature, run `claude` in VS Code's integrated terminal. This requires the [standalone CLI install](/docs/en/setup.md): the extension does not add `claude` to your PATH. See [Run CLI in VS Code](#run-cli-in-vs-code).

773Claude Code is available as both a VS Code extension (graphical panel) and a CLI (command-line interface in the terminal). Some features are only available in the CLI. If you need a CLI-only feature, run `claude` in VS Code's integrated terminal. This requires the [standalone CLI install](https://code.claude.com/docs/en/setup.md): the extension does not add `claude` to your PATH. See [Run CLI in VS Code](#run-cli-in-vs-code).

774774

775775| Feature | CLI | VS Code Extension |

776776| - | - | - |

777| Commands and skills | [All](/docs/en/commands.md) | Subset (type `/` to see available) |

777| Commands and skills | [All](https://code.claude.com/docs/en/commands.md) | Subset (type `/` to see available) |

778778| MCP server config | Yes | Yes: [add and manage servers](#connect-to-external-tools-with-mcp) with `/mcp` in the chat panel |

779779| Checkpoints | Yes | Yes |

780780| `!` Bash shortcut | Yes | No |

from line 784

784784

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

786786

787Installing 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](/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](/docs/en/troubleshoot-install.md#verify-your-path).

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

788788

789789### Switch between extension and CLI

790790

from line 797

797797To manage MCP servers without leaving VS Code, type `/mcp` in the chat panel. From the dialog that opens, you can:

798798

799799* Add servers

800* Remove servers saved at the local, user, or project [scope](/docs/en/mcp.md#mcp-installation-scopes)

800* Remove servers saved at the local, user, or project [scope](https://code.claude.com/docs/en/mcp.md#mcp-installation-scopes)

801801* Enable or disable servers

802802* Reconnect to a server

803803* Manage OAuth authentication

from line 817

817817

818818> [!NOTE]

819819>

820> To find servers to connect, see [Find and build MCP servers](/docs/en/mcp.md#find-and-build-mcp-servers).

820> To find servers to connect, see [Find and build MCP servers](https://code.claude.com/docs/en/mcp.md#find-and-build-mcp-servers).

821821

822822## The built-in IDE MCP server

823823

from line 831

831831

832832**Selection and open-file context.** While connected, the CLI includes your current editor selection and the path of the active file as context on each prompt you send. The transcript shows a `⧉ Selected N lines from <file>` line when this happens. These cases change that context:

833833

834* **Queued messages**: if you [queue a message while Claude works](/docs/en/interactive-mode.md#queue-messages-while-claude-works), it keeps the selection you had when you pressed `Enter`, whatever you select afterward.

835* **Sensitive files**: to exclude a sensitive file such as `.env`, add a [`Read` deny rule](/docs/en/permissions#read-and-edit) for its path. A matching deny rule prevents both the selected text and the open-file notice for that file from reaching Claude.

834* **Queued messages**: if you [queue a message while Claude works](https://code.claude.com/docs/en/interactive-mode.md#queue-messages-while-claude-works), it keeps the selection you had when you pressed `Enter`, whatever you select afterward.

835* **Sensitive files**: to exclude a sensitive file such as `.env`, add a [`Read` deny rule](https://code.claude.com/docs/en/permissions#read-and-edit) for its path. A matching deny rule prevents both the selected text and the open-file notice for that file from reaching Claude.

836836* **Attach Open File turned off**: if you turn off the [Attach Open File setting](#extension-settings), the CLI receives the active file's path only while you have text selected in it.

837837

838838**Transport and authentication.** The server binds to `127.0.0.1` on a random port in the range 10000–65535, and the port is not configurable. The transport and the auth token work as follows:

from line 865

865865}

866866```

867867

868A `Read` deny rule covers neither tool, so block them by name with a [deny rule](/docs/en/permissions.md#mcp) as the example does.

868A `Read` deny rule covers neither tool, so block them by name with a [deny rule](https://code.claude.com/docs/en/permissions.md#mcp) as the example does.

869869

870870**Jupyter execution always asks first.** `mcp__ide__executeCode` can't run anything silently. Each call goes through these steps:

871871

from line 885

885885

886886| What you see | Where to go |

887887| - | - |

888| `API Error: 403 Request not allowed` after you sign in | [403 Forbidden after login](/docs/en/troubleshoot-install.md#403-forbidden-after-login) |

889| You're asked to sign in again after you already signed in | [Not logged in or token expired](/docs/en/troubleshoot-install.md#not-logged-in-or-token-expired) |

890| Cloud provider credentials work in your terminal but not in the extension | [Bedrock, Agent Platform, or Foundry credentials not loading](/docs/en/troubleshoot-install.md#bedrock-agent-platform-or-foundry-credentials-not-loading) |

891| `SSL certificate verification failed` or `Self-signed certificate detected` | [SSL certificate errors](/docs/en/errors.md#ssl-certificate-errors) |

888| `API Error: 403 Request not allowed` after you sign in | [403 Forbidden after login](https://code.claude.com/docs/en/troubleshoot-install.md#403-forbidden-after-login) |

889| You're asked to sign in again after you already signed in | [Not logged in or token expired](https://code.claude.com/docs/en/troubleshoot-install.md#not-logged-in-or-token-expired) |

890| Cloud provider credentials work in your terminal but not in the extension | [Bedrock, Agent Platform, or Foundry credentials not loading](https://code.claude.com/docs/en/troubleshoot-install.md#bedrock-agent-platform-or-foundry-credentials-not-loading) |

891| `SSL certificate verification failed` or `Self-signed certificate detected` | [SSL certificate errors](https://code.claude.com/docs/en/errors.md#ssl-certificate-errors) |

892892| `Dictation error: WebSocket error:` followed by a certificate error such as `unable to get local issuer certificate`, or `Remote server is not connected` on the Web tab | [Dictation or the Web tab fails behind a TLS-inspecting proxy](#dictation-or-the-web-tab-fails-behind-a-tls-inspecting-proxy) |

893| `Claude Code process exited with code 1`, or another code | [Claude Code process exited with code N](/docs/en/errors.md#claude-code-process-exited-with-code-n) |

894| `Could not locate the Claude CLI on PATH` | [Could not locate the Claude CLI on PATH](/docs/en/errors.md#could-not-locate-the-claude-cli-on-path) |

895| `The connection to Claude Code ended before this message completed` | [The connection to Claude Code ended before this message completed](/docs/en/errors.md#the-connection-to-claude-code-ended-before-this-message-completed) |

893| `Claude Code process exited with code 1`, or another code | [Claude Code process exited with code N](https://code.claude.com/docs/en/errors.md#claude-code-process-exited-with-code-n) |

894| `Could not locate the Claude CLI on PATH` | [Could not locate the Claude CLI on PATH](https://code.claude.com/docs/en/errors.md#could-not-locate-the-claude-cli-on-path) |

895| `The connection to Claude Code ended before this message completed` | [The connection to Claude Code ended before this message completed](https://code.claude.com/docs/en/errors.md#the-connection-to-claude-code-ended-before-this-message-completed) |

896896| `claude` isn't found in VS Code's integrated terminal | [Run CLI in VS Code](#run-cli-in-vs-code) |

897897

898898### Extension won't install

from line 925

925925

926926### Ctrl+J adds a new line in the prompt box

927927

928To stop `Ctrl+J` from adding a new line in the prompt box, [unbind the key](/docs/en/keybindings.md#unbind-default-shortcuts) in Claude Code's `keybindings.json` file. The extension reads this file in version 2.1.309 or later, so update an older extension in the Extensions view first.

928To stop `Ctrl+J` from adding a new line in the prompt box, [unbind the key](https://code.claude.com/docs/en/keybindings.md#unbind-default-shortcuts) in Claude Code's `keybindings.json` file. The extension reads this file in version 2.1.309 or later, so update an older extension in the Extensions view first.

929929

930930This example is the whole file with the one entry that unbinds the key, `"ctrl+j": null` in a `Chat` block:

931931

from line 997

997997

998998### Dictation or the Web tab fails behind a TLS-inspecting proxy

999999

1000When dictation or the Web tab fails with a certificate error such as `unable to get local issuer certificate`, set [`NODE_EXTRA_CA_CERTS`](/docs/en/network-config#custom-ca-certificates) in the `env` block of `~/.claude/settings.json`. Set it to the path of a PEM file with your proxy's root CA certificate, which your IT team can give you. That error text is on the microphone button or in the extension's logs:

1000When dictation or the Web tab fails with a certificate error such as `unable to get local issuer certificate`, set [`NODE_EXTRA_CA_CERTS`](https://code.claude.com/docs/en/network-config#custom-ca-certificates) in the `env` block of `~/.claude/settings.json`. Set it to the path of a PEM file with your proxy's root CA certificate, which your IT team can give you. That error text is on the microphone button or in the extension's logs:

10011001

10021002* **Dictation**: the microphone button shows the error text after `Dictation error: WebSocket error:`.

10031003* **Web tab**: the tab that lists [cloud sessions](#resume-cloud-sessions-from-claude-ai) shows `Remote server is not connected` without the error text. To read it in the logs:

from line 1043

104310432. Search for "Claude Code"

104410443. Click **Uninstall**

10451045

1046If 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`](/docs/en/settings-reference#autoinstallideextension) to `false`. You can also set the [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/docs/en/env-vars) environment variable to `1`.

1046If 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`.

10471047

10481048To also remove extension data and reset all settings, delete the extension's storage directory for your platform.

10491049

from line 1065

10651065Remove-Item -Recurse -Force "$env:APPDATA\Code\User\globalStorage\anthropic.claude-code"

10661066```

10671067

1068For additional help, see the [troubleshooting guide](/docs/en/troubleshooting.md).

1068For additional help, see the [troubleshooting guide](https://code.claude.com/docs/en/troubleshooting.md).

10691069

10701070## Next steps

10711071

10721072Now that you have Claude Code set up in VS Code:

10731073

1074* [Explore common workflows](/docs/en/common-workflows.md) to get the most out of Claude Code

1075* [Set up MCP servers](/docs/en/mcp.md) to extend Claude's capabilities with external tools. Add and manage them with `/mcp` in the chat panel.

1076* [Configure Claude Code settings](/docs/en/settings.md) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.

1077* [Review security safeguards](/docs/en/security.md) and [data usage](/docs/en/data-usage.md) for Claude Code

1074* [Explore common workflows](https://code.claude.com/docs/en/common-workflows.md) to get the most out of Claude Code

1075* [Set up MCP servers](https://code.claude.com/docs/en/mcp.md) to extend Claude's capabilities with external tools. Add and manage them with `/mcp` in the chat panel.

1076* [Configure Claude Code settings](https://code.claude.com/docs/en/settings.md) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.

1077* [Review security safeguards](https://code.claude.com/docs/en/security.md) and [data usage](https://code.claude.com/docs/en/data-usage.md) for Claude Code

10781078

web-quickstart Changed · +40 / -40 lines

from line 17

1717* **Tasks that don't need frequent steering**: submit a well-defined task, do something else, and review the result when Claude is done

1818* **Code questions and exploration**: understand a codebase or trace how a feature is implemented without a local checkout

1919

20For work that needs your local config, tools, or environment, running Claude Code locally or using [Remote Control](/docs/en/remote-control.md) is a better fit.

20For work that needs your local config, tools, or environment, running Claude Code locally or using [Remote Control](https://code.claude.com/docs/en/remote-control.md) is a better fit.

2121

2222## How sessions run

2323

24The steps below describe Anthropic-hosted sessions. In a [self-hosted environment](/docs/en/self-hosted-environments), the clone and everything after it run on your organization's own runners, where network boundaries, setup, and push behavior are operator-configured. When you submit a task:

24The steps below describe Anthropic-hosted sessions. In a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments), the clone and everything after it run on your organization's own runners, where network boundaries, setup, and push behavior are operator-configured. When you submit a task:

2525

261. **Clone and prepare**: your repository is cloned to an Anthropic-managed VM, and your [setup script](/docs/en/cloud-environments.md#setup-scripts) runs if configured.

272. **Configure network**: internet access is set based on your environment's [access level](/docs/en/cloud-environments.md#access-levels).

261. **Clone and prepare**: your repository is cloned to an Anthropic-managed VM, and your [setup script](https://code.claude.com/docs/en/cloud-environments.md#setup-scripts) runs if configured.

272. **Configure network**: internet access is set based on your environment's [access level](https://code.claude.com/docs/en/cloud-environments.md#access-levels).

28283. **Work**: Claude analyzes code, makes changes, runs tests, and checks its work. You can watch and steer throughout, or step away and come back when it's done.

29294. **Push the branch**: when Claude reaches a stopping point, it pushes its branch to GitHub. You review the diff, leave inline comments, create a PR, or send another message to keep going.

3030

from line 34

3434

3535Claude Code behaves the same everywhere. What changes is where the session runs and whether your local configuration is available:

3636

3838| :- | :- | :- | :- |

4040| **You start it from** | claude.ai/code, the Claude mobile app, the Desktop app with **Cloud** selected, or `claude --cloud` | Your terminal, your IDE, or the Desktop app with **Local** selected | Your terminal, the VS Code extension, or the Desktop app |

4242| **Uses your local config** | No, repo only | Yes | Yes |

43| **Requires GitHub** | Yes, or [bundle a local repo](/docs/en/claude-code-on-the-web.md#send-local-repositories-without-github) via `--cloud` | No | No |

43| **Requires GitHub** | Yes, or [bundle a local repo](https://code.claude.com/docs/en/claude-code-on-the-web.md#send-local-repositories-without-github) via `--cloud` | No | No |

4444| **Keeps running if you disconnect** | Yes | No | While the session stays open on your machine |

45| **[Permission modes](/docs/en/permission-modes.md)** | Accept edits, Plan, Auto | All modes in the terminal; see [Switch permission modes](/docs/en/permission-modes.md#switch-permission-modes) for the IDE and Desktop app | Manual, Accept edits, Plan, or Auto from claude.ai and the mobile app |

45| **[Permission modes](https://code.claude.com/docs/en/permission-modes.md)** | Accept edits, Plan, Auto | All modes in the terminal; see [Switch permission modes](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes) for the IDE and Desktop app | Manual, Accept edits, Plan, or Auto from claude.ai and the mobile app |

4747

48See the [terminal quickstart](/docs/en/quickstart.md), [Desktop app](/docs/en/desktop.md), or [Remote Control](/docs/en/remote-control.md) docs to set up local sessions.

48See the [terminal quickstart](https://code.claude.com/docs/en/quickstart.md), [Desktop app](https://code.claude.com/docs/en/desktop.md), or [Remote Control](https://code.claude.com/docs/en/remote-control.md) docs to set up local sessions.

4949

5050## Connect GitHub

5151

from line 53

5353

5454> [!NOTE]

5555>

56> On Team and Enterprise plans, the **Sign in with GitHub** step works only after an [Owner](/docs/en/server-managed-settings.md#access-control) of your Claude organization turns on the GitHub connector at [**Organization settings > Connectors**](https://claude.ai/admin-settings/connectors). Until then, that step shows "GitHub access is required for Claude Code cloud sessions" instead of a sign-in button. After the connector is on, reload [claude.ai/code](https://claude.ai/code) and start again from the first step. A second toggle, [Quick setup](/docs/en/claude-code-on-the-web.md#quick-setup-for-team-and-enterprise) at [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code), is optional: with it on, `/web-setup` works and onboarding creates the environment for members.

56> On Team and Enterprise plans, the **Sign in with GitHub** step works only after an [Owner](https://code.claude.com/docs/en/server-managed-settings.md#access-control) of your Claude organization turns on the GitHub connector at [**Organization settings > Connectors**](https://claude.ai/admin-settings/connectors). Until then, that step shows "GitHub access is required for Claude Code cloud sessions" instead of a sign-in button. After the connector is on, reload [claude.ai/code](https://claude.ai/code) and start again from the first step. A second toggle, [Quick setup](https://code.claude.com/docs/en/claude-code-on-the-web.md#quick-setup-for-team-and-enterprise) at [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code), is optional: with it on, `/web-setup` works and onboarding creates the environment for members.

5757

5858**1. Visit claude.ai/code**

5959

from line 63

6363

6464After you sign in, claude.ai/code prompts you to connect GitHub. Follow the prompt, and claude.ai/code sends you to GitHub's authorization page. Approve the authorization request, and GitHub returns you to claude.ai/code. Cloud sessions work with existing GitHub repositories. To start a new project, [create a repository with a README on GitHub](https://github.com/new) first.

6565

66With this connection, a session can clone any public repository, but can work in a private repository only when the Claude GitHub App is installed on it. [Install the Claude GitHub App](https://github.com/apps/claude/installations/new) on each GitHub account or organization whose private repositories you want to use. On a GitHub organization, an organization owner may need to approve the installation. Installing it also enables [Auto-fix](/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests), which lets Claude respond to CI failures and review comments on pull requests in those repositories.

66With this connection, a session can clone any public repository, but can work in a private repository only when the Claude GitHub App is installed on it. [Install the Claude GitHub App](https://github.com/apps/claude/installations/new) on each GitHub account or organization whose private repositories you want to use. On a GitHub organization, an organization owner may need to approve the installation. Installing it also enables [Auto-fix](https://code.claude.com/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests), which lets Claude respond to CI failures and review comments on pull requests in those repositories.

6767

68When you connect, Claude also links the GitHub accounts you own to your Claude organization, if they have the Claude GitHub App installed. On Team and Enterprise plans, admins see those accounts in the [connected GitHub accounts list](/docs/en/admin-setup.md#connected-github-accounts).

68When you connect, Claude also links the GitHub accounts you own to your Claude organization, if they have the Claude GitHub App installed. On Team and Enterprise plans, admins see those accounts in the [connected GitHub accounts list](https://code.claude.com/docs/en/admin-setup.md#connected-github-accounts).

6969

7070If onboarding prompts you to install the Claude GitHub App at this point and you'd rather do it later, click **Skip**.

7171

7272**3. Set up your Default environment**

7373

74A [cloud environment](/docs/en/cloud-environments.md) is the saved configuration that controls what network access Claude has during sessions and what runs when a session starts. What happens after you connect GitHub depends on your plan:

74A [cloud environment](https://code.claude.com/docs/en/cloud-environments.md) is the saved configuration that controls what network access Claude has during sessions and what runs when a session starts. What happens after you connect GitHub depends on your plan:

7575

7676* **Pro and Max**: onboarding creates an environment named **Default** for you.

77* **Team and Enterprise**: onboarding shows a **Create your first cloud environment** form. Leave the prefilled name and network access unchanged and click **Create & finish** to create the **Default** environment. If an Owner has turned on [Quick setup](/docs/en/claude-code-on-the-web.md#quick-setup-for-team-and-enterprise), onboarding creates **Default** for you instead.

77* **Team and Enterprise**: onboarding shows a **Create your first cloud environment** form. Leave the prefilled name and network access unchanged and click **Create & finish** to create the **Default** environment. If an Owner has turned on [Quick setup](https://code.claude.com/docs/en/claude-code-on-the-web.md#quick-setup-for-team-and-enterprise), onboarding creates **Default** for you instead.

7878

79**Default** uses [`Trusted` network access](/docs/en/cloud-environments#access-levels): sessions reach [common package registries](/docs/en/cloud-environments.md#default-allowed-domains) and other allowlisted domains, and nothing else through the session's network. See [Installed tools](/docs/en/cloud-environments.md#installed-tools) for what's available without any configuration.

79**Default** uses [`Trusted` network access](https://code.claude.com/docs/en/cloud-environments#access-levels): sessions reach [common package registries](https://code.claude.com/docs/en/cloud-environments.md#default-allowed-domains) and other allowlisted domains, and nothing else through the session's network. See [Installed tools](https://code.claude.com/docs/en/cloud-environments.md#installed-tools) for what's available without any configuration.

8080

81For a first project, the **Default** environment works as is. To change its network access, add environment variables, or run a [setup script](/docs/en/cloud-environments.md#setup-scripts) before sessions start, [edit it or create additional environments](/docs/en/cloud-environments.md#configure-your-environment).

81For a first project, the **Default** environment works as is. To change its network access, add environment variables, or run a [setup script](https://code.claude.com/docs/en/cloud-environments.md#setup-scripts) before sessions start, [edit it or create additional environments](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment).

8282

8383### Connect from your terminal

8484

85If you already use the GitHub CLI (`gh`), you can connect GitHub for cloud sessions from your terminal. This requires the [Claude Code CLI](/docs/en/quickstart.md). On Team and Enterprise plans, `/web-setup` is available only after an Owner turns on [Quick setup](/docs/en/claude-code-on-the-web.md#quick-setup-for-team-and-enterprise).

85If you already use the GitHub CLI (`gh`), you can connect GitHub for cloud sessions from your terminal. This requires the [Claude Code CLI](https://code.claude.com/docs/en/quickstart.md). On Team and Enterprise plans, `/web-setup` is available only after an Owner turns on [Quick setup](https://code.claude.com/docs/en/claude-code-on-the-web.md#quick-setup-for-team-and-enterprise).

8686

87When you run `/web-setup`, Claude Code reads the token that `gh auth token` prints, asks you to confirm, and sends the token to Anthropic. Anthropic stores it encrypted with your claude.ai account, and your cloud sessions use it for GitHub access until you [remove it](#remove-the-web-setup-token). A cloud session you start yourself can then access any repository that token can access, with no Claude GitHub App installation. Threads in a [project](/docs/en/claude-projects.md#set-up-github-access) still need the Claude GitHub App.

87When you run `/web-setup`, Claude Code reads the token that `gh auth token` prints, asks you to confirm, and sends the token to Anthropic. Anthropic stores it encrypted with your claude.ai account, and your cloud sessions use it for GitHub access until you [remove it](#remove-the-web-setup-token). A cloud session you start yourself can then access any repository that token can access, with no Claude GitHub App installation. Threads in a [project](https://code.claude.com/docs/en/claude-projects.md#set-up-github-access) still need the Claude GitHub App.

8888

8989If you already connected GitHub in the browser, `/web-setup` warns you that continuing replaces that connection for your cloud sessions.

9090

9191> [!NOTE]

9292>

93> Organizations with [Zero Data Retention](/docs/en/zero-data-retention.md) enabled, or with the [HIPAA configuration](/docs/en/hipaa-setup.md) 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.

93> Organizations with [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md) enabled, or with the [HIPAA configuration](https://code.claude.com/docs/en/hipaa-setup.md) 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.

9494

9595**1. Authenticate with the GitHub CLI**

9696

from line 112

112112/web-setup

113113```

114114

115Confirm the prompt to send your `gh` token to your Claude account. On success, Claude Code prints `Connected as <your-github-username>` and opens [claude.ai/code](https://claude.ai/code) in your browser. If you don't have a cloud environment yet, `/web-setup` creates one with Trusted network access and no setup script. You can [edit the environment or add variables](/docs/en/cloud-environments.md#configure-your-environment) afterward. Once `/web-setup` completes, you can start cloud sessions from your terminal with [`--cloud`](/docs/en/claude-code-on-the-web#from-terminal-to-cloud) or set up recurring tasks with [`/schedule`](/docs/en/routines).

115Confirm the prompt to send your `gh` token to your Claude account. On success, Claude Code prints `Connected as <your-github-username>` and opens [claude.ai/code](https://claude.ai/code) in your browser. If you don't have a cloud environment yet, `/web-setup` creates one with Trusted network access and no setup script. You can [edit the environment or add variables](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment) afterward. Once `/web-setup` completes, you can start cloud sessions from your terminal with [`--cloud`](https://code.claude.com/docs/en/claude-code-on-the-web#from-terminal-to-cloud) or set up recurring tasks with [`/schedule`](https://code.claude.com/docs/en/routines).

116116

117117#### Remove the `/web-setup` token

118118

from line 132

132132

133133**2. Choose a permission mode**

134134

135The [permission mode control](/docs/en/permission-modes.md#switch-permission-modes) shows the permission mode the session will run in:

135The [permission mode control](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes) shows the permission mode the session will run in:

136136

137137* **Auto**: a classifier reviews Claude's actions instead of asking you. Appears when your organization allows auto mode and the selected model supports it

138138* **Accept edits**: Claude makes changes and pushes a branch without stopping for approval

139139* **Plan**: Claude proposes an approach and waits for you to approve it before editing files

140140

141Cloud sessions don't offer Manual or Bypass permissions. See the [full list of permission modes](/docs/en/permission-modes.md#available-modes) for what each one allows.

141Cloud sessions don't offer Manual or Bypass permissions. See the [full list of permission modes](https://code.claude.com/docs/en/permission-modes.md#available-modes) for what each one allows.

142142

143143**3. Describe the task and submit**

144144

from line 187

187187

188188**4. Keep iterating after the PR**

189189

190The session stays live after the PR is created. Paste CI failure output or reviewer comments into the chat and ask Claude to address them. To have Claude monitor the PR automatically, see [Auto-fix pull requests](/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests).

190The session stays live after the PR is created. Paste CI failure output or reviewer comments into the chat and ask Claude to address them. To have Claude monitor the PR automatically, see [Auto-fix pull requests](https://code.claude.com/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests).

191191

192192## Troubleshoot setup

193193

from line 199

199199

200200### The page only shows a GitHub login button

201201

202Cloud sessions require a connected GitHub account. Connect via the browser flow above, or run `/web-setup` from your terminal if you use the GitHub CLI. If you'd rather not connect GitHub at all, see [Remote Control](/docs/en/remote-control.md) to run Claude Code on your own machine and monitor it from your browser or phone.

202Cloud sessions require a connected GitHub account. Connect via the browser flow above, or run `/web-setup` from your terminal if you use the GitHub CLI. If you'd rather not connect GitHub at all, see [Remote Control](https://code.claude.com/docs/en/remote-control.md) to run Claude Code on your own machine and monitor it from your browser or phone.

203203

204204### "Claude Code isn't available on your account"

205205

from line 219

219219

220220If you typed it inside Claude Code and the command menu shows `No commands match "/web-setup"`, or submitting it returns `Unknown command: /web-setup`, the command is hidden because a requirement isn't met. The cause is usually that you're authenticated with an API key or third-party provider instead of a claude.ai subscription. Run `/login` to sign in with your claude.ai account.

221221

222On Team and Enterprise plans, the command is hidden by default: the [Quick setup toggle](/docs/en/claude-code-on-the-web.md#quick-setup-for-team-and-enterprise) is off until an Owner turns it on. While it's off, [connect GitHub from the browser](#connect-github) instead.

222On Team and Enterprise plans, the command is hidden by default: the [Quick setup toggle](https://code.claude.com/docs/en/claude-code-on-the-web.md#quick-setup-for-team-and-enterprise) is off until an Owner turns it on. While it's off, [connect GitHub from the browser](#connect-github) instead.

223223

224224The command is also hidden in two other cases:

225225

226* An administrator has disabled cloud sessions for your organization. In this case, submitting `/web-setup` returns [`Cloud sessions are disabled by your organization's policy`](/docs/en/errors#cloud-sessions-are-disabled-by-your-organizations-policy). Before v2.1.268, this case also returned `Unknown command: /web-setup`.

227* Your Enterprise organization has [Zero Data Retention](/docs/en/zero-data-retention.md) enabled, or has the [HIPAA configuration](/docs/en/hipaa-setup.md) applied. Either one makes cloud sessions unavailable.

226* An administrator has disabled cloud sessions for your organization. In this case, submitting `/web-setup` returns [`Cloud sessions are disabled by your organization's policy`](https://code.claude.com/docs/en/errors#cloud-sessions-are-disabled-by-your-organizations-policy). Before v2.1.268, this case also returned `Unknown command: /web-setup`.

227* Your Enterprise organization has [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md) enabled, or has the [HIPAA configuration](https://code.claude.com/docs/en/hipaa-setup.md) applied. Either one makes cloud sessions unavailable.

228228

229229### "Could not create a cloud environment" or "No cloud environment available" when using `--cloud`

230230

231Cloud session features create a default cloud environment automatically if you don't have one. If you see "Could not create a cloud environment", automatic creation failed. If you see "No cloud environment available", your CLI predates automatic creation. In either case, run `/web-setup` in the Claude Code CLI, or add an environment from the [environment selector](/docs/en/cloud-environments.md#configure-your-environment) at [claude.ai/code](https://claude.ai/code).

231Cloud session features create a default cloud environment automatically if you don't have one. If you see "Could not create a cloud environment", automatic creation failed. If you see "No cloud environment available", your CLI predates automatic creation. In either case, run `/web-setup` in the Claude Code CLI, or add an environment from the [environment selector](https://code.claude.com/docs/en/cloud-environments.md#configure-your-environment) at [claude.ai/code](https://claude.ai/code).

232232

233233### Setup script failed

234234

235235The setup script exited with a non-zero status, which blocks the session from starting. Common causes:

236236

237* A package install failed because the registry isn't in your [network access level](/docs/en/cloud-environments.md#access-levels). `Trusted` covers most package managers; `None` blocks them all.

237* A package install failed because the registry isn't in your [network access level](https://code.claude.com/docs/en/cloud-environments.md#access-levels). `Trusted` covers most package managers; `None` blocks them all.

238238* The script references a file or path that doesn't exist in a fresh clone.

239239* A command that works locally needs a different invocation on Ubuntu.

240240

from line 242

242242

243243### New sessions hang or time out during setup

244244

245If new sessions stall on the setup script step or fail with a generic container error before the script finishes, the script is likely exceeding the roughly five-minute time budget for building the [environment cache](/docs/en/cloud-environments.md#environment-caching). Heavy steps such as pulling large Docker images, syncing full dependency trees, or downloading model weights often push the total over the limit, especially when they run one after another.

245If new sessions stall on the setup script step or fail with a generic container error before the script finishes, the script is likely exceeding the roughly five-minute time budget for building the [environment cache](https://code.claude.com/docs/en/cloud-environments.md#environment-caching). Heavy steps such as pulling large Docker images, syncing full dependency trees, or downloading model weights often push the total over the limit, especially when they run one after another.

246246

247247To fix this, trim the script so it reliably finishes in under five minutes:

248248

249249* Run independent installs in parallel with `&` and a final `wait` instead of running them serially.

250* Move the largest downloads out of the setup script and into a [SessionStart hook](/docs/en/cloud-environments.md#setup-scripts-vs-sessionstart-hooks) that launches them in the background, so the session becomes usable while they finish.

250* Move the largest downloads out of the setup script and into a [SessionStart hook](https://code.claude.com/docs/en/cloud-environments.md#setup-scripts-vs-sessionstart-hooks) that launches them in the background, so the session becomes usable while they finish.

251251* Remove long retry sleeps from the setup script, since a stalled retry loop counts against the budget.

252252

253253### Session keeps running after closing the tab

254254

255This is by design. Closing the tab or navigating away doesn't stop the session. It continues running in the background until Claude finishes the current task, then idles. From the sidebar, you can [archive a session](/docs/en/claude-code-on-the-web.md#archive-sessions) to hide it from your list, or [delete it](/docs/en/claude-code-on-the-web.md#delete-sessions) to remove it permanently.

255This is by design. Closing the tab or navigating away doesn't stop the session. It continues running in the background until Claude finishes the current task, then idles. From the sidebar, you can [archive a session](https://code.claude.com/docs/en/claude-code-on-the-web.md#archive-sessions) to hide it from your list, or [delete it](https://code.claude.com/docs/en/claude-code-on-the-web.md#delete-sessions) to remove it permanently.

256256

257257## Next steps

258258

259259Now that you can submit and review tasks, these pages cover what comes next: starting cloud sessions from your terminal, scheduling recurring work, and giving Claude standing instructions.

260260

261* [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web.md): the full reference, including teleporting sessions to your terminal, session sharing, and auto-fixing pull requests

262* [Configure cloud environments](/docs/en/cloud-environments.md): network access levels, environment variables, and setup scripts for cloud sessions

263* [Cloud scheduled tasks](/docs/en/routines.md): automate work on a schedule, via API call, or in response to GitHub events

264* [CLAUDE.md](/docs/en/memory.md): give Claude persistent instructions and context that load at the start of every session

261* [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md): the full reference, including teleporting sessions to your terminal, session sharing, and auto-fixing pull requests

262* [Configure cloud environments](https://code.claude.com/docs/en/cloud-environments.md): network access levels, environment variables, and setup scripts for cloud sessions

263* [Cloud scheduled tasks](https://code.claude.com/docs/en/routines.md): automate work on a schedule, via API call, or in response to GitHub events

264* [CLAUDE.md](https://code.claude.com/docs/en/memory.md): give Claude persistent instructions and context that load at the start of every session

265265* Install the Claude mobile app for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) or [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) to monitor sessions from your phone. From the Claude Code CLI, `/mobile` shows a QR code for [claude.ai/mobile](https://claude.ai/mobile) that opens the right app store for your phone.

266266

whats-new/2026-w13 Changed · +8 / -8 lines

from line 2

33> Auto mode for hands-off permissions, computer use built in, PR auto-fix in the cloud, transcript search, and a PowerShell tool for Windows.

5Releases [v2.1.83 → v2.1.85](/docs/en/changelog.md#2-1-83)

5Releases [v2.1.83 → v2.1.85](https://code.claude.com/docs/en/changelog.md#2-1-83)

666 features · March 23–27

88Auto mode

from line 22

2222}

2323```

2424

25[Permission modes guide](/docs/en/permission-modes.md)

25[Permission modes guide](https://code.claude.com/docs/en/permission-modes.md)

2626

2727Computer use

2828Desktop

from line 37

3737Open the iOS simulator, tap through the onboarding flow, and screenshot each step

3838```

3939

40[Computer use guide](/docs/en/desktop.md#let-claude-use-your-computer)

40[Computer use guide](https://code.claude.com/docs/en/desktop.md#let-claude-use-your-computer)

4141

4242PR auto-fix

4343Web

from line 48

4848

4949After creating a PR on Claude Code web, toggle Auto fix in the CI panel.

5050

51[Auto-fix pull requests](/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests)

51[Auto-fix pull requests](https://code.claude.com/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests)

5252

5353Transcript search

5454v2.1.83

from line 64

6464N # previous match

6565```

6666

67[Fullscreen guide](/docs/en/fullscreen.md#search-and-review-the-conversation)

67[Fullscreen guide](https://code.claude.com/docs/en/fullscreen.md#search-and-review-the-conversation)

6868

6969PowerShell tool

7070preview

from line 82

8282}

8383```

8484

85[PowerShell tool docs](/docs/en/tools-reference.md#powershell-tool)

85[PowerShell tool docs](https://code.claude.com/docs/en/tools-reference.md#powershell-tool)

8686

8787Conditional hooks

8888v2.1.85

from line 105

105105}

106106```

107107

108[Hooks reference](/docs/en/hooks.md)

108[Hooks reference](https://code.claude.com/docs/en/hooks.md)

109109

110110Other wins

111111

112112Plugin `userConfig` now public: prompt for settings at enable time, keychain-backed secretsPasted images insert `[Image #N]` chips you can reference positionally`managed-settings.d/` drop-in directory for layered policy fragments`CwdChanged` and `FileChanged` hook events for direnv-style setupsAgents can declare `initialPrompt` in frontmatter to auto-submit a first turn`Ctrl+X Ctrl+E` opens your external editor, matching readlineInterrupting before any response restores your input automatically`/status` now works while Claude is respondingDeep links open in your preferred terminal, not first-detectedIdle-return nudge to `/clear` after 75+ minutes awayVS Code: rate limit banner, Esc-twice rewind picker

113113

114[Full changelog for v2.1.83–v2.1.85 →](/docs/en/changelog.md#2-1-83)

114[Full changelog for v2.1.83–v2.1.85 →](https://code.claude.com/docs/en/changelog.md#2-1-83)

115115

whats-new/2026-w14 Changed · +7 / -7 lines

from line 2

33> Computer use in the CLI, interactive in-product lessons, flicker-free rendering, per-tool MCP result-size overrides, and plugin executables on PATH.

5Releases [v2.1.86 → v2.1.91](/docs/en/changelog.md#2-1-86)

5Releases [v2.1.86 → v2.1.91](https://code.claude.com/docs/en/changelog.md#2-1-86)

665 features · March 30 – April 3

88Computer use in the CLI

from line 18

1818Open the iOS simulator, tap through onboarding, and screenshot each step

1919```

2020

21[Computer use guide](/docs/en/computer-use.md)

21[Computer use guide](https://code.claude.com/docs/en/computer-use.md)

2222

2323/powerup

2424v2.1.90

from line 33

3333/powerup

3434```

3535

36[Commands reference](/docs/en/commands.md)

36[Commands reference](https://code.claude.com/docs/en/commands.md)

3737

3838Flicker-free rendering

3939v2.1.89

from line 49

4949claude

5050```

5151

52[Fullscreen rendering](/docs/en/fullscreen.md)

52[Fullscreen rendering](https://code.claude.com/docs/en/fullscreen.md)

5353

5454MCP result-size override

5555v2.1.91

from line 68

6868}

6969```

7070

71[MCP reference](/docs/en/mcp.md#raise-the-limit-for-a-specific-tool)

71[MCP reference](https://code.claude.com/docs/en/mcp.md#raise-the-limit-for-a-specific-tool)

7272

7373Plugin executables on PATH

7474v2.1.91

from line 85

8585 └── my-tool

8686```

8787

88[Plugins reference](/docs/en/plugins/manifest-reference.md#standard-layout)

88[Plugins reference](https://code.claude.com/docs/en/plugins/manifest-reference.md#standard-layout)

8989

9090Other wins

9191

9292Auto mode follow-ups: new `PermissionDenied` hook fires on classifier denials (return `retry: true` to let Claude try a different approach), and `/permissions` → Recently denied lets you retry manually with `r`New `defer` value for `permissionDecision` in `PreToolUse` hooks: `-p` sessions pause at a tool call and exit with a `deferred_tool_use` payload so an SDK app or custom UI can surface it, then resume with `--resume``/buddy`: hatch a small creature that watches you code. An April Fools' joke, no longer available`disableSkillShellExecution` setting blocks inline shell from skills, custom commands, and plugin commandsEdit tool now works on files viewed via `cat` or `sed -n` without a separate ReadHook output over 50K saved to disk with a path + preview instead of injected into contextThinking summaries off by default in interactive sessions (`showThinkingSummaries: true` to restore)Voice mode: push-to-talk modifier combos, Windows WebSocket, macOS Apple Silicon mic permission`claude-cli://` deep links accept multi-line prompts (encoded `%0A`)

9393

94[Full changelog for v2.1.86–v2.1.91 →](/docs/en/changelog.md#2-1-86)

94[Full changelog for v2.1.86–v2.1.91 →](https://code.claude.com/docs/en/changelog.md#2-1-86)

9595

whats-new/2026-w15 Changed · +7 / -7 lines

from line 2

33> Ultraplan cloud planning, the Monitor tool with self-pacing /loop, /team-onboarding for packaging your setup, and /autofix-pr from your terminal.

5Releases [v2.1.92 → v2.1.101](/docs/en/changelog.md#2-1-92)

5Releases [v2.1.92 → v2.1.101](https://code.claude.com/docs/en/changelog.md#2-1-92)

664 features · April 6–10

88Ultraplan

from line 18

1818/ultraplan migrate the auth service from sessions to JWTs

1919```

2020

21[Ultraplan guide](/docs/en/ultraplan)

21[Ultraplan guide](https://code.claude.com/docs/en/ultraplan)

2222

2323Monitor tool

2424v2.1.98

from line 39

3939/loop check CI on my PR

4040```

4141

42[Monitor tool reference](/docs/en/tools-reference.md#monitor-tool)

42[Monitor tool reference](https://code.claude.com/docs/en/tools-reference.md#monitor-tool)

4343

4444/autofix-pr

4545CLI

from line 54

5454/autofix-pr

5555```

5656

57[Auto-fix pull requests](/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests)

57[Auto-fix pull requests](https://code.claude.com/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests)

5858

5959/team-onboarding

6060v2.1.101

from line 67

6767/team-onboarding

6868```

6969

70[Commands reference](/docs/en/commands.md)

70[Commands reference](https://code.claude.com/docs/en/commands.md)

7171

7272Other wins

7373

74Focus view: press `Ctrl+O` in flicker-free mode to collapse the view to your last prompt, a one-line tool summary with diffstats, and Claude's final responseGuided [Amazon Bedrock](/docs/en/amazon-bedrock.md) and [Google Cloud's Agent Platform](/docs/en/google-vertex-ai.md) setup wizards on the login screen: pick "3rd-party platform" for step-by-step auth, region, credential check, and model pinning`/agents` gets a tabbed layout: a Running tab shows live subagents with a `● N running` count, plus Run agent and View running instance actions in the Library tabDefault effort level is now `high` for API-key, Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Team, and Enterprise users (control with `/effort`)`/cost` shows a per-model and cache-hit breakdown for subscription users`/release-notes` is now an interactive version pickerStatus line: new `refreshInterval` setting re-runs the command every N seconds, and `workspace.git_worktree` in the JSON input`CLAUDE_CODE_PERFORCE_MODE`: Edit/Write fail on read-only files with a `p4 edit` hint instead of silently overwritingOS CA certificate store is now trusted by default, so enterprise TLS proxies work without extra setup (`CLAUDE_CODE_CERT_STORE=bundled` to opt out)Amazon Bedrock powered by Mantle: set `CLAUDE_CODE_USE_MANTLE=1`Hardened Bash tool permissions: backslash-escaped flags, env-var prefixes, `/dev/tcp` redirects, and compound commands now prompt correctly`UserPromptSubmit` hooks can set the session title via `hookSpecificOutput.sessionTitle`

74Focus view: press `Ctrl+O` in flicker-free mode to collapse the view to your last prompt, a one-line tool summary with diffstats, and Claude's final responseGuided [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md) and [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md) setup wizards on the login screen: pick "3rd-party platform" for step-by-step auth, region, credential check, and model pinning`/agents` gets a tabbed layout: a Running tab shows live subagents with a `● N running` count, plus Run agent and View running instance actions in the Library tabDefault effort level is now `high` for API-key, Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Team, and Enterprise users (control with `/effort`)`/cost` shows a per-model and cache-hit breakdown for subscription users`/release-notes` is now an interactive version pickerStatus line: new `refreshInterval` setting re-runs the command every N seconds, and `workspace.git_worktree` in the JSON input`CLAUDE_CODE_PERFORCE_MODE`: Edit/Write fail on read-only files with a `p4 edit` hint instead of silently overwritingOS CA certificate store is now trusted by default, so enterprise TLS proxies work without extra setup (`CLAUDE_CODE_CERT_STORE=bundled` to opt out)Amazon Bedrock powered by Mantle: set `CLAUDE_CODE_USE_MANTLE=1`Hardened Bash tool permissions: backslash-escaped flags, env-var prefixes, `/dev/tcp` redirects, and compound commands now prompt correctly`UserPromptSubmit` hooks can set the session title via `hookSpecificOutput.sessionTitle`

7575

76[Full changelog for v2.1.92–v2.1.101 →](/docs/en/changelog.md#2-1-92)

76[Full changelog for v2.1.92–v2.1.101 →](https://code.claude.com/docs/en/changelog.md#2-1-92)

7777

whats-new/2026-w16 Changed · +9 / -9 lines

from line 2

33> Claude Opus 4.7 with the new xhigh effort level, Routines on Claude Code on the web, mobile push notifications that ping your phone when Claude needs you, a /usage breakdown that shows what's driving your limits, and native binaries replacing the bundled JavaScript.

5Releases [v2.1.105 → v2.1.113](/docs/en/changelog.md#2-1-105)

5Releases [v2.1.105 → v2.1.113](https://code.claude.com/docs/en/changelog.md#2-1-105)

665 features · April 13–17

88Claude Opus 4.7

from line 17

1717> /effort xhigh

1818```

1919

20[Model config: effort levels](/docs/en/model-config.md#adjust-effort-level)

20[Model config: effort levels](https://code.claude.com/docs/en/model-config.md#adjust-effort-level)

2121

2222Routines

2323web

from line 32

3232> /schedule daily PR review at 9am

3333```

3434

35[Routines guide](/docs/en/routines.md)

35[Routines guide](https://code.claude.com/docs/en/routines.md)

3636

3737/usage breakdown

3838CLI

from line 47

4747> /usage

4848```

4949

50[Commands reference](/docs/en/commands.md)

50[Commands reference](https://code.claude.com/docs/en/commands.md)

5151

5252Mobile push notifications

5353mobile

5454

55With [Remote Control](/docs/en/remote-control.md) connected, Claude can send a push notification to your phone when a long task finishes or it needs a decision to keep going. Turn it on with "Push when Claude decides" in `/config`, or ask for one in your prompt. Useful when you kick off a long agent run and want to step away from the terminal.

55With [Remote Control](https://code.claude.com/docs/en/remote-control.md) connected, Claude can send a push notification to your phone when a long task finishes or it needs a decision to keep going. Turn it on with "Push when Claude decides" in `/config`, or ask for one in your prompt. Useful when you kick off a long agent run and want to step away from the terminal.

5656

5757<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/uII1TETOZxBUZ3lB/images/whats-new/push-notifications.mp4?fit=max&auto=format&n=uII1TETOZxBUZ3lB&q=85&s=c91a967139596500cbdb581a53822ac1" />

5858

from line 62

6262> notify me when the tests pass

6363```

6464

65[Remote Control: mobile push notifications](/docs/en/remote-control.md#mobile-push-notifications)

65[Remote Control: mobile push notifications](https://code.claude.com/docs/en/remote-control.md#mobile-push-notifications)

6666

6767Native binaries

6868v2.1.113

from line 76

7676claude --version

7777```

7878

79[Setup guide](/docs/en/setup.md)

79[Setup guide](https://code.claude.com/docs/en/setup.md)

8080

8181Other wins

8282

83New [`/ultrareview`](/docs/en/ultrareview): comprehensive code review in the cloud using parallel multi-agent analysis and an adversarial critique pass. Run it bare to review your current branch, or `/ultrareview <PR#>` for a specific PR[Auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) is now available for Max subscribers on Opus 4.7, and the `--enable-auto-mode` flag is no longer required[Session recap](/docs/en/interactive-mode.md#session-recap) shows a one-line summary of what happened while you were away; run `/recap` on demand or turn it off from `/config`New `/tui` command and `tui` setting switch between classic and flicker-free rendering mid-conversation; focus view moved from `Ctrl+O` to its own `/focus` commandPlugins can ship background watchers via a top-level `monitors` manifest key that auto-arms at session start or on skill invoke"Auto (match terminal)" option in `/theme` follows your terminal's dark/light mode`/fewer-permission-prompts` scans your transcripts for common read-only Bash and MCP calls and proposes an allowlist for `.claude/settings.json`Claude can now discover and run built-in commands like `/init`, `/review`, and `/security-review` via the Skill tool`PreCompact` hooks can block compaction by exiting with code 2 or returning `{"decision":"block"}``ENABLE_PROMPT_CACHING_1H` opts API key, Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry users into 1-hour prompt cache TTL`sandbox.network.deniedDomains` setting carves specific domains out of a broader `allowedDomains` wildcard`/undo` is now an alias for `/rewind`, and `/proactive` is an alias for `/loop`Hardened Bash permissions: deny rules now match through `env`/`sudo`/`watch` wrappers, and `Bash(find:*)` allow rules no longer auto-approve `-exec` or `-delete`

83New [`/ultrareview`](https://code.claude.com/docs/en/ultrareview): comprehensive code review in the cloud using parallel multi-agent analysis and an adversarial critique pass. Run it bare to review your current branch, or `/ultrareview <PR#>` for a specific PR[Auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) is now available for Max subscribers on Opus 4.7, and the `--enable-auto-mode` flag is no longer required[Session recap](https://code.claude.com/docs/en/interactive-mode.md#session-recap) shows a one-line summary of what happened while you were away; run `/recap` on demand or turn it off from `/config`New `/tui` command and `tui` setting switch between classic and flicker-free rendering mid-conversation; focus view moved from `Ctrl+O` to its own `/focus` commandPlugins can ship background watchers via a top-level `monitors` manifest key that auto-arms at session start or on skill invoke"Auto (match terminal)" option in `/theme` follows your terminal's dark/light mode`/fewer-permission-prompts` scans your transcripts for common read-only Bash and MCP calls and proposes an allowlist for `.claude/settings.json`Claude can now discover and run built-in commands like `/init`, `/review`, and `/security-review` via the Skill tool`PreCompact` hooks can block compaction by exiting with code 2 or returning `{"decision":"block"}``ENABLE_PROMPT_CACHING_1H` opts API key, Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry users into 1-hour prompt cache TTL`sandbox.network.deniedDomains` setting carves specific domains out of a broader `allowedDomains` wildcard`/undo` is now an alias for `/rewind`, and `/proactive` is an alias for `/loop`Hardened Bash permissions: deny rules now match through `env`/`sudo`/`watch` wrappers, and `Bash(find:*)` allow rules no longer auto-approve `-exec` or `-delete`

8484

85[Full changelog for v2.1.105–v2.1.113 →](/docs/en/changelog.md#2-1-105)

85[Full changelog for v2.1.105–v2.1.113 →](https://code.claude.com/docs/en/changelog.md#2-1-105)

8686

whats-new/2026-w17 Changed · +7 / -7 lines

from line 2

33> /ultrareview opens as a research preview, automatic session recaps when you return to a terminal, custom color themes you can build and ship in plugins, and a redesigned Claude Code on the web.

5Releases [v2.1.114 → v2.1.119](/docs/en/changelog.md#2-1-114)

5Releases [v2.1.114 → v2.1.119](https://code.claude.com/docs/en/changelog.md#2-1-114)

664 features · April 20–24

88/ultrareview

from line 24

2424> /ultrareview 1234

2525```

2626

27[Ultrareview guide](/docs/en/ultrareview.md)

27[Ultrareview guide](https://code.claude.com/docs/en/ultrareview.md)

2828

2929Session recap

3030CLI

from line 39

3939> /recap

4040```

4141

42[Interactive mode: session recap](/docs/en/interactive-mode.md#session-recap)

42[Interactive mode: session recap](https://code.claude.com/docs/en/interactive-mode.md#session-recap)

4343

4444Custom themes

4545v2.1.118

from line 52

5252> /theme

5353```

5454

55[Terminal config: create a custom theme](/docs/en/terminal-config.md#create-a-custom-theme)

55[Terminal config: create a custom theme](https://code.claude.com/docs/en/terminal-config.md#create-a-custom-theme)

5656

5757Claude Code on the web

5858web

from line 61

6161

6262![Claude Code on the web redesign overview: new UI, speed and reliability, work across web, mobile, and CLI](https://mintcdn.com/claude-code/FTi4SBJ9YRs7d-5X/images/whats-new/web-redesign.jpeg?fit=max\&auto=format\&n=FTi4SBJ9YRs7d-5X\&q=85\&s=a2aca1b49e295b7337f5779038db8e2c)

6363

64[Claude Code on the web](/docs/en/claude-code-on-the-web.md)

64[Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web.md)

6565

6666Other wins

6767

68[Vim visual mode](/docs/en/interactive-mode.md#vim-editor-mode): press `v` for character selection or `V` for line selection in the prompt input, with operators and visual feedbackHooks can now call MCP tools directly via [`type: "mcp_tool"`](/docs/en/hooks#mcp-tool-hook-fields), so a hook can hit an already-connected server without spawning a process`/cost` and `/stats` are merged into [`/usage`](/docs/en/commands); the old names still work as typing shortcuts that open the relevant tab`/config` changes (theme, editor mode, verbose, and similar) now persist to `~/.claude/settings.json` and follow the same project/local/policy precedence as other [settings](/docs/en/settings.md)[Forked subagents](/docs/en/sub-agents.md#fork-the-current-conversation) can be enabled on external builds with `CLAUDE_CODE_FORK_SUBAGENT=1`: a fork inherits your full conversation context instead of starting freshDefault [effort level](/docs/en/model-config.md#adjust-effort-level) for Pro and Max subscribers on Opus 4.6 and Sonnet 4.6 is now `high` (was `medium`)Native macOS and Linux builds replace the `Glob` and `Grep` tools with embedded `bfs` and `ugrep` available through Bash, for faster searches without a separate tool round-trip`--from-pr` now accepts GitLab merge request, Bitbucket pull request, and GitHub Enterprise PR URLs in addition to github.comAuto mode: include `"$defaults"` in [`autoMode.allow`, `soft_deny`, or `environment`](/docs/en/auto-mode-config) to add custom rules alongside the built-in list instead of replacing itNew [`claude plugin tag`](/docs/en/plugins/dependencies#tag-plugin-releases-for-version-resolution) command creates release git tags for plugins with version validationOpus 4.7 sessions now compute against the model's native 1M context window, fixing inflated `/context` percentages and premature autocompaction`/resume` on large sessions is up to 67% faster and now offers to summarize stale, large sessions before re-reading them

68[Vim visual mode](https://code.claude.com/docs/en/interactive-mode.md#vim-editor-mode): press `v` for character selection or `V` for line selection in the prompt input, with operators and visual feedbackHooks can now call MCP tools directly via [`type: "mcp_tool"`](https://code.claude.com/docs/en/hooks#mcp-tool-hook-fields), so a hook can hit an already-connected server without spawning a process`/cost` and `/stats` are merged into [`/usage`](https://code.claude.com/docs/en/commands); the old names still work as typing shortcuts that open the relevant tab`/config` changes (theme, editor mode, verbose, and similar) now persist to `~/.claude/settings.json` and follow the same project/local/policy precedence as other [settings](https://code.claude.com/docs/en/settings.md)[Forked subagents](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation) can be enabled on external builds with `CLAUDE_CODE_FORK_SUBAGENT=1`: a fork inherits your full conversation context instead of starting freshDefault [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) for Pro and Max subscribers on Opus 4.6 and Sonnet 4.6 is now `high` (was `medium`)Native macOS and Linux builds replace the `Glob` and `Grep` tools with embedded `bfs` and `ugrep` available through Bash, for faster searches without a separate tool round-trip`--from-pr` now accepts GitLab merge request, Bitbucket pull request, and GitHub Enterprise PR URLs in addition to github.comAuto mode: include `"$defaults"` in [`autoMode.allow`, `soft_deny`, or `environment`](https://code.claude.com/docs/en/auto-mode-config) to add custom rules alongside the built-in list instead of replacing itNew [`claude plugin tag`](https://code.claude.com/docs/en/plugins/dependencies#tag-plugin-releases-for-version-resolution) command creates release git tags for plugins with version validationOpus 4.7 sessions now compute against the model's native 1M context window, fixing inflated `/context` percentages and premature autocompaction`/resume` on large sessions is up to 67% faster and now offers to summarize stale, large sessions before re-reading them

6969

70[Full changelog for v2.1.114–v2.1.119 →](/docs/en/changelog.md#2-1-114)

70[Full changelog for v2.1.114–v2.1.119 →](https://code.claude.com/docs/en/changelog.md#2-1-114)

7171

whats-new/2026-w18 Changed · +7 / -7 lines

from line 2

33> Claude Code on Windows runs without Git Bash, claude auth login accepts a pasted OAuth code when the browser callback can't reach localhost, claude project purge cleans up local state per project, and pasting a PR URL into /resume finds the session that created it.

5Releases [v2.1.120 → v2.1.126](/docs/en/changelog.md#2-1-120)

5Releases [v2.1.120 → v2.1.126](https://code.claude.com/docs/en/changelog.md#2-1-120)

664 features · April 27 – May 1

88Sign in without a browser callback

from line 16

1616claude auth login

1717```

1818

19[CLI reference](/docs/en/cli-reference.md#cli-commands)

19[CLI reference](https://code.claude.com/docs/en/cli-reference.md#cli-commands)

2020

2121claude project purge

2222v2.1.124

from line 35

3535claude project purge

3636```

3737

38[CLI reference](/docs/en/cli-reference.md)

38[CLI reference](https://code.claude.com/docs/en/cli-reference.md)

3939

4040Resume by PR URL

4141v2.1.122

from line 60

6060claude --from-pr 1234

6161```

6262

63[Sessions: use the session picker](/docs/en/sessions.md#use-the-session-picker)

63[Sessions: use the session picker](https://code.claude.com/docs/en/sessions.md#use-the-session-picker)

6464

6565Windows without Git Bash

6666Windows

from line 67

6767

6868Git for Windows is no longer required. When Bash is absent, Claude Code uses PowerShell as the shell tool, and when the PowerShell tool is enabled it is treated as the primary shell. PowerShell 7 installed via the Microsoft Store, MSI without PATH, or a `.NET` global tool is now detected automatically.

6969

70[Setup guide](/docs/en/setup.md)

70[Setup guide](https://code.claude.com/docs/en/setup.md)

7171

7272Other wins

7373

74MCP servers can opt out of tool-search deferral with `alwaysLoad: true` in their config so all of that server's tools are always availableNew `claude plugin prune` removes orphaned auto-installed plugin dependencies, and `plugin uninstall --prune` cascades`/skills` now has a type-to-filter search box so you can find a skill in a long list without scrolling`PostToolUse` hooks can replace tool output for any tool via `hookSpecificOutput.updatedToolOutput`, not only MCP toolsNew [`claude ultrareview`](/docs/en/ultrareview) subcommand runs `/ultrareview` non-interactively from CI or scripts: prints findings to stdout (`--json` for raw output) and exits 0 on completion or 1 on failure`--dangerously-skip-permissions` now bypasses prompts for writes to `.claude/`, `.git/`, `.vscode/`, shell config files, and other previously protected paths, while catastrophic removal commands still prompt as a safety netThe `/model` picker can list models from your gateway's `/v1/models` endpoint when `ANTHROPIC_BASE_URL` points at an Anthropic-compatible gateway; opt in with `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` since v2.1.129MCP servers that hit a transient error during startup now auto-retry up to 3 times instead of staying disconnected`ANTHROPIC_BEDROCK_SERVICE_TIER` selects an Amazon Bedrock service tier: `default`, `flex`, or `priority``/terminal-setup` enables iTerm2's clipboard access setting so `/copy` works, including from tmuxGoogle Cloud's Agent Platform now supports X.509 certificate-based Workload Identity Federation (mTLS ADC)Significant memory leak fixes: image-heavy sessions, `/usage` on large transcript histories, and long-running tools without progress events

74MCP servers can opt out of tool-search deferral with `alwaysLoad: true` in their config so all of that server's tools are always availableNew `claude plugin prune` removes orphaned auto-installed plugin dependencies, and `plugin uninstall --prune` cascades`/skills` now has a type-to-filter search box so you can find a skill in a long list without scrolling`PostToolUse` hooks can replace tool output for any tool via `hookSpecificOutput.updatedToolOutput`, not only MCP toolsNew [`claude ultrareview`](https://code.claude.com/docs/en/ultrareview) subcommand runs `/ultrareview` non-interactively from CI or scripts: prints findings to stdout (`--json` for raw output) and exits 0 on completion or 1 on failure`--dangerously-skip-permissions` now bypasses prompts for writes to `.claude/`, `.git/`, `.vscode/`, shell config files, and other previously protected paths, while catastrophic removal commands still prompt as a safety netThe `/model` picker can list models from your gateway's `/v1/models` endpoint when `ANTHROPIC_BASE_URL` points at an Anthropic-compatible gateway; opt in with `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` since v2.1.129MCP servers that hit a transient error during startup now auto-retry up to 3 times instead of staying disconnected`ANTHROPIC_BEDROCK_SERVICE_TIER` selects an Amazon Bedrock service tier: `default`, `flex`, or `priority``/terminal-setup` enables iTerm2's clipboard access setting so `/copy` works, including from tmuxGoogle Cloud's Agent Platform now supports X.509 certificate-based Workload Identity Federation (mTLS ADC)Significant memory leak fixes: image-heavy sessions, `/usage` on large transcript histories, and long-running tools without progress events

7575

76[Full changelog for v2.1.120–v2.1.126 →](/docs/en/changelog.md#2-1-120)

76[Full changelog for v2.1.120–v2.1.126 →](https://code.claude.com/docs/en/changelog.md#2-1-120)

7777

whats-new/2026-w19 Changed · +4 / -4 lines

from line 2

33> Load plugins from .zip archives and URLs, search command history across every project with Ctrl+R, branch new worktrees from local HEAD or the remote default, and block actions unconditionally with auto mode hard deny rules.

5Releases [v2.1.128 → v2.1.136](/docs/en/changelog.md#2-1-128)

5Releases [v2.1.128 → v2.1.136](https://code.claude.com/docs/en/changelog.md#2-1-128)

662 features · May 4–8

88Plugins from .zip archives and URLs

from line 15

1515claude --plugin-url https://example.com/my-plugin.zip

1616```

1717

18[Plugins guide](/docs/en/plugins/overview.md)

18[Plugins guide](https://code.claude.com/docs/en/plugins/overview.md)

1919

2020History search across all your projects

2121v2.1.129

from line 22

2222

2323`Ctrl+R` reverse-search now defaults to all prompts across every project, restoring the behavior from before v2.1.124. Press `Ctrl+S` while searching to narrow back to the current project or session. Handy when you remember a command you ran in another repo last week and don't want to go digging for it.

2424

25[Interactive mode: command history](/docs/en/interactive-mode.md#command-history)

25[Interactive mode: command history](https://code.claude.com/docs/en/interactive-mode.md#command-history)

2626

2727Other wins

2828

2929New `worktree.baseRef` setting (`fresh` | `head`) controls whether `--worktree`, the `EnterWorktree` tool, and agent-isolation worktrees branch from the remote default branch or local `HEAD`; the default `fresh` keeps unpushed commits out of new worktreesNew `settings.autoMode.hard_deny` rules block matching actions unconditionally in auto mode, regardless of allow exceptions, for actions that should never run automatically even when broader allow rules applyHooks now receive the active effort level via the `effort.level` JSON input field and the `$CLAUDE_EFFORT` environment variable, and Bash tool commands can read `$CLAUDE_EFFORT``CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1` opts out of the fullscreen alternate-screen renderer and keeps the conversation in the terminal's native scrollback`CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` lets Homebrew or WinGet installations run the upgrade in the background and prompt to restart`CLAUDE_CODE_SESSION_ID` is now in the Bash tool subprocess environment, matching the `session_id` passed to hooks`/mcp` now shows the tool count for connected servers and flags servers that connected with 0 tools`--channels` now works with console (API key) authenticationSubprocesses such as Bash, hooks, MCP, and LSP no longer inherit `OTEL_*` environment variables, so OTEL-instrumented apps run via the Bash tool no longer pick up the CLI's own OTLP endpointSub-agent progress summaries now hit the prompt cache, cutting `cache_creation` token cost by roughly 3xSeveral OAuth and credential reliability fixes: parallel sessions no longer dead-end at 401 after a refresh-token race, MCP OAuth refresh tokens are no longer lost when multiple servers refresh concurrently, and a rare login loop from a concurrent credential write is fixedNew `parentSettingsBehavior` admin key lets admins opt SDK `managedSettings` into the policy merge

3030

31[Full changelog for v2.1.128–v2.1.136 →](/docs/en/changelog.md#2-1-128)

31[Full changelog for v2.1.128–v2.1.136 →](https://code.claude.com/docs/en/changelog.md#2-1-128)

3232

whats-new/2026-w20 Changed · +5 / -5 lines

from line 2

33> Manage every Claude Code session from one screen with agent view, keep Claude working toward a goal until a condition holds, and run fast mode on Opus 4.7 by default.

5Releases [v2.1.139 → v2.1.142](/docs/en/changelog.md#2-1-139)

5Releases [v2.1.139 → v2.1.142](https://code.claude.com/docs/en/changelog.md#2-1-139)

663 features · May 11–15

88Agent view

from line 18

1818claude agents

1919```

2020

21[Agent view](/docs/en/agent-view.md)

21[Agent view](https://code.claude.com/docs/en/agent-view.md)

2222

2323/goal

2424v2.1.139

from line 33

3333> /goal all tests in test/auth pass and the lint step is clean

3434```

3535

36[Goals](/docs/en/goal.md)

36[Goals](https://code.claude.com/docs/en/goal.md)

3737

3838Fast mode on Opus 4.7

3939research preview

from line 48

4848> /fast

4949```

5050

51[Fast mode on Opus 4.7](/docs/en/fast-mode.md#understand-the-cost-tradeoff)

51[Fast mode on Opus 4.7](https://code.claude.com/docs/en/fast-mode.md#understand-the-cost-tradeoff)

5252

5353Other wins

5454

5555`claude agents` gained dispatch flags (`--add-dir`, `--settings`, `--mcp-config`, `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, `--dangerously-skip-permissions`) to configure background sessions, and `claude agents --cwd <path>` scopes the session list to a directoryNew hook `args: string[]` exec form spawns the command directly without a shell, so path placeholders never need quotingNew `continueOnBlock` config option for `PostToolUse` hooks feeds the hook's rejection reason back to Claude and continues the turn instead of ending itNew `terminalSequence` field in hook JSON output lets hooks emit desktop notifications, window titles, and bells without a controlling terminalThe Rewind menu added "Summarize up to here" to compress earlier context while keeping recent turns intactRemote Control, `/schedule`, claude.ai MCP connectors, and notification preferences are now disabled when `ANTHROPIC_API_KEY`, `apiKeyHelper`, or `ANTHROPIC_AUTH_TOKEN` is set, even alongside a claude.ai login; unset the API key to use these featuresMCP stdio servers now receive `CLAUDE_PROJECT_DIR` in their environment, matching hooks, and plugin configs can reference `${CLAUDE_PROJECT_DIR}` in commands`claude plugin details <name>` shows a plugin's component inventory and projected per-session token cost, and the `/plugin` details pane now also lists the LSP servers a plugin providesPlugins with a root-level `SKILL.md` and no `skills/` subdirectory are now surfaced as a skill`/feedback` can now include recent sessions from the last 24 hours or 7 days for issues spanning more than the current sessionAgent tool `subagent_type` now matches case- and separator-insensitively, so `"Code Reviewer"` resolves to `code-reviewer`

5656

57[Full changelog for v2.1.139–v2.1.142 →](/docs/en/changelog.md#2-1-139)

57[Full changelog for v2.1.139–v2.1.142 →](https://code.claude.com/docs/en/changelog.md#2-1-139)

5858

whats-new/2026-w21 Changed · +4 / -4 lines

from line 2

33> Use auto mode on the Pro plan and with Sonnet 4.6, see which skills, subagents, and MCP servers drive your plan limits in /usage, and review diffs with the new /code-review command.

5Releases [v2.1.143 → v2.1.149](/docs/en/changelog.md#2-1-143)

5Releases [v2.1.143 → v2.1.149](https://code.claude.com/docs/en/changelog.md#2-1-143)

661 feature · May 18–22

88Auto mode on the Pro plan

from line 18

1818

1919The command prints `Successfully updated` with the new version number, or `Claude Code is up to date` if no update is needed. Once auto mode is active, the prompt footer shows `auto mode on`.

2020

21[Auto mode requirements](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode)

21[Auto mode requirements](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode)

2222

2323Other wins

2424

25[`/usage`](/docs/en/costs#track-your-costs) now shows a per-category breakdown of what's driving your plan limits, attributing recent usage to skills, subagents, plugins, and individual MCP servers"Extra usage" is renamed to "usage credits" across the CLI, and `/extra-usage` is now `/usage-credits`. The old name still works. The command requires signing in with your claude.ai subscription through `/login` and isn't available with API key authentication.New [`/code-review`](/docs/en/code-review) command reports correctness bugs at a chosen effort level such as `/code-review high`, and `--comment` posts findings as inline GitHub PR comments. `/simplify` remains as a separate cleanup-only review\.Background sessions now appear in `/resume` alongside interactive ones, marked with `bg`, and sessions pinned with `Ctrl+T` in `claude agents` stay alive when idle`claude agents --json` lists live sessions as JSON for scripting, such as status bars and session pickersThe PowerShell tool is now enabled by default on Windows for Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry users; opt out with `CLAUDE_CODE_USE_POWERSHELL_TOOL=0``claude plugin disable` now refuses when another enabled plugin depends on the target, and `claude plugin enable` force-enables transitive dependenciesThe `/plugin` marketplace browse pane shows projected context cost, and the Discover and Browse screens list a plugin's commands, agents, skills, hooks, and MCP/LSP servers before installationNew `worktree.bgIsolation: "none"` setting lets background sessions edit the working copy directly without `EnterWorktree`, for repos where worktrees are impracticalMarkdown output renders GFM task list checkboxes, and the `/diff` detail view scrolls with the keyboardStatus line JSON input now includes GitHub repo and PR information when detectedEnterprise: the `allowAllClaudeAiMcps` managed setting loads claude.ai cloud MCP connectors alongside `managed-mcp.json`

25[`/usage`](https://code.claude.com/docs/en/costs#track-your-costs) now shows a per-category breakdown of what's driving your plan limits, attributing recent usage to skills, subagents, plugins, and individual MCP servers"Extra usage" is renamed to "usage credits" across the CLI, and `/extra-usage` is now `/usage-credits`. The old name still works. The command requires signing in with your claude.ai subscription through `/login` and isn't available with API key authentication.New [`/code-review`](https://code.claude.com/docs/en/code-review) command reports correctness bugs at a chosen effort level such as `/code-review high`, and `--comment` posts findings as inline GitHub PR comments. `/simplify` remains as a separate cleanup-only review\.Background sessions now appear in `/resume` alongside interactive ones, marked with `bg`, and sessions pinned with `Ctrl+T` in `claude agents` stay alive when idle`claude agents --json` lists live sessions as JSON for scripting, such as status bars and session pickersThe PowerShell tool is now enabled by default on Windows for Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry users; opt out with `CLAUDE_CODE_USE_POWERSHELL_TOOL=0``claude plugin disable` now refuses when another enabled plugin depends on the target, and `claude plugin enable` force-enables transitive dependenciesThe `/plugin` marketplace browse pane shows projected context cost, and the Discover and Browse screens list a plugin's commands, agents, skills, hooks, and MCP/LSP servers before installationNew `worktree.bgIsolation: "none"` setting lets background sessions edit the working copy directly without `EnterWorktree`, for repos where worktrees are impracticalMarkdown output renders GFM task list checkboxes, and the `/diff` detail view scrolls with the keyboardStatus line JSON input now includes GitHub repo and PR information when detectedEnterprise: the `allowAllClaudeAiMcps` managed setting loads claude.ai cloud MCP connectors alongside `managed-mcp.json`

2626

27[Full changelog for v2.1.143–v2.1.149 →](/docs/en/changelog.md#2-1-143)

27[Full changelog for v2.1.143–v2.1.149 →](https://code.claude.com/docs/en/changelog.md#2-1-143)

2828

whats-new/2026-w22 Changed · +6 / -6 lines

from line 2

33> Run Claude Code on Claude Opus 4.8, orchestrate large tasks with dynamic workflows, catch security issues with the security-guidance plugin, and use fast mode on Opus 4.8 at a lower price.

5Releases [v2.1.150 → v2.1.157](/docs/en/changelog.md#2-1-150)

5Releases [v2.1.150 → v2.1.157](https://code.claude.com/docs/en/changelog.md#2-1-150)

664 features · May 25–29

88Claude Opus 4.8

from line 18

1818/model claude-opus-4-8

1919```

2020

21[Model configuration](/docs/en/model-config.md#available-models)

21[Model configuration](https://code.claude.com/docs/en/model-config.md#available-models)

2222

2323Dynamic workflows

2424research preview

from line 33

3333create a workflow that migrates every internal fetch() call to the new HttpClient wrapper

3434```

3535

36[Dynamic workflows](/docs/en/workflows.md)

36[Dynamic workflows](https://code.claude.com/docs/en/workflows.md)

3737

3838Security guidance plugin

3939plugin

from line 54

5454/reload-plugins

5555```

5656

57[Security guidance plugin](/docs/en/security-guidance.md)

57[Security guidance plugin](https://code.claude.com/docs/en/security-guidance.md)

5858

5959Fast mode on Opus 4.8

6060research preview

from line 67

6767/fast

6868```

6969

70[Fast mode pricing](/docs/en/fast-mode.md#understand-the-cost-tradeoff)

70[Fast mode pricing](https://code.claude.com/docs/en/fast-mode.md#understand-the-cost-tradeoff)

7171

7272Other wins

7373

7474In `claude agents`, prefix a shell command with `!` to run it as a background job you can attach to and detach from; also available as `claude --bg --exec 'pytest -x'`Plugins in `.claude/skills` directories are now loaded automatically, no marketplace required, and `claude plugin init <name>` scaffolds a new pluginNew `/reload-skills` command re-scans skill directories without restarting, and `SessionStart` hooks can return `reloadSkills: true` to make skills they install available in the same sessionSkills and commands can set `disallowed-tools` in frontmatter to remove tools from the model while the skill is activeNew `MessageDisplay` hook event lets hooks transform or hide assistant message text as it is displayedClaude Code now switches to your configured `--fallback-model` for the rest of the session when the primary model is not found, instead of failing every requestPlugins can declare `defaultEnabled: false` in `plugin.json` or a marketplace entry, so they install without turning on until you enable themVim mode: `/` in NORMAL mode opens reverse history search, matching Bash and Zsh vi-modeStreaming tool execution is now always enabled, including with telemetry disabled and on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry`←←` to open the agents view now works on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and with telemetry disabledClaude in Chrome: pick which connected browser to use via `/chrome` → "Select browser…", or in-chat when a browser action runs with multiple connected`claude mcp list` and `claude mcp get` now show unapproved `.mcp.json` servers as pending approval instead of auto-approving and connecting when output is piped

7575

76[Full changelog for v2.1.150–v2.1.157 →](/docs/en/changelog.md#2-1-150)

76[Full changelog for v2.1.150–v2.1.157 →](https://code.claude.com/docs/en/changelog.md#2-1-150)

7777

whats-new/2026-w23 Changed · +7 / -7 lines

from line 2

33> Run auto mode on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, prompt before writing files that can run code in acceptEdits mode, list installed plugins with /plugin list, and require an approved version range for managed deployments.

5Releases [v2.1.158 → v2.1.165](/docs/en/changelog.md#2-1-158)

5Releases [v2.1.158 → v2.1.165](https://code.claude.com/docs/en/changelog.md#2-1-158)

664 features · June 1–5

88Auto mode on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry

from line 16

1616export CLAUDE_CODE_ENABLE_AUTO_MODE=1

1717```

1818

19[Auto mode on third-party providers](/docs/en/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry)

19[Auto mode on third-party providers](https://code.claude.com/docs/en/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry)

2020

2121Safer automatic edits

2222v2.1.160

from line 29

2929claude --permission-mode acceptEdits

3030```

3131

32[Protected paths](/docs/en/permission-modes.md#protected-paths)

32[Protected paths](https://code.claude.com/docs/en/permission-modes.md#protected-paths)

3333

3434List installed plugins with /plugin list

3535v2.1.163

from line 42

4242> /plugin list --enabled

4343```

4444

45[Plugin commands](/docs/en/plugins/cli-reference.md#plugin-list)

45[Plugin commands](https://code.claude.com/docs/en/plugins/cli-reference.md#plugin-list)

4646

4747Version requirements for managed deployments

4848v2.1.163

from line 57

5757}

5858```

5959

60[Decide what to enforce](/docs/en/admin-setup.md#decide-what-to-enforce)

60[Decide what to enforce](https://code.claude.com/docs/en/admin-setup.md#decide-what-to-enforce)

6161

6262Other wins

6363

64The trigger keyword for [dynamic workflows](/docs/en/workflows.md) changed from `workflow` to `ultracode`; asking for a workflow in your own words still works, and the keyword is highlighted in violet in the prompt[Stop and SubagentStop hooks](/docs/en/hooks.md) can return `hookSpecificOutput.additionalContext` to give Claude feedback and keep the turn going instead of being treated as an error`claude mcp` list, get, and add no longer print secrets: environment-variable references are not expanded, and credential headers and URL secrets are redactedA failed Bash command in a parallel tool batch no longer cancels the others; each tool returns its own result independentlyEditing a file no longer needs a separate Read first when you viewed it with a single-file `grep`, `egrep`, or `fgrep`Clicking a command in the autocomplete menu now fills it into your prompt instead of running it immediately; press Enter to runListing `Grep` or `Glob` in `--tools` now provides the dedicated search tools on native builds with embedded search, instead of silently ignoring those names`/effort` now confirms when your chosen level will persist as the default for new sessions`OTEL_RESOURCE_ATTRIBUTES` values are now attached as labels on metric datapoints, so you can slice usage metrics by custom dimensions like team or repoWindsurf is renamed to Devin Desktop in `/ide`, `/terminal-setup`, and `/scroll-speed`, following the editor's rebrand`/btw` gains a `c to copy` shortcut that copies the raw markdown answer to the clipboard

64The trigger keyword for [dynamic workflows](https://code.claude.com/docs/en/workflows.md) changed from `workflow` to `ultracode`; asking for a workflow in your own words still works, and the keyword is highlighted in violet in the prompt[Stop and SubagentStop hooks](https://code.claude.com/docs/en/hooks.md) can return `hookSpecificOutput.additionalContext` to give Claude feedback and keep the turn going instead of being treated as an error`claude mcp` list, get, and add no longer print secrets: environment-variable references are not expanded, and credential headers and URL secrets are redactedA failed Bash command in a parallel tool batch no longer cancels the others; each tool returns its own result independentlyEditing a file no longer needs a separate Read first when you viewed it with a single-file `grep`, `egrep`, or `fgrep`Clicking a command in the autocomplete menu now fills it into your prompt instead of running it immediately; press Enter to runListing `Grep` or `Glob` in `--tools` now provides the dedicated search tools on native builds with embedded search, instead of silently ignoring those names`/effort` now confirms when your chosen level will persist as the default for new sessions`OTEL_RESOURCE_ATTRIBUTES` values are now attached as labels on metric datapoints, so you can slice usage metrics by custom dimensions like team or repoWindsurf is renamed to Devin Desktop in `/ide`, `/terminal-setup`, and `/scroll-speed`, following the editor's rebrand`/btw` gains a `c to copy` shortcut that copies the raw markdown answer to the clipboard

6565

66[Full changelog for v2.1.158–v2.1.165 →](/docs/en/changelog.md#2-1-158)

66[Full changelog for v2.1.158–v2.1.165 →](https://code.claude.com/docs/en/changelog.md#2-1-158)

6767