Home Docs Claude Code CLI

One capture · claude-code

One read of Claude Code CLIclaude-code-20261022T180701Z

220 pages moved out of 228 read.

Pages moved 220 significant first

Pages read 228 in this capture

Captured 22 Oct 2026 18:07 UTC

Corpus hash 237d0503e095 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 · +26 / -26 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). 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](/docs/en/quickstart.md). If you've never used a terminal before, see the [terminal guide](/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#network-access-requirements).

18* **Network**: internet connection required. See [network configuration](/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#search-and-discovery-issues).

24* **ripgrep**: usually included with Claude Code. If search fails, see [search troubleshooting](/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) 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).

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

3131

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

3333

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#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#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](/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#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.

90You can also install with [apt, dnf, or apk](/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).

100If you encounter any issues during installation, see [Troubleshoot installation and login](/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#bash-tool-behavior) and the [Monitor tool](/docs/en/tools-reference#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](/docs/en/tools-reference.md#bash-tool-behavior) and the [Monitor tool](/docs/en/tools-reference.md#monitor-tool) need.

115115

116116Whether 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.

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#powershell-tool).

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

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

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#powershell-tool) for setup and limitations.

132132

133133#### Install in WSL

134134

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

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

176176

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

178178

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), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), or [Microsoft Foundry](/docs/en/microsoft-foundry).

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

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) for all account types and team setup options.

190190

191191## Update Claude Code

192192

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#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](/docs/en/troubleshoot-install.md#permission-errors-during-installation) for details.

208208

209209> [!NOTE]

210210>

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

228Configure this via `/config` → **Auto-update channel**, or add it to your [settings.json file](/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).

238For enterprise deployments, you can enforce a consistent release channel across your organization using [managed settings](/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) to pin a floor explicitly:

250Add it to your [settings.json file](/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), this enforces an organization-wide minimum that user and project settings cannot override.

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

260260

261261The `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).

262262

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#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](/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#permission-errors-during-installation).

472472

473473### Install on network storage

474474

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#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](/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#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](/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 · +118 / -118 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).

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

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

2424

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

2626

from line 28

2828>

2929> 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"`.

3030

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

31Bundled skills are listed alongside built-in commands in the [commands reference](/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#configure-release-channel)

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

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

3939* **`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#permission-modes) your default permission mode and to [pre-approve](/docs/en/permissions) 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) is connected.

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

4242

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

4444

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#delivery-mechanisms) | All users on machines where your organization deploys it |

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 |

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#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](/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) is enabled, as `/plugin-name:skill-name` |

159| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Wherever the [plugin](/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#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#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#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](/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).

170170

171171### Load skills in monorepos and subdirectories

172172

173173Claude 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.

174174

175In a session running in a linked [git worktree](/docs/en/worktrees) 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#what-worktrees-share-with-the-main-checkout).

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

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#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 187

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#control-filesystem-settings-with-settingsources), which is on by default. A [`strictPluginOnlyCustomization`](/docs/en/settings-reference#strictpluginonlycustomization) policy, [bare mode](/docs/en/headless#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#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](/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.

191191

192192### Resolve skills that share a name

193193

from line 197

197197| :- | :- |

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

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

200| Any of those locations and a [built-in command](/docs/en/commands) | 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 |

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

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

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

203203| A plugin skill and a skill at any of the locations above | Both load, because plugin skills are namespaced as `/plugin-name:skill-name` |

from line 205

205205

206206### Use skills in Cowork and cloud sessions

207207

208[Cowork](https://claude.com/product/cowork) sessions and [cloud sessions](/docs/en/cloud-environments#what-carries-over-from-your-setup), including [cloud scheduled tasks](/docs/en/routines), 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.

208[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.

209209

210If 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) invokes it. This happens because each run starts as a fresh cloud session. To make a personal skill available in these sessions:

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

211211

212* For Cowork sessions, cloud sessions, and cloud threads in a [project](/docs/en/claude-projects#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#how-each-session’s-config-is-assembled) don't load your account's skills.

213* 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#what-carries-over-from-your-setup).

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

214214

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

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

216216

217217### Skills synced from claude.ai

218218

from line 231

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

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

233233

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

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

235235

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

236Claude 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:

237237

238238* 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

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

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

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

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

241* 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`

242242

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

244244

from line 250

250250

251251Some 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.

252252

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

254254

255If 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#cleaned-up-automatically) deletes them. Once your organization turns Skills back on, Claude Code downloads the skills you enabled at the next sync.

255If 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.

256256

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

258258

from line 267

267267* 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

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

269269* A plugin skill

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

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

271271

272272Claude 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.

273273

from line 279

279279

280280Claude 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.

281281

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

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

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

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

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

285285

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

287287

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

289289

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

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

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

292292

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

from line 300

300300

301301### Edit a skill during a session

302302

303Claude Code watches skill directories for file changes, except in [bare mode](/docs/en/headless#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.

303Claude 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.

304304

305305If 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.

306306

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

307Live 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.

308308

309309### Remove a skill

310310

from line 311

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

312312

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

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

315* **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#reload-plugins) or when you restart.

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

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

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

318318

from line 356

3563563. Push to the deployment target

357357```

358358

359Keep 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#write-an-effective-claude-md).

360360

361361### Frontmatter reference

362362

363Configure a skill with YAML [frontmatter](/docs/en/glossary#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:

363Configure 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:

364364

365365```yaml theme={null}

366366---

from line 386

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

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

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

389| `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#preload-skills-into-subagents) and from running when a [session-scoped scheduled task](/docs/en/scheduled-tasks) fires with the skill as its prompt. Default: `false`. |

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

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

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

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

393| `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#eliminate-prompts-with-auto-mode), and in [plan mode while the classifier reviews commands](/docs/en/permission-modes#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#restrict-model-selection). |

394| `effort` | No | [Effort level](/docs/en/model-config#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#adjust-effort-level). Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model. |

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

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

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

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

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

398| `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#hooks-in-skills-and-agents) for the configuration format, the `once` option, and the [limits on skill hooks](/docs/en/hooks#limits-on-skill-hooks). |

399| `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#path-specific-rules). |

400| `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](/en/tools-reference#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. |

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

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

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

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

403403| `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 408

408408

409409| Distribution path | Frontmatter fields you can use |

410410| :- | :- |

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

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

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

413413

414414When 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 434

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

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

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

437| 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#skills) |

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

439439

440440In 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.

441441

442In [non-interactive sessions](/docs/en/headless), 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.

442In [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.

443443

444444For 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.

445445

from line 458

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

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

460460

461To 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) for `[names]`. In an interactive session, a [startup notice](/docs/en/errors#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).

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

462462

463463#### Available string substitutions

464464

from line 473

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

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

475475| `${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. |

476| `${CLAUDE_PROJECT_DIR}` | The project root directory. This is the same path [hooks](/docs/en/hooks#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. |

477| `${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#environment-variables). |

478| `${CLAUDE_PLUGIN_DATA}` | The plugin's [persistent data directory](/docs/en/plugins/components#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. |

476| `${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. |

478| `${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. |

479479

480480Claude 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:

481481

from line 575

575575

576576> [!NOTE]

577577>

578> 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#preload-skills-into-subagents) work differently: the full skill content is injected at startup.

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

579579

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

581581

from line 594

594594

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

596596

597[Auto-compaction](/docs/en/how-claude-code-works#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.

597[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.

598598

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

600600

601601### Pre-approve tools for a skill

602602

603The `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) 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.

603The `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.

604604

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

606606

from line 615

615615---

616616```

617617

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

619619

620620#### When only managed permission rules apply

621621

622When 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#allowmanagedpermissionrulesonly). This requires Claude Code v2.1.282 or later.

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

623623

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

625625

from line 719

719719```

720720````

721721

722To 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). 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), where users cannot override it.

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

723723

724724Claude 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.

725725

726726> [!TIP]

727727>

728> 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#use-ultrathink-for-one-off-deep-reasoning).

729729

730730#### How injected commands run

731731

732732Claude 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:

733733

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

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

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

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

737737

from line 739

739739

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

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

742* **Timeout**: each command runs under the Bash tool's default 2-minute [timeout](/docs/en/tools-reference#timeout-and-output-limits). When the Bash tool [moves a timed-out command to the background](/docs/en/tools-reference#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).

743* **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#output-limits) covers the ceiling and how to adjust each boundary.

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

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

744744

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

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

746746

747747#### When an injected command fails

748748

749749A 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.

750750

751With 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#output-limits) as a normal result and injects their output. Exit codes of 2 or higher fail even for those commands.

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

752752

753753Which commands get the carveout depends on the shell:

754754

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

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

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

756* `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`

757757

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

759759

760760#### Control characters in injected commands

761761

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

763763

764764#### Permission checks on injected commands

765765

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

766Injected 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 "..."`.

767767

768Outside [auto mode](/docs/en/permission-modes#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#manage-permissions).

768Outside [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).

769769

770In 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#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).

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

771771

772772### Run skills in a subagent

773773

from line 775

775775

776776> [!NOTE]

777777>

778> Despite the name, a skill with `context: fork` doesn't run in a [fork of the current conversation](/docs/en/sub-agents#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`.

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

779779

780The forked subagent runs in the [background](/docs/en/sub-agents#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.

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

781781

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

783783

from line 784

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

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

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

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

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

788788

789When an agent in a [dynamic workflow](/docs/en/workflows) 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.

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

790790

791A backgrounded fork also runs with the [narrower tool set that applies to background subagents](/docs/en/sub-agents#run-subagents-in-foreground-or-background): the skill's subagent is a regular agent type, so the exemption for subagents that fork the conversation doesn't cover it. If your skill's steps depend on a tool outside that set, set `background: false` to keep the full tool set.

791A 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.

792792

793A forked skill that runs in the background applies its edits outside your session's [checkpoints](/docs/en/checkpointing#subagent-edits-not-restored). After one, `/rewind` restores only the files Claude had already edited in your conversation. The skill's edits to other files stay, so use git to revert them.

793A 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.

794794

795795> [!WARNING]

796796>

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

798798

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

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

800800

802802| :- | :- | :- | :- |

805805

806With `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#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.

806With `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.

807807

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

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

809809

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

811811

from line 837

837837

838838### Restrict Claude's skill access

839839

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

840By 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.

841841

842842Three ways to control which skills Claude can invoke:

843843

from line 848

848848Skill

849849```

850850

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

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

852852

853853```text theme={null}

854854# Allow only specific skills

from line 869

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

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

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

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

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

873873

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

875875

from line 887

887887

888888### Override skill visibility from settings

889889

890The `skillOverrides` setting controls skill visibility from your [settings](/docs/en/settings) 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`.

890The `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`.

891891

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

893893

from line 900

900900

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

902902

903`"off"` also hides the skill from the command lists advertised to [Remote Control](/docs/en/remote-control) clients and to [Agent SDK](/docs/en/agent-sdk/skills#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.

903`"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.

904904

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

906906

from line 913

913913}

914914```

915915

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

916Some 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.

917917

918918In 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.

919919

from line 921

921921

922922### Find unused skills

923923

924Every 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) with `-p`, Claude Code prints it as text.

925925

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

927927

928`/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#features-that-need-feature-flag-fetching). If you run `/skill-doctor` over [Remote Control](/docs/en/remote-control) 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.

928`/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.

929929

930930## Evaluate and iterate on a skill

931931

from line 938

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

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

940940

941Two tools automate the baseline comparison. For a skill that ships in a [plugin](/docs/en/plugins/overview), [`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.

941Two 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.

942942

943943### Run evals with skill-creator

944944

945The [`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#install-a-plugin). In a terminal, start Claude Code by running `claude`, then enter this at its prompt:

945The [`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:

946946

947947```text theme={null}

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

from line 951

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

952952

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

954* `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#plugin-not-found-in-marketplace).

955955

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

957957

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

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

959* **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

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

961961* **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

962962* **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 970

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

971971

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

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

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

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

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

975975

976976### Generate visual output

977977

from line 1194

11941194

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

11961196

1197* **Claude skipped a rule that must hold every time**: move the rule into a [hook](/docs/en/hooks-guide). 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.

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

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

1199* **The conversation was compacted**: invoke the skill again to restore its full content. After [compaction](/docs/en/how-claude-code-works#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`.

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

12001200

12011201### Skill descriptions are cut short

12021202

from line 1214

12141214

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

12161216

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

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

12181218

12191219## Related resources

12201220

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

12301230* **[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

12311231

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) are enabled for your account |

32| Cloud sessions | [Cloud sessions](/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#share-sessions)

154automatically visible to the organization. See [cloud session sharing](/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#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](/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#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](/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).

232* **Cloud session access required**: users need access to [cloud sessions](/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)**

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

237237>

238238> Learn more about cloud sessions

239239

statusline Changed · +23 / -23 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) 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](/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.

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#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](/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) |

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 |

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

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 |

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) is enabled for the session |

186| `fast_mode` | Whether [fast mode](/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) 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](/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#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 |

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 |

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

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#vim-editor-mode) is enabled |

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 |

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#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](/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#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) |

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

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). 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](/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#check-cache-performance).

364For what the cache fields mean and how they're billed, see [check cache performance](/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#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](/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.

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

from line 380

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). 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](/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#cache-lifetime) of the current cached prefix: `"5m"` or `"1h"` |

393| `ttl` | [Cache lifetime](/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 1083

10831083

10841084## Subagent status lines

10851085

1086The `subagentStatusLine` setting renders a custom row body for each [subagent](/docs/en/sub-agents) 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](/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#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](/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

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#subagent-names), when it has one |

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

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

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

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

from line 1115

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#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](/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#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).

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

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

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

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#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](/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), 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](/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#read-the-token-count-beside-the-spinner)

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

12091209

sub-agents Changed · +130 / -130 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#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) 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](/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.

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). For separate sessions that pass messages to each other, see [cross-session messaging](/docs/en/cross-session-messaging). For a coordinated team of sessions Claude spawns and supervises, see [agent teams](/docs/en/agent-teams).

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

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#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](/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 34

3434

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

3636 * 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), or a [Claude apps gateway](/docs/en/claude-apps-gateway), Explore stays on the main conversation's model.

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.

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#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.

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.

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); [which permission mode it starts in](/docs/en/agent-view#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](/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 |

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 79

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

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

8181* 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) and the [Agent SDK](/docs/en/agent-sdk/overview), set [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/docs/en/env-vars) to remove all built-in types and supply only your own.

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.

8383

8484An 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.

8585

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

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

167167

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

169169

from line 211

211211'@

212212```

213213

214In [non-interactive mode](/docs/en/headless), `--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](/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 221

221221

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

223223

224**Managed subagents** are deployed by organization administrators. Place markdown files in `.claude/agents/` inside the [managed settings directory](/docs/en/managed-settings#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](/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) 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#agents) for details on creating plugin subagents.

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.

227227

228228> [!NOTE]

229229>

from line 231

231231>

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

233233

234You can also reuse a subagent definition as an [agent team](/docs/en/agent-teams) 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#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](/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.

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), 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](/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.

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) 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](/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#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](/docs/en/worktrees.md#how-claude-code-enforces-isolation). PowerShell commands get only the working-directory check.

278278

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

279[Monitor](/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#how-claude-code-enforces-isolation).

282282

283283### Frontmatter reference

284284

285Configure a subagent with YAML [frontmatter](/docs/en/glossary#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](/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

from line 291

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#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) such as `my-plugin:reviewer` |

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

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#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](/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) 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) 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#installing-mcp-servers) as value. Ignored for [plugin subagents](#choose-the-subagent-scope) |

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

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

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 |

308308| `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), giving it an isolated copy of the repository branched by default from your [default branch](/docs/en/worktrees#choose-the-base-branch) rather than the parent session's `HEAD`. The worktree is automatically cleaned up if the subagent makes no changes |

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 |

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) and [skills](/docs/en/skills) 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#choose-the-ttl-yourself) for this subagent's requests, at the frontmatter's place in the [cache lifetime precedence](/docs/en/prompt-caching#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](/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 |

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#agents) whose frontmatter has no `name` or doesn't parse still loads, under its filename.

337A [plugin subagent](/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#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](/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 355

3553553. The [`CLAUDE_CODE_SUBAGENT_MODEL`](/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) 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](/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.

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#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#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)**: this can happen with an [application inference profile ARN](/docs/en/amazon-bedrock#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](/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.

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 370

370370

371371Claude 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:

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#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](/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#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`](/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.

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#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](/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#specify-teammates-and-models), and [workflow agent](/docs/en/workflows), 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](/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.

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

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

392392

393393```json theme={null}

394394{

from line 401

401401

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

403403

404While `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is [on](/docs/en/env-vars), 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](/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#run-skills-in-a-subagent) with `model: inherit`

407* A [skill that runs in a subagent](/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#adjust-effort-level), set the [`effort`](#supported-frontmatter-fields) field in its definition.

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.

412412

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

414414

from line 418

418418

419419#### Available tools

420420

421Subagents inherit the [built-in tools](/docs/en/tools-reference) 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#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](/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:

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#endconversation-tool-behavior)

425* `EndConversation`, which can end only the main conversation; see [EndConversation tool behavior](/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#agent-would-be-spawned-with-zero-tools).

433433

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

435435

436436[`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.

437437

438Teammates in [agent teams](/docs/en/agent-teams) additionally keep the task tools and cron tools: `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `CronCreate`, `CronDelete`, and `CronList`.

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

439439

440In a [session without the Task tools](/docs/en/tools-reference#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, while a teammate in its own [split pane](/docs/en/agent-teams#choose-a-display-mode) runs as a separate Claude Code process, so its own model decides.

440In 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, while a teammate in its own [split pane](/docs/en/agent-teams.md#choose-a-display-mode) runs as a separate Claude Code process, so its own model decides.

441441

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

443443

from line 463

463463---

464464```

465465

466When 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#agent-would-be-spawned-with-zero-tools) for the message and how to fix each entry.

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

467467

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

469469

from line 483

483483---

484484```

485485

486A `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#bash) such as `Bash(git push *)` to `permissions.deny` in your settings. The rule applies to the main conversation and to subagents.

486A `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.

487487

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

489489

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

491491

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

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

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

494494

495495#### Restrict which subagents can be spawned

from line 522

522522

523523#### Scope MCP servers to a subagent

524524

525Use the `mcpServers` field to give a subagent access to [MCP](/docs/en/mcp) 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.

525Use 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.

526526

527527> [!NOTE]

528528>

from line 559

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

560560

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

562* [Enterprise managed MCP configuration](/docs/en/managed-mcp)

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

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

564564

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

from line 568

568568

569569#### Trust required for inline MCP servers

570570

571Claude 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#what-runs-before-you-trust-a-folder). Before v2.1.238, Claude Code loaded these servers without checking trust.

571Claude 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.

572572

573* **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#what-runs-before-you-trust-a-folder)

573* **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)

574574* **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

575575* **`--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

576576

from line 581

581581

582582#### Permission modes

583583

584Set `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).

585585

586586The main conversation's permission mode decides whether Claude Code uses the value you set:

587587

588* When the main conversation is in `bypassPermissions`, `acceptEdits`, or [auto mode](/docs/en/permission-modes#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#eliminate-prompts-with-auto-mode) describes.

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

589589* When the main conversation is in `default`, `dontAsk`, or `plan` mode, the subagent runs in the permission mode you set. It keeps the main conversation's permission mode instead in these cases:

590590 * You set `bypassPermissions`. The `bypassPermissions` exception requires Claude Code v2.1.267 or later.

591 * You set `auto` and [auto mode isn't available](/docs/en/permission-modes#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.

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

592592

593593`permissionMode` accepts these values, and `manual` as an alias for `default`:

594594

from line 596

596596| :- | :- |

597597| `default` | Manual mode: prompts for permission |

598598| `acceptEdits` | Auto-accept file edits and common filesystem commands for paths in the working directory or `additionalDirectories` |

599| `auto` | [Auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode): a background classifier reviews commands and protected-directory writes |

600| `dontAsk` | Auto-denies calls that would prompt, though a [mod](/docs/en/plugins/mods/overview) you installed can still approve [some of those calls](/docs/en/permissions#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#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 |

601| `bypassPermissions` | [Skip permission prompts](/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode). A subagent runs in this mode only when the main conversation does |

599| `auto` | [Auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode): a background classifier reviews commands and protected-directory writes |

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

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

602602| `plan` | Plan mode (read-only exploration) |

603603

604604#### Preload skills into subagents

from line 625

625625

626626> [!NOTE]

627627>

628> This is the inverse of [running a skill in a subagent](/docs/en/skills#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.

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

629629

630630#### Enable persistent memory

631631

from line 650

650650| `project` | `.claude/agent-memory/<name-of-agent>/` | the subagent's knowledge is project-specific and shareable via version control |

651651| `local` | `.claude/agent-memory-local/<name-of-agent>/` | the subagent's knowledge is project-specific but shouldn't be checked into version control |

652652

653Subagent memory is part of [auto memory](/docs/en/memory#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.

653Subagent 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.

654654

655655When memory is enabled:

656656

from line 692

692692---

693693```

694694

695Claude Code [passes hook input as JSON](/docs/en/hooks#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#exit-code-2-behavior-per-event) to block write operations:

695Claude 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:

696696

697697```bash theme={null}

698698#!/bin/bash

from line 718

718718

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

720720

721See [Hook input](/docs/en/hooks#pretooluse-input) for the complete input schema and [exit codes](/docs/en/hooks#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#windows-powershell-tool).

721See [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).

722722

723723#### Disable specific subagents

724724

725You can prevent Claude from using specific subagents by adding them to the `deny` array in your [settings](/docs/en/settings-reference#permission-settings). Use the format `Agent(subagent-name)` where `subagent-name` matches the subagent's name field.

725You 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.

726726

727727```json theme={null}

728728{

from line 738

738738claude --disallowedTools "Agent(Explore)"

739739```

740740

741See [Permissions documentation](/docs/en/permissions#tool-specific-permission-rules) for more details on permission rules.

741See [Permissions documentation](/docs/en/permissions.md#tool-specific-permission-rules) for more details on permission rules.

742742

743743### Define hooks for subagents

744744

745Subagents can define [hooks](/docs/en/hooks) that run during the subagent's lifecycle. There are two ways to configure hooks:

745Subagents can define [hooks](/docs/en/hooks.md) that run during the subagent's lifecycle. There are two ways to configure hooks:

746746

747747* **In the subagent's frontmatter**: define hooks that run only while that subagent is active

748748* **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

749749

750Hooks from [settings files, managed policy settings, and plugins](/docs/en/hooks#hook-locations) all apply inside subagents, so a `PreToolUse` hook in `settings.json` also runs before every tool a subagent uses.

750Hooks 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.

751751

752752#### Hooks in subagent frontmatter

753753

from line 757

757757>

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

759759

760To let a project-level subagent's frontmatter hooks run, accept the [workspace trust dialog](/docs/en/permissions#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.

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

761761

762Until 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#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.

762Until 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.

763763

764All [hook events](/docs/en/hooks#hook-events) are supported. The most common events for subagents are:

764All [hook events](/docs/en/hooks.md#hook-events) are supported. The most common events for subagents are:

765765

766766| Event | Matcher input | When it fires |

767767| :- | :- | :- |

from line 800

800800| `SubagentStart` | Agent type name | When a subagent begins execution |

801801| `SubagentStop` | Agent type name | When a subagent completes |

802802

803Both 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#agents). A scoped name contains a colon, so it is evaluated as an [unanchored regular expression](/docs/en/hooks#matcher-patterns); anchor it with `^` and `$`, as in `^my-plugin:db-agent$`, to match only that agent.

803Both 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.

804804

805805This example runs a setup script only when the `db-agent` subagent starts, and a cleanup script when any subagent stops:

806806

from line 826

826826}

827827```

828828

829See [Hooks](/docs/en/hooks) for the complete hook configuration format.

829See [Hooks](/docs/en/hooks.md) for the complete hook configuration format.

830830

831831## Work with subagents

832832

from line 834

834834

835835Claude 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.

836836

837Keep descriptions brief: Claude Code shows a startup warning when your subagents' combined descriptions pass [the 15,000-token limit](/docs/en/errors#agent-descriptions-are-over-the-15000-token-limit), and still loads every subagent.

837Keep 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.

838838

839If the subagent ships in a [plugin](/docs/en/plugins/overview), 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.

839If 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.

840840

841841### Invoke subagents explicitly

842842

from line 861

861861

862862Your 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.

863863

864Subagents provided by an enabled [plugin](/docs/en/plugins/overview) 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.

864Subagents 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.

865865

866866You 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.

867867

from line 871

871871claude --agent code-reviewer

872872```

873873

874Unless 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#includegitinstructions).

875875

876876The agent name appears as `@<name>` in the startup header so you can confirm it's active.

877877

878This 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#session-agent-no-longer-available). For the system prompt in either case, see [System prompt flags in resumed conversations](/docs/en/cli-reference#system-prompt-flags-in-resumed-conversations).

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

879879

880880For a plugin-provided subagent, you can pass only the agent name and Claude Code finds it:

881881

from line 915

915915* **`claude -p` and the Agent SDK**: Claude can wait, on its own judgment or when you ask.

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

917917

918For a skill with `context: fork`, Claude Code follows the rules in [Run skills in a subagent](/docs/en/skills#run-skills-in-a-subagent) instead, whether or not fork mode is on.

918For 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.

919919

920920#### Let Claude wait for a subagent

921921

from line 933

933933

9349343. Ask Claude to wait when you need a result first, for example "run the reviewer subagent and wait for its report".

935935

936To keep working while Claude waits, press **Ctrl+B** in the terminal or click [**Run in background**](/docs/en/vs-code#move-a-running-command-or-subagent-to-the-background) in VS Code.

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

937937

938938If 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 and background tasks are off, **Ctrl+B** included.

939939

from line 943

943943

944944Background 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.

945945

946A background subagent can leave a background [Bash or PowerShell command](/docs/en/tools-reference#background-commands) [running past the end of its turn](/docs/en/interactive-mode#how-backgrounding-works). When that command ends, Claude Code sends the subagent a notification.

946A 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.

947947

948948A 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.

949949

from line 951

951951

952952Claude 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:

953953

954* When a subagent finishes successfully, Claude Code removes its row immediately and, except in [screen reader mode](/docs/en/accessibility), 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.

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

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

956956

957957A 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.

from line 958

958958

959959### Subagent names

960960

961If you start a session with [agent teams](/docs/en/agent-teams#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.

961If 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.

962962

963In an interactive session with [agent teams](/docs/en/agent-teams) 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#how-claude-starts-agent-teams).

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

964964

965965### API errors in subagents

966966

967When something [cuts off a subagent's response mid-stream](/docs/en/errors#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.

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

968968

969969A 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:

970970

from line 977

977977⚠ This agent switched to <model> because its earlier model could not be used.

978978```

979979

980When you configure a [fallback model chain](/docs/en/model-config#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.

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

981981

982982Once the underlying API error clears, ask Claude to retry the task or [resume the subagent](#resume-subagents).

983983

from line 988

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

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

990990

991The 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) and [sandboxing](/docs/en/sandboxing). It isn't a substitute for [restricting what a subagent can reach](#control-subagent-capabilities).

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

992992

993993A 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.

994994

from line 1018

10181018>

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

10201020

1021For work that needs to keep running in parallel or won't fit in one context window, run it in [separate sessions](/docs/en/agents) and let Claude [pass findings between them](/docs/en/cross-session-messaging).

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

10221022

10231023#### Chain subagents

10241024

from line 1043

10431043* You want to enforce specific tool restrictions or permissions

10441044* The work is self-contained and can return a summary

10451045

1046Consider [Skills](/docs/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.

1046Consider [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.

10471047

10481048For 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.

10491049

from line 1083

10831083

10841084Two 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.

10851085

1086By 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#adjust-effort-level) active are exempt: the limit isn't enforced there. Requires Claude Code v2.1.217 or later.

1086By 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.

10871087

10881088The limit blocks only subagents Claude spawns with the Agent tool, but other runs occupy the same slots:

10891089

from line 1090

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

10911091* [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.

10921092

1093Agents that other features run, such as [workflow](/docs/en/workflows) agents and [agent team](/docs/en/agent-teams) teammates, follow their own limits instead.

1093Agents 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.

10941094

10951095### Manage subagent context

10961096

from line 1102

11021102

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

11041104* **Task message**: the delegation prompt Claude writes when it hands off the work.

1105* **CLAUDE.md files**: every level of the [CLAUDE.md hierarchy](/docs/en/memory#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).

1106* **Git status**: a snapshot Claude Code reads from your repository when the subagent starts. For a subagent in [its own worktree](/docs/en/worktrees#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.

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

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

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

1108* **Sibling roster**: a [system reminder](/docs/en/glossary#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) teammate. It is a snapshot taken when the subagent starts, so agents named later don't appear.

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

11091109

1110To 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#path-specific-rules) still [load](/docs/en/memory#how-claude-md-files-load) when the subagent works with files there.

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

11111111

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

11131113

from line 1115

11151115

11161116Some main-conversation state never reaches a non-fork subagent:

11171117

1118* **Output style**: a subagent runs its own system prompt, so your [output style](/docs/en/output-styles) doesn't shape its responses, except in a [fork](#fork-the-current-conversation).

1119* **Auto memory**: the main conversation's [auto memory](/docs/en/memory#auto-memory) isn't loaded. To give a subagent persistent memory of its own, use the [`memory` field](#enable-persistent-memory).

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

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

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

11211121

11221122#### Resume subagents

from line 1129

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

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

11311131

1132Claude 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) 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), on this machine or [beyond it](/docs/en/cross-session-messaging#message-sessions-on-other-machines).

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

11331133

11341134To resume a subagent, ask Claude to continue the previous work:

11351135

from line 1141

11411141[Claude resumes the subagent with full context from previous conversation]

11421142```

11431143

1144When 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#subagents-and-the-cache).

11451145

11461146A 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.

11471147

from line 1161

11611161

11621162* **Main conversation compaction**: when the main conversation compacts, subagent transcripts are unaffected. They're stored in separate files.

11631163* **Session persistence**: subagent transcripts persist within their session. You can [resume a subagent](#resume-subagents) after restarting Claude Code by resuming the same session.

1164* **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#cleaned-up-automatically).

11651165

11661166##### Message a subagent by name after a restart

11671167

11681168> [!NOTE]

11691169>

1170> For a subagent that launched as a teammate, see the [agent team limitations](/docs/en/agent-teams#limitations) instead.

1170> For a subagent that launched as a teammate, see the [agent team limitations](/docs/en/agent-teams.md#limitations) instead.

11711171

1172If 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#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/`.

1172If 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/`.

11731173

11741174After 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.

11751175

11761176#### Auto-compaction

11771177

1178Subagents 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) for when the override takes effect.

11791179

11801180Compaction events are logged in subagent transcript files:

11811181

from line 1194

11941194

11951195##### Set the auto-compact window for one subagent

11961196

1197To 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#claude_code_auto_compact_window-values). Requires Claude Code v2.1.296 or later.

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

11981198

11991199This frontmatter sets `autoCompactWindow` to 200,000 tokens for a subagent that reads long log files:

12001200

from line 1210

12101210

12111211If the value is in range and you still see no change, check for these causes:

12121212

1213* **The value isn't below the [auto-compact window](/docs/en/model-config#context-window-and-auto-compaction) the subagent would otherwise inherit**: to compact earlier, set a value below that window.

1214* **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#set-the-auto-compact-window).

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

12151215

12161216## Fork the current conversation

12171217

12181218> [!NOTE]

12191219>

1220> When [agent view is turned off](/docs/en/agent-view#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#from-inside-a-session).

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

12211221

12221222A 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.

12231223

from line 1246

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

12471247| `Esc` | Return focus to the prompt input |

12481248

1249With a fork's or subagent's transcript open, follow-up messages and [skills](/docs/en/skills) go to that agent, and built-in commands go to your main conversation, with these safeguards:

1249With 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:

12501250

12511251* `/compact`, `/clear`, and `/rewind` act on the main conversation, so Claude Code asks you to confirm before running one of them from this view.

12521252* `/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.

12531253

1254To 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#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.

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

12551255

12561256### How forks differ from other subagents

12571257

from line 1264

12641264| Model | Same as main session | From the subagent's `model` field |

12651265| Prompt cache | Shared with main session | Separate cache |

12661266

1267Because 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#subagents-and-the-cache). Because of that reuse, a fork costs less than a fresh subagent for tasks that need the same context.

1267Because 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.

12681268

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

12701270

from line 1428

14281428You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

14291429```

14301430

1431Claude Code [passes hook input as JSON](/docs/en/hooks#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#exit-code-2-behavior-per-event) to block execution and returns an error message to Claude via stderr.

1431Claude 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.

14321432

14331433Create the validation script anywhere in your project. The path must match the `command` field in your hook configuration:

14341434

from line 1461

14611461chmod +x ./scripts/validate-readonly-query.sh

14621462```

14631463

1464On Windows, write the validation script in PowerShell and add `shell: powershell` to the hook entry. See [running hooks in PowerShell](/docs/en/hooks#windows-powershell-tool).

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

14651465

1466The 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#exit-code-output) for details on exit codes and [Hook input](/docs/en/hooks#pretooluse-input) for the complete input schema.

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

14671467

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

14691469

from line 1471

14711471

14721472Now that you understand subagents, explore these related features:

14731473

1474* [Distribute subagents with plugins](/docs/en/plugins/components#agents) to share subagents across teams or projects

1475* [Run Claude Code programmatically](/docs/en/headless) with the Agent SDK for CI/CD and automation

1476* [Use MCP servers](/docs/en/mcp) to give subagents access to external tools and data

1474* [Distribute subagents with plugins](/docs/en/plugins/components.md#agents) to share subagents across teams or projects

1475* [Run Claude Code programmatically](/docs/en/headless.md) with the Agent SDK for CI/CD and automation

1476* [Use MCP servers](/docs/en/mcp.md) to give subagents access to external tools and data

14771477

terminal-config Changed · +32 / -32 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) 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](/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). 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](/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#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).

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), `/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](/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#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](/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

7171By 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:

7272

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#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](/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) doesn't report its status to your terminal, even while you're attached to it. Agent view shows its status instead.

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.

118118* **[`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.

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#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](/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#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](/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

136136If 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.

137137

from line 139

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) 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](/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#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](/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#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](/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). 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](/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#watch-your-changes-in-the-diff-panel) or a [mod's pane](/docs/en/plugins/mods/interface) |

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

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) 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](/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>

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

285285

286286## Switch to fullscreen rendering

287287

288In [screen reader mode](/docs/en/accessibility), this section doesn't apply. Claude Code always renders as plain scrolling text except in attached [background sessions](/docs/en/agent-view), and if you run `/tui fullscreen` in any other session, Claude Code prints an explanation instead of switching.

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.

289289

290If the display flickers or the scroll position jumps while Claude is working, switch to [fullscreen rendering mode](/docs/en/fullscreen). 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#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](/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.

291291

292292If 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.

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#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](/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 317

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#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](/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#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](/docs/en/env-vars.md#features-that-need-feature-flag-fetching), pastes aren't marked.

325325

326326### Delete and restore a collapsed paste

327327

from line 329

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#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](/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#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`](/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:

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#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](/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

341341Claude 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.

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#vim-editor-mode) for the full key table.

344344

345345Vim 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.

346346

from line 348

348348

349349## Related resources

350350

351* [Interactive mode](/docs/en/interactive-mode): full keyboard shortcut reference and the Vim key table

352* [Keybindings](/docs/en/keybindings): remap any Claude Code shortcut, including Enter and Shift+Enter

353* [Fullscreen rendering](/docs/en/fullscreen): details on scrolling, search, and copy in fullscreen mode

354* [Hooks guide](/docs/en/hooks-guide): more Notification hook examples for Linux and Windows

355* [Troubleshooting](/docs/en/troubleshooting): fixes for issues outside terminal configuration

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

356356

third-party-integrations Changed · +20 / -20 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) 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](/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) 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](/docs/en/claude-code-on-the-web.md) on compute your organization operates, see [self-hosted environments](/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#sign-in-without-an-api-key)</td>

84 <td>API key or a [Console sign-in without one](/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).

123For a feature-by-feature breakdown of what's available on each option, see [Feature availability](/docs/en/feature-availability.md).

124124

125125Select a deployment option to view setup instructions:

126126

127* [Claude for Teams or Enterprise](/docs/en/authentication#claude-for-teams-or-enterprise)

128* [Anthropic Console](/docs/en/authentication#claude-console-authentication)

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)

129129* [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)

131* [Claude Platform on AWS](/docs/en/claude-platform-on-aws)

132* [Google Cloud's Agent Platform](/docs/en/google-vertex-ai)

133* [Microsoft Foundry](/docs/en/microsoft-foundry)

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)

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

142142* **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#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](/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#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#choose-where-to-put-claude-md-files) and [how to deploy an organization-wide CLAUDE.md](/docs/en/memory#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](/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).

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), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), [Microsoft Foundry](/docs/en/microsoft-foundry), or [Claude Platform on AWS](/docs/en/claude-platform-on-aws), 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#pin-models-for-third-party-deployments) for what each provider does when the default is unavailable.

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.

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

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

169169

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

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

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) and authenticate with their credentials.

1812. **Set up shared configuration**: Create a [CLAUDE.md file](/docs/en/memory) in your repositories to help Claude Code understand your codebase and coding standards.

1823. **Configure permissions**: Review [security settings](/docs/en/security) 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](/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.

183183

tools-reference Changed · +124 / -124 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#tool-specific-permission-rules), [subagent tool lists](/docs/en/sub-agents), and [hook matchers](/docs/en/hooks).

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

7To control which tools Claude can use and when it asks first, configure [permission rules](/docs/en/permissions#tool-specific-permission-rules) in your settings, [hooks](/docs/en/hooks), or a [subagent's tool list](/docs/en/sub-agents#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](/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.

9To add custom tools, connect an [MCP server](/docs/en/mcp). To extend Claude with reusable prompt-based workflows, write a [skill](/docs/en/skills), which runs through the existing `Skill` tool rather than adding a new tool entry.

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.

1010

1111> [!NOTE]

1212>

13> In [auto mode](/docs/en/permission-modes#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) 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#working-directories). `Bash` is marked Yes but runs a built-in set of [read-only commands](/docs/en/permissions#read-only-commands) without prompting.

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.

1414

1515| Tool | Description | Permission required |

1616| :- | :- | :- |

17| `Agent` | Spawns a [subagent](/docs/en/sub-agents) with its own context window to handle a task. With [agent teams](/docs/en/agent-teams) enabled, a call that carries a `name` can launch a [teammate](/docs/en/agent-teams#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): 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#control-public-sharing). Requires a Pro, Max, Team, or Enterprise plan and `/login` authentication; see [Availability](/docs/en/artifacts#availability) | Yes |

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 |

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) | 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) 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](/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 |

2828| `ExitPlanMode` | Presents a plan for approval and exits plan mode | Yes |

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

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) teammates, your other local Claude Code sessions, and, while this session is connected to [Remote Control](/docs/en/remote-control), your [cloud sessions](/docs/en/claude-code-on-the-web) and your Remote Control sessions on other machines. Backs the `/list-agents` command. See [cross-session messaging](/docs/en/cross-session-messaging). Requires Claude Code v2.1.224 or later, and appears only in sessions where [cross-session messaging is enabled](/docs/en/cross-session-messaging#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), leaving out [MCP Apps UI resources](/docs/en/mcp#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](/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 |

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) is connected, so a long-running task or [session-scoped scheduled task](/docs/en/scheduled-tasks) 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](/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 |

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), 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](/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 |

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#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) teammate, a [subagent it resumes](/docs/en/sub-agents#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) covers which sessions Claude can reach, [what a message looks like when it arrives](/docs/en/cross-session-messaging#what-a-message-looks-like), and [how Claude gets a notice when another session goes idle](/docs/en/cross-session-messaging#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#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) client is connected or in a [cloud session](/docs/en/claude-code-on-the-web). 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](/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 |

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#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#eliminate-prompts-with-auto-mode), to subagents that the Agent tool runs locally other than [forks](/docs/en/sub-agents#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](/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 |

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#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) 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](/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 |

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#scale-with-mcp-tool-search) is enabled | No |

58| `WaitForMcpServers` | Waits for one or more [MCP servers](/docs/en/mcp) 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#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](/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 |

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): a script that orchestrates many subagents in the background and returns one consolidated result | 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 |

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 66

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

6868* 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)

69* in the `--allowedTools` and `--disallowedTools` [CLI flags](/docs/en/cli-reference.md)

7070* in the Agent SDK's [`allowedTools` and `disallowedTools`](/docs/en/agent-sdk/permissions#allow-and-deny-rules) options

7171* in a [skill's `allowed-tools`](/docs/en/skills#frontmatter-reference) frontmatter

7272* in a hook's [`if` condition](/docs/en/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field)

from line 75

7575

7676| Rule format | Applies to | Details |

7777| :- | :- | :- |

78| `Bash(npm run *)` | Bash, Monitor | [Command pattern matching](/docs/en/permissions#bash) |

79| `PowerShell(Get-ChildItem *)` | PowerShell | [Command pattern matching](/docs/en/permissions#powershell) |

80| `Read(~/secrets/**)` | Read, Grep, Glob, LSP | [Path pattern matching](/docs/en/permissions#read-and-edit) |

81| `Edit(/src/**)` | Edit, Write, NotebookEdit | [Path pattern matching](/docs/en/permissions#read-and-edit) |

82| `Skill(deploy *)` | Skill | [Skill name matching](/docs/en/skills#restrict-claude’s-skill-access) |

83| `Agent(Explore)` | Agent | [Subagent type matching](/docs/en/permissions#agent-subagents) |

84| `WebFetch(domain:example.com)` | WebFetch | [Domain matching](/docs/en/permissions#webfetch) |

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

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#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#pretooluse-input).

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

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) enabled, a call that carries a `name` can launch a [teammate](/docs/en/agent-teams#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#turn-fork-mode-on-or-off) is on, the tool can launch a [forked subagent](/docs/en/sub-agents#fork-the-current-conversation), which inherits the full parent conversation instead of starting fresh

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

9999

100To cap how many turns a subagent runs, set `maxTurns` in the [subagent definition](/docs/en/sub-agents#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#resume-subagents) to continue.

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.

101101

102Which tools a non-fork subagent can use depends on the `tools` and `disallowedTools` fields in the [subagent definition](/docs/en/sub-agents):

102Which tools a non-fork subagent can use depends on the `tools` and `disallowedTools` fields in the [subagent definition](/docs/en/sub-agents.md):

103103

104* **Neither field set**: the subagent inherits every [tool available to subagents](/docs/en/sub-agents#available-tools).

104* **Neither field set**: the subagent inherits every [tool available to subagents](/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#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](/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#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](/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#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#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](/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 131

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), in [screen reader mode](/docs/en/accessibility), or while the session is connected to [Remote Control](/docs/en/remote-control). 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](/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.

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#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](/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#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`](/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.

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) control what Claude gets for a command that runs in the foreground:

155Two [environment variables](/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 180

180180

181181#### When a background command stops

182182

183A command that a [foreground subagent](/docs/en/sub-agents#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](/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#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](/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#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) 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](/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#start-faster-with-bare-mode) disables auto-backgrounding along with the rest of the background task functionality, so a command that reaches its timeout stops instead.

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 along with the rest of the background task functionality, 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 229

229229

230230Claude 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:

231231

232* `mcp`: local [MCP servers](/docs/en/mcp)

232* `mcp`: local [MCP servers](/docs/en/mcp.md)

233233* `lsp`: [language servers](#lsp-tool-behavior)

234* `hooks`: [hook](/docs/en/hooks) commands

235* `plugin`: commands that [plugins](/docs/en/plugins/overview) run

234* `hooks`: [hook](/docs/en/hooks.md) commands

235* `plugin`: commands that [plugins](/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)

237* `agent`: child Claude Code processes, such as [agent teammates](/docs/en/agent-teams.md)

238238

239239Whatever you list, these rules apply:

240240

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#path-specific-rules) that apply to that file. See [Read and Edit permission rules](/docs/en/permissions#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`](/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.

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#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](/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) 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](/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#pretooluse) don't run for it. While any other tool remains, you can't block it either: [deny and ask rules](/docs/en/permissions#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](/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.

283283

284[Subagents](/docs/en/sub-agents) never get the tool. Background tasks that share the main conversation's tool list see it, but calling it there ends nothing.

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.

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) 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](/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) TypeScript and Python packages

292 * the [VS Code extension](/docs/en/vs-code) panel, which bundles its own CLI

293 * [GitHub Actions](/docs/en/github-actions)

294 * [cloud sessions](/docs/en/claude-code-on-the-web)

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)

295295* **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), [Claude Platform on AWS](/docs/en/claude-platform-on-aws), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), or [Microsoft Foundry](/docs/en/microsoft-foundry), or on sessions signed in through a [cloud gateway](/docs/en/claude-apps-gateway).

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

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) 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#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#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`](/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.

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#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](/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#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](/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) for your language. In [cloud sessions](/docs/en/claude-code-on-the-web), 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](/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.

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) 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](/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) 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](/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#tool-specific-permission-rules), so `allow` and `deny` patterns you have set for Bash apply here too. While [auto mode](/docs/en/permission-modes#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#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](/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.

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

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

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#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](/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

406406Claude 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.

407407

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#powershell) receive the tool's command string in `tool_input.command`, with the same fields as the Bash tool.

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.

431431

432Match `Bash|PowerShell` in hooks that inspect shell commands; the [PowerShell hook input section](/docs/en/hooks#powershell) explains why matching `Bash` alone is not enough.

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.

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#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](/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

from line 465

465465Three additional settings control where PowerShell is used:

466466

467467* `"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#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#frontmatter-reference): runs `` !`command` `` blocks in 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.

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#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](/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#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](/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#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

from line 516

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) 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`](/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.

520520

521521What Claude receives when a read goes over the default limits:

522522

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#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](/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#features-disabled-under-zdr), and in organizations with the [HIPAA configuration](/docs/en/hipaa-setup) 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](/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.`

565565

566566### Discard or keep a draft

567567

from line 569

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), 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) sessions, which have no screen to review the queue on

579* [Cloud sessions](/docs/en/claude-code-on-the-web), which can't write to the queue on your machine

580* Sessions on [Amazon Bedrock](/docs/en/amazon-bedrock), [Claude Platform on AWS](/docs/en/claude-platform-on-aws), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), or [Microsoft Foundry](/docs/en/microsoft-foundry)

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#features-that-need-feature-flag-fetching)

582* Organizations that have turned off product feedback, [organizations with Zero Data Retention](/docs/en/zero-data-retention#features-disabled-under-zdr), and organizations with the [HIPAA configuration](/docs/en/hipaa-setup) applied

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)

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

583583

584584## Task tool availability

585585

586586The 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#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

from line 594

594594* 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

595595* 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

596596

597In [background sessions](/docs/en/agent-view) and in [cloud sessions](/docs/en/claude-code-on-the-web), Claude Code provides the same tools on every model, listed or not.

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.

598598

599Claude Code gives a subagent the tools only when your session has them, even when the subagent runs a different model. An in-process [agent team](/docs/en/agent-teams) teammate follows your session the same way, while a teammate in its own [split pane](/docs/en/agent-teams#choose-a-display-mode) runs as a separate Claude Code process, so its own model decides. Without the Task tools, an agent coordinates with its team through messages instead of the [shared task list](/docs/en/agent-teams#assign-and-claim-tasks).

599Claude Code gives a subagent the tools only when your session has them, even when the subagent runs a different model. An in-process [agent team](/docs/en/agent-teams.md) teammate follows your session the same way, while a teammate in its own [split pane](/docs/en/agent-teams.md#choose-a-display-mode) runs as a separate Claude Code process, so its own model decides. Without 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).

600600

601601The default set described here applies in Claude Code v2.1.268 and later.

602602

from line 608

608608

609609A few behaviors shape the response Claude receives:

610610

611* 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#webfetch-cannot-fetch-localhost) tells Claude to reach local servers with `curl` through Bash instead.

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

612612* HTTP URLs are automatically upgraded to HTTPS.

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

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

from line 616

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

617617* When the extraction step hits an overloaded API, Claude Code retries it with backoff; a fetch that still fails returns an error result.

618618

619In Manual and `acceptEdits` [permission modes](/docs/en/permission-modes), WebFetch prompts before fetching, except for domains your [permission rules](/docs/en/permissions#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#webfetch-domain-safety-check) first; that section covers what the check sends and the setting that skips it. The prompt offers three options:

619In 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:

620620

621621* **Yes**: approves this fetch only. The next WebFetch call prompts again, even for the same domain.

622* **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#permission-system). When your organization sets [`allowManagedPermissionRulesOnly`](/docs/en/permissions#managed-only-settings), Claude Code hides this option.

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

623623* **No, and tell Claude what to do differently**: rejects the fetch.

624624

625To 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#permission-modes) skip the prompt, except for a domain an explicit `ask` rule matches.

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

626626

627627An 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.

628628

629When the URL is a claude.ai [artifact](/docs/en/artifacts) 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#read-an-artifact-shared-with-you).

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

630630

631631WebFetch 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.

632632

633Sandboxed 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#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.

633Sandboxed 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.

634634

635635### WebFetch availability

636636

from line 650

650650

651651WebSearch permission rules take no specifier. A bare `WebSearch` entry in `allow` or `deny` is the only form.

652652

653The search backend is not configurable. To search with a different provider, add an [MCP server](/docs/en/mcp) that exposes a search tool.

653The search backend is not configurable. To search with a different provider, add an [MCP server](/docs/en/mcp.md) that exposes a search tool.

654654

655655> [!NOTE]

656656>

657> WebSearch is available on the Claude API, [Claude Platform on AWS](/docs/en/claude-platform-on-aws), 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.

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

658658

659659### Session search limit

660660

661An interactive terminal session has a limit of 200 WebSearch calls. Searches from the main conversation and from [subagents](/docs/en/sub-agents), such as a parallel research fan-out, count against the same limit.

661An 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.

662662

663663While 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.

664664

from line 668

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

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

670670

671In [non-interactive mode](/docs/en/headless) with `-p` and in the [Agent SDK](/docs/en/agent-sdk/overview), 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).

671In [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).

672672

673673## Write tool behavior

674674

from line 698

698698

699699> [!NOTE]

700700>

701> The [advisor tool](/docs/en/advisor) 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.

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

702702

703703## See also

704704

705* [MCP servers](/docs/en/mcp): add custom tools by connecting external servers

706* [Permissions](/docs/en/permissions): permission system, rule syntax, and tool-specific patterns

707* [Subagents](/docs/en/sub-agents): configure tool access for subagents

708* [Hooks](/docs/en/hooks-guide): run custom commands before or after tool execution

705* [MCP servers](/docs/en/mcp.md): add custom tools by connecting external servers

706* [Permissions](/docs/en/permissions.md): permission system, rule syntax, and tool-specific patterns

707* [Subagents](/docs/en/sub-agents.md): configure tool access for subagents

708* [Hooks](/docs/en/hooks-guide.md): run custom commands before or after tool execution

709709

troubleshoot-install Changed · +33 / -33 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). For configuration problems such as settings not applying or hooks not firing, see [Debug your configuration](/docs/en/debug-your-config).

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

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#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](/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) |

60| `API Error: 500`, `529 Overloaded`, `429`, or other 4xx and 5xx errors not listed above | See the [Error reference](/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) 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).

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

6767

6868## Run diagnostic checks

6969

from line 124

124124

125125> [!NOTE]

126126>

127> The [VS Code extension](/docs/en/vs-code) 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) to use `claude` from a terminal, then continue below.

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.

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#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](/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#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](/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#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](/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#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#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](/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#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](/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 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#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#auto-updates).

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

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#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#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](/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#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#install-claude-code)** instead of npm. It installs a binary rather than a `.ps1` script.

7193. **Use the [PowerShell installer](/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#system-requirements).

763Installing needs roughly 512 MB of free memory, and running Claude Code needs more. See the [system requirements](/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) include changes that need [security approval](/docs/en/server-managed-settings#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](/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`.

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#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](/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#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](/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#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](/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):

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#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](/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#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](/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#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](/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), skip this section.

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.

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#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](/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) for proxy setup.

1131* **Behind a proxy**: corporate proxies can interfere with API requests. See [network configuration](/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#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](/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#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), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), or [Microsoft Foundry](/docs/en/microsoft-foundry) for full provider setup.

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.

12461246

12471247## Still stuck

12481248

troubleshooting Changed · +27 / -27 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) |

10| Update or install download fails with `The connection dropped while downloading the update` or `aborted` | [Troubleshoot installation and login](/docs/en/troubleshoot-install#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#release-verification-failed) |

12| Session footer shows `Auto-update failed · Run claude doctor` in red | [Troubleshoot installation and login](/docs/en/troubleshoot-install#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#login-and-authentication) |

14| Settings not applying, hooks not firing, MCP servers not loading | [Debug your configuration](/docs/en/debug-your-config) |

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#which-mode-a-session-starts-in) |

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

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

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

18| `model not found` or `you may not have access to it` | [Error reference](/docs/en/errors#theres-an-issue-with-the-selected-model) |

19| A command Claude runs fails with `Your disk quota is full`, `is full (ENOSPC)`, or `Command output was lost` | [Error reference](/docs/en/errors#disk-quota-or-temp-filesystem-is-full) |

20| VS Code extension not connecting or detecting Claude | [VS Code integration](/docs/en/vs-code#fix-common-issues) |

21| `Claude Code process exited with code 1` in VS Code or an SDK app | [Error reference](/docs/en/errors#claude-code-process-exited-with-code-n) |

22| JetBrains plugin or IDE not detected | [JetBrains integration](/docs/en/jetbrains#troubleshooting) |

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

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#test-against-a-clean-configuration) to find which one

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

3939

4040If 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.

4141

42Outside [fullscreen rendering](/docs/en/fullscreen), running `/compact` frees memory too. The warning disappears once memory use drops back below 2.5GB.

42Outside [fullscreen rendering](/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#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](/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 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) so it runs in a separate context window

713. Move the large-file work to a [subagent](/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

7474If the error comes back after a `/clear`, run [`/context`](/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#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](/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) 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#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](/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), 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#mouse-wheel-scrolling) for the values each accepts.

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.

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) 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](/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

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

115115

from line 117

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) 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](/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#keep-native-text-selection) lists it for other terminals.

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.

127127* Set [`CLAUDE_CODE_DISABLE_MOUSE=1`](/docs/en/env-vars) on the remote machine so your terminal handles selection for the whole session.

128128

129129### Search and discovery issues

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#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](/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) 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](/docs/en/env-vars.md) or in the `env` block of your [`settings.json`](/docs/en/settings-reference#all-settings):

166166

167167```json theme={null}

168168{

ultrareview Changed · +10 / -10 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) 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](/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) 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](/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#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](/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) 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](/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

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#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](/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#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](/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#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](/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 181

181181* If the run fails, is stopped, or times out, the subcommand posts nothing.

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

183183

184For automatic reviews on GitHub pull requests, [Code Review](/docs/en/code-review) integrates with your repository directly and posts findings as inline PR comments without a CLI step.

184For 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.

185185

186186## How ultrareview compares to /code-review

187187

from line 200

200200

201201## Related resources

202202

203* [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web): learn how cloud sessions and cloud sandboxes work

204* [Manage costs effectively](/docs/en/costs): track usage and set spending limits

203* [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web.md): learn how cloud sessions and cloud sandboxes work

204* [Manage costs effectively](/docs/en/costs.md): track usage and set spending limits

205205

voice-dictation Changed · +15 / -13 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#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](/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) or SSH sessions.

14* **A local microphone**: voice dictation does not work in [cloud sessions](/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) 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](/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) 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](/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) instead of running `/voice`:

41Voice dictation persists across sessions. Set it directly in your [user settings file](/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) 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 61

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#transcript-viewer), `Space` pages through the conversation, and in [vim mode](/docs/en/interactive-mode#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](/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.

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#general-controls).

9999

100100## Change the dictation language

101101

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) 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](/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.

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

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

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

181183* **Transcription is garbled or in the wrong language**: dictation defaults to English. If you are dictating in another language, set it in `/config` first. See [Change the dictation language](#change-the-dictation-language).

182184

183185### Terminal not listed in macOS Microphone settings

from line 204

202204

203205## See also

204206

205* [Customize keyboard shortcuts](/docs/en/keybindings): rebind `voice:pushToTalk` and other CLI keyboard actions

206* [All settings](/docs/en/settings-reference#voice): the `voice`, `language`, and other settings keys

207* [Interactive mode](/docs/en/interactive-mode): keyboard shortcuts, input modes, and session controls

208* [Commands](/docs/en/commands): reference for `/voice`, `/config`, and all other commands

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

209211

vs-code Changed · +152 / -114 lines

#### The conversation is still open somewhere else ### Dictation or the Web tab fails behind a TLS-inspecting proxy

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#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](/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). 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](/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) 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).

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

4444

4545> [!NOTE]

4646>

from line 90

9090

9191**4. Review changes**

9292

93Check the [permission mode](/docs/en/permission-modes#which-mode-a-session-starts-in) shown at the bottom of the prompt box:

93Check the [permission mode](/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#protected-paths) in your workspace without asking.

95* In Auto or Edit automatically mode, Claude edits [most files](/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).

106For more ideas on what you can do with Claude Code, see [Common workflows](/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#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#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](/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.

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#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](/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.

130130

131 When [dynamic workflows](/docs/en/workflows) 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#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](/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.

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.

from line 135

135135

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

137137

138 Typing `/skills` also opens this dialog. Each [skill](/docs/en/skills) row shows its [visibility](/docs/en/skills#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), including your custom styles. Requires Claude Code v2.1.257 or later.

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.

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#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) 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), 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#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](/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.

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#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](/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). You can switch the sandbox mode and add [excluded commands](/docs/en/settings-reference#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) 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](/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.

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#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`](/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.

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), 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](/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

from line 163

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#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](/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#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`](/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.

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#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](/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.

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#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) has left before it expires. It counts down from the cache's five-minute or one-hour [lifetime](/docs/en/prompt-caching#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#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](/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.

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#choose-the-ttl-yourself).

180 * Right after the conversation is [compacted](/docs/en/prompt-caching#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), 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.

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.

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#background-commands), such as background shell commands and [monitors](/docs/en/tools-reference#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](/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.

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#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#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](/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#paste-large-content). In sessions where Claude Code [marks pasted text](/docs/en/terminal-config#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](/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.

228228

229Claude Code also removes [invisible Unicode characters](/docs/en/interactive-mode#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](/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. 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).

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) started in this workspace.

254254

255If the conversation is open in another Claude Code process, such as `claude` in a terminal or another VS Code window, this notice appears in place of the prompt box:

256

257```text theme={null}

258This conversation is still open somewhere else. Using it in two places at once can mix up its messages.

259```

260

261To continue here, close the conversation in the other place and then click **Open here anyway**. If you click without closing it, the conversation is open in both places. With [`claudeProcessWrapper`](#extension-settings) set, the extension skips this check and opens the conversation directly.

262

263255By 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**.

264256

265257To restore archived sessions:

from line 263

271263

272264When 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:

273265

274* The extension [chooses the starting permission mode](/docs/en/permission-modes#switch-permission-modes) from `claudeCode.initialPermissionMode` or a pick that carries over from an earlier conversation

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

275267* You have `claudeCode.claudeProcessWrapper` configured

276* A [deny rule](/docs/en/permissions#manage-permissions) removes the [`ExitPlanMode`](/docs/en/tools-reference) tool

268* A [deny rule](/docs/en/permissions.md#manage-permissions) removes the [`ExitPlanMode`](/docs/en/tools-reference) tool

277269

270#### The conversation is still open somewhere else

271

272To continue in this window when a notice says the conversation is still open somewhere else, click **Open here anyway** after the step for your case:

273

274* **You have nothing else open**: a Claude process from before the extension restarted may still have the conversation open. That process usually ends on its own within about 10 minutes, so wait that long and then click. If you click before it ends, the conversation is open in two places until it does.

275* **You have the conversation open somewhere else**: close it there first, for example by exiting `claude` in a terminal or closing its tab in another VS Code window

276

277When the conversation is still open in another Claude Code process, this notice appears in place of the prompt box:

278

279```text theme={null}

280This conversation is still open somewhere else. Using it in two places at once can mix up its messages. If the extension restarted recently, a Claude process from before the restart may still be finishing. It usually ends on its own within about 10 minutes. This notice stays until you choose Open here anyway.

281```

282

283With [`claudeProcessWrapper`](#extension-settings) set, the extension skips this check and opens the conversation directly.

284

278285### Resume cloud sessions from claude.ai

279286

280If you run [cloud sessions](/docs/en/claude-code-on-the-web), you can resume them directly in VS Code. This requires signing in with **Claude.ai Subscription**, not Anthropic Console.

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.

281288

282289**1. Open session history**

283290

from line 304

297304>

298305> When you resume a cloud session, the extension downloads a copy of the conversation history; changes don't sync back to claude.ai.

299306

300The Web tab also lists your [Remote Control](/docs/en/remote-control) 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](/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.

301308

302309If 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.

303310

from line 317

310317 The dialog also breaks down what is contributing to your plan limits:

311318

312319 * **Recommendations**: changes that lower your usage, one per row with the share of recent usage it addresses, such as `Trim ~/code/api/CLAUDE.md · 49k tokens per request`

313 * **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#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](/docs/en/costs.md#apply-recommendations-with-the-fix-shortcut). Requires Claude Code v2.1.305 or later.

314321

315 The button isn't shown while [Remote Control](/docs/en/remote-control) 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#check-connection-status) before you try again.

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.

316323 * **Attribution**: tables of how much usage came from each skill, subagent, plugin, and MCP server

317324

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

319* **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#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](/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.

320327

321For more on tracking and reducing usage, see [Track your costs](/docs/en/costs#track-your-costs).

328For more on tracking and reducing usage, see [Track your costs](/docs/en/costs.md#track-your-costs).

322329

323330### Rewind with checkpoints

324331

from line 335

328335* **Rewind code to here**: revert file changes back to this point in the conversation while keeping the full conversation history

329336* **Fork conversation and rewind code**: start a new conversation branch and revert file changes to this point

330337

331For full details on how checkpoints work and their limitations, see [Checkpointing](/docs/en/checkpointing).

338For full details on how checkpoints work and their limitations, see [Checkpointing](/docs/en/checkpointing.md).

332339

333340## Customize your workflow

334341

from line 364

357364* **Editor tab**: the conversation comes back with its tab.

358365* **Sidebar**: the conversation comes back if you sent a message or Claude responded in it within the last 10 minutes. If it doesn't come back, resume the conversation from [Session history](#resume-past-conversations).

359366

360If another Claude Code process still has the conversation open, you're asked before it opens here, with the same **Open here anyway** notice as when you [resume it from session history](#resume-past-conversations). If the messages stay blank at first, see [why they're blank and when they appear](#a-resumed-conversation-is-blank-at-first).

367If a notice in place of the prompt box says the conversation is still open somewhere else, see [how to continue the conversation here](#the-conversation-is-still-open-somewhere-else). If the messages stay blank at first, see [why they're blank and when they appear](#a-resumed-conversation-is-blank-at-first).

361368

362369#### Interrupted steps after a reload

363370

from line 424

417424

418425## Manage plugins

419426

420The VS Code extension includes a graphical interface for installing and managing [plugins](/docs/en/plugins/overview). 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](/docs/en/plugins/overview.md). Type `/plugins` in the prompt box to open the **Manage plugins** interface.

421428

422429### Install plugins

423430

from line 434

427434

428435* **Installed plugins** appear at the top with toggle switches to enable or disable them.

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

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

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

431438* **Available plugins** from your configured marketplaces appear below

432439* Search to filter plugins by name or description

433440* Click **Install** on any available plugin

from line 445

438445* **Install for this project**: shared with project collaborators (project scope)

439446* **Install locally**: only for you, only in this repository (local scope)

440447

441Once the install finishes, a form asks for any of the plugin's [configuration options](/docs/en/plugins/components#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](/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.

442449

443450Sensitive 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**.

444451

445452### Uninstall plugins

446453

447Each installed row names the [scope](/docs/en/plugins/install#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](/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.

448455

449456The extension asks first in two cases:

450457

from line 471

464471| Parameter | Description |

465472| - | - |

466473| `plugin` | The plugin's name as its marketplace lists it. Required. |

467| `marketplace` | The marketplace's [source](/docs/en/plugins/install#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](/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. |

468475

469476The extension checks both values before it opens anything:

470477

from line 487

480487* **The plugin is already installed**: the dialog says so, and nothing changes.

481488* **A different marketplace with the same name is already added**: the dialog says the link's marketplace wasn't added, and nothing installs.

482489

483GitHub 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#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](/docs/en/deep-links.md#the-link-renders-as-plain-text-instead-of-being-clickable) describes for `claude-cli://` links.

484491

485492### Manage marketplaces

486493

from line 495

488495

489496* Enter a GitHub repo, URL, or local path to add a new marketplace

490497* Click the refresh icon to update a marketplace's plugin list

491* Click the trash icon to remove a marketplace. Removing it [uninstalls every plugin you installed from it](/docs/en/plugins/install#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](/docs/en/plugins/install.md#manage-marketplaces), so a confirmation names those plugins first

492499

493500Plugin changes you make in the dialog apply right away to the Claude Code sessions open in that VS Code window.

494501

from line 505

498505>

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

500507

501For more about the plugin system, see [Plugins](/docs/en/plugins/overview) and [Plugin marketplaces](/docs/en/plugins/overview).

508For more about the plugin system, see [Plugins](/docs/en/plugins/overview.md) and [Plugin marketplaces](/docs/en/plugins/overview.md).

502509

503510### Plugins that draw in the panel

504511

505A plugin that contains a [mod](/docs/en/plugins/mods/overview) can draw in the chat panel. Drawing requires extension version 2.1.299 or later. A session that [doesn't fetch feature flags](/docs/en/env-vars#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](/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:

506513

507514* A pane beside the conversation or above the prompt box

508515* A toast or a status line above the prompt box

from line 539

532539

533540For more on working with the browser, see:

534541

535* [Enable Chrome by default](/docs/en/chrome#enable-chrome-by-default): have each session connect to your browser as it starts, without typing `@browser`

536* [Permission prompts in VS Code sessions](/docs/en/chrome#permission-prompts-in-vs-code-sessions): when Claude Code asks you before a browser action

537* [Use Claude Code with Chrome](/docs/en/chrome): setup instructions, the full list of capabilities, and troubleshooting

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

538545

539546## Work with git

540547

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

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

542549

543550### Create commits and pull requests

544551

from line 565

558565

559566### Move a running command or subagent to the background

560567

561When a command or a [subagent](/docs/en/sub-agents) 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](/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.

562569

563* **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#run-subagents-in-foreground-or-background) it spawned from the main conversation.

564* **After you click**: Claude stops waiting and continues the turn. The command or subagent keeps running as a [background task](/docs/en/tools-reference#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](/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.

565572

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

567574

from line 576

569576

570577By 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:

571578

572* **`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#let-claude-wait-for-a-subagent).

573* **`Spawned by` names another subagent**: the action appears only for subagents the main agent spawned, not a [nested subagent](/docs/en/sub-agents#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](/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.

574581

575582### Monitor background processes

576583

577584Type `/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.

578585

579For a background shell command, or a [monitor](/docs/en/tools-reference#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](/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.

580587

581588#### See a background subagent's tool calls

582589

from line 637

630637xdg-open "vscode://anthropic.claude-code/open"

631638```

632639

633The `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#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](/docs/en/deep-links.md#xdg-open-is-not-found-on-linux).

634641

635642**Windows**

636643

from line 658

651658| Parameter | Description |

652659| - | - |

653660| `prompt` | Text to pre-fill in the prompt box. Must be URL-encoded. The prompt is pre-filled but not submitted automatically. |

654| `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#continue-conversations). |

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

655662

656663For example, to open a tab pre-filled with "review my changes":

657664

from line 666

659666vscode://anthropic.claude-code/open?prompt=review%20my%20changes

660667```

661668

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

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

663670

664671## Configure settings

665672

from line 673

666673You configure the extension in two places, VS Code's extension settings and the Claude Code settings file:

667674

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

669* **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#switch-permission-modes) lists the order. See [Settings](/docs/en/settings) 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](/docs/en/permission-modes.md#switch-permission-modes) lists the order. See [Settings](/docs/en/settings.md) for details.

670677

671678> [!TIP]

672679>

from line 686

679686| Setting | Default | Description |

680687| - | - | - |

681688| `useTerminal` | `false` | Launch Claude in terminal mode instead of graphical panel |

682| `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#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](/docs/en/permission-modes.md#switch-permission-modes). |

683690| `preferredLocation` | `panel` | Where Claude opens: `sidebar` (right) or `panel` (new tab) |

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

685692| `autosave` | `true` | Auto-save files before Claude reads or writes them |

from line 722

715722

716723Follow the setup guide for your provider:

717724

718* [Claude Code on Amazon Bedrock](/docs/en/amazon-bedrock)

719* [Claude Code on Google Cloud's Agent Platform](/docs/en/google-vertex-ai)

720* [Claude Code on Microsoft Foundry](/docs/en/microsoft-foundry)

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)

721728

722729These guides cover configuring your provider in `~/.claude/settings.json`, which ensures your settings are shared between the VS Code extension and the CLI.

723730

724On 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), 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](/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).

725732

726733A claude.ai sign-in left over from an earlier `/login` stays unused: the extension doesn't send it with any request.

727734

728735## Use a screen reader

729736

730The 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), 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](/docs/en/accessibility.md), which adapts the terminal interface.

731738

732739Screen reader support in the chat panel requires Claude Code v2.1.236 or later.

733740

from line 742

735742

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

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

738* **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#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](/docs/en/hooks.md#sessionstart) hooks are still running, your screen reader also says "Running start-up hooks."

739746* **Queued messages**: when you send a message while Claude is working, the extension announces "Message queued." for that message.

740* **Errors and model prompts**: the extension announces errors in the conversation, and announces when the [usage-credits consent prompt](/docs/en/model-config#fable-and-usage-credits) or the [flagged-request prompt](/docs/en/model-config#ask-before-switching) appears.

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.

741748

742749While Claude works, your screen reader reads a text label in place of the progress spinner's animation.

743750

from line 770

763770

764771## VS Code extension vs. Claude Code CLI

765772

766Claude 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): 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](/docs/en/setup.md): the extension does not add `claude` to your PATH. See [Run CLI in VS Code](#run-cli-in-vs-code).

767774

768775| Feature | CLI | VS Code Extension |

769776| - | - | - |

770| Commands and skills | [All](/docs/en/commands) | Subset (type `/` to see available) |

777| Commands and skills | [All](/docs/en/commands.md) | Subset (type `/` to see available) |

771778| MCP server config | Yes | Yes: [add and manage servers](#connect-to-external-tools-with-mcp) with `/mcp` in the chat panel |

772779| Checkpoints | Yes | Yes |

773780| `!` Bash shortcut | Yes | No |

from line 784

777784

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

779786

780Installing 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). 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#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](/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).

781788

782789### Switch between extension and CLI

783790

from line 797

790797To manage MCP servers without leaving VS Code, type `/mcp` in the chat panel. From the dialog that opens, you can:

791798

792799* Add servers

793* Remove servers saved at the local, user, or project [scope](/docs/en/mcp#mcp-installation-scopes)

800* Remove servers saved at the local, user, or project [scope](/docs/en/mcp.md#mcp-installation-scopes)

794801* Enable or disable servers

795802* Reconnect to a server

796803* Manage OAuth authentication

from line 817

810817

811818> [!NOTE]

812819>

813> To find servers to connect, see [Find and build MCP servers](/docs/en/mcp#find-and-build-mcp-servers).

820> To find servers to connect, see [Find and build MCP servers](/docs/en/mcp.md#find-and-build-mcp-servers).

814821

815822## The built-in IDE MCP server

816823

from line 831

824831

825832**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:

826833

827* **Queued messages**: if you [queue a message while Claude works](/docs/en/interactive-mode#queue-messages-while-claude-works), it keeps the selection you had when you pressed `Enter`, whatever you select afterward.

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.

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

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

830837

from line 865

858865}

859866```

860867

861A `Read` deny rule covers neither tool, so block them by name with a [deny rule](/docs/en/permissions#mcp) as the example does.

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.

862869

863870**Jupyter execution always asks first.** `mcp__ide__executeCode` can't run anything silently. Each call goes through these steps:

864871

from line 885

878885

879886| What you see | Where to go |

880887| - | - |

881| `API Error: 403 Request not allowed` after you sign in | [403 Forbidden after login](/docs/en/troubleshoot-install#403-forbidden-after-login) |

882| You're asked to sign in again after you already signed in | [Not logged in or token expired](/docs/en/troubleshoot-install#not-logged-in-or-token-expired) |

883| Cloud provider credentials work in your terminal but not in the extension | [Bedrock, Agent Platform, or Foundry credentials not loading](/docs/en/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading) |

884| `SSL certificate verification failed` or `Self-signed certificate detected` | [SSL certificate errors](/docs/en/errors#ssl-certificate-errors) |

885| `Claude Code process exited with code 1`, or another code | [Claude Code process exited with code N](/docs/en/errors#claude-code-process-exited-with-code-n) |

886| `Could not locate the Claude CLI on PATH` | [Could not locate the Claude CLI on PATH](/docs/en/errors#could-not-locate-the-claude-cli-on-path) |

887| `The connection to Claude Code ended before this message completed` | [The connection to Claude Code ended before this message completed](/docs/en/errors#the-connection-to-claude-code-ended-before-this-message-completed) |

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

892| `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) |

888896| `claude` isn't found in VS Code's integrated terminal | [Run CLI in VS Code](#run-cli-in-vs-code) |

889897

890898### Extension won't install

from line 951

943951* **The formula is too large**: a formula longer than 8,192 characters, or one whose typeset output would be far larger than its TeX source, shows as written. Ask Claude to split it into smaller formulas or to write it more compactly.

944952* **The formula follows a large amount of math**: within one block of text in a response, the panel typesets formulas in order up to a limit. A later formula that would go past the limit shows as written. Ask Claude to send the formula you need again by itself.

945953

954### Dictation or the Web tab fails behind a TLS-inspecting proxy

955

956When 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:

957

958* **Dictation**: the microphone button shows the error text after `Dictation error: WebSocket error:`.

959* **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:

960 1. Run **Claude Code: Show Logs** from the [Command Palette](#vs-code-commands-and-shortcuts) to open the `Claude VSCode` output channel.

961 2. Click **Reconnect** on the tab and wait until it stops showing `Connecting…`.

962 3. Search the channel for `Error fetching remote sessions:` or `Failed to fetch organization UUID:`, then read the error text after that prefix on the newest matching line.

963

964This fix requires extension version 2.1.307 or later, so update the extension first. Then set `NODE_EXTRA_CA_CERTS` to the certificate file's full path, written without `~`. For a Windows path, write each backslash twice in `settings.json`, as in `C:\\certs\\example-ca.pem`.

965

966This example names a certificate file at the Linux or macOS path `/etc/ssl/certs/example-ca.pem`:

967

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

969{

970 "env": {

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

972 }

973}

974```

975

976Save `settings.json`, then start a recording or click **Reconnect** again. If the error comes back, open the output channel with **Claude Code: Show Logs** and search it for `use the CA certificates file`. Such a warning gives the reason the extension can't use your file and says where it read the path. Then find each place you set `NODE_EXTRA_CA_CERTS` in this table and do what its row says:

977

978| Where you set it | What to do |

979| - | - |

980| The environment VS Code was started with | A value set here takes precedence over one in `~/.claude/settings.json`, even when the file it names can't be used. Correct or remove it, then restart VS Code |

981| `env` in `~/.claude/settings.json` | Correct the value or the file it names, then start a recording or click **Reconnect** again |

982| VS Code's [`claudeCode.environmentVariables`](#extension-settings) setting, `~/.claude.json`, a project's `.claude/settings.json` or `.claude/settings.local.json`, or managed settings | A value set here doesn't apply to dictation or the Web tab. Set the variable in `env` in `~/.claude/settings.json` as well |

983

946984### Claude Code never responds

947985

948986If Claude Code isn't responding to your prompts:

from line 1021

9831021Remove-Item -Recurse -Force "$env:APPDATA\Code\User\globalStorage\anthropic.claude-code"

9841022```

9851023

986For additional help, see the [troubleshooting guide](/docs/en/troubleshooting).

1024For additional help, see the [troubleshooting guide](/docs/en/troubleshooting.md).

9871025

9881026## Next steps

9891027

9901028Now that you have Claude Code set up in VS Code:

9911029

992* [Explore common workflows](/docs/en/common-workflows) to get the most out of Claude Code

993* [Set up MCP servers](/docs/en/mcp) to extend Claude's capabilities with external tools. Add and manage them with `/mcp` in the chat panel.

994* [Configure Claude Code settings](/docs/en/settings) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.

995* [Review security safeguards](/docs/en/security) and [data usage](/docs/en/data-usage) for Claude Code

1030* [Explore common workflows](/docs/en/common-workflows.md) to get the most out of Claude Code

1031* [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.

1032* [Configure Claude Code settings](/docs/en/settings.md) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.

1033* [Review security safeguards](/docs/en/security.md) and [data usage](/docs/en/data-usage.md) for Claude Code

9961034

web-quickstart Changed · +39 / -39 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) is a better fit.

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.

2121

2222## How sessions run

2323

2424The 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:

2525

261. **Clone and prepare**: your repository is cloned to an Anthropic-managed VM, and your [setup script](/docs/en/cloud-environments#setup-scripts) runs if configured.

272. **Configure network**: internet access is set based on your environment's [access level](/docs/en/cloud-environments#access-levels).

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

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#send-local-repositories-without-github) via `--cloud` | No | No |

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 |

4444| **Keeps running if you disconnect** | Yes | No | While the session stays open on your machine |

45| **[Permission modes](/docs/en/permission-modes)** | Accept edits, Plan, Auto | All modes in the terminal; see [Switch permission modes](/docs/en/permission-modes#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](/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 |

4747

48See the [terminal quickstart](/docs/en/quickstart), [Desktop app](/docs/en/desktop), or [Remote Control](/docs/en/remote-control) docs to set up local sessions.

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.

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#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#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](/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.

5757

5858**1. Visit claude.ai/code**

5959

from line 61

6161

6262**2. Sign in with GitHub**

6363

64After 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 an empty repository on GitHub](https://github.com/new) first.

64After 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#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](/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#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) 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](/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#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](/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#default-allowed-domains) and other allowlisted domains, and nothing else through the session's network. See [Installed tools](/docs/en/cloud-environments#installed-tools) for what's available without any configuration.

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.

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#setup-scripts) before sessions start, [edit it or create additional environments](/docs/en/cloud-environments#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](/docs/en/cloud-environments.md#setup-scripts) before sessions start, [edit it or create additional environments](/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). On Team and Enterprise plans, `/web-setup` is available only after an Owner turns on [Quick setup](/docs/en/claude-code-on-the-web#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](/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).

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#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](/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) enabled, or with the [HIPAA configuration](/docs/en/hipaa-setup) applied, cannot use `/web-setup` or other cloud session features. Organizations that use [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek) (CMEK) can't start cloud sessions either. If the GitHub CLI isn't installed or isn't authenticated, Claude Code opens the browser onboarding flow instead.

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.

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#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](/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).

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#switch-permission-modes) shows the permission mode the session will run in:

135The [permission mode control](/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#available-modes) for what each one allows.

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.

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#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) 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](/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#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](/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

226226* 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) enabled, or has the [HIPAA configuration](/docs/en/hipaa-setup) applied. Either one makes cloud sessions unavailable.

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.

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#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](/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#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](/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#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](/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#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](/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#archive-sessions) to hide it from your list, or [delete it](/docs/en/claude-code-on-the-web#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](/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.

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): the full reference, including teleporting sessions to your terminal, session sharing, and auto-fixing pull requests

262* [Configure cloud environments](/docs/en/cloud-environments): network access levels, environment variables, and setup scripts for cloud sessions

263* [Cloud scheduled tasks](/docs/en/routines): automate work on a schedule, via API call, or in response to GitHub events

264* [CLAUDE.md](/docs/en/memory): give Claude persistent instructions and context that load at the start of every session

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

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#2-1-83)

5Releases [v2.1.83 → v2.1.85](/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)

25[Permission modes guide](/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#let-claude-use-your-computer)

40[Computer use guide](/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#auto-fix-pull-requests)

51[Auto-fix pull requests](/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#search-and-review-the-conversation)

67[Fullscreen guide](/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#powershell-tool)

85[PowerShell tool docs](/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)

108[Hooks reference](/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#2-1-83)

114[Full changelog for v2.1.83–v2.1.85 →](/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#2-1-86)

5Releases [v2.1.86 → v2.1.91](/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)

21[Computer use guide](/docs/en/computer-use.md)

2222

2323/powerup

2424v2.1.90

from line 33

3333/powerup

3434```

3535

36[Commands reference](/docs/en/commands)

36[Commands reference](/docs/en/commands.md)

3737

3838Flicker-free rendering

3939v2.1.89

from line 49

4949claude

5050```

5151

52[Fullscreen rendering](/docs/en/fullscreen)

52[Fullscreen rendering](/docs/en/fullscreen.md)

5353

5454MCP result-size override

5555v2.1.91

from line 68

6868}

6969```

7070

71[MCP reference](/docs/en/mcp#raise-the-limit-for-a-specific-tool)

71[MCP reference](/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#standard-layout)

88[Plugins reference](/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#2-1-86)

94[Full changelog for v2.1.86–v2.1.91 →](/docs/en/changelog.md#2-1-86)

9595

whats-new/2026-w15 Changed · +6 / -6 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#2-1-92)

5Releases [v2.1.92 → v2.1.101](/docs/en/changelog.md#2-1-92)

664 features · April 6–10

88Ultraplan

from line 39

3939/loop check CI on my PR

4040```

4141

42[Monitor tool reference](/docs/en/tools-reference#monitor-tool)

42[Monitor tool reference](/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#auto-fix-pull-requests)

57[Auto-fix pull requests](/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)

70[Commands reference](/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) and [Google Cloud's Agent Platform](/docs/en/google-vertex-ai) 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](/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`

7575

76[Full changelog for v2.1.92–v2.1.101 →](/docs/en/changelog#2-1-92)

76[Full changelog for v2.1.92–v2.1.101 →](/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#2-1-105)

5Releases [v2.1.105 → v2.1.113](/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#adjust-effort-level)

20[Model config: effort levels](/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)

35[Routines guide](/docs/en/routines.md)

3636

3737/usage breakdown

3838CLI

from line 47

4747> /usage

4848```

4949

50[Commands reference](/docs/en/commands)

50[Commands reference](/docs/en/commands.md)

5151

5252Mobile push notifications

5353mobile

5454

55With [Remote Control](/docs/en/remote-control) 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](/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#mobile-push-notifications)

65[Remote Control: mobile push notifications](/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)

79[Setup guide](/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#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#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`](/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`

8484

85[Full changelog for v2.1.105–v2.1.113 →](/docs/en/changelog#2-1-105)

85[Full changelog for v2.1.105–v2.1.113 →](/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#2-1-114)

5Releases [v2.1.114 → v2.1.119](/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)

27[Ultrareview guide](/docs/en/ultrareview.md)

2828

2929Session recap

3030CLI

from line 39

3939> /recap

4040```

4141

42[Interactive mode: session recap](/docs/en/interactive-mode#session-recap)

42[Interactive mode: session recap](/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#create-a-custom-theme)

55[Terminal config: create a custom theme](/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)

64[Claude Code on the web](/docs/en/claude-code-on-the-web.md)

6565

6666Other wins

6767

68[Vim visual mode](/docs/en/interactive-mode#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)[Forked subagents](/docs/en/sub-agents#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#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](/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

6969

70[Full changelog for v2.1.114–v2.1.119 →](/docs/en/changelog#2-1-114)

70[Full changelog for v2.1.114–v2.1.119 →](/docs/en/changelog.md#2-1-114)

7171

whats-new/2026-w18 Changed · +6 / -6 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#2-1-120)

5Releases [v2.1.120 → v2.1.126](/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#cli-commands)

19[CLI reference](/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)

38[CLI reference](/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#use-the-session-picker)

63[Sessions: use the session picker](/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)

70[Setup guide](/docs/en/setup.md)

7171

7272Other wins

7373

7474MCP 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

7575

76[Full changelog for v2.1.120–v2.1.126 →](/docs/en/changelog#2-1-120)

76[Full changelog for v2.1.120–v2.1.126 →](/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#2-1-128)

5Releases [v2.1.128 → v2.1.136](/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)

18[Plugins guide](/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#command-history)

25[Interactive mode: command history](/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#2-1-128)

31[Full changelog for v2.1.128–v2.1.136 →](/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#2-1-139)

5Releases [v2.1.139 → v2.1.142](/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)

21[Agent view](/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)

36[Goals](/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#understand-the-cost-tradeoff)

51[Fast mode on Opus 4.7](/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#2-1-139)

57[Full changelog for v2.1.139–v2.1.142 →](/docs/en/changelog.md#2-1-139)

5858

whats-new/2026-w21 Changed · +3 / -3 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#2-1-143)

5Releases [v2.1.143 → v2.1.149](/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#eliminate-prompts-with-auto-mode)

21[Auto mode requirements](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode)

2222

2323Other wins

2424

2525[`/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`

2626

27[Full changelog for v2.1.143–v2.1.149 →](/docs/en/changelog#2-1-143)

27[Full changelog for v2.1.143–v2.1.149 →](/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#2-1-150)

5Releases [v2.1.150 → v2.1.157](/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#available-models)

21[Model configuration](/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)

36[Dynamic workflows](/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)

57[Security guidance plugin](/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#understand-the-cost-tradeoff)

70[Fast mode pricing](/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#2-1-150)

76[Full changelog for v2.1.150–v2.1.157 →](/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#2-1-158)

5Releases [v2.1.158 → v2.1.165](/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#enable-auto-mode-on-bedrock-agent-platform-or-foundry)

19[Auto mode on third-party providers](/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#protected-paths)

32[Protected paths](/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#plugin-list)

45[Plugin commands](/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#decide-what-to-enforce)

60[Decide what to enforce](/docs/en/admin-setup.md#decide-what-to-enforce)

6161

6262Other wins

6363

64The trigger keyword for [dynamic workflows](/docs/en/workflows) 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) 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](/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

6565

66[Full changelog for v2.1.158–v2.1.165 →](/docs/en/changelog#2-1-158)

66[Full changelog for v2.1.158–v2.1.165 →](/docs/en/changelog.md#2-1-158)

6767