Home Docs Claude Code CLI

One capture · claude-code

One read of Claude Code CLIclaude-code-20261023T190701Z

220 pages moved out of 228 read.

Pages moved 220 significant first

Pages read 228 in this capture

Captured 23 Oct 2026 19:07 UTC

Corpus hash 7e3663570d29 corpus-hash

What this read moved

76-100 of 220, page 4 of 9

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

deep-links Changed · +5 / -5 lines

from line 154

154154

155155The handler launches Claude Code in a detected terminal emulator. On macOS, Claude Code remembers the terminal from your most recent interactive session and reuses it, supporting iTerm2, Ghostty, kitty, Alacritty, WezTerm, and Terminal.app. On Linux it honors the `$TERMINAL` environment variable, then `x-terminal-emulator`, then a list of common emulators. On Windows it prefers Windows Terminal, then PowerShell, then `cmd.exe`.

156156

157To prevent registration entirely, set [`disableDeepLinkRegistration`](/docs/en/settings-reference#disabledeeplinkregistration) to `"disable"` in `settings.json`. To enforce this across an organization so users cannot re-enable it, set it in [managed settings](/docs/en/server-managed-settings.md) instead. Claude Code's `disableDeepLinkRegistration` setting covers `claude-cli://` links only.

157To prevent registration entirely, set [`disableDeepLinkRegistration`](https://code.claude.com/docs/en/settings-reference#disabledeeplinkregistration) to `"disable"` in `settings.json`. To enforce this across an organization so users cannot re-enable it, set it in [managed settings](https://code.claude.com/docs/en/server-managed-settings.md) instead. Claude Code's `disableDeepLinkRegistration` setting covers `claude-cli://` links only.

158158

159159## Open a VS Code tab instead of a terminal

160160

161The VS Code extension registers its own handler at `vscode://anthropic.claude-code/open`, which opens a Claude Code editor tab rather than a terminal window. See [Launch a VS Code tab from other tools](/docs/en/vs-code.md#launch-a-vs-code-tab-from-other-tools) for that URL's parameters.

161The VS Code extension registers its own handler at `vscode://anthropic.claude-code/open`, which opens a Claude Code editor tab rather than a terminal window. See [Launch a VS Code tab from other tools](https://code.claude.com/docs/en/vs-code.md#launch-a-vs-code-tab-from-other-tools) for that URL's parameters.

162162

163163## Open a Claude Desktop session on an SSH connection

164164

165Claude Desktop handles its own `claude://` links. To open a Desktop session on a remote machine over SSH, see [Open an SSH session from a link](/docs/en/desktop.md#open-an-ssh-session-from-a-link).

165Claude Desktop handles its own `claude://` links. To open a Desktop session on a remote machine over SSH, see [Open an SSH session from a link](https://code.claude.com/docs/en/desktop.md#open-an-ssh-session-from-a-link).

166166

167167## Troubleshooting

168168

from line 190

190190

191191These pages cover related ways to launch or extend Claude Code sessions:

192192

193* [Skills](/docs/en/skills.md): store a long runbook prompt as a `/skill` in the repo so the deep link's `q` parameter only has to name it

194* [Non-interactive mode](/docs/en/headless.md): run Claude from a script and capture the output without opening a terminal

193* [Skills](https://code.claude.com/docs/en/skills.md): store a long runbook prompt as a `/skill` in the repo so the deep link's `q` parameter only has to name it

194* [Non-interactive mode](https://code.claude.com/docs/en/headless.md): run Claude from a script and capture the output without opening a terminal

195195

desktop Changed · +311 / -160 lines

#### Create an SSH connection from a command ##### Write the command ##### Connect to a new host ##### Replace the host ##### Distribute commands to your team ##### If a command is missing or gray

The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.

from line 12

1212>

1313> For x64 processors

1414

15> **[Get Claude for Linux (beta)](/docs/en/desktop-linux.md)**

15> **[Get Claude for Linux (beta)](https://code.claude.com/docs/en/desktop-linux.md)**

1616>

1717> apt or .deb for Ubuntu and Debian

1818

19For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](/docs/en/desktop-linux.md).

21After installing, launch Claude, sign in, and click the **Code** tab. For a walkthrough of your first session, see the [Get started guide](/docs/en/desktop-quickstart.md).

21After installing, launch Claude, sign in, and click the **Code** tab. For a walkthrough of your first session, see the [Get started guide](https://code.claude.com/docs/en/desktop-quickstart.md).

2222

2323In the Code tab, each conversation is a **session**: it has its own chat history and project folder, independent of any other session. The sidebar lists your sessions and lets you run several in parallel. Within a session you can:

2424

2525* [Review and comment on diffs](#review-changes-with-diff-view), then [watch the resulting PR through CI](#monitor-pull-request-status)

2626* [Preview your running app](#preview-your-app) in the Browser pane while Claude verifies its own changes, and [open external sites](#browse-external-sites) alongside it

27* Watch Claude [run and test your iOS app](/docs/en/desktop-ios-simulator.md) in the iOS Simulator pane

27* Watch Claude [run and test your iOS app](https://code.claude.com/docs/en/desktop-ios-simulator.md) in the iOS Simulator pane

2828* [Arrange panes](#arrange-your-workspace) for the chat, diff, browser, terminal, and file editor side by side

2929* Ask a [side question](#ask-a-side-question-without-derailing-the-session) that uses the session's context without derailing it

3030* Let Claude [check on, message, or archive your other sessions](#work-across-sessions)

from line 32

3232* Let Claude [open apps and control your screen](#let-claude-use-your-computer)

3333* Run on your machine, in the [cloud](#run-long-running-tasks-in-the-cloud), or over [SSH](#ssh-sessions)

3434

35For [scheduled recurring work](/docs/en/desktop-scheduled-tasks.md), [keyboard shortcuts](#keyboard-shortcuts), or [sending tasks from your phone](#sessions-from-dispatch), see the linked pages and sections. If you already use the terminal-based CLI, see the [CLI comparison](#coming-from-the-cli) for what carries over.

35For [scheduled recurring work](https://code.claude.com/docs/en/desktop-scheduled-tasks.md), [keyboard shortcuts](#keyboard-shortcuts), or [sending tasks from your phone](#sessions-from-dispatch), see the linked pages and sections. If you already use the terminal-based CLI, see the [CLI comparison](#coming-from-the-cli) for what carries over.

3636

3737## Start a session

3838

from line 44

4444 * **Cloud session**: select [repositories](#run-long-running-tasks-in-the-cloud) instead of a folder

4545 * **[Saved local or SSH environment](#create-a-saved-environment)**: the environment already holds its folders, so the row shows no project folder control. To change the folders, [edit the environment](#use-edit-or-remove-a-saved-environment).

4646* **Permission mode**: use the [mode selector](#choose-a-permission-mode) to choose how much autonomy Claude has. You can change the permission mode during the session.

47* **Model**: pick a [model](/docs/en/model-config.md#available-models) from the model picker toward the right end of the row. You can change the model during the session.

47* **Model**: pick a [model](https://code.claude.com/docs/en/model-config.md#available-models) from the model picker toward the right end of the row. You can change the model during the session.

4848

4949Type your task and press **Enter** to start. Each session tracks its own context and changes independently.

5050

from line 60

6060

6161### Accept a suggested prompt

6262

63After Claude replies, the Code tab can show a suggested next prompt as gray text in the empty prompt box. Claude Code [generates each suggestion](/docs/en/interactive-mode.md#prompt-suggestions) from your conversation with a short background request that counts toward your plan's usage limits or your API costs.

63After Claude replies, the Code tab can show a suggested next prompt as gray text in the empty prompt box. Claude Code [generates each suggestion](https://code.claude.com/docs/en/interactive-mode.md#prompt-suggestions) from your conversation with a short background request that counts toward your plan's usage limits or your API costs.

6464

6565* **Use the suggestion**: press **Tab** or **Right arrow** to place it in the prompt box, edit it if you want, then press **Enter** to send it. Pressing **Enter** before you accept the suggestion doesn't send it.

6666* **Write your own prompt**: start typing. The suggestion shows only while the prompt box is empty and has no attached files.

from line 74

7474* **@mention files**: type `@` followed by a filename to add a file to the conversation context.

7575 * **In a cloud session**: `@` can list files only after you send your first message. If `@` lists none, send your first message without the file, then @mention the file in your next message.

7676* **Attach files**: attach images, PDFs, and other files to your prompt from the **+** button next to the prompt box, or drag and drop files directly into the prompt. This is useful for sharing screenshots of bugs, design mockups, or reference documents.

77 * **In a [WSL session](/docs/en/desktop-wsl.md)**: if the **+** menu shows **Add image** instead of **Add files or photos**, you can attach only images. To give Claude any other file from the session's folder, @mention it.

77 * **In a [WSL session](https://code.claude.com/docs/en/desktop-wsl.md)**: if the **+** menu shows **Add image** instead of **Add files or photos**, you can attach only images. To give Claude any other file from the session's folder, @mention it.

7878

7979### Choose a permission mode

8080

8181Permission modes control how much autonomy Claude has during a session: whether it asks before editing files, running commands, or both. You can switch permission modes at any time using the mode selector in the row under the prompt box. To approve each change yourself, switch to Manual.

8282

83To set a default mode for new local sessions, add `permissions.defaultMode` to your [settings file](/docs/en/settings.md#where-settings-live). The desktop app reads the same settings files as the CLI. A mode you pick in the selector is remembered per folder and takes precedence over `defaultMode` for that folder, except Plan, which applies to the current session only.

83To set a default mode for new local sessions, add `permissions.defaultMode` to your [settings file](https://code.claude.com/docs/en/settings.md#where-settings-live). The desktop app reads the same settings files as the CLI. A mode you pick in the selector is remembered per folder and takes precedence over `defaultMode` for that folder, except Plan, which applies to the current session only.

8484

8585| Mode | Settings key | Behavior |

8686| - | - | - |

from line 88

8888| **Accept edits** | `acceptEdits` | Claude auto-accepts file edits and common filesystem commands like `mkdir`, `touch`, and `mv`, but still asks before running other terminal commands. Use this when you trust file changes and want faster iteration. |

8989| **Plan** | `plan` | Claude reads files and runs commands to explore, then proposes a plan without editing your source code. Good for complex tasks where you want to review the approach first. |

9090| **Auto** | `auto` | Claude runs without routine prompts; before actions such as shell commands and network requests run, a background classifier checks that they align with your request. Appears when [auto mode is available](#auto-mode-availability); there is no separate Settings toggle for it. |

91| **Bypass permissions** | `bypassPermissions` | Claude runs without permission prompts, except for the [actions no mode auto-approves](/docs/en/permission-modes.md#actions-no-mode-auto-approves), safety classifiers when Claude [acts on external sites](#browse-external-sites), or desktop actions such as deleting a session, though not [archiving one](#work-across-sessions). Equivalent to `--dangerously-skip-permissions` in the CLI. On Pro and Max plans, enable it in your Settings → Claude Code under "Allow bypass permissions mode"; on Team and Enterprise plans there is no Settings toggle, and organization policy controls it instead. Only use this in sandboxed containers or VMs. |

91| **Bypass permissions** | `bypassPermissions` | Claude runs without permission prompts, except for the [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves), safety classifiers when Claude [acts on external sites](#browse-external-sites), or desktop actions such as deleting a session, though not [archiving one](#work-across-sessions). Equivalent to `--dangerously-skip-permissions` in the CLI. On Pro and Max plans, enable it in your Settings → Claude Code under "Allow bypass permissions mode"; on Team and Enterprise plans there is no Settings toggle, and organization policy controls it instead. Only use this in sandboxed containers or VMs. |

9292

9393Earlier versions of the Code tab labeled these modes Ask permissions, Auto accept edits, and Plan mode.

9494

95The `dontAsk` permission mode is available only in the [CLI](/docs/en/permission-modes.md#allow-only-pre-approved-tools-with-dontask-mode).

95The `dontAsk` permission mode is available only in the [CLI](https://code.claude.com/docs/en/permission-modes.md#allow-only-pre-approved-tools-with-dontask-mode).

9696

9797> [!TIP]

9898>

99> Start complex tasks in Plan so Claude maps out an approach before making changes. Once you approve the plan, switch to Accept edits or Manual to execute it. See [explore first, then plan, then code](/docs/en/best-practices.md#explore-first-then-plan-then-code) for more on this workflow.

100

101Cloud sessions support Accept edits, Plan, and Auto. Accept edits corresponds to `default` mode: cloud sessions pre-approve file edits, so the selector shows Accept edits instead of Manual. Bypass permissions isn't available in cloud sessions, including sessions in a [self-hosted environment](/docs/en/self-hosted-environments).

99> Start complex tasks in Plan so Claude maps out an approach before making changes. Once you approve the plan, switch to Accept edits or Manual to execute it. See [explore first, then plan, then code](https://code.claude.com/docs/en/best-practices.md#explore-first-then-plan-then-code) for more on this workflow.

100

102102

103103Enterprise admins can restrict which permission modes are available. See [enterprise configuration](#enterprise-configuration) for details.

104104

105105#### Auto mode availability

106106

107Auto mode is available to all users on the Anthropic API and requires Claude Opus 4.6 or later, Sonnet 4.6 or later, Haiku 5.5, or a [Fable model](/docs/en/model-config.md#work-with-fable). Organization administrators can turn auto mode off with the `disableAutoMode` key in [managed settings](#managed-settings).

108

109In Enterprise deployments that route Desktop to Google Cloud's Agent Platform, auto mode is also available by default; see [Auto mode on Bedrock, Agent Platform, or Foundry](/docs/en/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry) for the supported models.

107Auto mode is available to all users on the Anthropic API and requires Claude Opus 4.6 or later, Sonnet 4.6 or later, Haiku 5.5, or a [Fable model](https://code.claude.com/docs/en/model-config.md#work-with-fable). Organization administrators can turn auto mode off with the `disableAutoMode` key in [managed settings](#managed-settings).

108

109In Enterprise deployments that route Desktop to Google Cloud's Agent Platform, auto mode is also available by default; see [Auto mode on Bedrock, Agent Platform, or Foundry](https://code.claude.com/docs/en/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry) for the supported models.

110110

111111### Preview your app

112112

from line 146

146146

147147The first time Claude acts on an external site, a permission card appears and Claude waits for your choice: **Allow once**, **Always allow**, or **Deny**. **Allow once** approves the action without saving anything. **Always allow** saves the approval for that site on your device, and you can revoke it in Settings. Each site needs its own approval, including subdomains. Your local dev servers and project files don't need approval, so [auto-verify](#auto-verify-changes) keeps working without prompts.

148148

149Even on an approved site, Claude won't purchase items, create accounts, or bypass CAPTCHAs without your input. Browsing in the Browser pane uses the same safety model as the [Claude in Chrome extension](/docs/en/chrome.md). See [Using Claude in Chrome safely](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely) for how Claude handles sensitive sites and risky actions.

149Even on an approved site, Claude won't purchase items, create accounts, or bypass CAPTCHAs without your input. Browsing in the Browser pane uses the same safety model as the [Claude in Chrome extension](https://code.claude.com/docs/en/chrome.md). See [Using Claude in Chrome safely](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely) for how Claude handles sensitive sites and risky actions.

150150

151151#### Choose between the Browser and the Chrome extension

152152

153The Browser pane uses a clean browser profile, separate from your personal browser, with none of your saved logins or history. Use it for building and testing your app and for sites that don't need your identity. When you want Claude to act as you in your logged-in sessions, use the [Claude in Chrome extension](/docs/en/chrome.md) instead, which shares your browser's login state.

153The Browser pane uses a clean browser profile, separate from your personal browser, with none of your saved logins or history. Use it for building and testing your app and for sites that don't need your identity. When you want Claude to act as you in your logged-in sessions, use the [Claude in Chrome extension](https://code.claude.com/docs/en/chrome.md) instead, which shares your browser's login state.

154154

155155#### Restrict external browsing for your organization

156156

from line 173

173173

174174To have Claude review your changes before you commit, enter `/code-review` in the [prompt box](#use-the-prompt-box). The findings arrive in the conversation when the review completes.

175175

176In local, [SSH](#ssh-sessions), and [WSL](/docs/en/desktop-wsl.md) sessions, the findings appear as a **Code review** card, grouped by file. Use the card to act on them:

176In local, [SSH](#ssh-sessions), and [WSL](https://code.claude.com/docs/en/desktop-wsl.md) sessions, the findings appear as a **Code review** card, grouped by file. Use the card to act on them:

177177

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

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

180180

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

182182

183183### Monitor pull request status

184184

from line 200

200200

201201## Arrange your workspace

202202

203The Code tab is built around panes you can arrange in any layout: chat, diff, browser, terminal, file, plan, tasks, and subagent, along with the [iOS Simulator](/docs/en/desktop-ios-simulator.md) on macOS. Drag a pane by its header to reposition it, or drag a pane edge to resize it. Press **Cmd+\\** on macOS or **Ctrl+\\** on Windows to close the focused pane.

203The Code tab is built around panes you can arrange in any layout: chat, diff, browser, terminal, file, plan, tasks, and subagent, along with the [iOS Simulator](https://code.claude.com/docs/en/desktop-ios-simulator.md) on macOS. Drag a pane by its header to reposition it, or drag a pane edge to resize it. Press **Cmd+\\** on macOS or **Ctrl+\\** on Windows to close the focused pane.

204204

205205To open another pane, click its icon button in the session's title bar. Hover to see each button's name, such as **Terminal**, **Changes** for the diff view, **Browser**, and **Files**. If the pane you want has no button in the title bar, select it from the **⋮** menu beside the buttons:

206206

from line 225

225225

226226The integrated terminal lets you run commands alongside your session without switching to another app. Click **Terminal** in the session's title bar or press **Ctrl+\`** on macOS or Windows. The terminal opens in your session's working directory and shares the same environment as Claude, so commands like `npm test` or `git status` see the same files Claude is editing. To open a second terminal tab, click **+** in the terminal pane header or right-click a folder in the chat to choose **Open in terminal**.

227227

228If a WSL session has no terminal, see [If the terminal or connectors are unavailable](/docs/en/desktop-wsl.md#check-for-the-terminal-and-connectors). The terminal is available in local and [SSH](#ssh-sessions) sessions, with a limit on [Windows remote machines](#windows-remote-machines).

228If a WSL session has no terminal, see [If the terminal or connectors are unavailable](https://code.claude.com/docs/en/desktop-wsl.md#check-for-the-terminal-and-connectors). The terminal is available in local and [SSH](#ssh-sessions) sessions, with a limit on [Windows remote machines](#windows-remote-machines).

229229

230230### Open and edit files

231231

from line 297

297297| `Cmd` `Shift` `E` | Open effort menu |

298298| `1`–`9` | Select item in an open menu |

299299

300These shortcuts apply to the Code tab. In Desktop, `Shift+Tab` doesn't cycle permission modes as it does in the terminal's [interactive mode](/docs/en/interactive-mode.md#keyboard-shortcuts).

300These shortcuts apply to the Code tab. In Desktop, `Shift+Tab` doesn't cycle permission modes as it does in the terminal's [interactive mode](https://code.claude.com/docs/en/interactive-mode.md#keyboard-shortcuts).

301301

302302### Check usage

303303

from line 312

312312

313313## Let Claude use your computer

314314

315Computer use lets Claude open your apps, control your screen, and work directly on your machine the way you would. Ask Claude to interact with a desktop tool that has no CLI, or automate something that only works through a GUI. For running and testing iOS apps, Desktop opens the dedicated [iOS Simulator pane](/docs/en/desktop-ios-simulator.md) instead of controlling your screen; the pane works without enabling computer use.

315Computer use lets Claude open your apps, control your screen, and work directly on your machine the way you would. Ask Claude to interact with a desktop tool that has no CLI, or automate something that only works through a GUI. For running and testing iOS apps, Desktop opens the dedicated [iOS Simulator pane](https://code.claude.com/docs/en/desktop-ios-simulator.md) instead of controlling your screen; the pane works without enabling computer use.

316316

317317> [!NOTE]

318318>

from line 324

324324

325325> [!WARNING]

326326>

327> Unlike the [sandboxed Bash tool](/docs/en/sandboxing.md), computer use runs on your actual desktop with access to whatever you approve. Claude checks each action and flags potential prompt injection from on-screen content, but the trust boundary is different. See the [computer use safety guide](https://support.claude.com/en/articles/14128542) for best practices.

327> Unlike the [sandboxed Bash tool](https://code.claude.com/docs/en/sandboxing.md), computer use runs on your actual desktop with access to whatever you approve. Claude checks each action and flags potential prompt injection from on-screen content, but the trust boundary is different. See the [computer use safety guide](https://support.claude.com/en/articles/14128542) for best practices.

328328

329329### When computer use applies

330330

from line 332

332332

333333* If you have a [connector](#connect-external-tools) for a service, Claude uses the connector.

334334* If the task is a shell command, Claude uses Bash.

335* If the task is browser work and you have [Claude in Chrome](/docs/en/chrome.md) set up, Claude uses that.

336* If the task is running or testing an iOS app, Claude uses the [iOS Simulator pane](/docs/en/desktop-ios-simulator.md), which doesn't use screen control.

335* If the task is browser work and you have [Claude in Chrome](https://code.claude.com/docs/en/chrome.md) set up, Claude uses that.

336* If the task is running or testing an iOS app, Claude uses the [iOS Simulator pane](https://code.claude.com/docs/en/desktop-ios-simulator.md), which doesn't use screen control.

337337* If none of those apply, Claude uses computer use.

338338

339339The [per-app access tiers](#app-permissions) reinforce this: browsers are capped at view-only, and terminals and IDEs at click-only, steering Claude toward the dedicated tool even when computer use is active. Screen control is reserved for things nothing else can reach, like native apps, hardware control panels, or proprietary tools without an API.

from line 344

344344

345345**1. Update the desktop app**

346346

347Make sure you have the latest version of Claude Desktop. On macOS and Windows, download or update at [claude.com/download](https://claude.com/download); on Linux, update through your package manager ([instructions](/docs/en/desktop-linux.md)). Then restart the app.

348348

349349**2. Turn on the toggle**

350350

from line 397

397397

398398#### Run a session in its own worktree

399399

400In a project that's a Git repository, turn on **Worktree** before you start a session to run it in its own [Git worktree](/docs/en/worktrees.md), an isolated copy of the project. By default, **Worktree** is off and Claude works in the project folder itself. Click the project folder control in the [row under the prompt box](#start-a-session) and turn on **Worktree**.

400In a project that's a Git repository, turn on **Worktree** before you start a session to run it in its own [Git worktree](https://code.claude.com/docs/en/worktrees.md), an isolated copy of the project. By default, **Worktree** is off and Claude works in the project folder itself. Click the project folder control in the [row under the prompt box](#start-a-session) and turn on **Worktree**.

401401

402402* **With a [saved environment](#create-a-saved-environment)**: set **Worktree** when you create or edit the environment

403403* **[Earlier layout](#check-which-layout-you-have)**: select the **worktree** checkbox beside the branch name, above the prompt box

from line 409

409409

410410You can also set a **Branch prefix** in **Settings > Claude Code**. Desktop prepends it to every worktree branch name, which is useful for keeping Claude-created branches organized.

411411

412To include gitignored files like `.env` in new worktrees, create a [`.worktreeinclude` file](/docs/en/worktrees#copy-gitignored-files-into-worktrees) in your project root. See [What worktrees share with the main checkout](/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout) for where a worktree session reads project settings, hooks, and skills.

412To include gitignored files like `.env` in new worktrees, create a [`.worktreeinclude` file](https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees) in your project root. See [What worktrees share with the main checkout](https://code.claude.com/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout) for where a worktree session reads project settings, hooks, and skills.

413413

414414> [!NOTE]

415415>

from line 447

447447

448448### Check and free up context

449449

450To check context usage, see [Check usage](#check-usage). When context fills up, Claude automatically summarizes the conversation and continues working. You can also type `/compact` to trigger summarization earlier and free up context space. See [the context window](/docs/en/how-claude-code-works.md#the-context-window) for details on how compaction works.

450To check context usage, see [Check usage](#check-usage). When context fills up, Claude automatically summarizes the conversation and continues working. You can also type `/compact` to trigger summarization earlier and free up context space. See [the context window](https://code.claude.com/docs/en/how-claude-code-works.md#the-context-window) for details on how compaction works.

451451

452452### Get notified when a session finishes

453453

454The desktop app sends an OS notification when a Code session finishes a task and you aren't currently viewing that session. For sessions that belong to a [project](/docs/en/claude-projects.md#see-what-needs-you-in-overview), you get the project's notifications instead.

454The desktop app sends an OS notification when a Code session finishes a task and you aren't currently viewing that session. For sessions that belong to a [project](https://code.claude.com/docs/en/claude-projects.md#see-what-needs-you-in-overview), you get the project's notifications instead.

455455

456456### Ask a side question without derailing the session

457457

from line 463

463463

464464### Watch background tasks

465465

466The tasks pane shows the background work running inside the current session: subagents, background shell commands, and [dynamic workflows](/docs/en/workflows.md). Once the session has background work, open the pane with **Background tasks** in the title bar's **⋮** menu.

466The tasks pane shows the background work running inside the current session: subagents, background shell commands, and [dynamic workflows](https://code.claude.com/docs/en/workflows.md). Once the session has background work, open the pane with **Background tasks** in the title bar's **⋮** menu.

467467

468468Click any entry to see its output in the subagent pane or stop it. To see what other sessions are doing, use the [sidebar](#work-in-parallel-with-sessions), or ask Claude to [check on them for you](#work-across-sessions).

469469

from line 473

473473

474474You can also ask Claude to rename or archive a session. For example, ask it to archive the sessions whose PRs have merged.

475475

476Through this surface, Claude sees only the sessions the desktop app runs itself: local, [SSH](#ssh-sessions), and [WSL](/docs/en/desktop-wsl.md) sessions in the Code tab. Claude doesn't see cloud sessions, or sessions you started from the terminal CLI or the VS Code extension, even in worktrees of the same project, so with nine terminal worktrees open and two desktop sessions, Claude answering in one of them reports the one other desktop session. Claude never lists the session you're asking from. By default it sees the 20 most recently active sessions and skips archived sessions unless you ask for them. [Cross-session messaging](/docs/en/cross-session-messaging.md) separately lets Claude message [your other Claude Code sessions](/docs/en/cross-session-messaging.md#see-which-sessions-claude-can-reach), including terminal sessions.

476Through this surface, Claude sees only the sessions the desktop app runs itself: local, [SSH](#ssh-sessions), and [WSL](https://code.claude.com/docs/en/desktop-wsl.md) sessions in the Code tab. Claude doesn't see cloud sessions, or sessions you started from the terminal CLI or the VS Code extension, even in worktrees of the same project, so with nine terminal worktrees open and two desktop sessions, Claude answering in one of them reports the one other desktop session. Claude never lists the session you're asking from. By default it sees the 20 most recently active sessions and skips archived sessions unless you ask for them. [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md) separately lets Claude message [your other Claude Code sessions](https://code.claude.com/docs/en/cross-session-messaging.md#see-which-sessions-claude-can-reach), including terminal sessions.

477477

478478When Claude messages another session through this surface, Claude Code shows it there as a card labeled with the sending session's title and a link back, so you can always tell where a message came from. If the receiving session is mid-task, Claude Code holds the message and Claude reads it once the current work finishes. The receiving Claude can reply, and Claude Code delivers the reply back through this surface. Claude can't deliver to an archived session, and tells you when a message doesn't go through.

479479

480480Claude Code applies three safety behaviors across sessions:

481481

482482* You get an approval card before Claude archives a session, except in Auto mode and Bypass permissions mode, where Claude can archive a session without one. To be asked, switch to Manual.

483* Claude Code checks each message from this surface against the receiving session's [inbound controls](/docs/en/cross-session-messaging.md#control-inbound-messages), even when the receiving session doesn't have [cross-session messaging](/docs/en/cross-session-messaging.md#availability) itself. If you set [`crossSessionInbound`](/docs/en/settings-reference#crosssessioninbound) to `refuse` in the receiving session, Claude Code drops messages from this surface. Claude Code reports the refusal to the Claude desktop app. Before v2.1.234, Claude Code dropped every message from this surface to a receiving session without cross-session messaging.

483* Claude Code checks each message from this surface against the receiving session's [inbound controls](https://code.claude.com/docs/en/cross-session-messaging.md#control-inbound-messages), even when the receiving session doesn't have [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md#availability) itself. If you set [`crossSessionInbound`](https://code.claude.com/docs/en/settings-reference#crosssessioninbound) to `refuse` in the receiving session, Claude Code drops messages from this surface. Claude Code reports the refusal to the Claude desktop app. Before v2.1.234, Claude Code dropped every message from this surface to a receiving session without cross-session messaging.

484484* Claude Code quotes each incoming message and attributes it to the session that sent it, and Claude still follows the receiving session's own permission settings when acting on one.

485485

486486### Start a task that Claude suggests

from line 496

496496

497497### Run long-running tasks in the cloud

498498

499For large refactors, test suites, migrations, or other long-running tasks, select an environment under **Cloud** in the [environment selector](#start-a-session) when starting a session. Cloud sessions run on Anthropic-managed infrastructure by default and continue even if you close the app or shut down your computer. Check back anytime to see progress or steer Claude in a different direction. You can also monitor cloud sessions from [claude.ai/code](https://claude.ai/code) or the [Claude mobile app](/docs/en/mobile.md).

500500

501501Cloud sessions also support multiple repositories. Choose the repositories:

502502

503503* **Current layout**: in the row under the prompt box, once you select a cloud environment.

504504* **[Earlier layout](#check-which-layout-you-have)**: above the prompt box. To add another repository, click **+** beside the selected one.

505505

506See [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web.md) for more on how cloud sessions work. When one body of work needs many cloud sessions, use a [project](/docs/en/claude-projects.md): Claude starts and tracks the sessions for you from one conversation. [Create a project](/docs/en/claude-projects.md#create-a-project) has the steps.

506See [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md) for more on how cloud sessions work. When one body of work needs many cloud sessions, use a [project](https://code.claude.com/docs/en/claude-projects.md): Claude starts and tracks the sessions for you from one conversation. [Create a project](https://code.claude.com/docs/en/claude-projects.md#create-a-project) has the steps.

507507

508508> [!NOTE]

509509>

from line 513

513513

514514To continue a session somewhere else, open the session menu from the caret beside the session title or from the session's row in the sidebar, then select **Open in**:

515515

516* Select **Cloud** to continue the session as a [cloud session](/docs/en/claude-code-on-the-web.md), with your conversation carried over as a summary. Before you confirm, the dialog states whether your files move too and whether this session is archived once the cloud one is ready. You can't move a session that runs over [SSH](#ssh-sessions) or in [WSL](/docs/en/desktop-wsl.md) this way.

516* Select **Cloud** to continue the session as a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md), with your conversation carried over as a summary. Before you confirm, the dialog states whether your files move too and whether this session is archived once the cloud one is ready. You can't move a session that runs over [SSH](#ssh-sessions) or in [WSL](https://code.claude.com/docs/en/desktop-wsl.md) this way.

517517* Select an installed editor or your file manager to open the session's folder on disk there.

518518

519519### Control which sessions appear on your other devices

520520

521A local session shows up on your other devices once [Remote Control](/docs/en/remote-control.md) connects it. A connected session appears in the session list at [claude.ai/code](https://claude.ai/code) and in the Claude apps on devices signed in to your claude.ai account.

521A local session shows up on your other devices once [Remote Control](https://code.claude.com/docs/en/remote-control.md) connects it. A connected session appears in the session list at [claude.ai/code](https://claude.ai/code) and in the Claude apps on devices signed in to your claude.ai account.

522522

523523A local session connects when you turn Remote Control on for it, or when it connects automatically as it starts:

524524

525525* **You turn it on for that session**: with the session's **Remote Control** switch, or by typing `/remote-control` in its prompt box.

526* **It connects when it starts**: new sessions connect automatically while **Connect new sessions to Remote Control** is on in **Settings > Claude Code**. If you've never changed that setting, Desktop follows [`remoteControlAtStartup`](/docs/en/settings-reference#remotecontrolatstartup) in your user or managed settings, then your organization's default.

526* **It connects when it starts**: new sessions connect automatically while **Connect new sessions to Remote Control** is on in **Settings > Claude Code**. If you've never changed that setting, Desktop follows [`remoteControlAtStartup`](https://code.claude.com/docs/en/settings-reference#remotecontrolatstartup) in your user or managed settings, then your organization's default.

527527

528528To see whether a session is connected, check the **Remote Control** switch in the **Environment** card of its [session details panel](#see-session-details).

529529

from line 531

531531

532532* **One session**: turn off its **Remote Control** switch. In a session that connected when it started, typing `/remote-control` leaves Remote Control on and shows `Remote Control is already on. This session connected automatically when it started.` Click **Turn off** on that line to disconnect.

533533* **New Desktop sessions on this computer**: turn off **Connect new sessions to Remote Control** in **Settings > Claude Code**. If it already shows off, turn it on and then off so Desktop saves your choice. Once saved, it takes precedence over `remoteControlAtStartup` and the defaults.

534* **Any session on this computer, including the CLI**: set [`disableRemoteControl`](/docs/en/settings-reference#disableremotecontrol) to `true` in `~/.claude/settings.json` to stop sessions from connecting. A session that was already connected when you saved the file stays connected until you turn Remote Control off for it.

535

536To hide a session that already appears on your other devices, archive it in Desktop. Desktop archives the session's Remote Control copy too, so it leaves the default session list on those devices. To view or delete it there, see [Archive sessions](/docs/en/claude-code-on-the-web.md#archive-sessions).

534* **Any session on this computer, including the CLI**: set [`disableRemoteControl`](https://code.claude.com/docs/en/settings-reference#disableremotecontrol) to `true` in `~/.claude/settings.json` to stop sessions from connecting. A session that was already connected when you saved the file stays connected until you turn Remote Control off for it.

535

536To hide a session that already appears on your other devices, archive it in Desktop. Desktop archives the session's Remote Control copy too, so it leaves the default session list on those devices. To view or delete it there, see [Archive sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md#archive-sessions).

537537

538538### Sessions from Dispatch

539539

from line 551

551551

552552For setup, pairing, and Dispatch settings, see the [Dispatch help article](https://support.claude.com/en/articles/13947068). Dispatch requires a Pro or Max plan and is not available on Team or Enterprise plans.

553553

554Dispatch is one of several ways to work with Claude when you're away from your terminal. For a comparison with the other options, see [Platforms and integrations](/docs/en/platforms.md#work-when-you-are-away-from-your-terminal).

554Dispatch is one of several ways to work with Claude when you're away from your terminal. For a comparison with the other options, see [Platforms and integrations](https://code.claude.com/docs/en/platforms.md#work-when-you-are-away-from-your-terminal).

555555

556556## Extend Claude Code

557557

558558Connect external services, add reusable workflows, customize Claude's behavior, and configure preview servers. To manage connectors, skills, and plugins in one place, click **Customize** in the sidebar. [Cowork](https://claude.com/product/cowork) in the Desktop app sources its skills, plugins, and connectors from this Customize configuration, which syncs through your claude.ai account, not from the CLI's `~/.claude` directory.

559559

560Claude Code also loads the skills and plugins enabled for your claude.ai account in terminal sessions where you sign in with the same account. See [Skills synced from claude.ai](/docs/en/skills.md#how-synced-skills-behave) and [Plugins synced from claude.ai](/docs/en/plugins/loading.md#synced-plugins).

560Claude Code also loads the skills and plugins enabled for your claude.ai account in terminal sessions where you sign in with the same account. See [Skills synced from claude.ai](https://code.claude.com/docs/en/skills.md#how-synced-skills-behave) and [Plugins synced from claude.ai](https://code.claude.com/docs/en/plugins/loading.md#synced-plugins).

561561

562562### Connect external tools

563563

564Connectors are [MCP servers](/docs/en/mcp.md) with a graphical setup flow.

564Connectors are [MCP servers](https://code.claude.com/docs/en/mcp.md) with a graphical setup flow.

565565

566566Click **+** next to the prompt box, before or during the session, to add connectors in a local or [SSH](#ssh-sessions) session with a Claude account. Select **Add connectors** to open the connector directory. If the menu shows **Connectors** instead, select it, then **Browse connectors**.

567567

from line 569

569569>

570570> These cases are covered on other pages:

571571>

572> * **Connectors is grayed out in a WSL session**: see [If the terminal or connectors are unavailable](/docs/en/desktop-wsl.md#check-for-the-terminal-and-connectors)

573> * **Cloud sessions**: see [How connectors reach Claude Code](/docs/en/mcp.md#how-connectors-reach-claude-code)

572> * **Connectors is grayed out in a WSL session**: see [If the terminal or connectors are unavailable](https://code.claude.com/docs/en/desktop-wsl.md#check-for-the-terminal-and-connectors)

573> * **Cloud sessions**: see [How connectors reach Claude Code](https://code.claude.com/docs/en/mcp.md#how-connectors-reach-claude-code)

574574

575575Once connected, Claude can read your calendar, send messages, create issues, and interact with your tools directly. You can ask Claude what connectors are configured in your session. To manage or disconnect connectors, go to **Settings > Connectors** in the desktop app.

576576

577For integrations not listed in Connectors, add MCP servers manually via [settings files](/docs/en/mcp.md#installing-mcp-servers). You can also [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

577For integrations not listed in Connectors, add MCP servers manually via [settings files](https://code.claude.com/docs/en/mcp.md#installing-mcp-servers). You can also [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

578578

579579### Use skills

580580

581[Skills](/docs/en/skills.md) extend what Claude can do. Claude loads them automatically when relevant, or you can invoke one directly: type `/` in the prompt box or click the **+** button and select **Slash commands** to browse what's available. This includes [built-in commands](/docs/en/commands.md), your [custom skills](/docs/en/skills.md#create-your-first-skill), project skills from your codebase, and skills from any [installed plugins](/docs/en/plugins/install.md). Select one and it appears highlighted in the input field. Type your task after it and send as usual.

581[Skills](https://code.claude.com/docs/en/skills.md) extend what Claude can do. Claude loads them automatically when relevant, or you can invoke one directly: type `/` in the prompt box or click the **+** button and select **Slash commands** to browse what's available. This includes [built-in commands](https://code.claude.com/docs/en/commands.md), your [custom skills](https://code.claude.com/docs/en/skills.md#create-your-first-skill), project skills from your codebase, and skills from any [installed plugins](https://code.claude.com/docs/en/plugins/install.md). Select one and it appears highlighted in the input field. Type your task after it and send as usual.

582582

583583You can send a command while Claude is working, the same as any other message, and the session returns to idle once the turn finishes.

584584

585585Local sessions load your personal skills from `~/.claude/skills/`. An [SSH](#ssh-sessions) session reads `~/.claude/skills/` from the remote host's home directory, not from your machine.

586586

587Local and cloud sessions also load the skills enabled for your claude.ai account, except local sessions when your organization sets [`disableSideloadFlags`](/docs/en/settings-reference#disablesideloadflags). Cloud sessions load them instead of `~/.claude/skills/`, as [Skills in Cowork and cloud sessions](/docs/en/skills.md#skills-in-cowork-and-cloud-sessions) describes.

587Local and cloud sessions also load the skills enabled for your claude.ai account, except local sessions when your organization sets [`disableSideloadFlags`](https://code.claude.com/docs/en/settings-reference#disablesideloadflags). Cloud sessions load them instead of `~/.claude/skills/`, as [Skills in Cowork and cloud sessions](https://code.claude.com/docs/en/skills.md#skills-in-cowork-and-cloud-sessions) describes.

588588

589589### Install plugins

590590

591[Plugins](/docs/en/plugins/overview.md) are reusable packages that add skills, agents, hooks, MCP servers, and LSP configurations to Claude Code. You can install plugins from the desktop app without using the terminal.

591[Plugins](https://code.claude.com/docs/en/plugins/overview.md) are reusable packages that add skills, agents, hooks, MCP servers, and LSP configurations to Claude Code. You can install plugins from the desktop app without using the terminal.

592592

593593In a local session or an [SSH session](#ssh-sessions), click **+** next to the prompt box and select **Add plugins** to open the plugin browser. If the menu shows **Plugins** instead, select it, then **Browse plugins**, or **Manage plugins** to enable, disable, or uninstall plugins.

594594

595You can scope plugins to your user account, a specific project, or local-only. If your organization manages plugins centrally, those plugins are available in desktop sessions the same way they are in the CLI, except the ones the desktop app [withholds under `disableSideloadFlags`](/docs/en/settings-reference#disablesideloadflags).

596

597The plugin browser is not available in cloud sessions, and plugins you install from the desktop app aren't available for cloud sessions. A cloud session also doesn't install plugins that the repository's `.claude/settings.json` declares, as [What carries over from your setup](/docs/en/cloud-environments.md#what-carries-over-from-your-setup) explains. Plugins aren't available in WSL sessions. For the full plugin reference including creating your own plugins, see [plugins](/docs/en/plugins/overview.md).

596

597The plugin browser is not available in cloud sessions, and plugins you install from the desktop app aren't available for cloud sessions. A cloud session also doesn't install plugins that the repository's `.claude/settings.json` declares, as [What carries over from your setup](https://code.claude.com/docs/en/cloud-environments.md#what-carries-over-from-your-setup) explains. Plugins aren't available in WSL sessions. For the full plugin reference including creating your own plugins, see [plugins](https://code.claude.com/docs/en/plugins/overview.md).

598598

599599### Configure preview servers

600600

from line 797

797797* **Local**: runs on your machine with direct access to your files

798798* **Cloud**: runs on Anthropic-managed infrastructure by default. Sessions continue even if you close the app.

799799* **SSH**: runs on a remote machine you connect to over SSH, such as your own servers, cloud VMs, or dev containers. A running task can [keep going while Desktop is disconnected](#keep-a-task-running-while-desktop-is-disconnected), but with a Claude account it can stop when its sign-in expires.

800* **WSL** (Windows): runs inside a [WSL 2 distribution](/docs/en/desktop-wsl.md) on your machine, using its Linux toolchain and native paths

800* **WSL** (Windows): runs inside a [WSL 2 distribution](https://code.claude.com/docs/en/desktop-wsl.md) on your machine, using its Linux toolchain and native paths

801801

802802### Create a saved environment

803803

from line 825

825825

826826* **Start a session**: select the entry.

827827* **Edit or delete**: hover over the entry and click the gear icon. To delete a local or SSH environment, click **Delete environment** in **Edit environment**.

828* **Archive cloud environments**: see [Archive an environment](/docs/en/cloud-environments.md#archive-an-environment).

828* **Archive cloud environments**: see [Archive an environment](https://code.claude.com/docs/en/cloud-environments.md#archive-an-environment).

829829

830830### Local sessions

831831

from line 853

853853

854854Only sessions you start from that environment get the variables.

855855

856To set a variable for every local session, add it to the [`env` key](/docs/en/env-vars#set-variables-in-settings-files) in your `~/.claude/settings.json` file. Claude Code [ignores the value](/docs/en/settings-reference.md#how-env-values-interact-with-your-shell) if that variable is already in the environment Desktop starts the session with. See [environment variables](/docs/en/env-vars.md) for the full list of supported variables.

856To set a variable for every local session, add it to the [`env` key](https://code.claude.com/docs/en/env-vars#set-variables-in-settings-files) in your `~/.claude/settings.json` file. Claude Code [ignores the value](https://code.claude.com/docs/en/settings-reference.md#how-env-values-interact-with-your-shell) if that variable is already in the environment Desktop starts the session with. See [environment variables](https://code.claude.com/docs/en/env-vars.md) for the full list of supported variables.

857857

858858#### Set environment variables for dev servers

859859

from line 876

876876

877877#### Environment variables Desktop sets itself

878878

879If you set `API_TIMEOUT_MS` or `ANTHROPIC_BASE_URL` and nothing changed in your local sessions, it's because Desktop sets those [variables](/docs/en/env-vars.md#variables), among others, itself. A local session gets Desktop's value whether you set yours in your shell profile, your Windows user or system variables, the local environment editor, or a saved environment. Moving yours to a settings file doesn't help, because Claude Code [ignores that value](/docs/en/settings-reference.md#how-env-values-interact-with-your-shell) in a local session.

880

881* `API_TIMEOUT_MS`: a local session gets `900000`, which is 15 minutes. For a longer timeout, [install the Claude Code CLI](/docs/en/quickstart.md) and use it instead of Desktop. [Set the variable in your shell](/docs/en/env-vars.md#set-variables-in-your-shell) and run `claude` in your terminal.

882* `ANTHROPIC_BASE_URL`: a local session gets Anthropic's API host when you're signed in with a Claude account. To use a gateway, set up Desktop's [third-party inference configuration](/docs/en/llm-gateway-connect.md#desktop-app) instead.

879If you set `API_TIMEOUT_MS` or `ANTHROPIC_BASE_URL` and nothing changed in your local sessions, it's because Desktop sets those [variables](https://code.claude.com/docs/en/env-vars.md#variables), among others, itself. A local session gets Desktop's value whether you set yours in your shell profile, your Windows user or system variables, the local environment editor, or a saved environment. Moving yours to a settings file doesn't help, because Claude Code [ignores that value](https://code.claude.com/docs/en/settings-reference.md#how-env-values-interact-with-your-shell) in a local session.

880

881* `API_TIMEOUT_MS`: a local session gets `900000`, which is 15 minutes. For a longer timeout, [install the Claude Code CLI](https://code.claude.com/docs/en/quickstart.md) and use it instead of Desktop. [Set the variable in your shell](https://code.claude.com/docs/en/env-vars.md#set-variables-in-your-shell) and run `claude` in your terminal.

882* `ANTHROPIC_BASE_URL`: a local session gets Anthropic's API host when you're signed in with a Claude account. To use a gateway, set up Desktop's [third-party inference configuration](https://code.claude.com/docs/en/llm-gateway-connect.md#desktop-app) instead.

883883

884884#### Turn off extended thinking

885885

886[Extended thinking](/docs/en/model-config.md#extended-thinking) is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. To turn it off, set `MAX_THINKING_TOKENS` to `0` in a [saved local environment](#set-environment-variables-for-local-sessions) or the [local environment editor](#use-the-local-environment-editor). Thinking then turns off on the Anthropic API, except on Opus 5.5, Sonnet 5.5, Haiku 5.5, and the Fable models, which always use extended thinking.

886[Extended thinking](https://code.claude.com/docs/en/model-config.md#extended-thinking) is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. To turn it off, set `MAX_THINKING_TOKENS` to `0` in a [saved local environment](#set-environment-variables-for-local-sessions) or the [local environment editor](#use-the-local-environment-editor). Thinking then turns off on the Anthropic API, except on Opus 5.5, Sonnet 5.5, Haiku 5.5, and the Fable models, which always use extended thinking.

887887

888888On Opus 5, also select effort `high` or lower before you start the session. In the [current layout](#check-which-layout-you-have), open the model picker and select a level under **Effort**. If you started the session at a higher level, start a new one at `high` or lower.

889889

890890#### Fixed thinking budgets

891891

892On models with [adaptive reasoning](/docs/en/model-config.md#adjust-effort-level), Claude Code ignores the number itself in a positive `MAX_THINKING_TOKENS` value because adaptive reasoning controls thinking depth instead. On Opus 4.6 and Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` to `1` to use a fixed thinking budget; Fable models, Sonnet 5 and later, Haiku 5.5, and Opus 4.7 and later always use adaptive reasoning and have no fixed-budget mode.

892On models with [adaptive reasoning](https://code.claude.com/docs/en/model-config.md#adjust-effort-level), Claude Code ignores the number itself in a positive `MAX_THINKING_TOKENS` value because adaptive reasoning controls thinking depth instead. On Opus 4.6 and Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` to `1` to use a fixed thinking budget; Fable models, Sonnet 5 and later, Haiku 5.5, and Opus 4.7 and later always use adaptive reasoning and have no fixed-budget mode.

893893

894894#### Local sessions on managed devices

895895

896If the entry for your computer is grayed out in the environment selector, with the tooltip **Disabled by your organization**, your administrator has [turned off local sessions](#managed-settings). On Windows the [WSL](/docs/en/desktop-wsl.md) entry, whose availability on managed devices is [governed separately](/docs/en/admin-setup.md#wsl-sessions-in-claude-code-desktop), is grayed out the same way.

896If the entry for your computer is grayed out in the environment selector, with the tooltip **Disabled by your organization**, your administrator has [turned off local sessions](#managed-settings). On Windows the [WSL](https://code.claude.com/docs/en/desktop-wsl.md) entry, whose availability on managed devices is [governed separately](https://code.claude.com/docs/en/admin-setup.md#wsl-sessions-in-claude-code-desktop), is grayed out the same way.

897897

898898New sessions default to the first SSH connection if one is configured. If you try to continue an existing local session, Desktop shows a message that local sessions aren't available on this device. [Saved local environments](#create-a-saved-environment) show this error when you select one: `Couldn’t switch environments: the Local environment isn’t available anymore.` Choose an [SSH](#ssh-sessions) or [cloud](#cloud-sessions) environment instead, or contact your IT team.

899899

900900### Cloud sessions

901901

902Cloud sessions continue in the background even if you close the app. Usage counts toward your [subscription plan limits](/docs/en/costs.md) with no separate compute charges.

903

904To add, edit, or [archive](/docs/en/cloud-environments.md#archive-an-environment) a cloud environment, open the [environment selector](#start-a-session):

902Cloud sessions continue in the background even if you close the app. Usage counts toward your [subscription plan limits](https://code.claude.com/docs/en/costs.md) with no separate compute charges.

903

904To add, edit, or [archive](https://code.claude.com/docs/en/cloud-environments.md#archive-an-environment) a cloud environment, open the [environment selector](#start-a-session):

905905

906906* **Add an environment**: select **New environment** at the bottom of the selector's menu, then the **Cloud** tab of the [**New environment** dialog](#create-a-saved-environment)

907907* **Edit or archive one of your own environments**: hover over it and click the gear icon

908908

909See [Configure cloud environments](/docs/en/cloud-environments.md) for details on configuring network access and environment variables.

909See [Configure cloud environments](https://code.claude.com/docs/en/cloud-environments.md) for details on configuring network access and environment variables.

910910

911911### SSH sessions

912912

from line 914

914914

915915> [!NOTE]

916916>

917> If you use Desktop with a [third-party provider](/docs/en/third-party-integrations.md), SSH sessions need their own setup. See [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).

917> If you use Desktop with a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md), SSH sessions need their own setup. See [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).

918918

919919Add an SSH connection in the [**New environment** dialog](#create-a-saved-environment), then start a session on that connection. If a new session has no environment selector under the prompt box, you have the earlier layout. See [Check which layout you have](#check-which-layout-you-have).

920920

from line 944

944944

945945A Linux or macOS remote machine needs a supported processor, an SSH server with SFTP, an install folder that isn't mounted `noexec`, a working shell, and network access. Check each requirement before you connect, or when a connection fails after you log in:

946946

947* **System**: an x86\_64 or arm64 processor. The machine also has to meet Claude Code's [system requirements](/docs/en/setup.md#system-requirements). On Linux, Claude Code needs glibc 2.17 or later, or musl. To see which one the machine has, run `ldd --version` there. On a musl-based distribution such as Alpine Linux, also install the [packages that Claude Code needs](/docs/en/setup.md#alpine-linux-and-musl-based-distributions).

947* **System**: an x86\_64 or arm64 processor. The machine also has to meet Claude Code's [system requirements](https://code.claude.com/docs/en/setup.md#system-requirements). On Linux, Claude Code needs glibc 2.17 or later, or musl. To see which one the machine has, run `ldd --version` there. On a musl-based distribution such as Alpine Linux, also install the [packages that Claude Code needs](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions).

948948* **SFTP**: the SSH server has to offer the SFTP subsystem, which a `Subsystem sftp` line in its `sshd_config` turns on. To check, connect to the same host and port with `sftp` in a terminal on your computer. A working server shows the `sftp>` prompt.

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

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

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

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

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

953953

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

955955

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

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

957957

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

959959

960960**1. Add the variables**

961961

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

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

963963

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

965965{

from line 976

976976

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

978978

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

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

980980

981981**1. List the variables that the remote machine sets**

982982

from line 1164

11641164Expect these limits, among others, on a Windows remote machine:

11651165

11661166* **Terminal**: the [terminal](#run-commands-in-the-terminal) doesn't open in a session whose folder is a Windows path, such as `C:/projects/app`

1167* **Sandbox**: Claude Code runs there on native Windows, where it runs commands unsandboxed. See [where the sandbox runs](/docs/en/sandboxing.md).

1167* **Sandbox**: Claude Code runs there on native Windows, where it runs commands unsandboxed. See [where the sandbox runs](https://code.claude.com/docs/en/sandboxing.md).

11681168* **Plugins**: Desktop doesn't copy a plugin that holds a file or folder name Windows can't store, such as a name with `:`. The session lists the plugins that Desktop left out.

11691169* **MCP servers**: on some Windows remote machines, Claude's calls to MCP servers from `claude_desktop_config.json` go through Desktop, so Claude can't call their tools [while Desktop is disconnected](#limits-while-desktop-is-disconnected). Before Claude Desktop v2.37337.0, this holds on every Windows remote machine.

11701170* **Worktrees**: worktrees go in `<project-root>/.claude/worktrees/`. If you [choose another folder](#choose-where-ssh-session-worktrees-go), Desktop ignores it.

from line 1187

11871187>

11881188> If the task must run through the night:

11891189>

1190> * [Keep your computer awake](/docs/en/desktop-scheduled-tasks.md#how-scheduled-tasks-run) and online, with the lid open and Desktop running

1190> * [Keep your computer awake](https://code.claude.com/docs/en/desktop-scheduled-tasks.md#how-scheduled-tasks-run) and online, with the lid open and Desktop running

11911191> * Use a login that works without a prompt, such as a key that your SSH agent holds, for the remote machine and for any jump host on the way. Desktop can then reconnect on its own after a drop.

11921192>

11931193> For a task that must run while your computer is asleep or off, start a [cloud session](#run-long-running-tasks-in-the-cloud) instead.

from line 1226

12261226* **Worktrees**: in a session that uses a [worktree](#run-a-session-in-its-own-worktree), Desktop checks each file edit before Claude makes it. While Desktop is disconnected, each edit waits about 30 seconds and then fails. Shell commands still run. On a Linux or macOS remote machine, [edits can keep working](#worktree-edits-while-disconnected). If you aren't sure, start the session without a worktree.

12271227* **Folder restrictions**: if your organization restricts which folders sessions may use, Desktop checks each file read, search, and edit, with or without a worktree. While Desktop is disconnected, each one waits up to 10 minutes and then fails.

12281228* **Connectors**: [connectors](#connect-external-tools) and other tools that Desktop provides run through Desktop, so while it is disconnected each call fails after about 30 seconds

1229* **Workflows**: Desktop checks each new [workflow](/docs/en/workflows.md) before it starts, so while Desktop is disconnected a new one waits up to 10 minutes and then fails

1229* **Workflows**: Desktop checks each new [workflow](https://code.claude.com/docs/en/workflows.md) before it starts, so while Desktop is disconnected a new one waits up to 10 minutes and then fails

12301230* **MCP servers**: MCP servers that Claude Code starts on the remote machine don't run through Desktop, so Claude can still call their tools. Servers from `claude_desktop_config.json` are among them only if Desktop doesn't use its [built-in SSH client](#worktree-edits-while-disconnected). Otherwise, and on [some Windows remote machines](#windows-remote-machines), Claude can't call their tools while Desktop is disconnected.

12311231

12321232> **When edits in a worktree keep working**

from line 1239

12391239> * **Repository location**: the repository is your home directory, a folder above it, or `~/.claude`

12401240> * **macOS paths**: on a macOS remote machine, the repository is under `/Volumes`, or a folder name in the path of the repository or the worktree has a `~` or a non-ASCII character

12411241> * **Folder restrictions**: your organization restricts which folders sessions may use

1242> * **Corporate launcher**: before Claude Desktop v2.37337.0, you sign in with a Claude account, and your organization starts Claude Code on the remote machine through a [corporate launcher](/docs/en/corporate-launcher.md)

12431243>

12441244> A session without a worktree has no such check, unless your organization restricts which folders sessions may use.

12451245

from line 1253

12531253

12541254To reduce how often a task stops to wait for you, and to hear from it while you are away, set up any of these before you leave:

12551255

1256* **Auto mode**: choose [Auto mode](#choose-a-permission-mode) if [it is available to you](#auto-mode-availability). After repeated blocks, you are [asked again](/docs/en/permission-modes.md#when-auto-mode-falls-back).

1257* **Allow rules**: in your user settings file on the remote machine, `~/.claude/settings.json`, add [allow rules](/docs/en/permissions.md#manage-permissions) for the commands the task needs. If your organization [accepts permission rules from managed settings only](/docs/en/settings-reference.md#allowmanagedpermissionrulesonly), ask your administrator to add them to the [managed settings](#managed-settings) that reach the remote machine. For allow rules in a project's `.claude/settings.json`, see [Project allow rules and workspace trust](/docs/en/permissions.md#project-allow-rules-and-workspace-trust).

1258* **A hook that answers**: configure a [`PermissionRequest` hook](/docs/en/hooks#permissionrequest) in `~/.claude/settings.json` on the remote machine to allow or deny requests in your place

1259* **A hook that alerts you**: configure a [`Notification` hook](/docs/en/hooks#notification) with the `permission_prompt` matcher in the same file to send yourself a message when a request is waiting

1260* **A hook that tells you when Claude is done**: configure a [`Stop` hook](/docs/en/hooks#stop) in the same file to send yourself a message when Claude has finished responding. It doesn't run when an API error ends the turn. For that case, configure a [`StopFailure` hook](/docs/en/hooks#stopfailure).

1261

1262If your organization [runs managed hooks only](/docs/en/settings-reference.md#allowmanagedhooksonly), ask your administrator to add the hook to the [managed settings](#managed-settings) that reach the remote machine.

1263

1264Claude Code doesn't auto-approve [a few actions](/docs/en/permission-modes.md#actions-no-mode-auto-approves) in any permission mode, including Bypass permissions. Depending on the permission mode, Claude Code denies such an action or asks you, and the task then waits for your answer.

1256* **Auto mode**: choose [Auto mode](#choose-a-permission-mode) if [it is available to you](#auto-mode-availability). After repeated blocks, you are [asked again](https://code.claude.com/docs/en/permission-modes.md#when-auto-mode-falls-back).

1257* **Allow rules**: in your user settings file on the remote machine, `~/.claude/settings.json`, add [allow rules](https://code.claude.com/docs/en/permissions.md#manage-permissions) for the commands the task needs. If your organization [accepts permission rules from managed settings only](https://code.claude.com/docs/en/settings-reference.md#allowmanagedpermissionrulesonly), ask your administrator to add them to the [managed settings](#managed-settings) that reach the remote machine. For allow rules in a project's `.claude/settings.json`, see [Project allow rules and workspace trust](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust).

1258* **A hook that answers**: configure a [`PermissionRequest` hook](https://code.claude.com/docs/en/hooks#permissionrequest) in `~/.claude/settings.json` on the remote machine to allow or deny requests in your place

1259* **A hook that alerts you**: configure a [`Notification` hook](https://code.claude.com/docs/en/hooks#notification) with the `permission_prompt` matcher in the same file to send yourself a message when a request is waiting

1260* **A hook that tells you when Claude is done**: configure a [`Stop` hook](https://code.claude.com/docs/en/hooks#stop) in the same file to send yourself a message when Claude has finished responding. It doesn't run when an API error ends the turn. For that case, configure a [`StopFailure` hook](https://code.claude.com/docs/en/hooks#stopfailure).

1261

1262If your organization [runs managed hooks only](https://code.claude.com/docs/en/settings-reference.md#allowmanagedhooksonly), ask your administrator to add the hook to the [managed settings](#managed-settings) that reach the remote machine.

1263

1264Claude Code doesn't auto-approve [a few actions](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves) in any permission mode, including Bypass permissions. Depending on the permission mode, Claude Code denies such an action or asks you, and the task then waits for your answer.

12651265

12661266##### Reconnect after sleep or a network loss

12671267

from line 1292

12921292

12931293> [!WARNING]

12941294>

1295> While a conversation's Claude Code process is still running, don't run [`claude --resume`](/docs/en/cli-reference#cli-flags) for it on the remote machine. Claude Code doesn't stop you, and both processes then write to the same conversation. If you aren't sure, add `--fork-session`, which continues in a copy of the conversation, but both processes still work on the same files.

1295> While a conversation's Claude Code process is still running, don't run [`claude --resume`](https://code.claude.com/docs/en/cli-reference#cli-flags) for it on the remote machine. Claude Code doesn't stop you, and both processes then write to the same conversation. If you aren't sure, add `--fork-session`, which continues in a copy of the conversation, but both processes still work on the same files.

12961296

12971297#### Choose where SSH session worktrees go

12981298

12991299Unless your organization restricts which folders sessions may use, new SSH sessions create their [worktrees](#run-a-session-in-its-own-worktree) in the first of these locations that is set:

13001300

130113011. **Worktree folder** on the SSH connection

13022. [`worktree.location`](/docs/en/settings-reference#worktree-location) in `~/.claude/settings.json` on the remote machine

13022. [`worktree.location`](https://code.claude.com/docs/en/settings-reference#worktree-location) in `~/.claude/settings.json` on the remote machine

130313033. `<project-root>/.claude/worktrees/`, the default

13041304

13051305Each project gets its own subfolder in the folder you set, so with `~/worktrees` a worktree's path is `~/worktrees/<project>-<id>/<worktree-name>`. If the folder you set is inside the project, Desktop ignores it for that project and uses the default. On a [Windows remote machine](#windows-remote-machines), Desktop always uses the default.

from line 1330

13301330| `~/.claude/remote/ccd-cli/` | Claude Code, in one file per version |

13311331| `~/.claude/remote/run/` | The helper's runtime files, such as its socket and log, in one folder per computer that connects |

13321332| `~/.claude/remote/plugins/` | Plugins that Desktop copies from the user's computer |

1333| [`~/.claude/uploads/`](/docs/en/claude-directory#clear-local-data) | Files that the user attaches to messages, in one folder per session |

1333| [`~/.claude/uploads/`](https://code.claude.com/docs/en/claude-directory#clear-local-data) | Files that the user attaches to messages, in one folder per session |

13341334

13351335To list one user's processes, run `pgrep -fl "$HOME/.claude/remote/"` on the remote machine as that user, or with the user's home directory in place of `$HOME`:

13361336

from line 1355

13551355

13561356**3. Delete the folder**

13571357

1358Delete `~/.claude/remote/`. To remove Claude Code's own files in `~/.claude/` and `~/.claude.json`, see [Remove configuration files](/docs/en/setup.md#remove-configuration-files).

1358Delete `~/.claude/remote/`. To remove Claude Code's own files in `~/.claude/` and `~/.claude.json`, see [Remove configuration files](https://code.claude.com/docs/en/setup.md#remove-configuration-files).

13591359

13601360##### End one session's process

13611361

from line 1373

13731373

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

13751375

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

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

13771377

13781378#### Connections that close before login

13791379

from line 1435

14351435

14361436#### Use MCP servers set up on the remote machine

14371437

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

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

14391439

14401440#### Open an SSH session from a link

14411441

1442A `claude://code/new` link opens Desktop's new-session page, and it can name an SSH connection. Put such a link in a runbook, dashboard, or wiki page to open Desktop set up for the right machine and folder. For platforms that strip such links, see [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).

1442A `claude://code/new` link opens Desktop's new-session page, and it can name an SSH connection. Put such a link in a runbook, dashboard, or wiki page to open Desktop set up for the right machine and folder. For platforms that strip such links, see [The link renders as plain text instead of being clickable](https://code.claude.com/docs/en/deep-links.md#the-link-renders-as-plain-text-instead-of-being-clickable).

14431443

14441444SSH links require Claude Desktop v2.110.0 or later.

14451445

from line 1484

14841484* **Desktop is older than v2.110.0**: earlier versions ignore the SSH parameters and open the new-session page with only the prompt.

14851485* **SSH sessions are turned off**: if your administrator sets the allowlist to an empty array, Desktop refuses SSH links.

14861486

1487#### Create an SSH connection from a command

1488

1489If a command-line tool makes your remote machines on demand, add its command to `sshHostCommands` in [`~/.claude/settings.json`](https://code.claude.com/docs/en/settings#settings-files). The environment selector then lists an item named after your entry, such as **Create Dev box**. When you select it, Desktop runs the command on your computer, saves the host that the command prints as an SSH connection, and connects.

1490

1491> [!NOTE]

1492>

1493> Connections from a command require Claude Desktop v3.6556.0 or later on macOS or Linux, signed in with a Claude account. Administrators can [distribute commands to a team](#distribute-commands-to-your-team).

1494

1495Each entry is one connection, with one host at a time. Desktop runs the command only when you create the connection or [replace its host](#replace-the-host), not each time you connect. To keep two machines at once, add a second entry.

1496

1497> [!WARNING]

1498>

1499> Desktop doesn't stop or delete machines. Each of these keeps running, and can keep costing money, until you delete it with your tool:

1500>

1501> * A host that you replaced

1502> * The host of an entry that you removed from the file, or whose `id` you changed

1503> * A machine that your command made without Desktop saving its host, for example in these cases:

1504> * The command fails or runs out of time

1505> * Desktop can't use the printed host, another connection already uses it, or your organization doesn't allow it

1506> * While the command runs, you cancel it, remove its entry, change its `command` or `id`, or quit Desktop

1507

1508The following example adds a connection named Dev box. If the file doesn't exist, create it. If it already holds settings, add the key beside them. The command `acme-dev create` stands for your own tool, and `~/project` is the folder that Desktop selects on each machine your command makes:

1509

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

1511{

1512 "sshHostCommands": [

1513 {

1514 "id": "devbox",

1515 "name": "Dev box",

1516 "command": "acme-dev create",

1517 "startDirectory": "~/project"

1518 }

1519 ]

1520}

1521```

1522

1523Each entry takes these fields, and `id`, `name`, and `command` are required:

1524

1525| Field | Value |

1526| :- | :- |

1527| `id` | Up to 64 ASCII letters, digits, `.`, `_`, and `-`, starting with a letter or digit. Use an `id` that no other entry in `sshHostCommands` or [`sshConfigs`](#pre-configure-ssh-connections-for-your-team) has. Desktop keeps the connection's host under it, so if you change it, the connection starts over with no host and the old machine keeps running. |

1528| `name` | The connection's name in the environment selector, up to 200 characters on one line |

1529| `command` | A program and its arguments, as [Write the command](#write-the-command) describes |

1530| `sshIdentityFile` | Path to your private key, such as `~/.ssh/id_ed25519`. Leave it out to use your SSH configuration or SSH agent. |

1531| `startDirectory` | The default folder on the remote machine. Start it with `/` or `~/`, or use `~`. |

1532

1533To change or remove the connection, edit its entry in the file, because the app's SSH connection dialog doesn't open for it. You don't need to restart Desktop after you edit the file. If the entry doesn't show up or you can't select it, see [If a command is missing or gray](#if-a-command-is-missing-or-gray).

1534

1535##### Write the command

1536

1537Desktop starts the program directly, with no shell and no terminal:

1538

1539* **Program**: write its name, or its full path from `/`, without spaces. Desktop looks for a bare name on the `PATH` that your login shell exports. Relative paths such as `./acme-dev`, paths that start with `~`, and shell aliases and functions don't work.

1540* **Arguments**: separate plain arguments with spaces. The command can hold only spaces, ASCII letters, digits, and the characters `+,-./:=@_~`, and no word can start with `~`.

1541* **Scripts**: if the command needs anything else, such as quotes, pipes, variables, or a URL with `?` or `&`, put it in a script. Make the script executable, start it with a `#!` line, and set `command` to its full path, such as `/Users/you/bin/make-devbox`. On macOS, keep the script out of the Documents, Desktop, and Downloads folders, where macOS can block it.

1542* **Input**: the program gets no input and no terminal, so it can't prompt you there. If your tool signs you in through a browser or a prompt, sign in from a terminal first, and again whenever that sign-in lapses.

1543* **Environment**: the program runs in your home directory with the variables that your login shell exports. Desktop reads them when it starts, as it does for [a `ProxyCommand`](#use-variables-from-your-shell-in-a-proxycommand), so quit and reopen Desktop after you change them.

1544* **Time limit**: Desktop stops a program that is still running after 10 minutes. Desktop's progress message doesn't show the program's output. To stop the program sooner, select **Cancel** next to that message.

1545

1546The program has to exit with code 0 and print only the host on standard output, in one of two forms:

1547

1548* **One line**: `host` or `user@host`, written as for `ssh_host` in [an SSH link](#open-an-ssh-session-from-a-link). To name a port, use the JSON form.

1549* **One JSON object**: `sshHost`, and optionally a numeric `sshPort` and a `startDirectory` that replaces the entry's, such as `{"sshHost": "[email protected]", "sshPort": 2222}`

1550

1551To see the output that Desktop reads, run the command in a terminal with no input and with standard output in a file:

1552

1553```bash theme={null}

1554acme-dev create < /dev/null > host.txt

1555```

1556

1557The file has to hold only the host. When you run this test, your tool makes a machine too, so delete it with your tool afterward.

1558

1559If your tool prints other lines before the host, such as progress messages, wrap it in a script that prints only the host. The following script prints the last line of your tool's output. If your tool fails, the script exits with the same code, so that Desktop reports the failure:

1560

1561```bash theme={null}

1562#!/bin/bash

1563out=$(mktemp) || exit

1564trap 'rm -f "$out"' EXIT

1565acme-dev create > "$out" || exit

1566tail -n 1 "$out"

1567```

1568

1569If the command fails, **View details** in Desktop's message shows the last line that the command wrote to standard error, if any.

1570

1571##### Connect to a new host

1572

1573Answer two questions the first time you connect to each new host:

1574

1575* **Host key**: with OpenSSH's default host key checking, check the key's fingerprint, then choose whether to connect. To skip the question, have your command add the key to `~/.ssh/known_hosts` before it prints the host, using a key that your tool learned when it made the machine. For a port other than 22, that line starts with `[host]:port`. If your tool reuses host names, remove the old key's line too.

1576* **Folder**: choose whether you trust the folder that you open there

1577

1578Keep host key checking on for these hosts, and keep a `known_hosts` file for them. If `StrictHostKeyChecking` is `no` or `accept-new` and `UserKnownHostsFile` is also `/dev/null` or `none`, nothing records the key. When your tool then reuses a name, you can connect to a different machine without a warning.

1579

1580##### Replace the host

1581

1582Once Dev box has a host, the selector lists Dev box among your SSH connections, and **Create Dev box** becomes **Replace Dev box's host**. If that item isn't in the list, look under **More**.

1583

1584Select it when the machine is gone or you want a fresh one. On the new-session page, the message that says Desktop can't reach the host offers it too. Desktop runs the command again, and new sessions use the new host.

1585

1586* **A new host**: the item is gray for 10 minutes after Desktop saves a host, because a new machine can take a while to start. While a new host doesn't answer, the new-session page keeps trying to connect for those 10 minutes.

1587* **Sessions on the old host**: they stay on it, and Desktop doesn't connect to that host unless you add it back. To continue one, open the session and select **Add SSH connection**. Desktop fills in the old host. Save it as a connection of its own.

1588

1589##### Distribute commands to your team

1590

1591To give your team a connection, set `sshHostCommands` in Claude Code's [managed settings](https://code.claude.com/docs/en/managed-settings.md) file or MDM policy on each computer, not in the desktop app's own [device management policy](#device-management-policies). Users see your entries alongside their own, and the app offers no way to edit or remove an entry, theirs or yours.

1592

1593The following managed settings file gives users a connection named Dev box and turns off their own entries, along with Claude Code hooks from user, project, and local settings:

1594

1595```json managed-settings.json theme={null}

1596{

1597 "sshHostCommands": [

1598 {

1599 "id": "acme-devbox",

1600 "name": "Dev box",

1601 "command": "/usr/local/bin/acme-dev create"

1602 }

1603 ],

1604 "strictPluginOnlyCustomization": ["hooks"]

1605}

1606```

1607

1608Before you deploy the key, settle each of these:

1609

1610* **Where to put the key**: if your MDM policy for Claude Code already sets a [policy key](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources), put it there. Otherwise, put it in the managed settings file. By default, such a policy outranks the file, and Desktop then ignores entries in the file. Set it on the computer even where [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) apply: Desktop ignores the key there, and in project and local settings.

1611* **The `id`**: if a user's `sshHostCommands` entry has your `id`, only yours works. If any other SSH connection has it, such as one in a user's `sshConfigs`, your entry is gray. Pick an `id` that users are unlikely to choose.

1612* **The program**: give its full path, because Desktop looks up a bare name on each user's own `PATH`. The program runs as the user, with the variables that their login shell exports.

1613* **Users' own entries**: Desktop treats a user's entry like a [hook](https://code.claude.com/docs/en/hooks.md), because both run a program on the computer. To allow only your entries, set [`strictPluginOnlyCustomization`](https://code.claude.com/docs/en/settings-reference#strictpluginonlycustomization) to `["hooks"]`, or add `"hooks"` to its list. You also stop Claude Code hooks from user, project, and local settings, with no way to keep them. If you set that key or [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) to `true` instead, you block more, as each key's entry lists.

1614* **Every entry**: to turn off your entries too, set [`disableAllHooks`](https://code.claude.com/docs/en/settings-reference#disableallhooks) in managed settings. If you set [`disableDesktopLocalSessions`](https://code.claude.com/docs/en/settings-reference#disabledesktoplocalsessions), or an `sshHostAllowlist` that allows no host, the selector lists no **Create** or **Replace** items.

1615* **Where the locks count**: for these entries, Desktop reads `allowManagedHooksOnly`, `strictPluginOnlyCustomization`, and `disableAllHooks` from server-managed settings and from the computer's own file or policy, and applies the stricter result. Every entry stays gray until Desktop has checked claude.ai for server-managed settings, even if your organization has none.

1616* **Allowed hosts**: if you set [`sshHostAllowlist`](#restrict-which-ssh-hosts-users-can-connect-to), make sure that a pattern matches each hostname that your tool prints, and leave `user@` out of the pattern. Desktop checks the printed name only after the command has run, so a machine that the list refuses already exists, and the user has to delete it with your tool. At each connection, the resolved `HostName` has to match too.

1617

1618After you deploy the key, restart Desktop on a test computer. In the Code tab's environment selector, look under **SSH**, or in the single **SSH** row. Your entry shows as a **Create** item, or as a gray item that gives the reason when you hover over it. If it's missing, check where you put the key, then the cases in [If a command is missing or gray](#if-a-command-is-missing-or-gray).

1619

1620##### If a command is missing or gray

1621

1622The environment selector lists no **Create** or **Replace** item in these cases:

1623

1624* **The file**: `~/.claude/settings.json` has [invalid JSON or a value that the schema rejects](https://code.claude.com/docs/en/settings.md#fix-a-broken-settings-file), you misspelled the key, or you put it in a project's settings. Fix the file.

1625* **Platform and account**: you use Windows, or a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md) instead of a Claude account. Add each host as an [SSH connection](#ssh-sessions) yourself.

1626* **Your organization's settings**: your administrator turned off local sessions, or turned off SSH sessions. Ask them whether you can use commands.

1627* **No `ssh` program**: Desktop couldn't start the OpenSSH client on your computer. Install it, or ask your administrator to allow it, then restart Desktop.

1628

1629An entry that you can't select is gray. Hover over it to see the reason:

1630

1631* **A mistake in the entry**: fix the field or the command that the message names. If the `id` is in use, give the entry another one.

1632* **A broken settings file**: while your own settings file is broken, your administrator's entries may be gray, with a message that names the file. [Fix the file](https://code.claude.com/docs/en/settings.md#fix-a-broken-settings-file).

1633* **A new host**: you can [replace a host](#replace-the-host) once it's 10 minutes old.

1634* **Hooks are off or restricted**: your own entries work only where your own hooks can run. Remove `disableAllHooks` from your settings, or ask your administrator.

1635* **Settings are still loading**: every entry is gray until Desktop has loaded your organization's [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), usually a few seconds after launch. If the entries stay gray, check your connection to claude.ai.

1636

14871637#### Pre-configure SSH connections for your team

14881638

1489Administrators can distribute SSH connections to team members by setting `sshConfigs` in [managed settings](/docs/en/managed-settings.md).

1639Administrators can distribute SSH connections to team members by setting `sshConfigs` in [managed settings](https://code.claude.com/docs/en/managed-settings.md).

14901640

14911641* **What users see**: connections defined this way appear in each user's environment selector automatically.

14921642* **What users can change**: users can select a managed connection and [set their own **Worktree folder**](#set-the-worktree-folder-on-an-existing-connection) for it. They can't edit its other fields or delete it in the app.

from line 1663

15131663

15141664#### Restrict which SSH hosts users can connect to

15151665

1516Administrators can limit Desktop's SSH sessions to an approved set of hosts by setting `sshHostAllowlist` in [managed settings](/docs/en/managed-settings.md). When set, users can only connect to hosts whose resolved hostname matches one of the patterns. Set it to an empty array to disable SSH sessions. The [`sshHostAllowlist` reference entry](/docs/en/settings-reference#sshhostallowlist) says how an empty array combines with lists in other managed sources.

1666Administrators can limit Desktop's SSH sessions to an approved set of hosts by setting `sshHostAllowlist` in [managed settings](https://code.claude.com/docs/en/managed-settings.md). When set, users can only connect to hosts whose resolved hostname matches one of the patterns. Set it to an empty array to disable SSH sessions. The [`sshHostAllowlist` reference entry](https://code.claude.com/docs/en/settings-reference#sshhostallowlist) says how an empty array combines with lists in other managed sources.

15171667

15181668The following example allows connections to any host under `devboxes.example.com` and to a single named bastion host:

15191669

from line 1675

15251675

15261676> [!WARNING]

15271677>

1528> If your organization delivers [server-managed settings](/docs/en/server-managed-settings.md), set `sshHostAllowlist` there. By default, Desktop reads the key only from the [highest-ranked managed source that delivers a policy key](/docs/en/managed-settings.md#how-claude-code-combines-managed-sources). If that source leaves the key unset, Desktop ignores a list in a lower-ranked MDM policy or managed settings file and treats the key as [unset](/docs/en/settings-reference.md#sshhostallowlist). Desktop shows no warning.

1678> If your organization delivers [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), set `sshHostAllowlist` there. By default, Desktop reads the key only from the [highest-ranked managed source that delivers a policy key](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources). If that source leaves the key unset, Desktop ignores a list in a lower-ranked MDM policy or managed settings file and treats the key as [unset](https://code.claude.com/docs/en/settings-reference.md#sshhostallowlist). Desktop shows no warning.

15291679>

15301680> Also keep the same list on each user's machine, in the highest-ranked MDM policy or managed settings file there. Desktop fetches server-managed settings at launch and keeps no cached copy, so until a fetch succeeds the machine's list is the one that applies.

15311681

from line 1713

15631713

15641714#### Turn off local sessions and distribute SSH connections

15651715

1566To turn off local sessions and limit SSH sessions to hosts that you choose, deploy [`disableDesktopLocalSessions`](/docs/en/settings-reference#disabledesktoplocalsessions), [`sshConfigs`](#pre-configure-ssh-connections-for-your-team), and [`sshHostAllowlist`](#restrict-which-ssh-hosts-users-can-connect-to) together.

1716To turn off local sessions and limit SSH sessions to hosts that you choose, deploy [`disableDesktopLocalSessions`](https://code.claude.com/docs/en/settings-reference#disabledesktoplocalsessions), [`sshConfigs`](#pre-configure-ssh-connections-for-your-team), and [`sshHostAllowlist`](#restrict-which-ssh-hosts-users-can-connect-to) together.

15671717

15681718> [!NOTE]

15691719>

1570> This setup is for users who sign in with a Claude account. With a [third-party provider](/docs/en/third-party-integrations.md), SSH sessions are off by default, and setting `sshHostAllowlist` can turn them on. Read [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions) before you deploy these keys.

1720> This setup is for users who sign in with a Claude account. With a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md), SSH sessions are off by default, and setting `sshHostAllowlist` can turn them on. Read [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions) before you deploy these keys.

15711721

15721722The following example turns off local sessions, adds one connection, and limits SSH sessions to that connection's host:

15731723

from line 1745

15951745

15961746* **Hostnames**: make sure that a pattern in `sshHostAllowlist` matches the hostname of each `sshConfigs` entry, without `user@`, or developers can't connect to it. Also add a pattern that matches each [jump host](#allow-jump-hosts) that Desktop checks on the way to it. For how Desktop matches a hostname, see [Restrict which SSH hosts users can connect to](#restrict-which-ssh-hosts-users-can-connect-to).

15971747* **Version**: `disableDesktopLocalSessions` requires Claude Desktop v1.37937.0 or later

1598* **File permissions**: make sure that each developer's account on the computer can read the managed settings file. Desktop doesn't apply the keys in a file that the account can't read, and Claude Code [starts without them](/docs/en/managed-settings.md#find-entries-claude-code-dropped) too.

1599

1600Put the three keys in one [managed source](/docs/en/managed-settings.md#how-claude-code-combines-managed-sources), the highest-ranked one that you deliver. If you deliver [server-managed settings](/docs/en/server-managed-settings.md), also keep a copy of the three keys in the highest-ranked MDM policy or managed settings file on each computer. Desktop fetches server-managed settings at launch, and the copy on the computer applies until a fetch succeeds.

1748* **File permissions**: make sure that each developer's account on the computer can read the managed settings file. Desktop doesn't apply the keys in a file that the account can't read, and Claude Code [starts without them](https://code.claude.com/docs/en/managed-settings.md#find-entries-claude-code-dropped) too.

1749

1750Put the three keys in one [managed source](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources), the highest-ranked one that you deliver. If you deliver [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), also keep a copy of the three keys in the highest-ranked MDM policy or managed settings file on each computer. Desktop fetches server-managed settings at launch, and the copy on the computer applies until a fetch succeeds.

16011751

16021752To confirm that the settings apply, check a developer's computer:

16031753

from line 1762

16121762

16131763* **Desktop version**: update Desktop if it's earlier than v1.37937.0.

16141764* **Managed settings file**: make sure that the file is valid JSON.

1615* **Managed source**: make sure that the computer reads the [managed source](/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) that holds the keys.

1765* **Managed source**: make sure that the computer reads the [managed source](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) that holds the keys.

16161766

16171767**2. Add a host that isn't on the allowlist**

16181768

from line 1777

16271777These settings are configured through the [admin settings console](https://claude.ai/admin-settings/claude-code):

16281778

16291779* **Desktop**: control whether users in your organization can access Claude Code in the desktop app

1630* **Cloud sessions**: enable or disable [cloud sessions](/docs/en/claude-code-on-the-web.md) for your organization

1631* **Remote Control**: enable or disable [Remote Control](/docs/en/remote-control.md) for your organization

1632

1633In Enterprise organizations that have HIPAA enabled, the **Desktop** toggle is off by default and an [Owner](/docs/en/server-managed-settings.md#access-control) can turn it on. Applying the [HIPAA configuration](/docs/en/hipaa-setup.md) turns it off, even if it was on, so an Owner has to turn it on afterward. **Cloud sessions** and **Remote Control** are also off by default, and an Owner can't turn them on once the organization has the HIPAA configuration applied.

1780* **Cloud sessions**: enable or disable [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) for your organization

1781* **Remote Control**: enable or disable [Remote Control](https://code.claude.com/docs/en/remote-control.md) for your organization

1782

1783In Enterprise organizations that have HIPAA enabled, the **Desktop** toggle is off by default and an [Owner](https://code.claude.com/docs/en/server-managed-settings.md#access-control) can turn it on. Applying the [HIPAA configuration](https://code.claude.com/docs/en/hipaa-setup.md) turns it off, even if it was on, so an Owner has to turn it on afterward. **Cloud sessions** and **Remote Control** are also off by default, and an Owner can't turn them on once the organization has the HIPAA configuration applied.

16341784

16351785> [!NOTE]

16361786>

16371787> The OpenTelemetry form for Cowork under **Monitoring** in the admin console's [Data and privacy settings](https://claude.ai/admin-settings/data-privacy-controls) applies to Cowork sessions only. In a Cowork session on this machine, the desktop app passes that collector to Claude Code as `OTEL_*` environment variables, so the form takes effect even though Claude Code in that session [never fetches admin-console settings](#managed-settings).

16381788>

1639> To export telemetry from Code tab sessions, set `CLAUDE_CODE_ENABLE_TELEMETRY` and the `OTEL_*` variables in the `env` block of your Claude Code managed settings, as shown in [administrator configuration for monitoring](/docs/en/monitoring-usage.md#administrator-configuration). Local, cloud, and SSH sessions each read [managed settings from different sources](#managed-settings). For the hosts a cloud session can reach, see [network access](/docs/en/cloud-environments.md#network-access). For the `service.name` that Code tab sessions report, see [service information](/docs/en/monitoring-usage.md#service-information).

1640>

1641> To find out which remote machine an SSH session ran on, see [Attribute telemetry to Desktop SSH sessions](/docs/en/monitoring-usage.md#attribute-telemetry-to-desktop-ssh-sessions).

1789> To export telemetry from Code tab sessions, set `CLAUDE_CODE_ENABLE_TELEMETRY` and the `OTEL_*` variables in the `env` block of your Claude Code managed settings, as shown in [administrator configuration for monitoring](https://code.claude.com/docs/en/monitoring-usage.md#administrator-configuration). Local, cloud, and SSH sessions each read [managed settings from different sources](#managed-settings). For the hosts a cloud session can reach, see [network access](https://code.claude.com/docs/en/cloud-environments.md#network-access). For the `service.name` that Code tab sessions report, see [service information](https://code.claude.com/docs/en/monitoring-usage.md#service-information).

1790>

1791> To find out which remote machine an SSH session ran on, see [Attribute telemetry to Desktop SSH sessions](https://code.claude.com/docs/en/monitoring-usage.md#attribute-telemetry-to-desktop-ssh-sessions).

16421792

16431793### Managed settings

16441794

1645Managed settings override project and user settings and apply to Claude Code sessions in Desktop. You can set these keys in your organization's [managed settings](/docs/en/managed-settings.md) file or push them remotely through the admin console.

1795Managed settings override project and user settings and apply to Claude Code sessions in Desktop. You can set these keys in your organization's [managed settings](https://code.claude.com/docs/en/managed-settings.md) file or push them remotely through the admin console, unless a key's row says otherwise.

16461796

16471797| Key | Description |

16481798| - | - |

16491799| `permissions.disableBypassPermissionsMode` | set to `"disable"` to prevent users from enabling Bypass permissions mode. |

1650| `disableAutoMode` | set to `"disable"` to remove [Auto](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) mode from the mode selector. Also accepted under `permissions`. |

1651| `autoMode` | customize what the auto mode classifier trusts and blocks across your organization. See [Configure auto mode](/docs/en/auto-mode-config.md). |

1800| `disableAutoMode` | set to `"disable"` to remove [Auto](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) mode from the mode selector. Also accepted under `permissions`. |

1801| `autoMode` | customize what the auto mode classifier trusts and blocks across your organization. See [Configure auto mode](https://code.claude.com/docs/en/auto-mode-config.md). |

16521802| `browserExternalPageTools` | set to `"disabled"` to prevent Claude from using tools to read or act on external pages in the [Browser pane](#browse-external-sites). Users can still navigate to external sites themselves, and local dev server previews are unaffected. |

1653| `disableMobileSimulatorTools` | set to `true` to block Claude's tools for controlling and capturing devices in the [iOS Simulator pane](/docs/en/desktop-ios-simulator.md#turn-off-simulator-access). The pane stays usable for the user's own taps; only Claude's access is removed. The value must be the JSON boolean `true`; the string `"true"` is ignored. |

1803| `disableMobileSimulatorTools` | set to `true` to block Claude's tools for controlling and capturing devices in the [iOS Simulator pane](https://code.claude.com/docs/en/desktop-ios-simulator.md#turn-off-simulator-access). The pane stays usable for the user's own taps; only Claude's access is removed. The value must be the JSON boolean `true`; the string `"true"` is ignored. |

16541804| `disableBrowserExternalNavigation` | set to `true` to turn off external browsing in the [Browser pane](#browse-external-sites) entirely. Neither users nor Claude can navigate to external sites, and localhost dev server previews are unaffected. The value must be the JSON boolean `true`; the string `"true"` is ignored. |

16551805| `sshConfigs` | pre-configure [SSH connections](#pre-configure-ssh-connections-for-your-team) that appear in the environment selector. Users can't delete managed connections or edit anything but their own **Worktree folder**. |

1806| `sshHostCommands` | give users [SSH connections whose host comes from a command](#distribute-commands-to-your-team), alongside their own. Desktop reads it from the managed settings file or MDM policy on the computer, and ignores it in [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md). Requires Claude Desktop v3.6556.0 or later on macOS or Linux, signed in with a Claude account. |

16561807| `sshHostAllowlist` | restrict [SSH sessions](#restrict-which-ssh-hosts-users-can-connect-to) to hosts whose resolved hostname matches one of these patterns. Read from managed settings only. |

16571808| `disableDesktopLocalSessions` | set to `true` to turn off [Code sessions that run on the device](#local-sessions-on-managed-devices), leaving SSH sessions to other hosts and cloud sessions available. The value must be the JSON boolean `true`. Read from managed settings only. Requires Claude Desktop v1.37937.0 or later. |

16581809| `disableSshSavedPasswords` | set to `true` to stop Desktop from offering to remember SSH passwords and from using or showing the ones it saved earlier. Turning it on doesn't delete them. Read from managed settings only. Requires Claude Desktop v1.49585.0 or later. |

1659| `managedMcpServers` | push MCP server configurations to all users. Available in third-party (3P) Desktop deployments only. In each entry, set a transport of `"http"`, `"sse"`, or `"stdio"`, connection details, and optionally a `toolPolicy` map to restrict which of that server's tools users can invoke. Deliver it through the managed settings file, MDM, or a Claude apps gateway policy's [`desktop` block](/docs/en/claude-apps-gateway-config#claude-desktop-overlay), since 3P deployments don't receive admin-console settings. To deliver it through the gateway, you need Claude Code v2.1.232 or later on the gateway server. This is the desktop app's own key; Claude Code reads a [same-named managed setting](/docs/en/managed-mcp.md#provide-servers-through-managed-settings) of its own, with a different entry shape. |

1660

1661Which managed settings reach a Desktop session depends on where that session runs. Model restrictions such as [`availableModels`](/docs/en/model-config#restrict-model-selection) are enforced in Desktop's Claude Code sessions the same way as in the terminal CLI; see [surface coverage](/docs/en/model-config.md#surface-coverage).

1662

1663* **Local sessions on this machine**: a managed settings file deployed to disk applies. Managed settings pushed remotely through the admin console also reach these sessions on Anthropic's API when the session authenticates with an [eligible login](/docs/en/server-managed-settings.md#platform-availability), following the same [settings precedence](/docs/en/settings.md#settings-precedence) as the terminal CLI.

1664* **[Cloud sessions](#cloud-sessions)**: receive [server-managed settings](/docs/en/server-managed-settings.md); device-deployed files don't reach them, because they run on Anthropic-managed VMs. Sessions routed to a [self-hosted environment](/docs/en/self-hosted-environments) also read the managed settings file in the runner image. [How Claude Code combines managed sources](/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) says when that file applies.

1665* **[SSH sessions](#ssh-sessions)**: the session reads the managed settings file from the remote host. Desktop itself reads `sshConfigs`, `sshHostAllowlist`, `disableSshSavedPasswords`, and `disableDesktopLocalSessions` on the local machine. If you deliver more than one managed source, it reads them from [one by default](/docs/en/managed-settings.md#how-claude-code-combines-managed-sources).

1666* **[Cowork](https://claude.com/docs/cowork/overview) sessions**: in a Cowork session on this machine, Claude Code never fetches admin-console settings, even when the user signs in with a Team or Enterprise account, and reads policy deployed to the machine unless your Claude Desktop configuration sets `requireCoworkFullVmSandbox`. Remote Cowork sessions receive neither. See [where and when a policy applies](/docs/en/managed-settings.md#where-and-when-a-policy-applies) for which device files reach Cowork, and [MCP permission rules](/docs/en/permissions.md#mcp) for how `Bash` and `WebFetch` rules apply to Cowork's tools.

1667

1668In local and SSH sessions, the desktop app delivers each user's connected claude.ai connectors to Claude Code directly. No MCP setting or `managed-mcp.json` reaches those connectors, whichever settings source or file location you use. To block a connector's tools in these sessions, use your organization's [connector tool controls](/docs/en/mcp.md#organization-controls-on-connector-tools). [How connectors reach Claude Code](/docs/en/mcp.md#how-connectors-reach-claude-code) shows which settings govern connectors in each kind of session.

1810| `managedMcpServers` | push MCP server configurations to all users. Available in third-party (3P) Desktop deployments only. In each entry, set a transport of `"http"`, `"sse"`, or `"stdio"`, connection details, and optionally a `toolPolicy` map to restrict which of that server's tools users can invoke. Deliver it through the managed settings file, MDM, or a Claude apps gateway policy's [`desktop` block](https://code.claude.com/docs/en/claude-apps-gateway-config#claude-desktop-overlay), since 3P deployments don't receive admin-console settings. To deliver it through the gateway, you need Claude Code v2.1.232 or later on the gateway server. This is the desktop app's own key; Claude Code reads a [same-named managed setting](https://code.claude.com/docs/en/managed-mcp.md#provide-servers-through-managed-settings) of its own, with a different entry shape. |

1811

1812Which managed settings reach a Desktop session depends on where that session runs. Model restrictions such as [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) are enforced in Desktop's Claude Code sessions the same way as in the terminal CLI; see [surface coverage](https://code.claude.com/docs/en/model-config.md#surface-coverage).

1813

1814* **Local sessions on this machine**: a managed settings file deployed to disk applies. Managed settings pushed remotely through the admin console also reach these sessions on Anthropic's API when the session authenticates with an [eligible login](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability), following the same [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) as the terminal CLI.

1815* **[Cloud sessions](#cloud-sessions)**: receive [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md); device-deployed files don't reach them, because they run on Anthropic-managed VMs. Sessions routed to a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) also read the managed settings file in the runner image. [How Claude Code combines managed sources](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) says when that file applies.

1816* **[SSH sessions](#ssh-sessions)**: the session reads the managed settings file from the remote host. Desktop itself reads `sshConfigs`, `sshHostAllowlist`, `disableSshSavedPasswords`, and `disableDesktopLocalSessions` on the local machine. If you deliver more than one managed source, it reads them from [one by default](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources).

1817* **[Cowork](https://claude.com/docs/cowork/overview) sessions**: in a Cowork session on this machine, Claude Code never fetches admin-console settings, even when the user signs in with a Team or Enterprise account, and reads policy deployed to the machine unless your Claude Desktop configuration sets `requireCoworkFullVmSandbox`. Remote Cowork sessions receive neither. See [where and when a policy applies](https://code.claude.com/docs/en/managed-settings.md#where-and-when-a-policy-applies) for which device files reach Cowork, and [MCP permission rules](https://code.claude.com/docs/en/permissions.md#mcp) for how `Bash` and `WebFetch` rules apply to Cowork's tools.

1818

1819In local and SSH sessions, the desktop app delivers each user's connected claude.ai connectors to Claude Code directly. No MCP setting or `managed-mcp.json` reaches those connectors, whichever settings source or file location you use. To block a connector's tools in these sessions, use your organization's [connector tool controls](https://code.claude.com/docs/en/mcp.md#organization-controls-on-connector-tools). [How connectors reach Claude Code](https://code.claude.com/docs/en/mcp.md#how-connectors-reach-claude-code) shows which settings govern connectors in each kind of session.

16691820

16701821`permissions.disableBypassPermissionsMode` and `disableAutoMode` also work in user and project settings, but placing them in managed settings prevents users from overriding them.

16711822

1672For the permission, plugin, and delivery keys only a managed source can set, see [Keys only managed settings can set](/docs/en/managed-settings.md#managed-only-settings).

1823For the permission, plugin, and delivery keys only a managed source can set, see [Keys only managed settings can set](https://code.claude.com/docs/en/managed-settings.md#managed-only-settings).

16731824

16741825### Device management policies

16751826

from line 1828

16771828

16781829* **macOS**: configure via `com.anthropic.claudefordesktop` preference domain using tools like Jamf or Kandji

16791830* **Windows**: configure via registry at `SOFTWARE\Policies\Claude`

1680* **Linux**: configure via a root-owned file at `/etc/claude-desktop/managed-settings.json`, which holds the policy keys as a JSON object. Desktop refuses the file if anyone but root can write to it or to its folder. It's a different file from Claude Code's [managed settings file](/docs/en/managed-settings.md).

1831* **Linux**: configure via a root-owned file at `/etc/claude-desktop/managed-settings.json`, which holds the policy keys as a JSON object. Desktop refuses the file if anyone but root can write to it or to its folder. It's a different file from Claude Code's [managed settings file](https://code.claude.com/docs/en/managed-settings.md).

16811832

16821833### Network access requirements

16831834

from line 1847

16961847*.claudemcpcontent.com

16971848```

16981849

1699Traffic is HTTPS on port 443 unless you configure a custom port for [OTLP](/docs/en/monitoring-usage.md), an LLM gateway, or an MCP server.

1700

1701For proxy servers, custom certificate authorities, mTLS, and the domains the standalone CLI needs, see [network configuration](/docs/en/network-config.md).

1850Traffic is HTTPS on port 443 unless you configure a custom port for [OTLP](https://code.claude.com/docs/en/monitoring-usage.md), an LLM gateway, or an MCP server.

1851

1852For proxy servers, custom certificate authorities, mTLS, and the domains the standalone CLI needs, see [network configuration](https://code.claude.com/docs/en/network-config.md).

17021853

17031854To reduce the number of firewall wildcards, allow these Anthropic hosts instead. Certain subdomains are dynamically generated and must remain wildcards.

17041855

from line 1877

17261877

17271878Anthropic checks connections to that host against your organization's IP allowlist using the address they arrive from. If your proxy sends traffic for it out through an address that isn't on that allowlist, Claude in Chrome and other features that connect through the bridge stop working while the rest of the app keeps working.

17281879

1729An [artifact](/docs/en/artifacts.md) that loads a typeface from [Google Fonts](/docs/en/artifacts.md#improve-the-visual-design) also requests `fonts.googleapis.com` and `fonts.gstatic.com`. Both hosts are optional. If you block them, artifacts render in fallback typefaces. Block with a fast rejection rather than a silent drop so the font request fails immediately instead of delaying the page's first render.

1880An [artifact](https://code.claude.com/docs/en/artifacts.md) that loads a typeface from [Google Fonts](https://code.claude.com/docs/en/artifacts.md#improve-the-visual-design) also requests `fonts.googleapis.com` and `fonts.gstatic.com`. Both hosts are optional. If you block them, artifacts render in fallback typefaces. Block with a fast rejection rather than a silent drop so the font request fails immediately instead of delaying the page's first render.

17301881

17311882Artifacts can also load JavaScript libraries, such as React or a charting package, from `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `cdn.tailwindcss.com`, `code.jquery.com`, and `unpkg.com`, and from no other external host. If you block those hosts, the parts of an artifact that depend on a library don't work, and unlike a blocked font, a blocked library has no fallback. Block with a fast rejection here too, so a blocked library request fails at once rather than hanging until it times out.

17321883

17331884### Authentication and SSO

17341885

1735Team and Enterprise organizations can require SSO for all users. See [authentication](/docs/en/authentication.md) for plan-level details and [Setting up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso) for SAML configuration; OIDC setup is covered in the [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide).

1886Team and Enterprise organizations can require SSO for all users. See [authentication](https://code.claude.com/docs/en/authentication.md) for plan-level details and [Setting up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso) for SAML configuration; OIDC setup is covered in the [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide).

17361887

17371888### Data handling

17381889

1739Claude Code processes your code locally in local sessions, or in cloud sessions on Anthropic-managed infrastructure, unless your organization routes them to a [self-hosted environment](/docs/en/self-hosted-environments). Cloud sessions, including in a self-hosted environment, send conversations and code context to Anthropic's API for processing; local and SSH sessions send them to whichever [model provider](#feature-comparison) your deployment configures, Anthropic's API by default. See [data handling](/docs/en/data-usage.md) for details on data retention, privacy, and compliance.

1890Claude Code processes your code locally in local sessions, or in cloud sessions on Anthropic-managed infrastructure, unless your organization routes them to a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments). Cloud sessions, including in a self-hosted environment, send conversations and code context to Anthropic's API for processing; local and SSH sessions send them to whichever [model provider](#feature-comparison) your deployment configures, Anthropic's API by default. See [data handling](https://code.claude.com/docs/en/data-usage.md) for details on data retention, privacy, and compliance.

17401891

17411892### Deployment

17421893

from line 1896

17451896* **macOS**: distribute via MDM such as Jamf or Kandji using the `.dmg` installer

17461897* **Windows**: deploy via the MSIX package. See [Deploy Claude Desktop for Windows](https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows) for enterprise deployment options including silent installation

17471898

1748For the domains to allowlist in your firewall, see [network access requirements](#network-access-requirements) above. For proxy settings, custom certificate authorities, and LLM gateways, see [network configuration](/docs/en/network-config.md).

1899For the domains to allowlist in your firewall, see [network access requirements](#network-access-requirements) above. For proxy settings, custom certificate authorities, and LLM gateways, see [network configuration](https://code.claude.com/docs/en/network-config.md).

17491900

17501901For the full enterprise configuration reference, see the [enterprise configuration guide](https://support.claude.com/en/articles/12622667-enterprise-configuration).

17511902

from line 1906

17551906

17561907To move a CLI session into Desktop, run `/desktop` in the terminal. Claude saves your session and opens it in the desktop app, then exits the CLI. This command is available on macOS and x64 Windows when you are signed in with a Claude subscription. It is not available with API key authentication or on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry.

17571908

1758From your shell, [`claude --desktop`](/docs/en/cli-reference#cli-flags) opens Desktop directly without starting a terminal session. It requires Claude Code v2.1.285 or later and has the same platform and sign-in requirements as `/desktop`. With no other arguments, it opens Desktop on the current directory. To open an existing CLI session in Desktop, add `--continue` for the most recent conversation in this directory, or `--resume` with the session ID that `/status` shows:

1909From your shell, [`claude --desktop`](https://code.claude.com/docs/en/cli-reference#cli-flags) opens Desktop directly without starting a terminal session. It requires Claude Code v2.1.285 or later and has the same platform and sign-in requirements as `/desktop`. With no other arguments, it opens Desktop on the current directory. To open an existing CLI session in Desktop, add `--continue` for the most recent conversation in this directory, or `--resume` with the session ID that `/status` shows:

17591910

17601911```bash theme={null}

17611912claude --desktop --resume <session-id>

from line 1939

17881939| `--permission-mode` | Mode selector in the row under the prompt box |

17891940| `--dangerously-skip-permissions` | Bypass permissions mode. On Pro and Max plans, enable it in Settings → Claude Code → "Allow bypass permissions mode"; on Team and Enterprise plans, organization policy controls it |

17901941| `--add-dir` | [Add folders to a session](#add-folders-to-a-session) in local and SSH sessions, or select [several repositories](#run-long-running-tasks-in-the-cloud) in a cloud session |

1791| `--allowedTools`, `--disallowedTools` | No per-session equivalent. Permission rules in [settings files](/docs/en/settings.md) still apply. |

1942| `--allowedTools`, `--disallowedTools` | No per-session equivalent. Permission rules in [settings files](https://code.claude.com/docs/en/settings.md) still apply. |

17921943| `--verbose` | [Verbose view mode](#switch-view-modes) |

17931944| `--print`, `--output-format` | Not available. Desktop is interactive only. |

17941945| `ANTHROPIC_MODEL` env var | Model picker in the row under the prompt box |

from line 1949

17981949

17991950Desktop and CLI read the same configuration files, so your setup carries over:

18001951

1801* **[CLAUDE.md](/docs/en/memory.md)** and `CLAUDE.local.md` files in your project are used by both

1802* **[MCP servers](/docs/en/mcp.md)** configured in `~/.claude.json` or `.mcp.json` work in both

1803* **[Hooks](/docs/en/hooks.md)** and **[skills](/docs/en/skills.md)** defined in settings apply to both

1804* **[Settings](/docs/en/settings.md)** in `~/.claude.json` and `~/.claude/settings.json` are shared. Permission rules, allowed tools, and other settings in `settings.json` apply to Desktop sessions.

1805* **Models**: the same [models](/docs/en/model-config.md#available-models) are available in both. In Desktop, select the model from the model picker in the row under the prompt box. You can change the model mid-session from the same picker.

1952* **[CLAUDE.md](https://code.claude.com/docs/en/memory.md)** and `CLAUDE.local.md` files in your project are used by both

1953* **[MCP servers](https://code.claude.com/docs/en/mcp.md)** configured in `~/.claude.json` or `.mcp.json` work in both

1954* **[Hooks](https://code.claude.com/docs/en/hooks.md)** and **[skills](https://code.claude.com/docs/en/skills.md)** defined in settings apply to both

1955* **[Settings](https://code.claude.com/docs/en/settings.md)** in `~/.claude.json` and `~/.claude/settings.json` are shared. Permission rules, allowed tools, and other settings in `settings.json` apply to Desktop sessions.

1956* **Models**: the same [models](https://code.claude.com/docs/en/model-config.md#available-models) are available in both. In Desktop, select the model from the model picker in the row under the prompt box. You can change the model mid-session from the same picker.

18061957

18071958#### MCP servers from the Claude Desktop chat app

18081959

from line 1961

18101961

18111962If you define the same server name in `claude_desktop_config.json` and in `~/.claude.json` or `.mcp.json`, the Code tab in local sessions connects once and uses the `claude_desktop_config.json` definition.

18121963

1813The app also re-delivers stdio servers from `~/.claude.json` to the embedded CLI in local sessions. When the top level of `~/.claude.json` (user scope) and `.mcp.json` define the same stdio server name, the Code tab uses the `~/.claude.json` definition, departing from the CLI [scope hierarchy](/docs/en/mcp.md#scope-hierarchy-and-precedence).

1964The app also re-delivers stdio servers from `~/.claude.json` to the embedded CLI in local sessions. When the top level of `~/.claude.json` (user scope) and `.mcp.json` define the same stdio server name, the Code tab uses the `~/.claude.json` definition, departing from the CLI [scope hierarchy](https://code.claude.com/docs/en/mcp.md#scope-hierarchy-and-precedence).

18141965

18151966> [!NOTE]

18161967>

1817> The standalone CLI does not read `claude_desktop_config.json`. On macOS and WSL, run `claude mcp add-from-claude-desktop` to copy those servers into `~/.claude.json`. See [Import MCP servers from Claude Desktop](/docs/en/mcp.md#import-mcp-servers-from-claude-desktop) for the import flow and scope options.

1968> The standalone CLI does not read `claude_desktop_config.json`. On macOS and WSL, run `claude mcp add-from-claude-desktop` to copy those servers into `~/.claude.json`. See [Import MCP servers from Claude Desktop](https://code.claude.com/docs/en/mcp.md#import-mcp-servers-from-claude-desktop) for the import flow and scope options.

18181969

18191970### Feature comparison

18201971

1821This table compares core capabilities between the CLI and Desktop. For a full list of CLI flags, see the [CLI reference](/docs/en/cli-reference.md).

1972This table compares core capabilities between the CLI and Desktop. For a full list of CLI flags, see the [CLI reference](https://code.claude.com/docs/en/cli-reference.md).

18221973

18231974| Feature | CLI | Desktop |

18241975| - | - | - |

18251976| Permission modes | All modes including `dontAsk` | Manual, Accept edits, Plan, and Auto. Bypass permissions appears in the mode selector once enabled: through the Settings toggle on Pro and Max plans, or through organization policy on Team and Enterprise plans |

1826| [Third-party providers](/docs/en/third-party-integrations.md) | Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry | Anthropic's API by default. For gateway routing, see [connect the desktop app to a gateway](/docs/en/llm-gateway-connect.md#desktop-app). To run the Code tab on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or a self-hosted LLM gateway, see [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview). |

1827| [MCP servers](/docs/en/mcp.md) | Configure in settings files | Connectors UI for local and SSH sessions, or settings files |

1828| [Plugins](/docs/en/plugins/overview.md) | `/plugin` command | Plugin manager UI |

1977| [Third-party providers](https://code.claude.com/docs/en/third-party-integrations.md) | Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry | Anthropic's API by default. For gateway routing, see [connect the desktop app to a gateway](https://code.claude.com/docs/en/llm-gateway-connect.md#desktop-app). To run the Code tab on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or a self-hosted LLM gateway, see [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview). |

1978| [MCP servers](https://code.claude.com/docs/en/mcp.md) | Configure in settings files | Connectors UI for local and SSH sessions, or settings files |

1979| [Plugins](https://code.claude.com/docs/en/plugins/overview.md) | `/plugin` command | Plugin manager UI |

18291980| @mention files | Text-based | With autocomplete, except for a cloud session's first message |

18301981| File attachments | Not available | Images, PDFs |

1831| Session isolation | [`--worktree`](/docs/en/cli-reference) flag | [Run a session in its own worktree](#run-a-session-in-its-own-worktree) |

1982| Session isolation | [`--worktree`](https://code.claude.com/docs/en/cli-reference) flag | [Run a session in its own worktree](#run-a-session-in-its-own-worktree) |

18321983| Multiple sessions | Separate terminals | Sidebar tabs |

1833| Recurring tasks | Cron jobs, CI pipelines | [Scheduled tasks](/docs/en/desktop-scheduled-tasks.md) |

1834| Computer use | [Enable via `/mcp`](/docs/en/computer-use) on macOS | [App and screen control](#let-claude-use-your-computer) on macOS and Windows |

1835| iOS simulator | Drive the simulator via [computer use](/docs/en/computer-use.md#test-a-simulator-flow) | [iOS Simulator pane](/docs/en/desktop-ios-simulator.md) opens automatically |

1984| Recurring tasks | Cron jobs, CI pipelines | [Scheduled tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks.md) |

1985| Computer use | [Enable via `/mcp`](https://code.claude.com/docs/en/computer-use) on macOS | [App and screen control](#let-claude-use-your-computer) on macOS and Windows |

1986| iOS simulator | Drive the simulator via [computer use](https://code.claude.com/docs/en/computer-use.md#test-a-simulator-flow) | [iOS Simulator pane](https://code.claude.com/docs/en/desktop-ios-simulator.md) opens automatically |

18361987| Dispatch integration | Not available | [Dispatch sessions](#sessions-from-dispatch) in the sidebar |

1837| Scripting and automation | [`--print`](/docs/en/cli-reference), [Agent SDK](/docs/en/headless.md) | Not available |

1988| Scripting and automation | [`--print`](https://code.claude.com/docs/en/cli-reference), [Agent SDK](https://code.claude.com/docs/en/headless.md) | Not available |

18381989

18391990### What's not available in Desktop

18401991

18411992The following features aren't available in Desktop, except where noted:

18421993

18431994* **Third-party providers**: Desktop connects to Anthropic's API by default. To route Desktop through a gateway, or to run the Code tab on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or a self-hosted LLM gateway, follow the links in the [Third-party providers row](#feature-comparison).

1844* **Linux (beta)**: Computer Use isn't yet available in the Linux desktop app. See [Claude Desktop on Linux](/docs/en/desktop-linux.md).

1995* **Linux (beta)**: Computer Use isn't yet available in the Linux desktop app. See [Claude Desktop on Linux](https://code.claude.com/docs/en/desktop-linux.md).

18451996* **Inline code suggestions**: Desktop doesn't offer autocomplete-style code completions. It works through conversational prompts and explicit code changes, and can [suggest your next prompt](#accept-a-suggested-prompt) after Claude replies.

1846* **Agent teams**: coordinated teams, where Claude as the team lead assigns tasks to teammates from a shared task list, are available in the [CLI](/docs/en/agent-teams.md), not in Desktop. For multi-agent work inside one session, use [dynamic workflows](/docs/en/workflows.md), which run in Desktop; Claude can also [message and manage your other sessions](#work-across-sessions) directly.

1847* **Terminal-dialog commands**: built-in commands that open an interactive panel in the terminal behave differently in the Code tab. Edit [settings files](/docs/en/settings.md) directly to manage permission rules and configuration, or run the commands from the standalone CLI.

1997* **Agent teams**: coordinated teams, where Claude as the team lead assigns tasks to teammates from a shared task list, are available in the [CLI](https://code.claude.com/docs/en/agent-teams.md), not in Desktop. For multi-agent work inside one session, use [dynamic workflows](https://code.claude.com/docs/en/workflows.md), which run in Desktop; Claude can also [message and manage your other sessions](#work-across-sessions) directly.

1998* **Terminal-dialog commands**: built-in commands that open an interactive panel in the terminal behave differently in the Code tab. Edit [settings files](https://code.claude.com/docs/en/settings.md) directly to manage permission rules and configuration, or run the commands from the standalone CLI.

18481999 * Commands with no argument form, such as `/permissions`, reply with `isn't available in this environment`.

18492000 * `/config` opens **Settings > Claude Code**.

18502001

18512002## Troubleshooting

18522003

1853The sections below cover issues specific to the desktop app. For runtime API errors that appear in the chat such as `API Error: 500`, `529 Overloaded`, `429`, or `Prompt is too long`, see the [Error reference](/docs/en/errors.md).

2004The sections below cover issues specific to the desktop app. For runtime API errors that appear in the chat such as `API Error: 500`, `529 Overloaded`, `429`, or `Prompt is too long`, see the [Error reference](https://code.claude.com/docs/en/errors.md).

18542005

18552006### Check your version

18562007

from line 2025

18742025If a new session has no [environment selector](#start-a-session) under the prompt box, you have the earlier layout:

18752026

18762027* **[Desktop older than v2.37337.0](#check-your-version)**: update to get the current layout. Select **Claude > Check for Updates…** on macOS or **Help > Check for Updates…** on Windows.

1877* **[Third-party provider](/docs/en/third-party-integrations.md) with sessions on your computer**: the current layout requires Claude Desktop v3.1623.0 or later, so [check your version](#check-your-version). To update, select **Claude > Check for Updates…** on macOS or **Help > Check for Updates…** on Windows. If your organization [turns off auto-updates](#device-management-policies), **Check for Updates…** is hidden, so ask your administrator for v3.1623.0 or later.

2028* **[Third-party provider](https://code.claude.com/docs/en/third-party-integrations.md) with sessions on your computer**: the current layout requires Claude Desktop v3.1623.0 or later, so [check your version](#check-your-version). To update, select **Claude > Check for Updates…** on macOS or **Help > Check for Updates…** on Windows. If your organization [turns off auto-updates](#device-management-policies), **Check for Updates…** is hidden, so ask your administrator for v3.1623.0 or later.

18782029* **Third-party provider with sessions on your organization's infrastructure**: when your organization runs sessions on its own infrastructure rather than on your computer, Desktop keeps the earlier layout, and updating doesn't change the layout. If you don't know where your sessions run, ask your administrator.

18792030

18802031In the earlier layout, choose the environment and project folder above the prompt box, and the permission mode and model in the row under it. The earlier layout lacks the [session details panel](#see-session-details) and [saved local and SSH environments](#create-a-saved-environment).

from line 2044

18932044If the app opens but shows a blank or unresponsive screen:

18942045

189520461. Restart the app.

18962. Check for pending updates. On macOS and Windows the app auto-updates on launch; on Linux, update through apt as described in [Claude Desktop on Linux](/docs/en/desktop-linux.md).

20472. Check for pending updates. On macOS and Windows the app auto-updates on launch; on Linux, update through apt as described in [Claude Desktop on Linux](https://code.claude.com/docs/en/desktop-linux.md).

189720483. On a managed network, confirm your firewall allows the CDN hosts in [network access requirements](#network-access-requirements).

189820494. On Windows, check Event Viewer for crash logs under **Windows Logs → Application**.

18992050

19002051

desktop-ios-simulator Changed · +10 / -10 lines

from line 8

99The iOS Simulator pane shows your app running in Apple's iOS Simulator next to your conversation in Claude Code Desktop. When Claude builds, installs, launches, or checks your app in a simulator, the pane opens automatically and streams the device screen live. Use it to watch Claude run and test your app, or to tap through the app yourself while Claude keeps working.

1010

11The simulator pane drives the simulator directly, so it doesn't need [computer use](/docs/en/desktop.md#let-claude-use-your-computer) and never takes over your screen or hides your other windows. From the CLI, Claude reaches the iOS Simulator through [computer use](/docs/en/computer-use.md#test-a-simulator-flow) instead, which controls the simulator on your screen the same way you would with a mouse.

11The simulator pane drives the simulator directly, so it doesn't need [computer use](https://code.claude.com/docs/en/desktop.md#let-claude-use-your-computer) and never takes over your screen or hides your other windows. From the CLI, Claude reaches the iOS Simulator through [computer use](https://code.claude.com/docs/en/computer-use.md#test-a-simulator-flow) instead, which controls the simulator on your screen the same way you would with a mouse.

1212

1313## Requirements

1414

from line 23

2323>

2424> On this page, "device" refers to a simulated iPhone or iPad, one of the same simulator devices you manage in Xcode under **Window → Devices and Simulators**, not physical hardware.

2525

26The simulator pane is available in local sessions only. In [cloud](/docs/en/desktop.md#run-long-running-tasks-in-the-cloud) and [SSH](/docs/en/desktop.md#ssh-sessions) sessions, Claude runs on a machine that can't reach the simulators on your Mac.

26The simulator pane is available in local sessions only. In [cloud](https://code.claude.com/docs/en/desktop.md#run-long-running-tasks-in-the-cloud) and [SSH](https://code.claude.com/docs/en/desktop.md#ssh-sessions) sessions, Claude runs on a machine that can't reach the simulators on your Mac.

2727

2828### Choose which Xcode the simulator pane uses

2929

from line 45

4545

4646**1. Open your iOS project**

4747

48In Claude Code Desktop, open the **Code** tab and start a session with your app's project as the [project folder](/docs/en/desktop.md#start-a-session). Any project that builds an app for the iOS Simulator works.

48In Claude Code Desktop, open the **Code** tab and start a session with your app's project as the [project folder](https://code.claude.com/docs/en/desktop.md#start-a-session). Any project that builds an app for the iOS Simulator works.

4949

5050**2. Ask Claude to run or test the app**

5151

from line 84

8484

8585## How sessions manage devices

8686

87Each device belongs to the session that launched it, so [parallel sessions](/docs/en/desktop.md#work-in-parallel-with-sessions) don't share a device: what you see in one session's pane reflects that session's work, not another's. Switching sessions in the sidebar switches the simulator view along with the conversation, and switching back resumes the same device where it left off. If Claude works with more than one device, each opens its own pane, up to 4 per session.

87Each device belongs to the session that launched it, so [parallel sessions](https://code.claude.com/docs/en/desktop.md#work-in-parallel-with-sessions) don't share a device: what you see in one session's pane reflects that session's work, not another's. Switching sessions in the sidebar switches the simulator view along with the conversation, and switching back resumes the same device where it left off. If Claude works with more than one device, each opens its own pane, up to 4 per session.

8888

8989Claude Code Desktop shuts down the simulators it booted once they're no longer in use: when you quit the app, when you archive the session, or 10 minutes after you detach a device from its pane. Devices you boot outside Claude Code Desktop, such as in Apple's Simulator app or in Device Hub, are never shut down automatically. To shut down the attached device right away, use the shutdown button in the pane.

9090

from line 102

102102

103103### Actions that follow your permission mode

104104

105Two actions follow your session's [permission mode](/docs/en/permissions.md#permission-modes) instead of the one-time consent:

105Two actions follow your session's [permission mode](https://code.claude.com/docs/en/permissions.md#permission-modes) instead of the one-time consent:

106106

107107* Opening a URL on the device, for example to test a deep link or load a page in the device's Safari, because a URL can carry data off the device.

108108* Building the app, because `xcodebuild` runs your project's build scripts on your Mac. Checking on a build already in progress doesn't prompt.

from line 111

111111

112112You can turn Claude's simulator access off in the desktop app's settings. Organizations have two ways to turn it off for everyone:

113113

114* The `disableMobileSimulatorTools` [managed setting](/docs/en/desktop.md#managed-settings) blocks Claude's simulator tools. The simulator pane stays usable for your own taps, and the setting can't be overridden from within the app.

114* The `disableMobileSimulatorTools` [managed setting](https://code.claude.com/docs/en/desktop.md#managed-settings) blocks Claude's simulator tools. The simulator pane stays usable for your own taps, and the setting can't be overridden from within the app.

115115* The `requireCoworkFullVmSandbox` policy key, which runs Claude's tools inside an isolated virtual machine instead of on your Mac, disables the simulator pane and Claude's simulator tools entirely, so the pane can't attach a device while it's set.

116116

117117Claude tells you when either applies.

from line 138

138138

139139## See also

140140

141* [Computer use in Desktop](/docs/en/desktop.md#let-claude-use-your-computer): screen control for apps without a dedicated pane

142* [Computer use from the CLI](/docs/en/computer-use.md): how the CLI reaches the iOS Simulator

143* [Run a session in its own worktree](/docs/en/desktop.md#run-a-session-in-its-own-worktree): how sessions isolate changes

144* [Get started with Claude Code Desktop](/docs/en/desktop-quickstart.md)

141* [Computer use in Desktop](https://code.claude.com/docs/en/desktop.md#let-claude-use-your-computer): screen control for apps without a dedicated pane

142* [Computer use from the CLI](https://code.claude.com/docs/en/computer-use.md): how the CLI reaches the iOS Simulator

143* [Run a session in its own worktree](https://code.claude.com/docs/en/desktop.md#run-a-session-in-its-own-worktree): how sessions isolate changes

144* [Get started with Claude Code Desktop](https://code.claude.com/docs/en/desktop-quickstart.md)

145145

desktop-linux Changed · +6 / -6 lines

from line 6

66>

77> Linux support for the Claude desktop app is in beta.

9The desktop app on Linux gives you the same Chat, Cowork, and Claude Code experience as on macOS and Windows: parallel sessions, visual diff review, an integrated terminal and editor, and live app preview. See [Use Claude Code Desktop](/docs/en/desktop.md) for the feature reference.

1010

1111## Requirements

1212

from line 13

1313* A Debian-based distribution: Ubuntu 22.04 or later, or Debian 12 or later

1414* x86\_64 or arm64

1515

16Other Debian-based distributions that meet these requirements may work but aren't officially tested. On distributions that aren't Debian-based, such as Fedora or Arch, run the [CLI](/docs/en/setup.md#system-requirements) instead. If you work on Windows with WSL 2, install the Windows desktop app and run sessions inside your distribution; see [Claude Code Desktop in WSL](/docs/en/desktop-wsl.md).

16Other Debian-based distributions that meet these requirements may work but aren't officially tested. On distributions that aren't Debian-based, such as Fedora or Arch, run the [CLI](https://code.claude.com/docs/en/setup.md#system-requirements) instead. If you work on Windows with WSL 2, install the Windows desktop app and run sessions inside your distribution; see [Claude Code Desktop in WSL](https://code.claude.com/docs/en/desktop-wsl.md).

1717

1818### Cowork requirements

1919

from line 67

6767

6868Launch **Claude** from your application launcher, or run `claude-desktop` from a terminal, and sign in with your Anthropic account.

6969

70The Linux app signs in the same way as on macOS and Windows: with a claude.ai subscription, or through your organization's SSO. For API-key authentication, use the [CLI](/docs/en/quickstart.md). To use Desktop with Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an LLM gateway instead, see [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview). For proxy servers and custom certificate authorities in those deployments, see [network configuration](/docs/en/network-config.md).

70The Linux app signs in the same way as on macOS and Windows: with a claude.ai subscription, or through your organization's SSO. For API-key authentication, use the [CLI](https://code.claude.com/docs/en/quickstart.md). To use Desktop with Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an LLM gateway instead, see [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview). For proxy servers and custom certificate authorities in those deployments, see [network configuration](https://code.claude.com/docs/en/network-config.md).

7171

7272### Install from a downloaded file

7373

from line 158

158158

159159## What's not in the Linux beta yet

160160

161* **Computer Use**: [app and screen control](/docs/en/desktop.md#let-claude-use-your-computer) isn't available on Linux.

162* **Dictation**: voice input isn't available in the Linux desktop app. Use [voice dictation](/docs/en/voice-dictation.md) in the CLI instead.

161* **Computer Use**: [app and screen control](https://code.claude.com/docs/en/desktop.md#let-claude-use-your-computer) isn't available on Linux.

162* **Dictation**: voice input isn't available in the Linux desktop app. Use [voice dictation](https://code.claude.com/docs/en/voice-dictation.md) in the CLI instead.

163163* **Quick Entry global hotkey**: works on X11. On native Wayland it requires your desktop environment's GlobalShortcuts portal.

164164* **Fedora and RHEL**: only Debian-based distributions are supported today. Support for additional distributions is coming in the future.

165165

166For anything not yet available in the desktop app, the [CLI](/docs/en/quickstart.md) runs the same Claude Code engine and supports a wider range of Linux distributions; see the [system requirements](/docs/en/setup.md#system-requirements).

166For anything not yet available in the desktop app, the [CLI](https://code.claude.com/docs/en/quickstart.md) runs the same Claude Code engine and supports a wider range of Linux distributions; see the [system requirements](https://code.claude.com/docs/en/setup.md#system-requirements).

167167

desktop-quickstart Changed · +31 / -31 lines

from line 14

1414>

1515> For x64 processors

1616

17> **[Get Claude for Linux (beta)](/docs/en/desktop-linux.md)**

17> **[Get Claude for Linux (beta)](https://code.claude.com/docs/en/desktop-linux.md)**

1818>

1919> apt or .deb for Ubuntu and Debian

2020

21For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](/docs/en/desktop-linux.md).

2222

2323> [!NOTE]

2424>

2525> These cases are covered on other pages:

2626>

27> * **Already set up**: see [Use Claude Code Desktop](/docs/en/desktop.md) for everything the Code tab can do

28> * **Want `claude` in your terminal**: [install the CLI](/docs/en/quickstart.md) separately

27> * **Already set up**: see [Use Claude Code Desktop](https://code.claude.com/docs/en/desktop.md) for everything the Code tab can do

28> * **Want `claude` in your terminal**: [install the CLI](https://code.claude.com/docs/en/quickstart.md) separately

2929> * **Using chat or Cowork**: see the [Claude Help Center](https://support.claude.com/)

3030> * **Need more on installing or deploying the desktop app**: see the [Claude Desktop support articles](https://support.claude.com/en/collections/16163169-claude-desktop)

3131

from line 33

3333

3434**1. Install and sign in**

3535

36On macOS and Windows, download the installer from the links above and run it. On Linux, follow the install steps in [Claude Desktop on Linux](/docs/en/desktop-linux.md). Launch Claude from your Applications folder on macOS, the Start menu on Windows, or your application launcher on Linux, then sign in with your Anthropic account.

36On macOS and Windows, download the installer from the links above and run it. On Linux, follow the install steps in [Claude Desktop on Linux](https://code.claude.com/docs/en/desktop-linux.md). Launch Claude from your Applications folder on macOS, the Start menu on Windows, or your application launcher on Linux, then sign in with your Anthropic account.

3737

3838**2. Open the Code tab**

3939

from line 41

4141

4242* **Prompt to upgrade**: you need to [subscribe to a paid plan](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_upgrade) first

4343* **Prompt to sign in online**: complete the sign-in and restart the app

44* **403 error**: see [authentication troubleshooting](/docs/en/desktop.md#403-or-authentication-errors-in-the-code-tab)

44* **403 error**: see [authentication troubleshooting](https://code.claude.com/docs/en/desktop.md#403-or-authentication-errors-in-the-code-tab)

4545

4646The desktop app includes Claude Code, so you don't need to install Node.js or the CLI to use the Code tab.

4747

from line 51

5151

5252**1. Choose an environment and folder**

5353

54In the [row under the prompt box](/docs/en/desktop.md#start-a-session), click the first control, the environment selector, and select the top entry in the **Local** group. Then click the project folder control beside the environment selector, select **Open folder…**, and choose your project's directory.

54In the [row under the prompt box](https://code.claude.com/docs/en/desktop.md#start-a-session), click the first control, the environment selector, and select the top entry in the **Local** group. Then click the project folder control beside the environment selector, select **Open folder…**, and choose your project's directory.

5555

56If no environment selector appears under your prompt box, you have the earlier layout. See [Check which layout you have](/docs/en/desktop.md#check-which-layout-you-have).

56If no environment selector appears under your prompt box, you have the earlier layout. See [Check which layout you have](https://code.claude.com/docs/en/desktop.md#check-which-layout-you-have).

5757

5858> [!TIP]

5959>

from line 61

6161

6262You can also select:

6363

64* **Cloud**: Run sessions in the cloud that continue even if you close the app. See [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web.md) for how cloud sessions work.

65* **SSH**: Connect to a remote machine over SSH, such as your own servers, cloud VMs, or dev containers. [Add a connection](/docs/en/desktop.md#ssh-sessions) first. Desktop installs Claude Code on the remote machine automatically the first time you connect. A running task can [keep going while Desktop is disconnected](/docs/en/desktop.md#keep-a-task-running-while-desktop-is-disconnected), but with a Claude account it can stop when its sign-in expires.

66* **WSL** (Windows): Run the session inside a [WSL 2 distribution](/docs/en/desktop-wsl.md); Claude Code, tools, and git execute on the Linux side with native paths.

64* **Cloud**: Run sessions in the cloud that continue even if you close the app. See [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md) for how cloud sessions work.

65* **SSH**: Connect to a remote machine over SSH, such as your own servers, cloud VMs, or dev containers. [Add a connection](https://code.claude.com/docs/en/desktop.md#ssh-sessions) first. Desktop installs Claude Code on the remote machine automatically the first time you connect. A running task can [keep going while Desktop is disconnected](https://code.claude.com/docs/en/desktop.md#keep-a-task-running-while-desktop-is-disconnected), but with a Claude account it can stop when its sign-in expires.

66* **WSL** (Windows): Run the session inside a [WSL 2 distribution](https://code.claude.com/docs/en/desktop-wsl.md); Claude Code, tools, and git execute on the Linux side with native paths.

6767

6868**2. Choose a model**

6969

70Select a model from the model picker toward the right end of the row under the prompt box. See [models](/docs/en/model-config.md#available-models) for a comparison of the available models. You can change the model later from the model picker.

70Select a model from the model picker toward the right end of the row under the prompt box. See [models](https://code.claude.com/docs/en/model-config.md#available-models) for a comparison of the available models. You can change the model later from the model picker.

7171

7272**3. Tell Claude what to do**

7373

from line 77

7777* `Add tests for the main function`

7878* `Create a CLAUDE.md with instructions for this codebase`

7979

80A [session](/docs/en/desktop.md#work-in-parallel-with-sessions) is a conversation with Claude about your code. Each session tracks its own context and changes.

80A [session](https://code.claude.com/docs/en/desktop.md#work-in-parallel-with-sessions) is a conversation with Claude about your code. Each session tracks its own context and changes.

8181

8282**4. Review and accept changes**

8383

84Check your [permission mode](/docs/en/desktop.md#choose-a-permission-mode) in the row under the prompt box to see whether Claude waits for your approval:

84Check your [permission mode](https://code.claude.com/docs/en/desktop.md#choose-a-permission-mode) in the row under the prompt box to see whether Claude waits for your approval:

8585

86* **Auto or Accept edits**: Claude applies its file changes, and an indicator such as `+12 -1` appears so you can review them in the [diff view](/docs/en/desktop.md#review-changes-with-diff-view)

86* **Auto or Accept edits**: Claude applies its file changes, and an indicator such as `+12 -1` appears so you can review them in the [diff view](https://code.claude.com/docs/en/desktop.md#review-changes-with-diff-view)

8787* **Manual**: Claude proposes each change and waits for your approval before applying it

8888

8989In Manual mode, you'll see:

from line 94

9494

9595## Now what?

9696

97You've made your first edit. For the full reference on everything Desktop can do, see [Use Claude Code Desktop](/docs/en/desktop.md). Here are some things to try next.

97You've made your first edit. For the full reference on everything Desktop can do, see [Use Claude Code Desktop](https://code.claude.com/docs/en/desktop.md). Here are some things to try next.

9898

9999**Interrupt and steer.** You can redirect Claude at any point. Click the stop button to interrupt immediately, or type a correction and press **Enter** to send it without stopping the running action. Either way, you don't have to wait for it to finish or start over.

100100

101**Give Claude more context.** Type `@filename` in the prompt box to pull a specific file into the conversation. The more context Claude has, the better the results. See [Add files and context](/docs/en/desktop.md#add-files-and-context-to-prompts).

101**Give Claude more context.** Type `@filename` in the prompt box to pull a specific file into the conversation. The more context Claude has, the better the results. See [Add files and context](https://code.claude.com/docs/en/desktop.md#add-files-and-context-to-prompts).

102102

103**Use skills for repeatable tasks.** Type `/` or click **+** → **Slash commands** to browse [built-in commands](/docs/en/commands.md), [custom skills](/docs/en/skills.md), and plugin skills. Skills are reusable prompts you can invoke whenever you need them, like code review checklists or deployment steps.

103**Use skills for repeatable tasks.** Type `/` or click **+** → **Slash commands** to browse [built-in commands](https://code.claude.com/docs/en/commands.md), [custom skills](https://code.claude.com/docs/en/skills.md), and plugin skills. Skills are reusable prompts you can invoke whenever you need them, like code review checklists or deployment steps.

104104

105**Review changes before committing.** After Claude edits files, a `+12 -1` indicator appears. Click it to open the [diff view](/docs/en/desktop.md#review-changes-with-diff-view), review modifications file by file, and comment on specific lines. Claude reads your comments and revises. To have Claude review the changes itself, enter [`/code-review`](/docs/en/desktop#review-your-code) in the prompt box.

105**Review changes before committing.** After Claude edits files, a `+12 -1` indicator appears. Click it to open the [diff view](https://code.claude.com/docs/en/desktop.md#review-changes-with-diff-view), review modifications file by file, and comment on specific lines. Claude reads your comments and revises. To have Claude review the changes itself, enter [`/code-review`](https://code.claude.com/docs/en/desktop#review-your-code) in the prompt box.

106106

107**Adjust how much control you have.** Your [permission mode](/docs/en/desktop.md#choose-a-permission-mode) sets how much Claude can do without asking for approval:

107**Adjust how much control you have.** Your [permission mode](https://code.claude.com/docs/en/desktop.md#choose-a-permission-mode) sets how much Claude can do without asking for approval:

108108

109109* **Auto**: a classifier reviews actions in the background and blocks the risky ones instead of asking you.

110110* **Manual**: Claude asks before editing files or running commands.

from line 111

111111* **Accept edits**: Claude auto-accepts file edits for faster iteration.

112112* **Plan**: Claude proposes an approach without editing any files, which is useful before a large refactor.

113113

114**Add plugins for more capabilities.** Install [plugins](/docs/en/desktop.md#install-plugins) that add skills, agents, MCP servers, and more.

114**Add plugins for more capabilities.** Install [plugins](https://code.claude.com/docs/en/desktop.md#install-plugins) that add skills, agents, MCP servers, and more.

115115

116**Arrange your workspace.** Drag the chat, diff, terminal, file, and browser panes into whatever layout you want. Open the terminal with **Ctrl+\`** to run commands alongside your session, or click a file path to open it. See [Arrange your workspace](/docs/en/desktop.md#arrange-your-workspace).

117117

118**Preview your app.** When you run your dev server in the desktop, your app opens in the Browser pane, which can also [open external sites](/docs/en/desktop.md#browse-external-sites). Claude can view the running app, test endpoints, inspect logs, and iterate on what it sees. See [Preview your app](/docs/en/desktop.md#preview-your-app).

118**Preview your app.** When you run your dev server in the desktop, your app opens in the Browser pane, which can also [open external sites](https://code.claude.com/docs/en/desktop.md#browse-external-sites). Claude can view the running app, test endpoints, inspect logs, and iterate on what it sees. See [Preview your app](https://code.claude.com/docs/en/desktop.md#preview-your-app).

119119

120**Track your pull request.** After opening a PR, Claude Code monitors CI check results and can automatically fix failures. See [Monitor pull request status](/docs/en/desktop.md#monitor-pull-request-status).

120**Track your pull request.** After opening a PR, Claude Code monitors CI check results and can automatically fix failures. See [Monitor pull request status](https://code.claude.com/docs/en/desktop.md#monitor-pull-request-status).

121121

122**Put Claude on a schedule.** Set up [scheduled tasks](/docs/en/desktop-scheduled-tasks.md) to run Claude automatically on a recurring basis: a daily code review every morning, a weekly dependency audit, or a briefing that pulls from your connected tools.

122**Put Claude on a schedule.** Set up [scheduled tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks.md) to run Claude automatically on a recurring basis: a daily code review every morning, a weekly dependency audit, or a briefing that pulls from your connected tools.

123123

124**Scale up when you're ready.** Open [parallel sessions](/docs/en/desktop.md#work-in-parallel-with-sessions) from the sidebar to work on multiple tasks at once, optionally each in its own Git worktree, and open the [tasks pane](/docs/en/desktop.md#watch-background-tasks) to watch the subagents and background commands a session has running. Open a [side chat](/docs/en/desktop.md#ask-a-side-question-without-derailing-the-session) to ask a question without derailing the main thread. Send [long-running work to the cloud](/docs/en/desktop.md#run-long-running-tasks-in-the-cloud) so it continues even if you close the app, or [move a session you already started to the cloud](/docs/en/desktop.md#continue-in-another-surface) if a task takes longer than expected. [Connect external tools](/docs/en/desktop.md#extend-claude-code) like GitHub, Slack, and Linear to bring your workflow together.

124**Scale up when you're ready.** Open [parallel sessions](https://code.claude.com/docs/en/desktop.md#work-in-parallel-with-sessions) from the sidebar to work on multiple tasks at once, optionally each in its own Git worktree, and open the [tasks pane](https://code.claude.com/docs/en/desktop.md#watch-background-tasks) to watch the subagents and background commands a session has running. Open a [side chat](https://code.claude.com/docs/en/desktop.md#ask-a-side-question-without-derailing-the-session) to ask a question without derailing the main thread. Send [long-running work to the cloud](https://code.claude.com/docs/en/desktop.md#run-long-running-tasks-in-the-cloud) so it continues even if you close the app, or [move a session you already started to the cloud](https://code.claude.com/docs/en/desktop.md#continue-in-another-surface) if a task takes longer than expected. [Connect external tools](https://code.claude.com/docs/en/desktop.md#extend-claude-code) like GitHub, Slack, and Linear to bring your workflow together.

125125

126126## What's next

127127

128* [Use Claude Code Desktop](/docs/en/desktop.md): permission modes, parallel sessions, diff view, connectors, and enterprise configuration

129* [Coming from the CLI?](/docs/en/desktop.md#coming-from-the-cli): run Desktop and the CLI on the same project, and compare features, flag equivalents, and what's not available in Desktop

130* [Troubleshooting](/docs/en/desktop.md#troubleshooting): solutions to common errors and setup issues

131* [Best practices](/docs/en/best-practices.md): tips for writing effective prompts and getting the most out of Claude Code

132* [Common workflows](/docs/en/common-workflows.md): tutorials for debugging, refactoring, testing, and more

128* [Use Claude Code Desktop](https://code.claude.com/docs/en/desktop.md): permission modes, parallel sessions, diff view, connectors, and enterprise configuration

129* [Coming from the CLI?](https://code.claude.com/docs/en/desktop.md#coming-from-the-cli): run Desktop and the CLI on the same project, and compare features, flag equivalents, and what's not available in Desktop

130* [Troubleshooting](https://code.claude.com/docs/en/desktop.md#troubleshooting): solutions to common errors and setup issues

131* [Best practices](https://code.claude.com/docs/en/best-practices.md): tips for writing effective prompts and getting the most out of Claude Code

132* [Common workflows](https://code.claude.com/docs/en/common-workflows.md): tutorials for debugging, refactoring, testing, and more

133133

desktop-scheduled-tasks Changed · +21 / -21 lines

from line 4

55Scheduled tasks start a new session automatically at a time and frequency you choose. Use them for recurring work like daily code reviews, dependency update checks, or morning briefings that pull from your calendar and inbox.

7The Desktop app's **Scheduled tasks** page lists both local scheduled tasks and [cloud scheduled tasks](/docs/en/routines.md), formerly routines:

7The Desktop app's **Scheduled tasks** page lists both local scheduled tasks and [cloud scheduled tasks](https://code.claude.com/docs/en/routines.md), formerly routines:

99* **Local task**: runs on your machine with direct access to your files and tools, but only fires while the app is open and your computer is awake

1010* **Cloud task**: runs even when your computer is off, and can also start on API calls or GitHub events

1111

12This page covers local scheduled tasks; for cloud scheduled tasks and their trigger options, see [Automate work with scheduled tasks](/docs/en/routines.md).

12This page covers local scheduled tasks; for cloud scheduled tasks and their trigger options, see [Automate work with scheduled tasks](https://code.claude.com/docs/en/routines.md).

1313

1414## Compare scheduling options

1515

1616Claude Code offers three ways to schedule recurring or one-off work:

1717

18| | [Cloud](https://code.claude.com/docs/en/routines.md) | [Desktop](https://code.claude.com/docs/en/desktop-scheduled-tasks.md) | [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) |

1919| :- | :- | :- | :- |

2121| Requires machine on | No | Yes | Yes |

2222| Requires open session | No | No | Yes |

23| Persistent across restarts | Yes | Yes | Restored on `--resume`, with [exceptions](/docs/en/scheduled-tasks.md#limitations) |

23| Persistent across restarts | Yes | Yes | Restored on `--resume`, with [exceptions](https://code.claude.com/docs/en/scheduled-tasks.md#limitations) |

2424| Access to local files | No (fresh clone) | Yes | Yes |

2727| Customizable schedule | Yes | Yes | Yes |

2929

3030> [!TIP]

3131>

from line 33

3333

3434> [!NOTE]

3535>

36> By default, local scheduled tasks run against whatever state your working directory is in, including uncommitted changes. To give each run its own [isolated Git worktree](/docs/en/desktop.md#run-a-session-in-its-own-worktree) instead, select **Worktree** in the task's [**Edit** form](#manage-scheduled-tasks) after you create it. The checkbox is available when the task's folder is a Git repository.

36> By default, local scheduled tasks run against whatever state your working directory is in, including uncommitted changes. To give each run its own [isolated Git worktree](https://code.claude.com/docs/en/desktop.md#run-a-session-in-its-own-worktree) instead, select **Worktree** in the task's [**Edit** form](#manage-scheduled-tasks) after you create it. The checkbox is available when the task's folder is a Git repository.

3737

3838## Create a scheduled task

3939

from line 41

4141

4242**1. Open the Scheduled tasks page**

4343

44In the [**Code** tab](/docs/en/desktop.md), click **Scheduled** in the sidebar or in the sidebar's **More** menu.

44In the [**Code** tab](https://code.claude.com/docs/en/desktop.md), click **Scheduled** in the sidebar or in the sidebar's **More** menu.

4545

4646**2. Start a new task**

4747

from line 59

5959

6060Skip past the **Trigger** card for now and expand **Advanced settings** below it. On the **General** tab, turn on **Only on this computer**. With it on, the task runs on your machine in a local folder.

6161

62If the switch is unavailable, clear the repository or the GitHub event or API trigger, because those make the task a [cloud scheduled task](/docs/en/routines.md).

62If the switch is unavailable, clear the repository or the GitHub event or API trigger, because those make the task a [cloud scheduled task](https://code.claude.com/docs/en/routines.md).

6363

6464**6. Pick the local folder**

6565

from line 116

116116

117117> [!NOTE]

118118>

119> For tasks that need to run even when your computer is off, or that should trigger on an API call or GitHub event, create a [cloud scheduled task](/docs/en/routines.md) instead.

119> For tasks that need to run even when your computer is off, or that should trigger on an API call or GitHub event, create a [cloud scheduled task](https://code.claude.com/docs/en/routines.md) instead.

120120

121121### Find a run's session

122122

123123To open the session a run started, go to the task's [detail page](#manage-scheduled-tasks) and click that run's row in the **History** list.

124124

125The sidebar's session list can show a **Scheduled** group as well, with one row per task. To open the session of a task's latest run, click the task's row in that group. To show the group, [check which layout you have](/docs/en/desktop.md#check-which-layout-you-have):

126126

127* **Current layout**: open the [**Group and sort** menu](/docs/en/desktop.md#organize-and-find-sessions), select **Show**, then select **Scheduled**. The group starts collapsed, so click its heading to expand it. **Show** lists **Scheduled** when at least one of your tasks is **Active**, the **Status** a task's detail page shows. If it isn't listed, use the **History** list, which works whether or not the group shows.

127* **Current layout**: open the [**Group and sort** menu](https://code.claude.com/docs/en/desktop.md#organize-and-find-sessions), select **Show**, then select **Scheduled**. The group starts collapsed, so click its heading to expand it. **Show** lists **Scheduled** when at least one of your tasks is **Active**, the **Status** a task's detail page shows. If it isn't listed, use the **History** list, which works whether or not the group shows.

128128* **Earlier layout**: the group is in the session list with nothing to turn on

129129

130130In a run's session, whichever way you reached it, you can see what Claude did, review changes, and respond to permission prompts. Claude can edit files, run commands, create commits, and open pull requests, the same as in a session you start yourself.

from line 137

137137

138138## Permissions for scheduled tasks

139139

140Each task has its own permission mode, which you set when creating or editing the task. Allow rules from `~/.claude/settings.json` also apply to scheduled task sessions. If a task runs in [Manual mode](/docs/en/desktop.md#choose-a-permission-mode) and needs to run a tool it doesn't have permission for, the run stalls until you approve it. To approve it, [find the run's session](#find-a-runs-session) and answer the permission prompt there.

140Each task has its own permission mode, which you set when creating or editing the task. Allow rules from `~/.claude/settings.json` also apply to scheduled task sessions. If a task runs in [Manual mode](https://code.claude.com/docs/en/desktop.md#choose-a-permission-mode) and needs to run a tool it doesn't have permission for, the run stalls until you approve it. To approve it, [find the run's session](#find-a-runs-session) and answer the permission prompt there.

141141

142142To avoid stalls, click **Run now** after creating a task, watch for permission prompts, and select "always allow" for each one. Future runs of that task auto-approve the same tools without prompting. You can review and revoke these approvals from the task's detail page.

143143

144MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool) prompt on every call and don't offer an always-allow option. Runs that call these tools stall each time.

144MCP tools marked [`requiresUserInteraction`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool) prompt on every call and don't offer an always-allow option. Runs that call these tools stall each time.

145145

146146## Manage scheduled tasks

147147

from line 152

152152* **Edit**: change the instructions, schedule, folder, or other settings

153153* **Review history**: see every past run, including skipped runs. Hover a skipped entry to see why: your computer was asleep, the previous run was still in progress, or other scheduled tasks were already running. Click **Show more** to load older entries.

154154* **Review allowed permissions**: see and revoke saved tool approvals for this task from the **Always allowed** panel

155* **Delete**: remove the task. The sessions the task created are [archived](/docs/en/desktop.md#organize-and-find-sessions), not deleted. The folder holding the task's `SKILL.md` file stays on disk at `~/.claude/scheduled-tasks/<task-name>/`, or at `scheduled-tasks/<task-name>/` under [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars) if you set that variable. To remove that folder, delete it yourself.

155* **Delete**: remove the task. The sessions the task created are [archived](https://code.claude.com/docs/en/desktop.md#organize-and-find-sessions), not deleted. The folder holding the task's `SKILL.md` file stays on disk at `~/.claude/scheduled-tasks/<task-name>/`, or at `scheduled-tasks/<task-name>/` under [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars) if you set that variable. To remove that folder, delete it yourself.

156156

157157You can also list, create, edit, and pause tasks by asking Claude in any Desktop session. For example, "pause my dependency-audit task" or "show me my scheduled tasks." To delete a task, use the **Delete** button on its detail page.

158158

159159A scheduled task can also modify its own schedule or prompt from within a running session using the `update_scheduled_task` MCP tool. This lets a task reschedule itself based on what it finds, for example, rescheduling a code review to run earlier when it detects a release branch has been created.

160160

161To edit a task's prompt on disk, open `~/.claude/scheduled-tasks/<task-name>/SKILL.md` (or under [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars) if set). The file uses YAML frontmatter for `name` and `description`, with the prompt as the body. Changes take effect on the next run. Schedule, folder, model, and enabled state are not in this file: change them through the Edit form or ask Claude.

161To edit a task's prompt on disk, open `~/.claude/scheduled-tasks/<task-name>/SKILL.md` (or under [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars) if set). The file uses YAML frontmatter for `name` and `description`, with the prompt as the body. Changes take effect on the next run. Schedule, folder, model, and enabled state are not in this file: change them through the Edit form or ask Claude.

162162

163163## Related resources

164164

165* [Cloud scheduled tasks](/docs/en/routines.md): run tasks in the cloud on a schedule, via API call, or in response to GitHub events, even when your computer is off

166* [Run prompts on a schedule](/docs/en/scheduled-tasks.md): session-scoped scheduling with `/loop` in the CLI

167* [Claude Code GitHub Actions](/docs/en/github-actions.md): run Claude on a schedule in CI instead of on your machine

168* [Use Claude Code Desktop](/docs/en/desktop.md): the full Desktop app guide

165* [Cloud scheduled tasks](https://code.claude.com/docs/en/routines.md): run tasks in the cloud on a schedule, via API call, or in response to GitHub events, even when your computer is off

166* [Run prompts on a schedule](https://code.claude.com/docs/en/scheduled-tasks.md): session-scoped scheduling with `/loop` in the CLI

167* [Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions.md): run Claude on a schedule in CI instead of on your machine

168* [Use Claude Code Desktop](https://code.claude.com/docs/en/desktop.md): the full Desktop app guide

169169

desktop-wsl Changed · +7 / -7 lines

from line 16

1616

1717**1. Pick a distribution**

1818

19Start a new session in the Code tab and open the [environment selector](/docs/en/desktop.md#start-a-session) under the prompt box, or above it in the [earlier layout](/docs/en/desktop.md#check-which-layout-you-have). Your installed WSL 2 distributions appear under **WSL**. Pick one.

19Start a new session in the Code tab and open the [environment selector](https://code.claude.com/docs/en/desktop.md#start-a-session) under the prompt box, or above it in the [earlier layout](https://code.claude.com/docs/en/desktop.md#check-which-layout-you-have). Your installed WSL 2 distributions appear under **WSL**. Pick one.

2020

2121**2. Choose a folder**

2222

from line 34

3434

3535If a Desktop feature is unavailable or limited in a WSL session, check whether it's one of these:

3636

37* **Terminal and connectors**: your session may lack the [integrated terminal](/docs/en/desktop.md#run-commands-in-the-terminal), [connectors](/docs/en/desktop.md#connect-external-tools), or both. See [If the terminal or connectors are unavailable](#check-for-the-terminal-and-connectors).

38* **[Plugins](/docs/en/desktop.md#install-plugins)**: not available in WSL sessions

39* **File editing**: you can view files in the [file pane](/docs/en/desktop.md#open-and-edit-files) but can't edit them there, so ask Claude to make the changes

40* **Attachments**: if the **+** menu shows **Add image** in place of **Add files or photos**, you can attach only images. See [Add files and context to prompts](/docs/en/desktop.md#add-files-and-context-to-prompts).

37* **Terminal and connectors**: your session may lack the [integrated terminal](https://code.claude.com/docs/en/desktop.md#run-commands-in-the-terminal), [connectors](https://code.claude.com/docs/en/desktop.md#connect-external-tools), or both. See [If the terminal or connectors are unavailable](#check-for-the-terminal-and-connectors).

38* **[Plugins](https://code.claude.com/docs/en/desktop.md#install-plugins)**: not available in WSL sessions

39* **File editing**: you can view files in the [file pane](https://code.claude.com/docs/en/desktop.md#open-and-edit-files) but can't edit them there, so ask Claude to make the changes

40* **Attachments**: if the **+** menu shows **Add image** in place of **Add files or photos**, you can attach only images. See [Add files and context to prompts](https://code.claude.com/docs/en/desktop.md#add-files-and-context-to-prompts).

4141

4242### If the terminal or connectors are unavailable

4343

from line 44

4444You can't turn on the integrated terminal or connectors for a WSL session yourself:

4545

4646* **Claude account**: the two features are rolling out separately. Select **Help > Check for Updates…**, and if a feature is still missing after you update, there's nothing to do.

47* **[Third-party provider](/docs/en/third-party-integrations.md)**: WSL sessions don't get the terminal or connectors, and updating Desktop doesn't change that

47* **[Third-party provider](https://code.claude.com/docs/en/third-party-integrations.md)**: WSL sessions don't get the terminal or connectors, and updating Desktop doesn't change that

4848

4949## Managed devices

5050

51On devices managed by an organization, WSL sessions may be unavailable. If session start fails with a message that the device is managed, that's controlled by your administrator. Administrators: see [how settings reach devices](/docs/en/admin-setup.md#decide-how-settings-reach-devices) in the deployment guide.

51On devices managed by an organization, WSL sessions may be unavailable. If session start fails with a message that the device is managed, that's controlled by your administrator. Administrators: see [how settings reach devices](https://code.claude.com/docs/en/admin-setup.md#decide-how-settings-reach-devices) in the deployment guide.

5252

devcontainer Changed · +25 / -25 lines

from line 9

99> [!WARNING]

1010>

1111> While the dev container provides substantial protections, no system is completely immune to all attacks.

12> When executed with `--dangerously-skip-permissions`, dev containers do not prevent a malicious project from exfiltrating anything accessible inside the container, including the Claude Code credentials stored in [`~/.claude`](/docs/en/claude-directory).

1313> Only use dev containers when developing with trusted repositories, and monitor Claude's activities.

1414> Avoid mounting host secrets such as `~/.ssh` or cloud credential files into the container; prefer repository-scoped or short-lived tokens.

1515

from line 19

1919>

2020> A dev container runs as a Docker container, either on your machine or on a cloud host such as GitHub Codespaces. An editor that supports the Dev Containers spec, such as VS Code, GitHub Codespaces, a JetBrains IDE, or Cursor, connects to that container: you browse and edit files in the editor as usual, but the integrated terminal, language servers, and build tools all run inside the container rather than on your host. Editors without dev container support, such as plain Vim, are not part of this workflow.

2121>

22> Claude Code runs inside the container, so it sees the same files, dependencies, and tools as the rest of your project's toolchain. In VS Code you can use either the [Claude Code extension panel](/docs/en/vs-code.md) or run `claude` in the integrated terminal; both run inside the container and share the same `~/.claude` configuration.

22> Claude Code runs inside the container, so it sees the same files, dependencies, and tools as the rest of your project's toolchain. In VS Code you can use either the [Claude Code extension panel](https://code.claude.com/docs/en/vs-code.md) or run `claude` in the integrated terminal; both run inside the container and share the same `~/.claude` configuration.

2323

2424## Add Claude Code to your dev container

2525

from line 67

6767What you see at the authentication prompt depends on your provider:

6868

6969* **Anthropic**: sign in through a browser with your Claude or Anthropic Console account

70* **[Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry](/docs/en/third-party-integrations.md)**: Claude Code uses your cloud provider credentials, with no browser prompt

70* **[Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry](https://code.claude.com/docs/en/third-party-integrations.md)**: Claude Code uses your cloud provider credentials, with no browser prompt

7171

72For cloud providers, pass credentials into the container as environment variables through `containerEnv`, a Codespaces secret, or your cloud's workload identity rather than mounting credential files from the host. See [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 the credential chain Claude Code reads.

72For cloud providers, pass credentials into the container as environment variables through `containerEnv`, a Codespaces secret, or your cloud's workload identity rather than mounting credential files from the host. See [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md) for the credential chain Claude Code reads.

7373

74See [Choose your API provider](/docs/en/admin-setup.md#choose-your-api-provider) to decide which path fits your organization.

74See [Choose your API provider](https://code.claude.com/docs/en/admin-setup.md#choose-your-api-provider) to decide which path fits your organization.

7575

7676> [!NOTE]

7777>

from line 79

7979

8080## Persist authentication and settings across rebuilds

8181

82By default, the container's home directory is discarded on rebuild, so engineers must sign in again each time. Claude Code stores its authentication token, user settings, and session history under the [`~/.claude`](/docs/en/claude-directory) directory. It stores your account details, personal MCP servers, and per-project trust in a separate file outside that directory: [`~/.claude.json`](/docs/en/settings-reference#global-config-settings).

82By default, the container's home directory is discarded on rebuild, so engineers must sign in again each time. Claude Code stores its authentication token, user settings, and session history under the [`~/.claude`](https://code.claude.com/docs/en/claude-directory) directory. It stores your account details, personal MCP servers, and per-project trust in a separate file outside that directory: [`~/.claude.json`](https://code.claude.com/docs/en/settings-reference#global-config-settings).

8383

84To keep the directory and the file, mount a named volume at `~/.claude` and set [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars) to the same path so Claude Code writes `.claude.json` inside the volume. The following example mounts the volume and sets `CLAUDE_CONFIG_DIR` for a container whose `remoteUser` is `node`:

84To keep the directory and the file, mount a named volume at `~/.claude` and set [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars) to the same path so Claude Code writes `.claude.json` inside the volume. The following example mounts the volume and sets `CLAUDE_CONFIG_DIR` for a container whose `remoteUser` is `node`:

8585

8686```json devcontainer.json theme={null}

8787"mounts": [

from line 102

102102

103103In GitHub Codespaces, `~/.claude` persists when you stop and start a codespace but is cleared when you rebuild the container, so the configuration above applies there too.

104104

105To carry authentication across codespaces, store `ANTHROPIC_API_KEY` or a `CLAUDE_CODE_OAUTH_TOKEN` from [`claude setup-token`](/docs/en/authentication#generate-a-long-lived-token) as a [Codespaces secret](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces). Codespaces exposes secrets as environment variables inside the container automatically.

105To carry authentication across codespaces, store `ANTHROPIC_API_KEY` or a `CLAUDE_CODE_OAUTH_TOKEN` from [`claude setup-token`](https://code.claude.com/docs/en/authentication#generate-a-long-lived-token) as a [Codespaces secret](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces). Codespaces exposes secrets as environment variables inside the container automatically.

106106

107107## Enforce organization policy

108108

109109A dev container is a convenient place to apply organization policy, because the same image and configuration run on every engineer's machine.

110110

111Claude Code reads `/etc/claude-code/managed-settings.json` on Linux and applies it at the highest precedence in the [settings hierarchy](/docs/en/settings.md#settings-precedence), so values there override anything an engineer sets in `~/.claude` or the project's `.claude/` directory. Copy the file into place from your Dockerfile:

111Claude Code reads `/etc/claude-code/managed-settings.json` on Linux and applies it at the highest precedence in the [settings hierarchy](https://code.claude.com/docs/en/settings.md#settings-precedence), so values there override anything an engineer sets in `~/.claude` or the project's `.claude/` directory. Copy the file into place from your Dockerfile:

112112

113113```dockerfile Dockerfile theme={null}

114114RUN mkdir -p /etc/claude-code

from line 115

115115COPY managed-settings.json /etc/claude-code/managed-settings.json

116116```

117117

118Because the Dockerfile lives in the repository, anyone with write access can change or remove this step. For policy that engineers cannot bypass by editing repository files, deliver managed settings through [server-managed settings](/docs/en/server-managed-settings.md) or your MDM instead. See [managed settings files](/docs/en/managed-settings.md#delivery-mechanisms) for the available keys and the other delivery paths.

118Because the Dockerfile lives in the repository, anyone with write access can change or remove this step. For policy that engineers cannot bypass by editing repository files, deliver managed settings through [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) or your MDM instead. See [managed settings files](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms) for the available keys and the other delivery paths.

119119

120To set [environment variables](/docs/en/env-vars.md) that apply to every Claude Code session in the container, add them to `containerEnv` in your `devcontainer.json`. The following example opts out of telemetry and error reporting and prevents Claude Code from auto-updating after install:

120To set [environment variables](https://code.claude.com/docs/en/env-vars.md) that apply to every Claude Code session in the container, add them to `containerEnv` in your `devcontainer.json`. The following example opts out of telemetry and error reporting and prevents Claude Code from auto-updating after install:

121121

122122```json devcontainer.json theme={null}

123123"containerEnv": {

from line 126

126126}

127127```

128128

129`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` also disables the feature-flag evaluation that [Remote Control](/docs/en/remote-control.md#requirements) and the other [features that need feature-flag fetching](/docs/en/env-vars.md#features-that-need-feature-flag-fetching) depend on, so sessions in the container can't use them.

129`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` also disables the feature-flag evaluation that [Remote Control](https://code.claude.com/docs/en/remote-control.md#requirements) and the other [features that need feature-flag fetching](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching) depend on, so sessions in the container can't use them.

130130

131131The Dev Container Feature always installs the latest Claude Code release. To pin a specific Claude Code version for reproducible builds, install it from your Dockerfile with `npm install -g @anthropic-ai/[email protected]` instead of using the feature, and set `DISABLE_AUTOUPDATER` to `1` in `containerEnv`.

132132

133For the full list of policy controls including permission rules, tool restrictions, and MCP server allowlists, see [Set up Claude Code for your organization](/docs/en/admin-setup.md).

133For the full list of policy controls including permission rules, tool restrictions, and MCP server allowlists, see [Set up Claude Code for your organization](https://code.claude.com/docs/en/admin-setup.md).

134134

135To make [MCP servers](/docs/en/mcp.md) available inside the container, define them at [project scope](/docs/en/mcp.md#mcp-installation-scopes) in a `.mcp.json` file at the repository root so they are checked in alongside your dev container configuration. Install any binaries that local stdio servers depend on in your Dockerfile, and add remote server domains to your network allowlist.

135To make [MCP servers](https://code.claude.com/docs/en/mcp.md) available inside the container, define them at [project scope](https://code.claude.com/docs/en/mcp.md#mcp-installation-scopes) in a `.mcp.json` file at the repository root so they are checked in alongside your dev container configuration. Install any binaries that local stdio servers depend on in your Dockerfile, and add remote server domains to your network allowlist.

136136

137137## Restrict network egress

138138

139You can limit the container's outbound traffic to only the domains Claude Code needs. See [Network access requirements](/docs/en/network-config.md#network-access-requirements) for the inference and authentication domains, and [Telemetry services](/docs/en/data-usage.md#telemetry-services) for the optional telemetry and error reporting connections and how to disable them.

139You can limit the container's outbound traffic to only the domains Claude Code needs. See [Network access requirements](https://code.claude.com/docs/en/network-config.md#network-access-requirements) for the inference and authentication domains, and [Telemetry services](https://code.claude.com/docs/en/data-usage.md#telemetry-services) for the optional telemetry and error reporting connections and how to disable them.

140140

141141The reference container includes an [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) script that limits outbound traffic to the destinations the script allows. Running a firewall inside a container requires extra permissions, so the reference adds the `NET_ADMIN` and `NET_RAW` capabilities through `runArgs`. The firewall script and these capabilities are not required for Claude Code itself: you can leave them out and rely on your own network controls instead.

142142

from line 146

146146

147147Skipping permission prompts removes your opportunity to review tool calls before they run. Claude can still modify any file in the bind-mounted workspace, which appears directly on your host, and reach anything the container's network policy allows. Pair this flag with the [network egress restrictions](#restrict-network-egress) above to limit what a bypassed session can reach.

148148

149If you want fewer prompts without disabling safety checks, consider [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) instead, which has a classifier review actions before they run. To prevent engineers from using `--dangerously-skip-permissions` at all, set `permissions.disableBypassPermissionsMode` to `"disable"` in [managed settings](/docs/en/settings-reference.md#permission-settings).

149If you want fewer prompts without disabling safety checks, consider [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) instead, which has a classifier review actions before they run. To prevent engineers from using `--dangerously-skip-permissions` at all, set `permissions.disableBypassPermissionsMode` to `"disable"` in [managed settings](https://code.claude.com/docs/en/settings-reference.md#permission-settings).

150150

151151## Try the reference container

152152

from line 182

182182

183183Once Claude Code is running in your dev container, the pages below cover the rest of an organization rollout: choosing an authentication path, delivering managed policy outside the repository, monitoring usage, and understanding what Claude Code stores and sends.

184184

185* [Set up Claude Code for your organization](/docs/en/admin-setup.md): choose an authentication provider, decide how policy reaches devices, and plan the rollout

186* [Server-managed settings](/docs/en/server-managed-settings.md): deliver managed policy from the claude.ai admin console so engineers cannot bypass it by editing repository files

187* [Monitor usage and audit activity](/docs/en/monitoring-usage.md): export OpenTelemetry metrics and review what your team is running

188* [Network access requirements](/docs/en/network-config.md#network-access-requirements): the full domain allowlist for proxies and firewalls

189* [Telemetry services and opt-out](/docs/en/data-usage.md#telemetry-services): what Claude Code sends by default and the environment variables that disable it

190* [Explore the `.claude` directory](/docs/en/claude-directory): what the volume mount holds, including credentials, settings, and session history

191* [Sandbox environments](/docs/en/sandbox-environments.md): compare dev containers with the built-in Bash sandbox, custom containers, and VMs

192* [Security model](/docs/en/security.md): how Claude Code's permission system, sandboxing, and prompt-injection protections fit together

193* [Permission modes](/docs/en/permission-modes.md): the full range from plan mode to auto mode to bypass, and when to use each

185* [Set up Claude Code for your organization](https://code.claude.com/docs/en/admin-setup.md): choose an authentication provider, decide how policy reaches devices, and plan the rollout

186* [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md): deliver managed policy from the claude.ai admin console so engineers cannot bypass it by editing repository files

187* [Monitor usage and audit activity](https://code.claude.com/docs/en/monitoring-usage.md): export OpenTelemetry metrics and review what your team is running

188* [Network access requirements](https://code.claude.com/docs/en/network-config.md#network-access-requirements): the full domain allowlist for proxies and firewalls

189* [Telemetry services and opt-out](https://code.claude.com/docs/en/data-usage.md#telemetry-services): what Claude Code sends by default and the environment variables that disable it

190* [Explore the `.claude` directory](https://code.claude.com/docs/en/claude-directory): what the volume mount holds, including credentials, settings, and session history

191* [Sandbox environments](https://code.claude.com/docs/en/sandbox-environments.md): compare dev containers with the built-in Bash sandbox, custom containers, and VMs

192* [Security model](https://code.claude.com/docs/en/security.md): how Claude Code's permission system, sandboxing, and prompt-injection protections fit together

193* [Permission modes](https://code.claude.com/docs/en/permission-modes.md): the full range from plan mode to auto mode to bypass, and when to use each

194194

errors Changed · +765 / -765 lines

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

Nothing in the body moved in this read. What changed is above.

fast-mode Changed · +22 / -22 lines

from line 14

1414

1515What to know:

1616

17* Use `/fast` to toggle on fast mode in the Claude Code CLI. The [VS Code extension](/docs/en/vs-code.md) offers a **Toggle fast mode** command when the selected model supports fast mode. Claude Code saves that toggle to your [`fastMode` setting](#toggle-fast-mode).

17* Use `/fast` to toggle on fast mode in the Claude Code CLI. The [VS Code extension](https://code.claude.com/docs/en/vs-code.md) offers a **Toggle fast mode** command when the selected model supports fast mode. Claude Code saves that toggle to your [`fastMode` setting](#toggle-fast-mode).

1818* Fast mode pricing per MTok input/output is \$8/\$40 on Opus 5.5 and \$10/\$50 on Opus 5 and Opus 4.8.

1919* Available to Claude Code users on subscription plans (Pro/Max/Team/Enterprise) and on Claude Console. Team and Enterprise organizations need an Owner to enable it first, and Console organizations need access provisioned first, both described under [Requirements](#requirements).

2020* For Claude Code users on subscription plans (Pro/Max/Team/Enterprise), fast mode is available via usage credits only and not included in the subscription rate limits.

from line 24

2424In the CLI, toggle fast mode in either of these ways:

2525

2626* Run `/fast`, press Space to toggle on or off, then press Enter to confirm

27* Set `"fastMode": true` in your [user settings file](/docs/en/settings.md)

27* Set `"fastMode": true` in your [user settings file](https://code.claude.com/docs/en/settings.md)

2828

2929By default, fast mode you turn on in an interactive session persists across sessions. You can configure fast mode to reset each session. See [require per-session opt-in](#require-per-session-opt-in) for details.

3030

31Outside a [cloud session](#use-fast-mode-in-cloud-sessions), in [non-interactive mode](/docs/en/headless.md) with the `-p` flag, `/fast` works only in a session launched with fast mode in its [`--settings`](/docs/en/cli-reference#cli-flags) value, for example `claude -p --settings '{"fastMode": true}'`; the toggle then applies to that session only and isn't saved as your default. The `-p` form requires Claude Code v2.1.205 or later. Elsewhere in non-interactive mode, the command reports that fast mode isn't available.

31Outside a [cloud session](#use-fast-mode-in-cloud-sessions), in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag, `/fast` works only in a session launched with fast mode in its [`--settings`](https://code.claude.com/docs/en/cli-reference#cli-flags) value, for example `claude -p --settings '{"fastMode": true}'`; the toggle then applies to that session only and isn't saved as your default. The `-p` form requires Claude Code v2.1.205 or later. Elsewhere in non-interactive mode, the command reports that fast mode isn't available.

3232

3333You can run `/fast` while Claude is working, and Claude Code toggles fast mode without waiting for the turn to end. Claude Code finishes the running turn at its original speed, so the speed change takes effect from your next turn. If your current model doesn't support fast mode, turning it on also switches your model, and Claude Code uses the new model from its next request in that turn.

3434

from line 52

5252* **Switch away**: when you switch to a model that doesn't support fast mode, Claude Code turns fast mode off. This includes Opus 4.7; before v2.1.221, fast mode stayed on after a switch to Opus 4.7 and the API rejected the requests.

5353* **Switch back**: switching back to a supported Opus model turns fast mode on again when your saved fast mode preference is on, the same preference a new session starts from by default. A model switch never turns fast mode on for a session whose saved preference is off, and with [per-session opt-in](#require-per-session-opt-in) configured, switching back doesn't turn it on either; run `/fast` to re-enable it.

5454

55Whenever a model switch turns fast mode on or off, Claude Code shows a `Fast mode ON` or `Fast mode OFF` confirmation, and the `↯` icon appears while fast mode is on. This holds whether you switch with `/model`, with [`/config model=<model>`](/docs/en/settings), or from a device connected through [Remote Control](/docs/en/remote-control.md).

55Whenever a model switch turns fast mode on or off, Claude Code shows a `Fast mode ON` or `Fast mode OFF` confirmation, and the `↯` icon appears while fast mode is on. This holds whether you switch with `/model`, with [`/config model=<model>`](https://code.claude.com/docs/en/settings), or from a device connected through [Remote Control](https://code.claude.com/docs/en/remote-control.md).

5656

5757Claude Code resends the session's fast mode status to devices connected through Remote Control after a model switch, a reconnection, or a failed [availability check](#use-fast-mode-behind-proxies-and-llm-gateways).

5858

5959### Use fast mode in cloud sessions

6060

61Fast mode works in [cloud sessions](/docs/en/claude-code-on-the-web.md) when it's available on your account, whether the session runs on Anthropic-managed infrastructure or a [self-hosted runner](/docs/en/self-hosted-environments). Requires Claude Code v2.1.271 or later in the session's environment.

61Fast mode works in [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) when it's available on your account, whether the session runs on Anthropic-managed infrastructure or a [self-hosted runner](https://code.claude.com/docs/en/self-hosted-environments). Requires Claude Code v2.1.271 or later in the session's environment.

6262

6363Type `/fast on` in the session to turn fast mode on. It stays on for that session only and isn't saved as your default. The [requirements](#requirements) apply in cloud sessions too.

6464

from line 76

7676

7777Fast mode pricing is flat across the full 1M token context window. For the standard Opus rate to compare against, see the [Claude pricing reference](https://platform.claude.com/docs/en/about-claude/pricing).

7878

79The first time you enable fast mode in a conversation, you pay the full fast mode uncached input token price for the entire conversation context. The deeper into a conversation you are, the more this costs, so the charge is smallest when you enable fast mode at the start. The cost applies once per conversation, so toggling fast mode off and on again later doesn't repeat it. For the mechanism, see [how fast mode interacts with the prompt cache](/docs/en/prompt-caching.md#turning-on-fast-mode).

8080

8181### See where fast mode spend appears

8282

83You see fast mode spend in a different place depending on how you signed in, so first run [`/status`](/docs/en/commands) to check. If it shows a `Login method` row such as `Claude Max account`, you signed in with a Claude subscription. If it shows an `API key` row instead, your requests bill to a Claude Console organization.

83You see fast mode spend in a different place depending on how you signed in, so first run [`/status`](https://code.claude.com/docs/en/commands) to check. If it shows a `Login method` row such as `Claude Max account`, you signed in with a Claude subscription. If it shows an `API key` row instead, your requests bill to a Claude Console organization.

8484

8585* **Pro and Max**: you pay for fast mode from your usage credits. Go to [**Settings > Usage**](https://claude.ai/settings/usage) on claude.ai, where the **Usage credits** section shows how much you've spent in usage credits this month. That figure includes fast mode but doesn't break it out separately.

86* **Team and Enterprise**: your organization pays for your fast mode usage from its usage credits. To see your own usage-credits spend, run [`/usage`](/docs/en/costs#check-your-usage-credits-spend). For where your organization sees that spend, see [Claude for Teams and Enterprise](/docs/en/costs.md#claude-for-teams-and-enterprise).

86* **Team and Enterprise**: your organization pays for your fast mode usage from its usage credits. To see your own usage-credits spend, run [`/usage`](https://code.claude.com/docs/en/costs#check-your-usage-credits-spend). For where your organization sees that spend, see [Claude for Teams and Enterprise](https://code.claude.com/docs/en/costs.md#claude-for-teams-and-enterprise).

8787* **Claude Console**: your organization pays for fast mode with the rest of its API usage. On the Console [Usage](https://platform.claude.com/usage) and [Cost](https://platform.claude.com/cost) pages, select **Speed (Research Preview)** in the **Group by** menu to separate fast mode from standard-speed usage. You see that option only when the selected date range includes fast mode usage.

8888

8989## Decide when to use fast mode

from line 109

109109| **Fast mode** | Same model quality, lower latency, higher cost |

110110| **Lower effort level** | Less thinking time, faster responses, potentially lower quality on complex tasks |

111111

112You can combine both: use fast mode with a lower [effort level](/docs/en/model-config.md#adjust-effort-level) for maximum speed on straightforward tasks.

112You can combine both: use fast mode with a lower [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) for maximum speed on straightforward tasks.

113113

114114## Requirements

115115

from line 116

116116Fast mode requires all of the following:

117117

118118* **Anthropic API or subscription only**: fast mode is available through the Anthropic Console API and for Claude subscription plans using usage credits. It is not available on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Platform on AWS. Console organizations must also have [fast mode access provisioned](#enable-fast-mode-for-your-organization).

119* **Usage credits turned on for subscription plans**: on a Pro, Max, Team, or Enterprise plan, your account must have [usage credits](/docs/en/costs.md#add-usage-credits-to-your-subscription) turned on, which allows billing beyond your plan's included usage. Until they're on, `/fast` reports "Fast mode requires usage credits". How you turn them on depends on your plan:

119* **Usage credits turned on for subscription plans**: on a Pro, Max, Team, or Enterprise plan, your account must have [usage credits](https://code.claude.com/docs/en/costs.md#add-usage-credits-to-your-subscription) turned on, which allows billing beyond your plan's included usage. Until they're on, `/fast` reports "Fast mode requires usage credits". How you turn them on depends on your plan:

120120 * On Pro and Max, turn them on in the **Usage credits** section of [**Settings > Usage**](https://claude.ai/settings/usage) on claude.ai, or run `/usage-credits` to open that page.

121121 * On Team and Enterprise, a member with billing access turns them on for the organization at [**Organization settings > Usage**](https://claude.ai/admin-settings/usage), and a member without it runs `/usage-credits` to send the organization's admins a request.

122122

from line 132

132132> Four organization settings can block turning fast mode on with `/fast`:

133133>

134134> * **Fast mode not enabled**: if fast mode hasn't been enabled for your organization, turning fast mode on with `/fast` shows "Fast mode has been disabled by your organization."

135> * **Fast mode turned off by managed settings**: if your organization deploys [managed settings](/docs/en/managed-settings.md) that set [`fastMode: false`](/docs/en/settings-reference#fastmode), turning fast mode on with `/fast` shows the same "Fast mode has been disabled by your organization" message.

135> * **Fast mode turned off by managed settings**: if your organization deploys [managed settings](https://code.claude.com/docs/en/managed-settings.md) that set [`fastMode: false`](https://code.claude.com/docs/en/settings-reference#fastmode), turning fast mode on with `/fast` shows the same "Fast mode has been disabled by your organization" message.

136136> * **Per-session opt-in required**: managed settings that set [`fastModePerSessionOptIn: true`](#require-per-session-opt-in) refuse `/fast on` with the same message everywhere except an interactive terminal session.

137> * **Fast-mode model not allowed**: if your organization's [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist excludes the fast-mode Opus model, turning it on is refused with "is not in your organization's allowed models". In a session already running on an allowed Opus model that supports fast mode, `/fast` instead enables fast mode on your current model without switching models.

137> * **Fast-mode model not allowed**: if your organization's [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) allowlist excludes the fast-mode Opus model, turning it on is refused with "is not in your organization's allowed models". In a session already running on an allowed Opus model that supports fast mode, `/fast` instead enables fast mode on your current model without switching models.

138138

139139### Enable fast mode for your organization

140140

from line 145

145145 Without provisioned access, the API rejects each fast mode request with a 429, and Claude Code treats each rejection as a [fast mode rate limit](#handle-rate-limits). Unlike a rate limit's cooldown, the rejections continue until access is provisioned.

146146* **Claude AI** (Team and Enterprise): an Owner enables it at [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code)

147147

148Another option to disable fast mode entirely is to set `CLAUDE_CODE_DISABLE_FAST_MODE=1`. See [Environment variables](/docs/en/env-vars.md).

148Another option to disable fast mode entirely is to set `CLAUDE_CODE_DISABLE_FAST_MODE=1`. See [Environment variables](https://code.claude.com/docs/en/env-vars.md).

149149

150150### Use fast mode behind proxies and LLM gateways

151151

152Before offering fast mode, Claude Code checks your organization's fast mode availability with a request directly to `api.anthropic.com`. The check doesn't follow [`ANTHROPIC_BASE_URL`](/docs/en/llm-gateway-connect#set-the-base-url-and-credential), so on a network that routes Claude traffic through an [LLM gateway](/docs/en/llm-gateway) and blocks direct egress to `api.anthropic.com`, the check fails even though inference requests work. The check does use a configured [HTTP proxy](/docs/en/network-config.md#proxy-configuration), so a network block fails the check only where `api.anthropic.com` is unreachable even through the proxy.

152Before offering fast mode, Claude Code checks your organization's fast mode availability with a request directly to `api.anthropic.com`. The check doesn't follow [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/en/llm-gateway-connect#set-the-base-url-and-credential), so on a network that routes Claude traffic through an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) and blocks direct egress to `api.anthropic.com`, the check fails even though inference requests work. The check does use a configured [HTTP proxy](https://code.claude.com/docs/en/network-config.md#proxy-configuration), so a network block fails the check only where `api.anthropic.com` is unreachable even through the proxy.

153153

154154When the check fails, `/fast` reports "Fast mode unavailable due to network connectivity issues", and requests run at standard speed, even when your organization has fast mode enabled. A check that succeeded in the past keeps working from its cached result, so a blocked check mostly affects new installations.

155155

156The same connectivity message appears on an open network when the check reaches `api.anthropic.com` but presents a credential Anthropic rejects. A session whose resolved key is a gateway-issued credential, held in [`ANTHROPIC_API_KEY`](/docs/en/llm-gateway-connect#set-the-base-url-and-credential) or produced by an [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper), sends the check with that key, and the rejected request is reported as a connectivity failure.

156The same connectivity message appears on an open network when the check reaches `api.anthropic.com` but presents a credential Anthropic rejects. A session whose resolved key is a gateway-issued credential, held in [`ANTHROPIC_API_KEY`](https://code.claude.com/docs/en/llm-gateway-connect#set-the-base-url-and-credential) or produced by an [`apiKeyHelper`](https://code.claude.com/docs/en/settings-reference#apikeyhelper), sends the check with that key, and the rejected request is reported as a connectivity failure.

157157

158158To restore fast mode, allowlist direct egress to `api.anthropic.com` where a network block is the cause, or set whichever variable matches how the check fails:

159159

from line 162

162162

163163Two gateway configurations report "Fast mode has been disabled by your organization" rather than the connectivity message, even when your organization has fast mode enabled:

164164

165* A session that authenticates with [`ANTHROPIC_AUTH_TOKEN`](/docs/en/llm-gateway-connect#set-the-base-url-and-credential) alone skips the check: without a claude.ai login or an Anthropic API key, and without a cached successful check, Claude Code treats fast mode as disabled by your organization without sending the request.

165* A session that authenticates with [`ANTHROPIC_AUTH_TOKEN`](https://code.claude.com/docs/en/llm-gateway-connect#set-the-base-url-and-credential) alone skips the check: without a claude.ai login or an Anthropic API key, and without a cached successful check, Claude Code treats fast mode as disabled by your organization without sending the request.

166166* A proxy that intercepts the check and answers with its own page, for example a TLS-inspecting proxy returning an HTTP 200 block page, is read as a response saying your organization has fast mode disabled.

167167

168168In both cases, set `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1` to restore fast mode. `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` doesn't apply to either case, since it only bypasses failed checks and both of these produce a disabled response instead. Allowlisting direct egress doesn't help the bearer-token case, which never sends the request.

from line 173

173173

174174### Require per-session opt-in

175175

176By default, fast mode a user turns on in an interactive session persists across sessions. To change this, set `fastModePerSessionOptIn` to `true` in any [settings file](/docs/en/settings.md#where-settings-live), which causes each session to start with fast mode off and requires users to explicitly enable it with `/fast`. Owners on [Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) or [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) plans can deploy it organization-wide through [server-managed settings](/docs/en/server-managed-settings.md).

176By default, fast mode a user turns on in an interactive session persists across sessions. To change this, set `fastModePerSessionOptIn` to `true` in any [settings file](https://code.claude.com/docs/en/settings.md#where-settings-live), which causes each session to start with fast mode off and requires users to explicitly enable it with `/fast`. Owners on [Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) or [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) plans can deploy it organization-wide through [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md).

177177

178178```json theme={null}

179179{

from line 183

183183

184184This is useful for controlling costs in organizations where users run multiple concurrent sessions. The user's fast mode preference is still saved, so removing this setting restores the default persistent behavior.

185185

186When managed settings set the key, `/fast on` works only in an interactive terminal session. Everywhere else, including [non-interactive mode](/docs/en/headless.md), the [VS Code extension](/docs/en/vs-code.md), and [cloud sessions](#use-fast-mode-in-cloud-sessions), it's refused with a message that your organization has disabled fast mode.

186When managed settings set the key, `/fast on` works only in an interactive terminal session. Everywhere else, including [non-interactive mode](https://code.claude.com/docs/en/headless.md), the [VS Code extension](https://code.claude.com/docs/en/vs-code.md), and [cloud sessions](#use-fast-mode-in-cloud-sessions), it's refused with a message that your organization has disabled fast mode.

187187

188188## Handle rate limits

189189

from line 199

199199If you run out of usage credits mid-session, Claude Code retries each rejected fast mode request at standard speed and pricing, so you keep working, and there is no cooldown. How you see the rejection depends on the session type:

200200

201201* In an interactive session, Claude Code shows a "Fast mode disabled · usage credits exhausted" notification and turns fast mode off for the rest of the session. Your saved fast mode preference doesn't change; run `/fast` to turn fast mode back on.

202* In [non-interactive mode](/docs/en/headless.md) with `--output-format stream-json`, and through the Agent SDK, Claude Code emits the same text on the message stream as a `system` message with subtype `notification`, once per turn while you're out of usage credits. Fast mode stays on. Requires Claude Code v2.1.221 or later.

202* In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with `--output-format stream-json`, and through the Agent SDK, Claude Code emits the same text on the message stream as a `system` message with subtype `notification`, once per turn while you're out of usage credits. Fast mode stays on. Requires Claude Code v2.1.221 or later.

203203

204204## Research preview

205205

from line 213

213213

214214## See also

215215

216* [Model configuration](/docs/en/model-config.md): switch models and adjust effort levels

217* [Manage costs effectively](/docs/en/costs.md): track token usage and reduce costs

218* [Status line configuration](/docs/en/statusline.md): display model and context information

216* [Model configuration](https://code.claude.com/docs/en/model-config.md): switch models and adjust effort levels

217* [Manage costs effectively](https://code.claude.com/docs/en/costs.md): track token usage and reduce costs

218* [Status line configuration](https://code.claude.com/docs/en/statusline.md): display model and context information

219219

feature-availability Changed · +147 / -147 lines

from line 2

33> Compare which Claude Code features are available across Anthropic subscription plans, the Anthropic Console, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry.

5The Claude Code CLI and everything that runs locally work on every provider. For setup instructions per provider, see the [Enterprise deployment overview](/docs/en/third-party-integrations.md). To skip straight to what is missing on your provider, see the [summary by provider](#summary-by-provider) tabs.

5The Claude Code CLI and everything that runs locally work on every provider. For setup instructions per provider, see the [Enterprise deployment overview](https://code.claude.com/docs/en/third-party-integrations.md). To skip straight to what is missing on your provider, see the [summary by provider](#summary-by-provider) tabs.

77In the tables below, ✓ means available, ✗ means not available, and "See note" links to a footnote for partial support. A qualifier after ✓ narrows availability to that subset, and "Admin-enabled" means the feature is off until an organization admin turns it on.

from line 11

1111How you authenticate determines which features Claude Code can reach. For a single list of what is missing on your provider, see the [summary by provider](#summary-by-provider) tabs. To find your column in the tables:

1212

1313* **Claude subscription**: you sign in with a claude.ai account on the Pro, Max, Team, or Enterprise plan

14* **Anthropic Console**: you authenticate with an Anthropic API key or by [signing in to a Console account without one](/docs/en/authentication.md#sign-in-without-an-api-key)

15* **Amazon Bedrock**: you use Claude models from the Amazon Bedrock model catalog and set `CLAUDE_CODE_USE_BEDROCK`. The [Mantle endpoint](/docs/en/amazon-bedrock.md#use-the-mantle-endpoint) (`CLAUDE_CODE_USE_MANTLE`) is covered by this column

14* **Anthropic Console**: you authenticate with an Anthropic API key or by [signing in to a Console account without one](https://code.claude.com/docs/en/authentication.md#sign-in-without-an-api-key)

15* **Amazon Bedrock**: you use Claude models from the Amazon Bedrock model catalog and set `CLAUDE_CODE_USE_BEDROCK`. The [Mantle endpoint](https://code.claude.com/docs/en/amazon-bedrock.md#use-the-mantle-endpoint) (`CLAUDE_CODE_USE_MANTLE`) is covered by this column

1616* **Claude Platform on AWS**: you bought Claude through AWS Marketplace but call the Anthropic API, and set `CLAUDE_CODE_USE_ANTHROPIC_AWS`

1717* **Google Cloud's Agent Platform**: Google-operated; you set `CLAUDE_CODE_USE_VERTEX`

1818* **Microsoft Foundry**: Anthropic-operated; you set `CLAUDE_CODE_USE_FOUNDRY`

from line 21

2121

2222These work on every provider:

2323

24* [CLI](/docs/en/quickstart.md) and [Agent SDK](/docs/en/agent-sdk/overview.md)

25* [VS Code](/docs/en/vs-code.md) and [JetBrains](/docs/en/jetbrains.md) extensions

26* [Subagents](/docs/en/sub-agents.md), [hooks](/docs/en/hooks-guide.md), [commands](/docs/en/commands.md), and [skills](/docs/en/skills.md)

27* [CLAUDE.md memory](/docs/en/memory.md), [plugins](/docs/en/plugins/overview.md), and [MCP servers](/docs/en/mcp.md)

28* [Checkpoints](/docs/en/checkpointing.md), [sandboxing](/docs/en/sandboxing.md), and [Workflows](/docs/en/workflows.md)

29* [OpenTelemetry metrics](/docs/en/monitoring-usage.md) and the [managed settings file](/docs/en/managed-settings.md#delivery-mechanisms)

24* [CLI](https://code.claude.com/docs/en/quickstart.md) and [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md)

25* [VS Code](https://code.claude.com/docs/en/vs-code.md) and [JetBrains](https://code.claude.com/docs/en/jetbrains.md) extensions

26* [Subagents](https://code.claude.com/docs/en/sub-agents.md), [hooks](https://code.claude.com/docs/en/hooks-guide.md), [commands](https://code.claude.com/docs/en/commands.md), and [skills](https://code.claude.com/docs/en/skills.md)

27* [CLAUDE.md memory](https://code.claude.com/docs/en/memory.md), [plugins](https://code.claude.com/docs/en/plugins/overview.md), and [MCP servers](https://code.claude.com/docs/en/mcp.md)

28* [Checkpoints](https://code.claude.com/docs/en/checkpointing.md), [sandboxing](https://code.claude.com/docs/en/sandboxing.md), and [Workflows](https://code.claude.com/docs/en/workflows.md)

29* [OpenTelemetry metrics](https://code.claude.com/docs/en/monitoring-usage.md) and the [managed settings file](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms)

3030

3131These have provider-specific differences:

3232

33* **MCP servers**: [connectors from claude.ai](/docs/en/mcp.md#use-mcp-servers-from-claude-ai) load only when your claude.ai subscription is the active authentication method. [Tool search](/docs/en/mcp.md#configure-tool-search) isn't supported on Microsoft Foundry [deployments hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options). On Google Cloud's Agent Platform, tool search isn't supported on models earlier than Claude Opus 4.5, Claude Sonnet 4.5, and Claude Haiku 4.5

34* **Subagents**: when the main conversation runs Fable, the built-in [Explore subagent](/docs/en/sub-agents.md#built-in-subagents) runs on Opus with a Claude subscription, an Anthropic Console account, or an [LLM gateway](/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`. On other providers, including Claude Platform on AWS, it runs on Fable

35* **[Commands](/docs/en/commands.md#all-commands)**:

36 * `/design-sync` and `/import` with its `claude import` subcommand form are unavailable on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS, and through a [Claude apps gateway](/docs/en/claude-apps-gateway#availability-and-limitations)

33* **MCP servers**: [connectors from claude.ai](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai) load only when your claude.ai subscription is the active authentication method. [Tool search](https://code.claude.com/docs/en/mcp.md#configure-tool-search) isn't supported on Microsoft Foundry [deployments hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options). On Google Cloud's Agent Platform, tool search isn't supported on models earlier than Claude Opus 4.5, Claude Sonnet 4.5, and Claude Haiku 4.5

34* **Subagents**: when the main conversation runs Fable, the built-in [Explore subagent](https://code.claude.com/docs/en/sub-agents.md#built-in-subagents) runs on Opus with a Claude subscription, an Anthropic Console account, or an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`. On other providers, including Claude Platform on AWS, it runs on Fable

35* **[Commands](https://code.claude.com/docs/en/commands.md#all-commands)**:

36 * `/design-sync` and `/import` with its `claude import` subcommand form are unavailable on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS, and through a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway#availability-and-limitations)

3737 * `/voice` requires a claude.ai account

38 * `/list-agents` and its alias `/peers` are available only in sessions where [cross-session messaging is enabled](/docs/en/cross-session-messaging.md#availability)

38 * `/list-agents` and its alias `/peers` are available only in sessions where [cross-session messaging is enabled](https://code.claude.com/docs/en/cross-session-messaging.md#availability)

3939

4040### Features that require a Claude subscription

4141

4242These require signing in with a claude.ai account and are not reachable with an Anthropic Console API key or from a third-party provider:

4343

44* [Cloud sessions](/docs/en/claude-code-on-the-web.md) and Claude Code on mobile

45* [Claude Code in Slack](/docs/en/slack.md): Pro and Max plans

46* [Claude Code Desktop](/docs/en/desktop.md)

47* [Cloud scheduled tasks](/docs/en/routines.md) (`/schedule`)

48* [Ultrareview](/docs/en/ultrareview.md)

49* [Code Review](/docs/en/code-review.md): Team and Enterprise plans

50* [Remote Control](/docs/en/remote-control.md)

51* [Chrome extension](/docs/en/chrome.md)

52* [Computer use](/docs/en/computer-use.md): Pro and Max plans

53* [Artifacts](/docs/en/artifacts.md): Pro, Max, Team, and Enterprise plans

54* [Voice dictation](/docs/en/voice-dictation.md)

44* [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) and Claude Code on mobile

45* [Claude Code in Slack](https://code.claude.com/docs/en/slack.md): Pro and Max plans

46* [Claude Code Desktop](https://code.claude.com/docs/en/desktop.md)

47* [Cloud scheduled tasks](https://code.claude.com/docs/en/routines.md) (`/schedule`)

48* [Ultrareview](https://code.claude.com/docs/en/ultrareview.md)

49* [Code Review](https://code.claude.com/docs/en/code-review.md): Team and Enterprise plans

50* [Remote Control](https://code.claude.com/docs/en/remote-control.md)

51* [Chrome extension](https://code.claude.com/docs/en/chrome.md)

52* [Computer use](https://code.claude.com/docs/en/computer-use.md): Pro and Max plans

53* [Artifacts](https://code.claude.com/docs/en/artifacts.md): Pro, Max, Team, and Enterprise plans

54* [Voice dictation](https://code.claude.com/docs/en/voice-dictation.md)

5555

56Desktop is the partial exception: [gateway routing can be configured in the app or by an administrator](/docs/en/llm-gateway-connect.md#desktop-app). [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview) also runs the Code tab on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or a self-hosted LLM gateway. It also runs the Code tab on the [Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api) with an Anthropic Console API key. For per-plan availability of these features, see [Availability by subscription plan](#availability-by-subscription-plan).

56Desktop is the partial exception: [gateway routing can be configured in the app or by an administrator](https://code.claude.com/docs/en/llm-gateway-connect.md#desktop-app). [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview) also runs the Code tab on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or a self-hosted LLM gateway. It also runs the Code tab on the [Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api) with an Anthropic Console API key. For per-plan availability of these features, see [Availability by subscription plan](#availability-by-subscription-plan).

5757

5858### CLI capabilities that vary by provider

5959

from line 74

7474

7575 <tbody>

7676 <tr>

77 <td>[Web search](/docs/en/tools-reference.md#websearch-tool-behavior)</td>

77 <td>[Web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior)</td>

7878 <td>✓</td>

7979 <td>✓</td>

8080 <td>✗</td>

from line 84

8484 </tr>

8585

8686 <tr>

87 <td>[Fast mode](/docs/en/fast-mode.md)</td>

88 <td>✓ ([Owner-enabled](/docs/en/fast-mode.md#enable-fast-mode-for-your-organization) on Team and Enterprise)</td>

87 <td>[Fast mode](https://code.claude.com/docs/en/fast-mode.md)</td>

88 <td>✓ ([Owner-enabled](https://code.claude.com/docs/en/fast-mode.md#enable-fast-mode-for-your-organization) on Team and Enterprise)</td>

8989 <td>✓ (provisioned organizations)</td>

9090 <td>✗</td>

9191 <td>✗</td>

from line 94

9494 </tr>

9595

9696 <tr>

97 <td>[Auto mode](/docs/en/auto-mode-config.md)</td>

97 <td>[Auto mode](https://code.claude.com/docs/en/auto-mode-config.md)</td>

9898 <td>✓</td>

9999 <td>✓</td>

100100 <td>See note [2](#fn2)</td>

from line 104

104104 </tr>

105105

106106 <tr>

107 <td>[Advisor](/docs/en/advisor.md)</td>

107 <td>[Advisor](https://code.claude.com/docs/en/advisor.md)</td>

108108 <td>✓</td>

109109 <td>✓</td>

110110 <td>✗</td>

from line 114

114114 </tr>

115115

116116 <tr>

117 <td>[Cross-session messaging](/docs/en/cross-session-messaging.md)</td>

117 <td>[Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md)</td>

118118 <td>✓ [5](#fn5)</td>

119119 <td>✓ (same machine) [5](#fn5)</td>

120120 <td>✓ (same machine) [5](#fn5)</td>

from line 124

124124 </tr>

125125

126126 <tr>

127 <td>[Channels](/docs/en/channels.md)</td>

127 <td>[Channels](https://code.claude.com/docs/en/channels.md)</td>

128128 <td>✓</td>

129129 <td>✓</td>

130130 <td>✗</td>

from line 134

134134 </tr>

135135

136136 <tr>

137 <td>[GitHub Actions](/docs/en/github-actions.md)</td>

137 <td>[GitHub Actions](https://code.claude.com/docs/en/github-actions.md)</td>

138138 <td>✓</td>

139139 <td>✓</td>

140140 <td>✓</td>

from line 144

144144 </tr>

145145

146146 <tr>

147 <td>[GitLab CI/CD](/docs/en/gitlab-ci-cd.md)</td>

147 <td>[GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md)</td>

148148 <td>✓</td>

149149 <td>✓</td>

150150 <td>✓</td>

from line 174

174174

175175 <tbody>

176176 <tr>

177 <td>[Analytics dashboard and API](/docs/en/analytics.md)</td>

177 <td>[Analytics dashboard and API](https://code.claude.com/docs/en/analytics.md)</td>

178178 <td>✓ (dashboard: Team and Enterprise; API: Enterprise)</td>

179179 <td>✓ [4](#fn4)</td>

180180 <td>✗</td>

from line 184

184184 </tr>

185185

186186 <tr>

187 <td>[Server-managed settings](/docs/en/server-managed-settings.md)</td>

187 <td>[Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md)</td>

188188 <td>✓ (Team and Enterprise)</td>

189 <td>See [Platform availability](/docs/en/server-managed-settings.md#platform-availability)</td>

189 <td>See [Platform availability](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability)</td>

190190 <td>✗</td>

191191 <td>✗</td>

192192 <td>✗</td>

from line 194

194194 </tr>

195195

196196 <tr>

197 <td>[Zero Data Retention](/docs/en/zero-data-retention.md)</td>

197 <td>[Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md)</td>

198198 <td>✓ (qualified Enterprise accounts)</td>

199199 <td>✓ (qualified accounts)</td>

200200 <td>See note [3](#fn3)</td>

from line 207

207207

2082081 On Google Cloud's Agent Platform, web search is available for Opus 4, Sonnet 4, Haiku 4.5, and later models.\

209209

2102 On these providers, auto mode supports only Claude Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and the Fable models. See [Auto mode configuration](/docs/en/auto-mode-config.md). For the permission mode a session on these providers starts in, see [Which mode a session starts in](/docs/en/permission-modes.md#which-mode-a-session-starts-in).\

2102 On these providers, auto mode supports only Claude Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and the Fable models. See [Auto mode configuration](https://code.claude.com/docs/en/auto-mode-config.md). For the permission mode a session on these providers starts in, see [Which mode a session starts in](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in).\

211211

2122123 Subject to your agreement with the cloud provider.\

213213

2144 Dashboard and API only. [Contribution metrics](/docs/en/analytics.md#enable-contribution-metrics) requires a claude.ai Team or Enterprise organization.\

2144 Dashboard and API only. [Contribution metrics](https://code.claude.com/docs/en/analytics.md#enable-contribution-metrics) requires a claude.ai Team or Enterprise organization.\

215215

2165 Requires Claude Code v2.1.224 or later on macOS and Linux, including Linux inside WSL 2. On native Windows, requires Claude Code v2.1.234 or later. With API key authentication, messaging is same-machine only. On Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry, messaging is same-machine only and requires Claude Code v2.1.248 or later. Claude can find your [cloud sessions](/docs/en/claude-code-on-the-web.md) and your sessions on other machines only from a session that is connected to [Remote Control](/docs/en/remote-control.md). To connect, you need a claude.ai sign-in and the other [Remote Control requirements](/docs/en/remote-control.md#requirements). See [Message sessions on other machines](/docs/en/cross-session-messaging.md#message-sessions-on-other-machines).

2165 Requires Claude Code v2.1.224 or later on macOS and Linux, including Linux inside WSL 2. On native Windows, requires Claude Code v2.1.234 or later. With API key authentication, messaging is same-machine only. On Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry, messaging is same-machine only and requires Claude Code v2.1.248 or later. Claude can find your [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) and your sessions on other machines only from a session that is connected to [Remote Control](https://code.claude.com/docs/en/remote-control.md). To connect, you need a claude.ai sign-in and the other [Remote Control requirements](https://code.claude.com/docs/en/remote-control.md#requirements). See [Message sessions on other machines](https://code.claude.com/docs/en/cross-session-messaging.md#message-sessions-on-other-machines).

217217

218218> [!NOTE]

219219>

220> If you authenticate through an [LLM gateway](/docs/en/llm-gateway), feature availability matches the underlying provider the gateway forwards to, except for the features Claude Code itself turns off. Whenever `ANTHROPIC_BASE_URL` points at a host other than `api.anthropic.com`, Claude Code turns off features such as [Remote Control](/docs/en/remote-control.md#requirements) and [server-managed settings](/docs/en/server-managed-settings.md#platform-availability), whatever the gateway forwards. Some Anthropic-only features such as the [Advisor](/docs/en/advisor.md) work only if the gateway forwards requests intact to the Anthropic API.

220> If you authenticate through an [LLM gateway](https://code.claude.com/docs/en/llm-gateway), feature availability matches the underlying provider the gateway forwards to, except for the features Claude Code itself turns off. Whenever `ANTHROPIC_BASE_URL` points at a host other than `api.anthropic.com`, Claude Code turns off features such as [Remote Control](https://code.claude.com/docs/en/remote-control.md#requirements) and [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability), whatever the gateway forwards. Some Anthropic-only features such as the [Advisor](https://code.claude.com/docs/en/advisor.md) work only if the gateway forwards requests intact to the Anthropic API.

221221>

222> For how the requests Claude Code sends differ between an Amazon Bedrock- or Agent Platform-format gateway, an `ANTHROPIC_BASE_URL` gateway, and a Claude apps gateway sign-in, see [client behavior by connection method](/docs/en/llm-gateway-protocol.md#how-the-connection-method-changes-client-behavior).

222> For how the requests Claude Code sends differ between an Amazon Bedrock- or Agent Platform-format gateway, an `ANTHROPIC_BASE_URL` gateway, and a Claude apps gateway sign-in, see [client behavior by connection method](https://code.claude.com/docs/en/llm-gateway-protocol.md#how-the-connection-method-changes-client-behavior).

223223

224224### Summary by provider

225225

226Each tab lists what is unavailable or partially supported on that provider, with alternatives where one exists. Everything not listed works the same as on a Claude subscription, apart from the [provider-specific differences](#features-available-on-every-provider) noted above. On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS, error reporting and telemetry to Anthropic are off by default. See [default behaviors by API provider](/docs/en/data-usage.md#default-behaviors-by-api-provider) for what traffic still reaches Anthropic and how to opt out.

226Each tab lists what is unavailable or partially supported on that provider, with alternatives where one exists. Everything not listed works the same as on a Claude subscription, apart from the [provider-specific differences](#features-available-on-every-provider) noted above. On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS, error reporting and telemetry to Anthropic are off by default. See [default behaviors by API provider](https://code.claude.com/docs/en/data-usage.md#default-behaviors-by-api-provider) for what traffic still reaches Anthropic and how to opt out.

227227

228228**Amazon Bedrock**

229229

230**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [web search](/docs/en/tools-reference.md#websearch-tool-behavior), [fast mode](/docs/en/fast-mode.md), [Advisor](/docs/en/advisor.md), [Channels](/docs/en/channels.md), the [analytics dashboard](/docs/en/analytics.md), [server-managed settings](/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).

230**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior), [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

231231

232232**Partial support:**

233233

234* [Desktop](/docs/en/desktop.md): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

235* [Auto mode](/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

236* [Cross-session messaging](/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

237* [Zero Data Retention](/docs/en/zero-data-retention.md): subject to your AWS agreement

234* [Desktop](https://code.claude.com/docs/en/desktop.md): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

235* [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

236* [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

237* [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your AWS agreement

238238

239**Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](/docs/en/github-actions.md) or [GitLab CI/CD](/docs/en/gitlab-ci-cd.md). For web lookups, use the [WebFetch tool](/docs/en/tools-reference.md#webfetch-tool-behavior) with a specific URL.

239**Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) or [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md). For web lookups, use the [WebFetch tool](https://code.claude.com/docs/en/tools-reference.md#webfetch-tool-behavior) with a specific URL.

240240

241241**Claude Platform on AWS**

242242

243**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](/docs/en/fast-mode.md), [Advisor](/docs/en/advisor.md), [Channels](/docs/en/channels.md), [GitHub Actions](/docs/en/github-actions.md), the [analytics dashboard](/docs/en/analytics.md), [server-managed settings](/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).

243**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), [GitHub Actions](https://code.claude.com/docs/en/github-actions.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

244244

245**Available where Amazon Bedrock is not:** [web search](/docs/en/tools-reference.md#websearch-tool-behavior).

245**Available where Amazon Bedrock is not:** [web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior).

246246

247247**Partial support:**

248248

249* [Cross-session messaging](/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

249* [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

250250

251**Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitLab CI/CD](/docs/en/gitlab-ci-cd.md).

251**Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md).

252252

253253**Google Cloud's Agent Platform**

254254

255**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](/docs/en/fast-mode.md), [Advisor](/docs/en/advisor.md), [Channels](/docs/en/channels.md), the [analytics dashboard](/docs/en/analytics.md), [server-managed settings](/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).

255**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

256256

257257**Partial support:**

258258

259* [Desktop](/docs/en/desktop.md): via [managed settings](https://claude.com/docs/third-party/claude-desktop/configuration) or [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

260* [Web search](/docs/en/tools-reference.md#websearch-tool-behavior): Opus 4, Sonnet 4, Haiku 4.5, and later models

261* [Auto mode](/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

262* [Cross-session messaging](/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

263* [Zero Data Retention](/docs/en/zero-data-retention.md): subject to your Google Cloud agreement

259* [Desktop](https://code.claude.com/docs/en/desktop.md): via [managed settings](https://claude.com/docs/third-party/claude-desktop/configuration) or [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

260* [Web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior): Opus 4, Sonnet 4, Haiku 4.5, and later models

261* [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

262* [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

263* [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your Google Cloud agreement

264264

265**Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](/docs/en/github-actions.md) or [GitLab CI/CD](/docs/en/gitlab-ci-cd.md).

265**Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) or [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md).

266266

267267**Microsoft Foundry**

268268

269**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](/docs/en/fast-mode.md), [Advisor](/docs/en/advisor.md), [Channels](/docs/en/channels.md), [GitLab CI/CD](/docs/en/gitlab-ci-cd.md), the [analytics dashboard](/docs/en/analytics.md), [server-managed settings](/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).

269**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

270270

271271**Partial support:**

272272

273* [Desktop](/docs/en/desktop.md): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

274* [Auto mode](/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

275* [Cross-session messaging](/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

276* [Zero Data Retention](/docs/en/zero-data-retention.md): subject to your Azure agreement

273* [Desktop](https://code.claude.com/docs/en/desktop.md): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

274* [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

275* [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

276* [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your Azure agreement

277277

278**Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](/docs/en/github-actions.md).

278**Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](https://code.claude.com/docs/en/github-actions.md).

279279

280280**Anthropic Console**

281281

282282**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription).

283283

284Everything in [CLI capabilities that vary by provider](#cli-capabilities-that-vary-by-provider) is available, except that [fast mode](/docs/en/fast-mode.md) requires [provisioned access](/docs/en/fast-mode.md#enable-fast-mode-for-your-organization). [Server-managed settings](/docs/en/server-managed-settings.md) that you configure in a claude.ai Team or Enterprise organization don't reach a session that authenticates with a Console API key. See [Platform availability](/docs/en/server-managed-settings.md#platform-availability) for how to cover those sessions.

284Everything in [CLI capabilities that vary by provider](#cli-capabilities-that-vary-by-provider) is available, except that [fast mode](https://code.claude.com/docs/en/fast-mode.md) requires [provisioned access](https://code.claude.com/docs/en/fast-mode.md#enable-fast-mode-for-your-organization). [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) that you configure in a claude.ai Team or Enterprise organization don't reach a session that authenticates with a Console API key. See [Platform availability](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability) for how to cover those sessions.

285285

286286**Partial support:**

287287

288* [Desktop](/docs/en/desktop.md): via [Claude Desktop on 3P with the Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api)

288* [Desktop](https://code.claude.com/docs/en/desktop.md): via [Claude Desktop on 3P with the Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api)

289289

290290## Availability by subscription plan

291291

292292If you authenticate through Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an Anthropic Console API key, this section does not apply to you. When you sign in with a claude.ai account, your plan determines which of the features below are available.

293293

294In Enterprise organizations with the [HIPAA configuration](/docs/en/hipaa-setup.md) applied, some features in this table are turned off.

294In Enterprise organizations with the [HIPAA configuration](https://code.claude.com/docs/en/hipaa-setup.md) applied, some features in this table are turned off.

295295

296296| Feature | Pro | Max | Team | Enterprise |

297297| :- | :- | :- | :- | :- |

298| [Cloud sessions](/docs/en/claude-code-on-the-web.md) | ✓ | ✓ | ✓ | ✓ [6](#fn6) |

299| [Cloud scheduled tasks](/docs/en/routines.md) | ✓ | ✓ | ✓ | ✓ |

300| [Remote Control](/docs/en/remote-control.md) | ✓ | ✓ | Admin-enabled | Admin-enabled |

301| [Channels](/docs/en/channels.md) | ✓ | ✓ | Admin-enabled | Admin-enabled |

302| [Computer use](/docs/en/computer-use.md) | ✓ | ✓ | ✗ | ✗ |

303| Dispatch ([Desktop](/docs/en/desktop.md#sessions-from-dispatch)) | ✓ | ✓ | ✗ | ✗ |

304| [Code Review](/docs/en/code-review.md) | ✗ | ✗ | ✓ | ✓ |

305| [Artifacts](/docs/en/artifacts.md) | ✓ | ✓ | ✓ | ✓ |

306| [Analytics dashboard and contribution metrics](/docs/en/analytics.md) | ✗ | ✗ | ✓ | ✓ |

307| [Enterprise Analytics API](/docs/en/analytics.md#access-data-programmatically) | ✗ | ✗ | ✗ | ✓ |

308| [Server-managed settings](/docs/en/server-managed-settings.md) | ✗ | ✗ | ✓ | ✓ |

298| [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) | ✓ | ✓ | ✓ | ✓ [6](#fn6) |

299| [Cloud scheduled tasks](https://code.claude.com/docs/en/routines.md) | ✓ | ✓ | ✓ | ✓ |

300| [Remote Control](https://code.claude.com/docs/en/remote-control.md) | ✓ | ✓ | Admin-enabled | Admin-enabled |

301| [Channels](https://code.claude.com/docs/en/channels.md) | ✓ | ✓ | Admin-enabled | Admin-enabled |

302| [Computer use](https://code.claude.com/docs/en/computer-use.md) | ✓ | ✓ | ✗ | ✗ |

303| Dispatch ([Desktop](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch)) | ✓ | ✓ | ✗ | ✗ |

304| [Code Review](https://code.claude.com/docs/en/code-review.md) | ✗ | ✗ | ✓ | ✓ |

305| [Artifacts](https://code.claude.com/docs/en/artifacts.md) | ✓ | ✓ | ✓ | ✓ |

306| [Analytics dashboard and contribution metrics](https://code.claude.com/docs/en/analytics.md) | ✗ | ✗ | ✓ | ✓ |

307| [Enterprise Analytics API](https://code.claude.com/docs/en/analytics.md#access-data-programmatically) | ✗ | ✗ | ✗ | ✓ |

308| [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) | ✗ | ✗ | ✓ | ✓ |

309309| [SSO](https://support.claude.com/en/articles/9266767-what-is-the-team-plan) | ✗ | ✗ | ✓ | ✓ |

310310| SCIM | ✗ | ✗ | ✗ | ✓ |

311311| [Compliance API](https://platform.claude.com/docs/en/api/compliance) | ✗ | ✗ | ✗ | ✓ |

312| [Zero Data Retention](/docs/en/zero-data-retention.md) | ✗ | ✗ | ✗ | ✓ [7](#fn7) |

312| [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md) | ✗ | ✗ | ✗ | ✓ [7](#fn7) |

313313

3146 On Enterprise, requires a premium seat or a Chat + Claude Code seat. See [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web.md).\

3146 On Enterprise, requires a premium seat or a Chat + Claude Code seat. See [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md).\

315315

3167 Not included in the standard Enterprise plan. Requires separate enablement by Anthropic for qualified accounts. See [Zero Data Retention](/docs/en/zero-data-retention.md).

3167 Not included in the standard Enterprise plan. Requires separate enablement by Anthropic for qualified accounts. See [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md).

317317

318318For pricing and the full plan comparison, see [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).

319319

320320## Model availability

321321

322For which Claude models and context-window sizes are available per provider and region, see [Model configuration](/docs/en/model-config.md) and the [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). Vision, PDF input, and extended thinking are model capabilities rather than Claude Code features and work on every provider that offers the model. [Prompt caching](/docs/en/prompt-caching.md) works the same way on most providers; on Amazon Bedrock, support varies by model.

322For which Claude models and context-window sizes are available per provider and region, see [Model configuration](https://code.claude.com/docs/en/model-config.md) and the [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). Vision, PDF input, and extended thinking are model capabilities rather than Claude Code features and work on every provider that offers the model. [Prompt caching](https://code.claude.com/docs/en/prompt-caching.md) works the same way on most providers; on Amazon Bedrock, support varies by model.

323323

324324## Related resources

325325

326* [Enterprise deployment overview](/docs/en/third-party-integrations.md): compare authentication, billing, and regions across providers

327* Provider setup guides: [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), [Microsoft Foundry](/docs/en/microsoft-foundry.md)

328* [Platforms and integrations](/docs/en/platforms.md): where Claude Code runs, including the CLI, Desktop, IDE extensions, web, mobile, and CI/CD

326* [Enterprise deployment overview](https://code.claude.com/docs/en/third-party-integrations.md): compare authentication, billing, and regions across providers

327* Provider setup guides: [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md)

328* [Platforms and integrations](https://code.claude.com/docs/en/platforms.md): where Claude Code runs, including the CLI, Desktop, IDE extensions, web, mobile, and CI/CD

329329

features-overview Changed · +79 / -79 lines

from line 2

33> Understand when to use CLAUDE.md, Skills, subagents, hooks, MCP, and plugins.

5Claude Code combines a model that reasons about your code with [built-in tools](/docs/en/how-claude-code-works.md#tools) for file operations, search, execution, and web access. The built-in tools cover most coding tasks. This guide covers the extension layer: features you add to customize what Claude knows, connect it to external services, and automate workflows.

5Claude Code combines a model that reasons about your code with [built-in tools](https://code.claude.com/docs/en/how-claude-code-works.md#tools) for file operations, search, execution, and web access. The built-in tools cover most coding tasks. This guide covers the extension layer: features you add to customize what Claude knows, connect it to external services, and automate workflows.

77> [!NOTE]

88>

9> For how the core agentic loop works, see [How Claude Code works](/docs/en/how-claude-code-works.md).

9> For how the core agentic loop works, see [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md).

1010

11**New to Claude Code?** Start with [CLAUDE.md](/docs/en/memory.md) for project conventions, then add other extensions [as specific triggers come up](#build-your-setup-over-time).

11**New to Claude Code?** Start with [CLAUDE.md](https://code.claude.com/docs/en/memory.md) for project conventions, then add other extensions [as specific triggers come up](#build-your-setup-over-time).

1212

1313## Overview

1414

1515Extensions plug into different parts of the agentic loop:

1616

17* **[CLAUDE.md](/docs/en/memory.md)** adds persistent context Claude sees every session

18* **[Output styles](/docs/en/output-styles.md)** set Claude's role, tone, and response format for every response in a session

19* **[Skills](/docs/en/skills.md)** add reusable knowledge and invocable workflows

20* **[Code intelligence](/docs/en/tools-reference.md#lsp-tool-behavior)** connects Claude to a language server for symbol-level navigation and live type errors

21* **[MCP](/docs/en/mcp.md)** connects Claude to external services and tools

22* **[Subagents](/docs/en/sub-agents.md)** run their own loops in isolated context, returning summaries

23* **[Dynamic workflows](/docs/en/workflows.md)** run many subagents from a script Claude writes, returning one result

24* **[Cross-session messaging](/docs/en/cross-session-messaging.md)** lets Claude pass a message from one of your sessions to another

25* **[Hooks](/docs/en/hooks-guide.md)** run your script, HTTP request, MCP tool call, prompt, or subagent when Claude Code reaches a lifecycle event

26* **[Plugins](/docs/en/plugins/overview.md)** and **[marketplaces](/docs/en/plugins/overview.md)** package and distribute these features

17* **[CLAUDE.md](https://code.claude.com/docs/en/memory.md)** adds persistent context Claude sees every session

18* **[Output styles](https://code.claude.com/docs/en/output-styles.md)** set Claude's role, tone, and response format for every response in a session

19* **[Skills](https://code.claude.com/docs/en/skills.md)** add reusable knowledge and invocable workflows

20* **[Code intelligence](https://code.claude.com/docs/en/tools-reference.md#lsp-tool-behavior)** connects Claude to a language server for symbol-level navigation and live type errors

21* **[MCP](https://code.claude.com/docs/en/mcp.md)** connects Claude to external services and tools

22* **[Subagents](https://code.claude.com/docs/en/sub-agents.md)** run their own loops in isolated context, returning summaries

23* **[Dynamic workflows](https://code.claude.com/docs/en/workflows.md)** run many subagents from a script Claude writes, returning one result

24* **[Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md)** lets Claude pass a message from one of your sessions to another

25* **[Hooks](https://code.claude.com/docs/en/hooks-guide.md)** run your script, HTTP request, MCP tool call, prompt, or subagent when Claude Code reaches a lifecycle event

26* **[Plugins](https://code.claude.com/docs/en/plugins/overview.md)** and **[marketplaces](https://code.claude.com/docs/en/plugins/overview.md)** package and distribute these features

2727

28[Skills](/docs/en/skills.md) are the most flexible extension. A skill is a markdown file containing knowledge, workflows, or instructions. You can invoke skills with a command like `/deploy`, or Claude can load them automatically when relevant. Skills can run in your current conversation or in an isolated context via subagents.

28[Skills](https://code.claude.com/docs/en/skills.md) are the most flexible extension. A skill is a markdown file containing knowledge, workflows, or instructions. You can invoke skills with a command like `/deploy`, or Claude can load them automatically when relevant. Skills can run in your current conversation or in an isolated context via subagents.

2929

3030## Match features to your goal

3131

from line 34

3535| - | - | - | - |

37| **[Output style](/docs/en/output-styles.md)** | Instructions that set Claude's role, tone, and response format for a whole session | A voice, length, or format you want in every response, or Claude working as something other than a software engineer | The built-in Concise style for shorter responses; a custom style that answers every question with a diagram first |

37| **[Output style](https://code.claude.com/docs/en/output-styles.md)** | Instructions that set Claude's role, tone, and response format for a whole session | A voice, length, or format you want in every response, or Claude working as something other than a software engineer | The built-in Concise style for shorter responses; a custom style that answers every question with a diagram first |

40| **[Dynamic workflow](/docs/en/workflows.md)** | Script Claude writes that runs many subagents in the background | Work that outgrows a handful of subagents, or findings you want cross-checked | Audit a whole codebase, with a second set of agents verifying each finding |

41| **[Cross-session messaging](/docs/en/cross-session-messaging.md)** | Claude delivers a message from one of your sessions to another | Sessions you run yourself that need each other's findings mid-task | One session warns another that a change it made breaks what the other is building on |

42| **[Code intelligence](/docs/en/tools-reference.md#lsp-tool-behavior)** | Language-server navigation and diagnostics | Typed languages, large codebases where grep is slow or imprecise | Jump to a symbol's definition instead of reading the whole file |

40| **[Dynamic workflow](https://code.claude.com/docs/en/workflows.md)** | Script Claude writes that runs many subagents in the background | Work that outgrows a handful of subagents, or findings you want cross-checked | Audit a whole codebase, with a second set of agents verifying each finding |

41| **[Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md)** | Claude delivers a message from one of your sessions to another | Sessions you run yourself that need each other's findings mid-task | One session warns another that a change it made breaks what the other is building on |

42| **[Code intelligence](https://code.claude.com/docs/en/tools-reference.md#lsp-tool-behavior)** | Language-server navigation and diagnostics | Typed languages, large codebases where grep is slow or imprecise | Jump to a symbol's definition instead of reading the whole file |

45| **[Artifact](/docs/en/artifacts.md)** | Publish session output as a private, interactive web page | Output you want to see or share visually rather than as terminal text | An incident timeline that updates as Claude investigates |

45| **[Artifact](https://code.claude.com/docs/en/artifacts.md)** | Publish session output as a private, interactive web page | Output you want to see or share visually rather than as terminal text | An incident timeline that updates as Claude investigates |

4646

47**[Plugins](/docs/en/plugins/overview.md)** are the packaging layer. A plugin bundles skills, hooks, subagents, and MCP servers into a single installable unit. Plugin skills are namespaced (like `/my-plugin:review`) so multiple plugins can coexist. Use plugins when you want to reuse the same setup across multiple repositories or distribute to others via a **[marketplace](/docs/en/plugins/overview.md)**.

47**[Plugins](https://code.claude.com/docs/en/plugins/overview.md)** are the packaging layer. A plugin bundles skills, hooks, subagents, and MCP servers into a single installable unit. Plugin skills are namespaced (like `/my-plugin:review`) so multiple plugins can coexist. Use plugins when you want to reuse the same setup across multiple repositories or distribute to others via a **[marketplace](https://code.claude.com/docs/en/plugins/overview.md)**.

4848

4949### Build your setup over time

5050

from line 52

5252

5353| Trigger | Add |

5454| :- | :- |

55| Claude gets a convention or command wrong twice | Add it to [CLAUDE.md](/docs/en/memory.md) |

56| You keep asking Claude to be shorter, explain more, or answer in the same format | Set an [output style](/docs/en/output-styles.md) |

57| You keep typing the same prompt to start a task | Save it as a user-invocable [skill](/docs/en/skills.md) |

58| You paste the same playbook or multi-step procedure into chat for the third time | Capture it as a [skill](/docs/en/skills.md) |

59| You keep copying data from a browser tab Claude can't see | Connect that system as an [MCP server](/docs/en/mcp.md) |

60| Claude reads many files to find where a symbol is defined or used | Install a [code intelligence plugin](/docs/en/plugins/code-intelligence.md) for your language |

61| A side task floods your conversation with output you won't reference again | Route it through a [subagent](/docs/en/sub-agents.md) |

62| You want something to happen every time without asking | Write a [hook](/docs/en/hooks-guide.md) |

63| A second repository needs the same setup | Package it as a [plugin](/docs/en/plugins/overview.md) |

55| Claude gets a convention or command wrong twice | Add it to [CLAUDE.md](https://code.claude.com/docs/en/memory.md) |

56| You keep asking Claude to be shorter, explain more, or answer in the same format | Set an [output style](https://code.claude.com/docs/en/output-styles.md) |

57| You keep typing the same prompt to start a task | Save it as a user-invocable [skill](https://code.claude.com/docs/en/skills.md) |

58| You paste the same playbook or multi-step procedure into chat for the third time | Capture it as a [skill](https://code.claude.com/docs/en/skills.md) |

59| You keep copying data from a browser tab Claude can't see | Connect that system as an [MCP server](https://code.claude.com/docs/en/mcp.md) |

60| Claude reads many files to find where a symbol is defined or used | Install a [code intelligence plugin](https://code.claude.com/docs/en/plugins/code-intelligence.md) for your language |

61| A side task floods your conversation with output you won't reference again | Route it through a [subagent](https://code.claude.com/docs/en/sub-agents.md) |

62| You want something to happen every time without asking | Write a [hook](https://code.claude.com/docs/en/hooks-guide.md) |

63| A second repository needs the same setup | Package it as a [plugin](https://code.claude.com/docs/en/plugins/overview.md) |

6464

6565The same triggers tell you when to update what you already have. A repeated mistake or a recurring review comment is a CLAUDE.md edit, not a one-off correction in chat. A workflow you keep tweaking by hand is a skill that needs another revision.

6666

from line 79

7979| - | - | - |

8080| **What it is** | Reusable instructions, knowledge, or workflows | Isolated worker with its own context |

8181| **Key benefit** | Share content across contexts | Context isolation. Work happens separately, only summary returns |

82| **[Context window](/docs/en/context-window.md) impact** | Adds to your main window | Uses a separate window with its own input and output tokens |

82| **[Context window](https://code.claude.com/docs/en/context-window.md) impact** | Adds to your main window | Uses a separate window with its own input and output tokens |

8383| **Best for** | Reference material, invocable workflows | Tasks that read many files, parallel work, specialized workers |

8484

8585**Skills can be reference or action.** Reference skills provide knowledge Claude uses throughout your session (like your API style guide). Action skills tell Claude to do something specific (like `/deploy` that runs your deployment workflow).

from line 86

8686

8787**Use a subagent** when you need context isolation or when your context window is getting full. The subagent might read dozens of files or run extensive searches, but your main conversation only receives a summary. Since subagent work doesn't consume your main context, this is also useful when you don't need the intermediate work to remain visible. Custom subagents can have their own instructions and can preload skills.

8888

89**They can combine.** A subagent can preload specific skills (`skills:` field). A skill can run in isolated context using `context: fork`. See [Skills](/docs/en/skills.md) for details.

89**They can combine.** A subagent can preload specific skills (`skills:` field). A skill can run in isolated context using `context: fork`. See [Skills](https://code.claude.com/docs/en/skills.md) for details.

9090

9191**CLAUDE.md vs Skill**

9292

from line 103

103103

104104**Put it in a skill** if it's reference material Claude needs sometimes (API docs, style guides) or a workflow you trigger with `/<name>` (deploy, review, release).

105105

106**Rule of thumb:** Keep CLAUDE.md under 200 lines. If it's growing, move reference content to skills or split into [`.claude/rules/`](/docs/en/memory#organize-rules-with-claude/rules/) files.

106**Rule of thumb:** Keep CLAUDE.md under 200 lines. If it's growing, move reference content to skills or split into [`.claude/rules/`](https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/) files.

107107

108108**CLAUDE.md vs Output style**

109109

from line 112

112112| Aspect | CLAUDE.md | Output style |

113113| - | - | - |

114114| **Holds** | Facts and rules about your project | A role, tone, and response format |

115| **Switching** | Always loaded | One active at a time; [switch styles](/docs/en/output-styles.md#change-your-output-style) whenever you want |

115| **Switching** | Always loaded | One active at a time; [switch styles](https://code.claude.com/docs/en/output-styles.md#change-your-output-style) whenever you want |

116116| **Best for** | Build commands, conventions, "never do X" rules | Shorter responses, explanations alongside code, a non-engineering role |

117117

118118**Put it in CLAUDE.md** if it's true of the project whatever style you're in: coding conventions, build commands, project structure.

119119

120**Use an output style** if it's about the response itself and you might want it off again: length, format, how much Claude explains, or a different role such as a writing assistant. Claude Code includes [built-in styles](/docs/en/output-styles.md#built-in-output-styles), and you can write your own.

120**Use an output style** if it's about the response itself and you might want it off again: length, format, how much Claude explains, or a different role such as a writing assistant. Claude Code includes [built-in styles](https://code.claude.com/docs/en/output-styles.md#built-in-output-styles), and you can write your own.

121121

122**They combine.** CLAUDE.md stays loaded whichever style you pick. Claude follows both as instructions, so neither is enforced. For anything that has to happen every time, use a [hook](/docs/en/hooks-guide.md).

123123

124124**CLAUDE.md vs Rules vs Skills**

125125

from line 133

133133

134134**Use CLAUDE.md** for instructions every session needs: build commands, test conventions, project architecture.

135135

136**Use rules** to keep CLAUDE.md focused. Rules with [`paths` frontmatter](/docs/en/memory#path-specific-rules) only load when Claude works with matching files, saving context.

136**Use rules** to keep CLAUDE.md focused. Rules with [`paths` frontmatter](https://code.claude.com/docs/en/memory#path-specific-rules) only load when Claude works with matching files, saving context.

137137

138138**Use skills** for content Claude only needs sometimes, like API documentation or a deployment checklist you trigger with `/<name>`.

139139

from line 142

142142Both do work outside your main conversation. With subagents, Claude decides turn by turn what runs next. In a workflow, the script decides:

143143

144144* **Subagents** are workers Claude spawns, each returning a summary to the conversation that spawned it

145* **[Dynamic workflows](/docs/en/workflows.md)** are scripts Claude writes that run many subagents in the background and return one result

145* **[Dynamic workflows](https://code.claude.com/docs/en/workflows.md)** are scripts Claude writes that run many subagents in the background and return one result

146146

147**Use a subagent** when you need a quick, focused worker: research a question, verify a claim, review a file. The subagent does the work and returns a summary, so your main conversation stays clean. Subagents that Claude [named](/docs/en/sub-agents.md#subagent-names) when it spawned them can also [message each other](/docs/en/sub-agents.md#what-loads-at-startup).

147**Use a subagent** when you need a quick, focused worker: research a question, verify a claim, review a file. The subagent does the work and returns a summary, so your main conversation stays clean. Subagents that Claude [named](https://code.claude.com/docs/en/sub-agents.md#subagent-names) when it spawned them can also [message each other](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup).

148148

149**Use a dynamic workflow** when a job [outgrows a handful of subagents](/docs/en/workflows.md#when-to-use-a-workflow), or when you want the findings cross-checked before you see them, such as a codebase-wide audit, a large migration, or a plan drafted from several angles. To start one, [ask for a workflow in your prompt](/docs/en/workflows.md#ask-for-a-workflow-in-your-prompt).

149**Use a dynamic workflow** when a job [outgrows a handful of subagents](https://code.claude.com/docs/en/workflows.md#when-to-use-a-workflow), or when you want the findings cross-checked before you see them, such as a codebase-wide audit, a large migration, or a plan drafted from several angles. To start one, [ask for a workflow in your prompt](https://code.claude.com/docs/en/workflows.md#ask-for-a-workflow-in-your-prompt).

150150

151**To pass a finding from one of your sessions to another**, ask the first session's Claude to send it. Claude delivers it with [cross-session messaging](/docs/en/cross-session-messaging.md). [Run agents in parallel](/docs/en/agents.md) compares the other ways to run more than one Claude at once, including sessions you hand off and check back on later.

151**To pass a finding from one of your sessions to another**, ask the first session's Claude to send it. Claude delivers it with [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md). [Run agents in parallel](https://code.claude.com/docs/en/agents.md) compares the other ways to run more than one Claude at once, including sessions you hand off and check back on later.

152152

153153**MCP vs Skill**

154154

from line 173

173173| Aspect | Hook | Skill |

174174| - | - | - |

175175| **Runs** | A shell command, HTTP request, MCP tool call, LLM prompt, or subagent | Instructions Claude reads and follows |

176| **Triggered by** | [Lifecycle events](/docs/en/hooks.md#hook-events) such as `PostToolUse` or `SessionStart` | You typing `/<name>`, or Claude matching the description to your task |

176| **Triggered by** | [Lifecycle events](https://code.claude.com/docs/en/hooks.md#hook-events) such as `PostToolUse` or `SessionStart` | You typing `/<name>`, or Claude matching the description to your task |

177177| **Determinism** | Fires on its event without Claude deciding | Claude interprets the instructions; outcome can vary |

178178| **Context cost** | Zero unless the hook returns output | Description loads each session; full content loads when used |

179179| **Best for** | Linting after edits, blocking unsafe commands, logging, notifications | Workflows that need reasoning, reference material, multi-step tasks |

from line 190

190190

191191Features can be defined at multiple levels: user-wide, per-project, via plugins, or through managed policies. You can also nest CLAUDE.md files in subdirectories or place skills in specific packages of a monorepo. When the same feature exists at multiple levels, here's how they layer:

192192

193* **CLAUDE.md files** are additive: all levels contribute content to Claude's context simultaneously. Files from your working directory and above load at launch; subdirectories load as you work in them. When instructions conflict, Claude uses judgment to reconcile them. See [how CLAUDE.md files load](/docs/en/memory.md#how-claude-md-files-load).

194* **Skills and subagents** override by name: when the same name exists at multiple levels, one definition wins based on priority (managed > user > project for skills; managed > CLI flag > project > user > plugin for subagents). Plugin skills are [namespaced](/docs/en/plugins/components.md#skills) to avoid conflicts. See [skill discovery](/docs/en/skills.md#resolve-skills-that-share-a-name) and [subagent scope](/docs/en/sub-agents.md#choose-the-subagent-scope).

195* **MCP servers** override by name: local > project > user. See [MCP scope](/docs/en/mcp.md#scope-hierarchy-and-precedence).

196* **Hooks** merge: all registered hooks fire for their matching events regardless of source. See [hooks](/docs/en/hooks.md).

194* **Skills and subagents** override by name: when the same name exists at multiple levels, one definition wins based on priority (managed > user > project for skills; managed > CLI flag > project > user > plugin for subagents). Plugin skills are [namespaced](https://code.claude.com/docs/en/plugins/components.md#skills) to avoid conflicts. See [skill discovery](https://code.claude.com/docs/en/skills.md#resolve-skills-that-share-a-name) and [subagent scope](https://code.claude.com/docs/en/sub-agents.md#choose-the-subagent-scope).

195* **MCP servers** override by name: local > project > user. See [MCP scope](https://code.claude.com/docs/en/mcp.md#scope-hierarchy-and-precedence).

196* **Hooks** merge: all registered hooks fire for their matching events regardless of source. See [hooks](https://code.claude.com/docs/en/hooks.md).

197197

198198### Combine features

199199

from line 210

210210

211211## Understand context costs

212212

213Every feature you add consumes some of Claude's context. Too much can fill up your context window, but it can also add noise that makes Claude less effective; skills may not trigger correctly, or Claude may lose track of your conventions. Understanding these trade-offs helps you build an effective setup. For an interactive view of how these features combine in a running session, see [Explore the context window](/docs/en/context-window.md).

214214

215215### Context cost by feature

216216

from line 223

226| **Subagents** | When spawned | Fresh context with specified skills, or the parent conversation for a [fork](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation) | Isolated from main session |

228228

229\*Set [`disable-model-invocation: true`](/docs/en/skills#control-who-invokes-a-skill) in a skill's frontmatter to keep its description out of Claude's context. For a skill you didn't write, set [`skillOverrides`](/docs/en/skills#override-skill-visibility-from-settings) in settings to do the same without editing its file.

229\*Set [`disable-model-invocation: true`](https://code.claude.com/docs/en/skills#control-who-invokes-a-skill) in a skill's frontmatter to keep its description out of Claude's context. For a skill you didn't write, set [`skillOverrides`](https://code.claude.com/docs/en/skills#override-skill-visibility-from-settings) in settings to do the same without editing its file.

230230

231231### Understand how features load

232232

from line 240

240240

241241**What loads:** Full content of each CLAUDE.md file that loads at session start (managed, user, and project levels).

242242

243**Inheritance:** Claude reads CLAUDE.md files from your working directory up to the root, and discovers nested ones in subdirectories as it accesses those files. See [How CLAUDE.md files load](/docs/en/memory.md#how-claude-md-files-load) for details. If a nested CLAUDE.md is over its [per-file size limit](/docs/en/memory.md#claude-ignores-the-end-of-my-subdirectory-claude-md), Claude receives only the start of the file.

243**Inheritance:** Claude reads CLAUDE.md files from your working directory up to the root, and discovers nested ones in subdirectories as it accesses those files. See [How CLAUDE.md files load](https://code.claude.com/docs/en/memory.md#how-claude-md-files-load) for details. If a nested CLAUDE.md is over its [per-file size limit](https://code.claude.com/docs/en/memory.md#claude-ignores-the-end-of-my-subdirectory-claude-md), Claude receives only the start of the file.

244244

245245> [!TIP]

246246>

247> Keep CLAUDE.md under 200 lines. Move reference material to skills, which load on demand. To get [trim proposals for a checked-in CLAUDE.md](/docs/en/memory.md#my-claude-md-is-too-large), run `/doctor`.

247> Keep CLAUDE.md under 200 lines. Move reference material to skills, which load on demand. To get [trim proposals for a checked-in CLAUDE.md](https://code.claude.com/docs/en/memory.md#my-claude-md-is-too-large), run `/doctor`.

248248

249249**Skills**

250250

251Skills are extra capabilities in Claude's toolkit. They can be reference material (like an API style guide) or invocable workflows you trigger with `/<name>` (like `/deploy`). Claude Code includes [bundled skills](/docs/en/commands.md) like `/code-review`, `/batch`, and `/debug` that work without setup. You can also create your own.

251Skills are extra capabilities in Claude's toolkit. They can be reference material (like an API style guide) or invocable workflows you trigger with `/<name>` (like `/deploy`). Claude Code includes [bundled skills](https://code.claude.com/docs/en/commands.md) like `/code-review`, `/batch`, and `/debug` that work without setup. You can also create your own.

252252

253253**When:** Depends on the skill's configuration. By default, descriptions load at session start and full content loads when used. For user-only skills (`disable-model-invocation: true`), nothing loads until you invoke them.

254254

from line 270

270270

271271**What loads:** Tool names and server instructions from connected servers. Full JSON schemas stay deferred until Claude needs a specific tool.

272272

273**Context cost:** [Tool search](/docs/en/mcp.md#scale-with-mcp-tool-search) is on by default, so idle MCP tools consume minimal context.

273**Context cost:** [Tool search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search) is on by default, so idle MCP tools consume minimal context.

274274

275275> [!TIP]

276276>

277> Run `/mcp` to see each server's connection status. Run `/context all` to see how many tokens each loaded MCP tool uses. Claude Code [reconnects to remote servers automatically](/docs/en/mcp.md#automatic-reconnection) if they drop, and you can disconnect servers you're not actively using.

277> Run `/mcp` to see each server's connection status. Run `/context all` to see how many tokens each loaded MCP tool uses. Claude Code [reconnects to remote servers automatically](https://code.claude.com/docs/en/mcp.md#automatic-reconnection) if they drop, and you can disconnect servers you're not actively using.

278278

279279**Code intelligence**

280280

from line 286

286286

287287> [!TIP]

288288>

289> The LSP tool is inactive until you install a [code intelligence plugin](/docs/en/plugins/code-intelligence.md) for your language.

289> The LSP tool is inactive until you install a [code intelligence plugin](https://code.claude.com/docs/en/plugins/code-intelligence.md) for your language.

290290

291291**Subagents**

292292

from line 296

296296

297297* The agent's own system prompt, not the Claude Code system prompt

298298* Full content of skills listed in the agent's `skills:` field

299* CLAUDE.md and git status. The built-in Explore and Plan agents [start with neither](/docs/en/sub-agents.md#what-loads-at-startup), and an agent whose definition sets [`omitClaudeMd`](/docs/en/sub-agents#supported-frontmatter-fields) starts without the user, project, and local CLAUDE.md files.

299* CLAUDE.md and git status. The built-in Explore and Plan agents [start with neither](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup), and an agent whose definition sets [`omitClaudeMd`](https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields) starts without the user, project, and local CLAUDE.md files.

300300* Whatever context the lead agent passes in the prompt

301301

302For a [fork](/docs/en/sub-agents.md#fork-the-current-conversation), Claude Code loads the parent's conversation so far, system prompt, and tools instead.

302For a [fork](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation), Claude Code loads the parent's conversation so far, system prompt, and tools instead.

303303

304304**Context cost:** Isolated from main session.

305305

from line 309

309309

310310**Hooks**

311311

312**When:** On trigger. Claude Code runs hooks at specific lifecycle events like tool execution, session boundaries, prompt submission, permission requests, and compaction. See [Hooks](/docs/en/hooks.md) for the full list.

313313

314314**What loads:** Nothing by default. Hooks execute outside the main conversation.

315315

from line 323

323323

324324Each feature has its own guide with setup instructions, examples, and configuration options.

325325

326> **[CLAUDE.md](/docs/en/memory.md)**

326> **[CLAUDE.md](https://code.claude.com/docs/en/memory.md)**

327327>

328328> Store project context, conventions, and instructions

329329

330> **[Skills](/docs/en/skills.md)**

330> **[Skills](https://code.claude.com/docs/en/skills.md)**

331331>

332332> Give Claude domain expertise and reusable workflows

333333

334> **[Subagents](/docs/en/sub-agents.md)**

334> **[Subagents](https://code.claude.com/docs/en/sub-agents.md)**

335335>

336336> Offload work to isolated context

337337

338> **[Dynamic workflows](/docs/en/workflows.md)**

338> **[Dynamic workflows](https://code.claude.com/docs/en/workflows.md)**

339339>

340340> Run many subagents from one script

341341

342> **[Cross-session messaging](/docs/en/cross-session-messaging.md)**

342> **[Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md)**

343343>

344344> Let Claude message your other sessions

345345

346> **[MCP](/docs/en/mcp.md)**

346> **[MCP](https://code.claude.com/docs/en/mcp.md)**

347347>

348348> Connect Claude to external services

349349

350> **[Hooks](/docs/en/hooks-guide.md)**

350> **[Hooks](https://code.claude.com/docs/en/hooks-guide.md)**

351351>

352352> Automate actions with hooks

353353

354> **[Plugins](/docs/en/plugins/overview.md)**

354> **[Plugins](https://code.claude.com/docs/en/plugins/overview.md)**

355355>

356356> Bundle and share feature sets

357357

358> **[Marketplaces](/docs/en/plugins/create-marketplace.md)**

358> **[Marketplaces](https://code.claude.com/docs/en/plugins/create-marketplace.md)**

359359>

360360> Host and distribute plugin collections

361361

fullscreen Changed · +29 / -29 lines

from line 16

1616

1717## Enable fullscreen rendering

1818

19Run `/tui fullscreen` inside any Claude Code conversation. The CLI saves the [`tui` setting](/docs/en/settings-reference#tui) and relaunches into fullscreen with your conversation intact, so you can switch mid-session without losing context. Run `/tui default` to switch back to the classic renderer, or `/tui` with no argument to print which renderer is active.

19Run `/tui fullscreen` inside any Claude Code conversation. The CLI saves the [`tui` setting](https://code.claude.com/docs/en/settings-reference#tui) and relaunches into fullscreen with your conversation intact, so you can switch mid-session without losing context. Run `/tui default` to switch back to the classic renderer, or `/tui` with no argument to print which renderer is active.

2020

21In [screen reader mode](/docs/en/accessibility.md), Claude Code always uses the classic renderer except in attached [background sessions](/docs/en/agent-view.md), which still render fullscreen. If you run `/tui fullscreen` in any other session, Claude Code prints an explanation instead of switching and doesn't change the saved `tui` setting.

21In [screen reader mode](https://code.claude.com/docs/en/accessibility.md), Claude Code always uses the classic renderer except in attached [background sessions](https://code.claude.com/docs/en/agent-view.md), which still render fullscreen. If you run `/tui fullscreen` in any other session, Claude Code prints an explanation instead of switching and doesn't change the saved `tui` setting.

2222

2323Claude Code carries these into the relaunched session:

2424

25* The conversation as it appears on screen. After a [`/rewind`](/docs/en/checkpointing#rewind-and-summarize), that means:

25* The conversation as it appears on screen. After a [`/rewind`](https://code.claude.com/docs/en/checkpointing#rewind-and-summarize), that means:

2626 * If you rewound earlier in the session, Claude Code relaunches from the rewound point, not from the longer transcript saved on disk. For example, if you rewound past your last three messages, the relaunched session opens without them

2727 * If you rewound to before your first message, Claude Code relaunches with an empty conversation

28* Your [permission mode](/docs/en/permission-modes.md) and [effort level](/docs/en/model-config.md#adjust-effort-level)

29* The model you last picked with [`/model`](/docs/en/model-config#setting-your-model)

30* Rules you passed with [`--allowed-tools` or `--disallowed-tools`](/docs/en/cli-reference#cli-flags), and your `--agent`, `--agents`, `--append-system-prompt`, and `--system-prompt-snapshot` flags

31* A `--chrome` or `--no-chrome` flag you launched with, so [Chrome integration](/docs/en/chrome.md) stays on or off as you chose for this session

28* Your [permission mode](https://code.claude.com/docs/en/permission-modes.md) and [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level)

29* The model you last picked with [`/model`](https://code.claude.com/docs/en/model-config#setting-your-model)

30* Rules you passed with [`--allowed-tools` or `--disallowed-tools`](https://code.claude.com/docs/en/cli-reference#cli-flags), and your `--agent`, `--agents`, `--append-system-prompt`, and `--system-prompt-snapshot` flags

31* A `--chrome` or `--no-chrome` flag you launched with, so [Chrome integration](https://code.claude.com/docs/en/chrome.md) stays on or off as you chose for this session

3232

3333Claude Code declines to relaunch if the session has a restriction it can't pass to the restarted process. Restrictions it can't pass include:

3434

35* Launch flags such as a [`--system-prompt`](/docs/en/cli-reference#cli-flags) replacement, a [`--tools`](/docs/en/cli-reference#cli-flags) allowlist, or [`--setting-sources`](/docs/en/cli-reference#cli-flags)

36* Deny or ask rules that a [hook or SDK permission update](/docs/en/hooks.md#permission-update-entries) added for this session only

35* Launch flags such as a [`--system-prompt`](https://code.claude.com/docs/en/cli-reference#cli-flags) replacement, a [`--tools`](https://code.claude.com/docs/en/cli-reference#cli-flags) allowlist, or [`--setting-sources`](https://code.claude.com/docs/en/cli-reference#cli-flags)

36* Deny or ask rules that a [hook or SDK permission update](https://code.claude.com/docs/en/hooks.md#permission-update-entries) added for this session only

3737

38In that case Claude Code prints [`Cannot switch renderers in this session`](/docs/en/errors#cannot-switch-renderers-in-this-session) with the reasons. It doesn't switch or save anything.

38In that case Claude Code prints [`Cannot switch renderers in this session`](https://code.claude.com/docs/en/errors#cannot-switch-renderers-in-this-session) with the reasons. It doesn't switch or save anything.

3939

4040You can also set the `CLAUDE_CODE_NO_FLICKER` environment variable before starting Claude Code:

4141

from line 43

4343CLAUDE_CODE_NO_FLICKER=1 claude

4444```

4545

46For how the [`tui`](/docs/en/settings-reference#tui) setting and the variable combine when both are set, see the setting's entry. After a [failed fullscreen start](#fullscreen-renderer-didnt-finish-starting), Claude Code still honors the variable but not the setting. The `/tui` command clears `CLAUDE_CODE_NO_FLICKER` from the relaunched process so the setting it writes takes effect.

46For how the [`tui`](https://code.claude.com/docs/en/settings-reference#tui) setting and the variable combine when both are set, see the setting's entry. After a [failed fullscreen start](#fullscreen-renderer-didnt-finish-starting), Claude Code still honors the variable but not the setting. The `/tui` command clears `CLAUDE_CODE_NO_FLICKER` from the relaunched process so the setting it writes takes effect.

4747

4848### Fullscreen by default

4949

50Attached [background sessions](/docs/en/agent-view.md) render fullscreen, and other sessions in [screen reader mode](/docs/en/accessibility.md) use the classic renderer. Otherwise, Claude Code starts you in the renderer from the first row of this table that matches your setup:

50Attached [background sessions](https://code.claude.com/docs/en/agent-view.md) render fullscreen, and other sessions in [screen reader mode](https://code.claude.com/docs/en/accessibility.md) use the classic renderer. Otherwise, Claude Code starts you in the renderer from the first row of this table that matches your setup:

5151

5252| Your situation | Renderer you start in |

5353| :- | :- |

54| You set [`CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`](/docs/en/env-vars) or `CLAUDE_CODE_NO_FLICKER=0` | Classic |

54| You set [`CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`](https://code.claude.com/docs/en/env-vars) or `CLAUDE_CODE_NO_FLICKER=0` | Classic |

5555| You set `CLAUDE_CODE_NO_FLICKER=1` | Fullscreen |

5656| Claude Code [turned fullscreen off after a failed fullscreen start](#fullscreen-renderer-didnt-finish-starting) on this machine | Classic |

5757| You're in iTerm2's [`tmux -CC` integration mode](#use-with-tmux), or you're connected over SSH to Claude Code running on Windows | Classic |

58| You saved a [`tui` setting](/docs/en/settings-reference#tui) | The renderer the setting names |

59| Your session doesn't [fetch feature flags from Anthropic](/docs/en/env-vars.md#features-that-need-feature-flag-fetching), and Claude Code has stopped offering the startup dialog on this machine | Classic |

58| You saved a [`tui` setting](https://code.claude.com/docs/en/settings-reference#tui) | The renderer the setting names |

59| Your session doesn't [fetch feature flags from Anthropic](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), and Claude Code has stopped offering the startup dialog on this machine | Classic |

6060| Your session doesn't fetch feature flags from Anthropic, and this machine's first Claude Code launch ran v2.1.239 or later | Fullscreen |

6161| Your session fetches feature flags from Anthropic, and you first used Claude Code on or after May 6, 2026 | Fullscreen |

6262| Anything else | Classic |

6363

64Sessions that don't fetch feature flags include those through [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), and those with telemetry turned off.

64Sessions that don't fetch feature flags include those through [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md), and those with telemetry turned off.

6565

6666If you start in the classic renderer and haven't saved a `tui` setting, Claude Code may open a dialog at startup offering the switch:

6767

from line 98

9898* **Click the `↑ N more` or `↓ N more` row at the edge of a list** to jump to that end of the list without choosing an option. Requires Claude Code v2.1.286 or later.

9999* **Click a collapsed tool result** to expand it and see the full output. Click again to collapse. The tool call and its result expand together. Only messages that have more to show are clickable.

100100 * Clicking also expands the output of a `!` shell command, whether an older truncated result or the live progress row while the command runs. Requires Claude Code v2.1.257 or later.

101 * Clicking also expands a dim `Message from @<sender>` line when the sender is a [teammate](/docs/en/agent-teams.md) or another agent running in your session.

101 * Clicking also expands a dim `Message from @<sender>` line when the sender is a [teammate](https://code.claude.com/docs/en/agent-teams.md) or another agent running in your session.

102102* **Hold `Cmd` on macOS, or `Ctrl` on Linux and Windows, and click a URL or file path** to open it. Plain `http://` and `https://` URLs open in your browser. When Claude Code handles the click, file paths in tool output, like the ones printed after an Edit or Write, open in your file manager with the file selected. A plain click without the modifier doesn't open links, matching native terminal behavior.

103103 * On Linux and WSL, clicking a file path needs a file manager that provides the `org.freedesktop.FileManager1` D-Bus interface. Without one, nothing opens.

104104 * Claude Code renders a network (UNC) path, such as `\\server\share\file.ts`, as plain text with no link, because opening a network path can send your Windows credentials to the host it names.

from line 118

118118* **`Esc`**: Claude Code performs the key's usual action, such as interrupting the running response or dismissing an open dialog, and the selection stays highlighted.

119119* **`PgUp`, `PgDn`, `Ctrl+Home`, `Ctrl+End`, or `Shift`, `Alt` or `Option`, or `Cmd`, `Win`, or `Super` with an arrow, `Home`, or `End` key**: the selection stays.

120120* **Any other key, including plain arrow keys, `Enter`, and typed characters**: Claude Code clears the selection.

121* **A key bound to [`selection:clear`](/docs/en/keybindings#scroll-actions)**: Claude Code clears the selection, even when the key is `Esc` or another key that otherwise keeps it. The action has no default binding.

121* **A key bound to [`selection:clear`](https://code.claude.com/docs/en/keybindings#scroll-actions)**: Claude Code clears the selection, even when the key is `Esc` or another key that otherwise keeps it. The action has no default binding.

122122

123123In [transcript mode](#search-and-review-the-conversation), the navigation keys listed there also keep the selection.

124124

from line 133

133133| `Ctrl+End` | Jump to the latest message and re-enable auto-follow |

134134| Mouse wheel | Scroll a few lines at a time |

135135

136If you close a [compacted](/docs/en/context-window.md#what-survives-compaction) session and [resume](/docs/en/sessions.md#what-a-resumed-session-restores) it, scrolling up stops at the `Conversation compacted` row, and your earlier messages stay on disk in the [transcript file](/docs/en/sessions.md#where-transcripts-are-stored). To get a detail from those messages, ask Claude to look it up in that file.

136If you close a [compacted](https://code.claude.com/docs/en/context-window.md#what-survives-compaction) session and [resume](https://code.claude.com/docs/en/sessions.md#what-a-resumed-session-restores) it, scrolling up stops at the `Conversation compacted` row, and your earlier messages stay on disk in the [transcript file](https://code.claude.com/docs/en/sessions.md#where-transcripts-are-stored). To get a detail from those messages, ask Claude to look it up in that file.

137137

138138On keyboards without dedicated `PgUp`, `PgDn`, `Home`, or `End` keys, like MacBook keyboards, hold `Fn` with the arrow keys: `Fn+↑` sends `PgUp`, `Fn+↓` sends `PgDn`, `Fn+←` sends `Home`, and `Fn+→` sends `End`. `Ctrl+Fn+→` doesn't reach Claude Code on macOS, so a MacBook keyboard has no working jump-to-bottom chord by default. Instead, use one of these options:

139139

from line 141

141141* Scroll to the bottom with the mouse wheel to resume following.

142142* Rebind `scroll:bottom` to a chord your keyboard can send.

143143

144These actions are rebindable. See [Scroll actions](/docs/en/keybindings.md#scroll-actions) for the full list of action names, including half-page and full-page variants that have no default binding.

144These actions are rebindable. See [Scroll actions](https://code.claude.com/docs/en/keybindings.md#scroll-actions) for the full list of action names, including half-page and full-page variants that have no default binding.

145145

146146While you're scrolled up, a dim header row at the top of the conversation shows the most recent prompt that has scrolled above the view. Click the row to jump to that prompt.

147147

from line 151

151151

152152While auto-follow is paused, the view also stays where you scrolled it when a response finishes streaming.

153153

154The button's keyboard hint reflects what your keyboard can send. On macOS it suggests clicking, or `Fn+↓` to scroll, because `Ctrl+End` doesn't reach Claude Code from a Mac keyboard. Rebind [`scroll:bottom`](/docs/en/keybindings#scroll-actions) and the button shows your chord on every platform.

154The button's keyboard hint reflects what your keyboard can send. On macOS it suggests clicking, or `Fn+↓` to scroll, because `Ctrl+End` doesn't reach Claude Code from a Mac keyboard. Rebind [`scroll:bottom`](https://code.claude.com/docs/en/keybindings#scroll-actions) and the button shows your chord on every platform.

155155

156156On a terminal too narrow for the full label, the button shortens the hint instead of wrapping onto the transcript row underneath.

157157

from line 175

175175

176176The command writes the same value the `CLAUDE_CODE_SCROLL_SPEED` environment variable sets, persisted to `~/.claude/settings.json`. The dialog's maximum is 10: if you set a higher value through the environment variable, the dialog shows 10, and saving from the dialog persists 10. The command isn't available in the JetBrains IDE terminal.

177177

178Separately from the base speed, Claude Code accelerates the scroll rate when you spin the wheel quickly, so a fast spin covers more distance than the same number of slow notches. To turn acceleration off and keep a constant rate per notch, set `wheelScrollAccelerationEnabled` to `false` in [`settings.json`](/docs/en/settings-reference#all-settings). This setting requires Claude Code v2.1.174 or later.

178Separately from the base speed, Claude Code accelerates the scroll rate when you spin the wheel quickly, so a fast spin covers more distance than the same number of slow notches. To turn acceleration off and keep a constant rate per notch, set `wheelScrollAccelerationEnabled` to `false` in [`settings.json`](https://code.claude.com/docs/en/settings-reference#all-settings). This setting requires Claude Code v2.1.174 or later.

179179

180180### Scroll in the JetBrains IDE terminal

181181

from line 209

209209

210210## Watch your changes in the diff panel

211211

212In fullscreen rendering, [`/diff`](/docs/en/interactive-mode#review-changes-with-%2Fdiff) opens a panel beside the conversation, so you can watch the changes accumulate while Claude works. [Diff panel](/docs/en/interactive-mode.md#diff-panel) covers what it shows, when it opens on its own, how to keep it closed, and how to change what it compares against.

212In fullscreen rendering, [`/diff`](https://code.claude.com/docs/en/interactive-mode#review-changes-with-%2Fdiff) opens a panel beside the conversation, so you can watch the changes accumulate while Claude works. [Diff panel](https://code.claude.com/docs/en/interactive-mode.md#diff-panel) covers what it shows, when it opens on its own, how to keep it closed, and how to change what it compares against.

213213

214214## Clear the conversation

215215

from line 247

247247

248248Inside tmux it also writes to the tmux paste buffer. Over SSH it falls back to OSC 52 escape sequences. Inside GNU screen, Claude Code copies long selections to the clipboard too. Before v2.1.219, if you copied a selection longer than roughly 570 characters, GNU screen printed base64 text into the window instead. Claude Code prints a toast after each copy telling you which path it used.

249249

250Some terminals block OSC 52 by default. iTerm2 blocks it until you turn on Settings → General → Selection → Applications in terminal may access clipboard; running [`/terminal-setup`](/docs/en/terminal-config) in iTerm2 enables this for you.

250Some terminals block OSC 52 by default. iTerm2 blocks it until you turn on Settings → General → Selection → Applications in terminal may access clipboard; running [`/terminal-setup`](https://code.claude.com/docs/en/terminal-config) in iTerm2 enables this for you.

251251

252252For a one-off native selection, the key to use depends on your terminal:

253253

from line 278

278278

279279Fullscreen rendering sends only the cells that changed between frames. Some terminals, most commonly Windows Terminal and other ConPTY-backed hosts, coalesce these positioned writes incorrectly and leave fragments of earlier output on screen until you resize the window.

280280

281Set [`CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1`](/docs/en/env-vars) to repaint every cell on every frame instead of sending incremental updates.

281Set [`CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1`](https://code.claude.com/docs/en/env-vars) to repaint every cell on every frame instead of sending incremental updates.

282282

283283On Windows PowerShell:

284284

from line 293

293293CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1 claude

294294```

295295

296On Windows, Claude Code already enables full repaint automatically for background sessions and [agent view](/docs/en/agent-view.md), so you only need to set the variable for an interactive fullscreen session you launched directly.

296On Windows, Claude Code already enables full repaint automatically for background sessions and [agent view](https://code.claude.com/docs/en/agent-view.md), so you only need to set the variable for an interactive fullscreen session you launched directly.

297297

298298### `Claude Code's fullscreen renderer didn't finish starting last time` appears at startup

299299

from line 323

323323

324324To turn fullscreen rendering off, run `/tui default`, or unset `CLAUDE_CODE_NO_FLICKER` if you enabled it that way. When you switch back with `/tui default`, Claude Code may first show an optional feedback prompt asking what made you switch. Type a reason and press `Enter` to send it, or press `Esc` to skip. The CLI relaunches into the classic renderer either way. To force the classic renderer regardless of the saved `tui` setting, set `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`. The classic renderer keeps the conversation in your terminal's native scrollback so `Cmd+f` and tmux copy mode work as usual.

325325

326Background sessions opened from [agent view](/docs/en/agent-view.md) or `claude attach` always use fullscreen rendering. The attaching terminal enters the alternate screen buffer to show the session, and the classic renderer has no scrollback or mouse handling there, so the `tui` setting and `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` don't apply to them.

326Background sessions opened from [agent view](https://code.claude.com/docs/en/agent-view.md) or `claude attach` always use fullscreen rendering. The attaching terminal enters the alternate screen buffer to show the session, and the classic renderer has no scrollback or mouse handling there, so the `tui` setting and `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` don't apply to them.

327327

gateways Changed · +18 / -18 lines

from line 4

55A gateway is a proxy your organization runs between Claude Code and a model provider. Claude Code sends API traffic to the gateway instead of directly to the provider, and the gateway forwards it using a credential your organization holds. Developers authenticate to the gateway rather than holding provider credentials, so authentication, usage tracking, budgets, and audit logging happen in one place you control.

7Claude Code includes a self-hosted gateway, [Claude apps gateway](/docs/en/claude-apps-gateway), in the `claude` binary, so you don't have to adopt a separate gateway product to run one. If your organization already runs an [LLM gateway](/docs/en/llm-gateway), Claude Code works with that too.

7Claude Code includes a self-hosted gateway, [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway), in the `claude` binary, so you don't have to adopt a separate gateway product to run one. If your organization already runs an [LLM gateway](https://code.claude.com/docs/en/llm-gateway), Claude Code works with that too.

99This page covers:

1010

from line 17

1717

1818Each developer's Claude Code sends its requests to the gateway's address and authenticates with a gateway-issued credential.

1919

20The gateway authenticates the developer, applies whatever access and budget rules you configure, and forwards the request to your provider with the organization's credential. The provider can be Anthropic's API or a [cloud provider](/docs/en/third-party-integrations.md) such as Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry; the gateway's configuration decides. With Claude apps gateway, or another gateway that exposes a single Anthropic-format endpoint, changing provider doesn't require touching developer machines.

20The gateway authenticates the developer, applies whatever access and budget rules you configure, and forwards the request to your provider with the organization's credential. The provider can be Anthropic's API or a [cloud provider](https://code.claude.com/docs/en/third-party-integrations.md) such as Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry; the gateway's configuration decides. With Claude apps gateway, or another gateway that exposes a single Anthropic-format endpoint, changing provider doesn't require touching developer machines.

2121

2222![Diagram showing Claude Code routing through a gateway. In a developer machines zone, the Claude Code CLI and VS Code extension send requests to the gateway address with a per-developer credential. In a zone labeled your infrastructure, the gateway handles authentication, usage tracking, budgets, and routing, and forwards requests with your organization's credential. In a model providers zone, a solid arrow leads to the provider you configure, shown as the Anthropic API, and dashed arrows lead to other provider options, illustrated with Amazon Bedrock, Google Cloud, and Microsoft Foundry as examples.](https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/llm-gateway-flow.svg?fit=max\&auto=format\&n=-uq-4JE0W_JO5Er5\&q=85\&s=1c1a8dcc0cfcc3a58652cc8e28cd3e20)

2323

from line 32

3232

3333### Claude apps gateway

3434

35Claude apps gateway is Anthropic's self-hosted gateway, included in the `claude` binary. It routes to Amazon Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry, or the Anthropic API as the upstream. Developers sign in with your corporate identity provider through `/login`, the gateway enforces model access and [managed settings](/docs/en/managed-settings.md) by IdP group, and it emits [OpenTelemetry Protocol (OTLP)](/docs/en/monitoring-usage.md) usage metrics to your own observability stack.

35Claude apps gateway is Anthropic's self-hosted gateway, included in the `claude` binary. It routes to Amazon Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry, or the Anthropic API as the upstream. Developers sign in with your corporate identity provider through `/login`, the gateway enforces model access and [managed settings](https://code.claude.com/docs/en/managed-settings.md) by IdP group, and it emits [OpenTelemetry Protocol (OTLP)](https://code.claude.com/docs/en/monitoring-usage.md) usage metrics to your own observability stack.

3636

37Because it is built and tested alongside each Claude Code release, it forwards the `anthropic-beta` values and request fields Claude Code sends. A gateway maintained separately needs its [forwarding rules updated](/docs/en/llm-gateway-protocol.md#forward-as-open-lists) as those change with each release; Claude apps gateway releases with the CLI, so there is no list to keep current. See [Availability and limitations](/docs/en/claude-apps-gateway#availability-and-limitations) for the small set of features that behave differently on a gateway session.

37Because it is built and tested alongside each Claude Code release, it forwards the `anthropic-beta` values and request fields Claude Code sends. A gateway maintained separately needs its [forwarding rules updated](https://code.claude.com/docs/en/llm-gateway-protocol.md#forward-as-open-lists) as those change with each release; Claude apps gateway releases with the CLI, so there is no list to keep current. See [Availability and limitations](https://code.claude.com/docs/en/claude-apps-gateway#availability-and-limitations) for the small set of features that behave differently on a gateway session.

3838

39The gateway sign-in is a browser SSO step, and there is no service-token flow, so a CI pipeline with no developer to approve the sign-in can't authenticate through it; configure those against your provider directly. Agent SDK sessions and `claude -p` runs on a machine where a developer has signed in use that machine's gateway session and are governed by its policies. See [CI pipelines and remote machines](/docs/en/claude-apps-gateway#ci-pipelines-and-remote-machines).

39The gateway sign-in is a browser SSO step, and there is no service-token flow, so a CI pipeline with no developer to approve the sign-in can't authenticate through it; configure those against your provider directly. Agent SDK sessions and `claude -p` runs on a machine where a developer has signed in use that machine's gateway session and are governed by its policies. See [CI pipelines and remote machines](https://code.claude.com/docs/en/claude-apps-gateway#ci-pipelines-and-remote-machines).

4040

41See [Claude apps gateway](/docs/en/claude-apps-gateway) to deploy it.

41See [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) to deploy it.

4242

4343### Other gateways

4444

45If your organization already runs an LLM gateway or API gateway, you can use it instead. Anthropic doesn't endorse, maintain, or audit other gateway products, and doesn't support routing Claude Code to non-Claude models through any gateway. See [Other LLM gateways](/docs/en/llm-gateway) for the admin rollout checklist, what a gateway must implement, and how to point Claude Code at it.

45If your organization already runs an LLM gateway or API gateway, you can use it instead. Anthropic doesn't endorse, maintain, or audit other gateway products, and doesn't support routing Claude Code to non-Claude models through any gateway. See [Other LLM gateways](https://code.claude.com/docs/en/llm-gateway) for the admin rollout checklist, what a gateway must implement, and how to point Claude Code at it.

4646

4747## Subscriptions and gateways

4848

49When developers connect through a gateway with a gateway credential, usage is billed to your organization's provider account at API rates, and their claude.ai subscriptions aren't used or charged. Setting [`ANTHROPIC_AUTH_TOKEN`](/docs/en/env-vars) for a gateway you run, or signing in to a Claude apps gateway with `/login`, turns off subscription login for that session. Every request forwarded under that credential is charged to the account behind the gateway's provider credential.

49When developers connect through a gateway with a gateway credential, usage is billed to your organization's provider account at API rates, and their claude.ai subscriptions aren't used or charged. Setting [`ANTHROPIC_AUTH_TOKEN`](https://code.claude.com/docs/en/env-vars) for a gateway you run, or signing in to a Claude apps gateway with `/login`, turns off subscription login for that session. Every request forwarded under that credential is charged to the account behind the gateway's provider credential.

5050

51The exception is setting only `ANTHROPIC_BASE_URL`, with no gateway credential. Requests still route through the gateway, but a saved claude.ai login stays the active credential, so the subscription's usage limits and billing apply. [Other LLM gateways](/docs/en/llm-gateway#subscriptions-and-gateways) covers that configuration and what the gateway has to forward for it to work.

51The exception is setting only `ANTHROPIC_BASE_URL`, with no gateway credential. Requests still route through the gateway, but a saved claude.ai login stays the active credential, so the subscription's usage limits and billing apply. [Other LLM gateways](https://code.claude.com/docs/en/llm-gateway#subscriptions-and-gateways) covers that configuration and what the gateway has to forward for it to work.

5252

5353## Configure separately from the gateway

5454

5555A gateway routes model API requests. A few things you might expect it to handle are configured elsewhere:

5656

57* **Which model answers**: pick the model with the `/model` command or [model environment variables](/docs/en/model-config.md#setting-your-model). The gateway decides where requests go, not which model the developer selects. Claude apps gateway can bound the choice with a per-group `availableModels` allowlist, but the developer still picks within it.

58* **Other network traffic**: Claude Code itself sends version checks and downloads directly to Anthropic, separate from the gateway path. Your network still needs egress to the [required domains](/docs/en/network-config.md), or set [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/en/env-vars) to turn off the optional streams.

59* **Client telemetry**: Claude Code disables its Anthropic-bound client analytics when a session signs in to a Claude apps gateway. To keep pre-sign-in startup analytics off as well, deliver [`DISABLE_TELEMETRY`](/docs/en/managed-settings#turn-telemetry-off-for-your-organization) in the [client-side managed settings](/docs/en/claude-apps-gateway-config.md#client-side-managed-settings) on each device.

60* **Client telemetry on other gateways**: whether Claude Code sends the optional client telemetry stream depends on your provider, and the [telemetry defaults table](/docs/en/data-usage.md#default-behaviors-by-api-provider) covers each case.

61* **Telemetry destinations**: where Claude Code sends a gateway session's telemetry depends on how the session signed in, and [What's enforced on developers](/docs/en/claude-apps-gateway#whats-enforced-on-developers) says where each kind of session's exports go.

62* **Corporate HTTP proxies**: an `HTTPS_PROXY` sits between Claude Code and every server it talks to, including the gateway. If your network requires one, [configure the proxy](/docs/en/network-config.md) in addition to the gateway. For a Claude apps gateway you host, [sign-in checks that the proxy host is also on a private network](/docs/en/claude-apps-gateway#prerequisites); if it isn't, add the gateway host to `NO_PROXY` so the CLI connects to it directly.

57* **Which model answers**: pick the model with the `/model` command or [model environment variables](https://code.claude.com/docs/en/model-config.md#setting-your-model). The gateway decides where requests go, not which model the developer selects. Claude apps gateway can bound the choice with a per-group `availableModels` allowlist, but the developer still picks within it.

58* **Other network traffic**: Claude Code itself sends version checks and downloads directly to Anthropic, separate from the gateway path. Your network still needs egress to the [required domains](https://code.claude.com/docs/en/network-config.md), or set [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/en/env-vars) to turn off the optional streams.

59* **Client telemetry**: Claude Code disables its Anthropic-bound client analytics when a session signs in to a Claude apps gateway. To keep pre-sign-in startup analytics off as well, deliver [`DISABLE_TELEMETRY`](https://code.claude.com/docs/en/managed-settings#turn-telemetry-off-for-your-organization) in the [client-side managed settings](https://code.claude.com/docs/en/claude-apps-gateway-config.md#client-side-managed-settings) on each device.

60* **Client telemetry on other gateways**: whether Claude Code sends the optional client telemetry stream depends on your provider, and the [telemetry defaults table](https://code.claude.com/docs/en/data-usage.md#default-behaviors-by-api-provider) covers each case.

61* **Telemetry destinations**: where Claude Code sends a gateway session's telemetry depends on how the session signed in, and [What's enforced on developers](https://code.claude.com/docs/en/claude-apps-gateway#whats-enforced-on-developers) says where each kind of session's exports go.

62* **Corporate HTTP proxies**: an `HTTPS_PROXY` sits between Claude Code and every server it talks to, including the gateway. If your network requires one, [configure the proxy](https://code.claude.com/docs/en/network-config.md) in addition to the gateway. For a Claude apps gateway you host, [sign-in checks that the proxy host is also on a private network](https://code.claude.com/docs/en/claude-apps-gateway#prerequisites); if it isn't, add the gateway host to `NO_PROXY` so the CLI connects to it directly.

6363

6464## Next steps

6565

6666The next page depends on who runs the gateway. Anthropic's gateway runs from the `claude` binary and has its own setup guide; a gateway your organization already runs has a compatibility guide to follow and an admin rollout checklist.

6767

68* [Claude apps gateway](/docs/en/claude-apps-gateway) to deploy Anthropic's self-hosted gateway with SSO sign-in and OTLP telemetry

69* [Other LLM gateways](/docs/en/llm-gateway) for what a gateway your organization already runs must implement, and how to point Claude Code at it

70* [Set up Claude Code for your organization](/docs/en/admin-setup.md) for the wider rollout decisions a gateway is one part of

68* [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) to deploy Anthropic's self-hosted gateway with SSO sign-in and OTLP telemetry

69* [Other LLM gateways](https://code.claude.com/docs/en/llm-gateway) for what a gateway your organization already runs must implement, and how to point Claude Code at it

70* [Set up Claude Code for your organization](https://code.claude.com/docs/en/admin-setup.md) for the wider rollout decisions a gateway is one part of

7171

github-actions Changed · +25 / -25 lines

from line 6

77Several products share the Claude Code name. This page covers the `claude-code-action` workflow integration, which you configure with workflow files in your repository. For the related products, see:

9* [Code Review](/docs/en/code-review.md): automatic review on every pull request, without writing a workflow

10* [Claude Code in the cloud](/docs/en/claude-code-on-the-web.md): Claude Code sessions that run on cloud infrastructure instead of your machine

11* [Claude Agent SDK](/docs/en/agent-sdk/overview.md): custom automation outside GitHub Actions. The Claude Code GitHub Action is built on the SDK

12* [GitHub Enterprise Server](/docs/en/github-enterprise-server.md): Claude Code with self-hosted GitHub

9* [Code Review](https://code.claude.com/docs/en/code-review.md): automatic review on every pull request, without writing a workflow

10* [Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md): Claude Code sessions that run on cloud infrastructure instead of your machine

11* [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md): custom automation outside GitHub Actions. The Claude Code GitHub Action is built on the SDK

12* [GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server.md): Claude Code with self-hosted GitHub

1313

1414## Setup

1515

from line 22

2222

2323### Quick setup

2424

25`/install-github-app` works only with github.com repositories. If your repository's git remote is on gitlab.com or bitbucket.org, the command prints a notice and exits instead of starting setup. To run Claude Code from GitLab pipelines, see [Claude Code GitLab CI/CD](/docs/en/gitlab-ci-cd.md).

2626

2727Before you start, install the [GitHub CLI](https://cli.github.com) and authenticate it with `gh auth login`. Claude Code checks for it and warns you if it's missing.

2828

from line 49

4949> [!NOTE]

5050>

5151> * When you install the GitHub App, you grant it several permissions. See [GitHub App permissions](#github-app-permissions) for the full set

52> * Quick setup works with the Claude API and Claude subscriptions. If you use Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, see [Use Claude Code GitHub Actions with cloud providers](/docs/en/github-actions-cloud-providers.md)

5353

5454### Manual setup

5555

from line 70

7070Add one of the following secrets to your repository, depending on how you authenticate. See GitHub's guide to [using secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).

7171

7272* `ANTHROPIC_API_KEY`: a Claude API key from the [Claude Console](https://platform.claude.com)

73* `CLAUDE_CODE_OAUTH_TOKEN`: an OAuth token that authenticates with your Claude subscription, available on Pro, Max, Team, and Enterprise plans. Generate one by running `claude setup-token` locally. See [Generate a long-lived token](/docs/en/authentication.md#generate-a-long-lived-token)

73* `CLAUDE_CODE_OAUTH_TOKEN`: an OAuth token that authenticates with your Claude subscription, available on Pro, Max, Team, and Enterprise plans. Generate one by running `claude setup-token` locally. See [Generate a long-lived token](https://code.claude.com/docs/en/authentication.md#generate-a-long-lived-token)

7474

7575In workflow files, pass the secret to the matching input: `anthropic_api_key` for an API key, or `claude_code_oauth_token` for an OAuth token.

7676

from line 101

101101

102102Grant the workflow the `id-token: write` permission, which the Claude Code GitHub Action needs for the federation exchange even when you pass your own `github_token`. See the [Claude Code GitHub Action's setup guide](https://github.com/anthropics/claude-code-action/blob/main/docs/setup.md) for the Console-side configuration.

103103

104For data handling and retention questions in a security review, see [data usage](/docs/en/data-usage.md) and [security](/docs/en/security.md).

104For data handling and retention questions in a security review, see [data usage](https://code.claude.com/docs/en/data-usage.md) and [security](https://code.claude.com/docs/en/security.md).

105105

106106### Uninstall

107107

from line 111

111111* **Secrets**: delete the `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` secret from the repository, and from organization-level Actions secrets if you [shared it across repositories](#set-up-for-an-organization). If you delete a secret, the credential it held stays valid. To retire an API key entirely, also delete the key in the [Claude Console](https://platform.claude.com)

112112* **GitHub App**: uninstall the Claude GitHub App in your repository or organization settings under GitHub Apps, but only if you don't use it for another Claude feature, such as Code Review or web auto-fix

113113

114If you configured a [cloud provider](/docs/en/github-actions-cloud-providers.md), also delete the provider secrets, such as `AWS_ROLE_TO_ASSUME`, the `GCP_*` secrets, or the `AZURE_*` secrets, and uninstall the custom GitHub App along with its `APP_ID` and `APP_PRIVATE_KEY` secrets.

114If you configured a [cloud provider](https://code.claude.com/docs/en/github-actions-cloud-providers.md), also delete the provider secrets, such as `AWS_ROLE_TO_ASSUME`, the `GCP_*` secrets, or the `AZURE_*` secrets, and uninstall the custom GitHub App along with its `APP_ID` and `APP_PRIVATE_KEY` secrets.

115115

116116### GitHub App permissions

117117

118The [Claude GitHub App](https://github.com/apps/claude) is shared by every Claude feature that integrates with GitHub, including the Claude Code GitHub Action, [Code Review](/docs/en/code-review.md), and [auto-fix for pull requests](/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests) in cloud sessions. A GitHub App has a single permission set covering all of its features, so the set includes some permissions that the Claude Code GitHub Action doesn't use.

118The [Claude GitHub App](https://github.com/apps/claude) is shared by every Claude feature that integrates with GitHub, including the Claude Code GitHub Action, [Code Review](https://code.claude.com/docs/en/code-review.md), and [auto-fix for pull requests](https://code.claude.com/docs/en/claude-code-on-the-web.md#auto-fix-pull-requests) in cloud sessions. A GitHub App has a single permission set covering all of its features, so the set includes some permissions that the Claude Code GitHub Action doesn't use.

119119

120120When you install the app, you grant the following permissions:

121121

from line 210

210210

211211### Run a skill

212212

213The `prompt` input accepts a [skill](/docs/en/skills.md) invocation as well as plain text:

213The `prompt` input accepts a [skill](https://code.claude.com/docs/en/skills.md) invocation as well as plain text:

214214

215215* For a skill in your repository's `.claude/skills/` directory, run `actions/checkout` before the `anthropics/claude-code-action` step so the skill files are available on the runner, then pass `/skill-name` as the `prompt`.

216* For a skill packaged in a [plugin](/docs/en/plugins/overview.md), install the plugin with the `plugin_marketplaces` and `plugins` inputs, then pass the namespaced `/plugin-name:skill-name` as the `prompt`. The `plugins` input takes `plugin-name@marketplace-name`, where the marketplace name comes from the marketplace's own manifest rather than its repository URL.

216* For a skill packaged in a [plugin](https://code.claude.com/docs/en/plugins/overview.md), install the plugin with the `plugin_marketplaces` and `plugins` inputs, then pass the namespaced `/plugin-name:skill-name` as the `prompt`. The `plugins` input takes `plugin-name@marketplace-name`, where the marketplace name comes from the marketplace's own manifest rather than its repository URL.

217217

218The following workflow installs the `code-review` plugin and runs its skill when a pull request is opened, updated, reopened, or marked ready for review. It runs the same plugin as the review workflow from quick setup. Use a workflow like this when you want to control the prompt, model, and triggers yourself. For automatic reviews without maintaining a workflow file, see [Code Review](/docs/en/code-review.md). On public repositories, GitHub withholds secrets from runs triggered by fork pull requests, so the review runs only on pull requests from branches in the same repository.

218The following workflow installs the `code-review` plugin and runs its skill when a pull request is opened, updated, reopened, or marked ready for review. It runs the same plugin as the review workflow from quick setup. Use a workflow like this when you want to control the prompt, model, and triggers yourself. For automatic reviews without maintaining a workflow file, see [Code Review](https://code.claude.com/docs/en/code-review.md). On public repositories, GitHub withholds secrets from runs triggered by fork pull requests, so the review runs only on pull requests from branches in the same repository.

219219

220220```yaml theme={null}

221221name: Code Review

from line 252

252252

253253### Run on a schedule

254254

255With a `prompt` input, the Claude Code GitHub Action runs in automation mode on any GitHub event, including a cron schedule. For a plain-text prompt, Claude has no shell or GitHub API access until you grant the tools the prompt needs, with `--allowedTools` in `claude_args` or a [`permissions.allow` rule](/docs/en/permissions#permission-rule-syntax) in the `settings` input. If you invoke a skill instead, Claude can use the tools its [`allowed-tools` frontmatter](/docs/en/skills#pre-approve-tools-for-a-skill) grants. GitHub runs scheduled workflows only from the default branch and, in public repositories, disables the schedule after 60 days without repository activity.

255With a `prompt` input, the Claude Code GitHub Action runs in automation mode on any GitHub event, including a cron schedule. For a plain-text prompt, Claude has no shell or GitHub API access until you grant the tools the prompt needs, with `--allowedTools` in `claude_args` or a [`permissions.allow` rule](https://code.claude.com/docs/en/permissions#permission-rule-syntax) in the `settings` input. If you invoke a skill instead, Claude can use the tools its [`allowed-tools` frontmatter](https://code.claude.com/docs/en/skills#pre-approve-tools-for-a-skill) grants. GitHub runs scheduled workflows only from the default branch and, in public repositories, disables the schedule after 60 days without repository activity.

256256

257257This workflow generates a report in the workflow run log at 09:00 UTC each day. Its `claude_args` line [passes CLI arguments](#pass-cli-arguments) that select the model and allow two GitHub MCP tools. Claude reads commits and issues through the GitHub API with those tools, so you can omit the checkout step:

258258

from line 282

282282

283283### Define project standards in CLAUDE.md

284284

285Create a `CLAUDE.md` file in your repository root to define code style guidelines, review criteria, project-specific rules, and preferred patterns. Claude follows these guidelines when creating PRs and responding to requests. See the [memory documentation](/docs/en/memory.md) for details.

286286

287287### Protect your credentials

288288

from line 310

310310* Set workflow-level timeouts to avoid runaway jobs

311311* Use GitHub's concurrency controls to limit parallel runs

312312

313For usage tracking across your organization, see the [analytics dashboard](/docs/en/analytics.md) and [monitoring](/docs/en/monitoring-usage.md). For how usage is measured and billed, see [costs](/docs/en/costs.md).

313For usage tracking across your organization, see the [analytics dashboard](https://code.claude.com/docs/en/analytics.md) and [monitoring](https://code.claude.com/docs/en/monitoring-usage.md). For how usage is measured and billed, see [costs](https://code.claude.com/docs/en/costs.md).

314314

315315## Use a cloud provider

316316

317By default, the Claude Code GitHub Action calls the Claude API directly with your API key or OAuth token. To route inference through your own cloud account instead, set the input for your provider and follow [Use Claude Code GitHub Actions with cloud providers](/docs/en/github-actions-cloud-providers.md):

318318

319319* **Amazon Bedrock**: `use_bedrock: "true"`

320320* **Google Cloud's Agent Platform**: `use_vertex: "true"`

from line 340

340340### Authentication errors

341341

342342* Confirm the API key or OAuth token is valid by testing it locally with `claude` before debugging the workflow

343* For Bedrock, Agent Platform, and Foundry, see the cloud provider page's [troubleshooting section](/docs/en/github-actions-cloud-providers.md#troubleshooting)

343* For Bedrock, Agent Platform, and Foundry, see the cloud provider page's [troubleshooting section](https://code.claude.com/docs/en/github-actions-cloud-providers.md#troubleshooting)

344344

345345For more solutions, see the Claude Code GitHub Action's [FAQ](https://github.com/anthropics/claude-code-action/blob/main/docs/faq.md).

346346

from line 352

352352

353353| Parameter | Description | Required |

354354| - | - | - |

355| `prompt` | Instructions for Claude, as plain text or a [skill](/docs/en/skills.md) invocation. When omitted, Claude responds to the [trigger phrase](#interactive-and-automation-modes) instead | No |

355| `prompt` | Instructions for Claude, as plain text or a [skill](https://code.claude.com/docs/en/skills.md) invocation. When omitted, Claude responds to the [trigger phrase](#interactive-and-automation-modes) instead | No |

356356| `claude_args` | CLI arguments passed to Claude Code | No |

357357| `anthropic_api_key` | Claude API key | For the Claude API, unless you use `claude_code_oauth_token` or [workload identity federation](#set-up-for-an-organization). Not used for Bedrock, Agent Platform, or Foundry |

358358| `claude_code_oauth_token` | OAuth token for authenticating with a Claude subscription, generated with `claude setup-token` | No |

from line 369

369369

370370### Pass CLI arguments

371371

372The `claude_args` parameter accepts any [Claude Code CLI argument](/docs/en/cli-reference.md):

372The `claude_args` parameter accepts any [Claude Code CLI argument](https://code.claude.com/docs/en/cli-reference.md):

373373

374374```yaml theme={null}

375375claude_args: "--max-turns 5 --model claude-sonnet-5 --mcp-config /path/to/config.json"

from line 378

378378Common arguments:

379379

380380* `--max-turns`: limit the number of conversation turns

381* `--model`: model to use, for example `claude-sonnet-5`. Without this argument, the Claude Code GitHub Action uses the Claude Code [default model](/docs/en/model-config.md)

382* `--mcp-config`: path to [MCP configuration](/docs/en/mcp.md)

381* `--model`: model to use, for example `claude-sonnet-5`. Without this argument, the Claude Code GitHub Action uses the Claude Code [default model](https://code.claude.com/docs/en/model-config.md)

382* `--mcp-config`: path to [MCP configuration](https://code.claude.com/docs/en/mcp.md)

383383* `--allowedTools`: comma-separated list of allowed tools. The `--allowed-tools` alias also works

384384* `--debug`: enable debug output

385385

from line 396

396396

397397## What's next

398398

399* [Use Claude Code GitHub Actions with cloud providers](/docs/en/github-actions-cloud-providers.md): route inference through Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry

399* [Use Claude Code GitHub Actions with cloud providers](https://code.claude.com/docs/en/github-actions-cloud-providers.md): route inference through Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry

400400* [Configuration reference](https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md#inputs): the full list of action inputs

401401* [Examples directory](https://github.com/anthropics/claude-code-action/tree/main/examples): ready-to-use workflows for more scenarios

402* [Code Review](/docs/en/code-review.md): automatic pull request review without maintaining a workflow file

402* [Code Review](https://code.claude.com/docs/en/code-review.md): automatic pull request review without maintaining a workflow file

403403

github-actions-cloud-providers Changed · +17 / -17 lines

from line 2

33> Run Claude Code GitHub Actions through Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry instead of the Claude API

5[Claude Code GitHub Actions](/docs/en/github-actions.md) calls the Claude API by default. To route inference through your own cloud account instead, set the Claude Code GitHub Action's provider input and configure your cloud to trust the workflow's OpenID Connect (OIDC) token. The workflow authenticates with that token, so you store no long-lived cloud credential in your repository.

5[Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions.md) calls the Claude API by default. To route inference through your own cloud account instead, set the Claude Code GitHub Action's provider input and configure your cloud to trust the workflow's OpenID Connect (OIDC) token. The workflow authenticates with that token, so you store no long-lived cloud credential in your repository.

77> [!NOTE]

88>

9> This page builds on the [GitHub Actions setup](/docs/en/github-actions.md#setup). It assumes you already know the workflow file and the `anthropics/claude-code-action` step, and covers only what a cloud provider changes.

9> This page builds on the [GitHub Actions setup](https://code.claude.com/docs/en/github-actions.md#setup). It assumes you already know the workflow file and the `anthropics/claude-code-action` step, and covers only what a cloud provider changes.

1010

1111## Choose your provider

1212

from line 25

2525* Admin access to the repository where the Claude Code GitHub Action runs, to install a GitHub App and add secrets

2626* Permission to create identity resources in your cloud account: IAM roles and OIDC identity providers on AWS, Workload Identity Federation resources and service accounts on Google Cloud, or Microsoft Entra applications on Azure

2727* Claude model access on your provider:

28 * **Amazon Bedrock**: access granted to Claude models. Cross-region inference profiles, such as the `us.` model IDs in this page's examples, need access granted in every region of their region group. See [Claude Code on Amazon Bedrock](/docs/en/amazon-bedrock.md)

29 * **Google Cloud's Agent Platform**: a project with the Agent Platform API enabled and access to Claude models. See [Claude Code on Google Cloud's Agent Platform](/docs/en/google-vertex-ai.md)

30 * **Microsoft Foundry**: a Foundry resource with a Claude model deployment. See [Claude Code on Microsoft Foundry](/docs/en/microsoft-foundry.md)

29 * **Google Cloud's Agent Platform**: a project with the Agent Platform API enabled and access to Claude models. See [Claude Code on Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md)

30 * **Microsoft Foundry**: a Foundry resource with a Claude model deployment. See [Claude Code on Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md)

3131

3232## Set up the integration

3333

from line 35

3535

3636**1. Choose a GitHub identity**

3737

38The Claude Code GitHub Action pushes commits and posts comments through a GitHub identity. The [quick setup](/docs/en/github-actions.md#quick-setup) installs the official Claude GitHub App for this. With a cloud provider, you choose the identity yourself:

38The Claude Code GitHub Action pushes commits and posts comments through a GitHub identity. The [quick setup](https://code.claude.com/docs/en/github-actions.md#quick-setup) installs the official Claude GitHub App for this. With a cloud provider, you choose the identity yourself:

3939

4040* **Official [Claude GitHub App](https://github.com/apps/claude)**: install it on the repository, or skip to the next step if it's already installed

41* **Custom GitHub App**: create your own app when you want only the three permissions the Claude Code GitHub Action uses rather than the [official app's full set](/docs/en/github-actions.md#github-app-permissions)

41* **Custom GitHub App**: create your own app when you want only the three permissions the Claude Code GitHub Action uses rather than the [official app's full set](https://code.claude.com/docs/en/github-actions.md#github-app-permissions)

4242* **GitHub's automatic `GITHUB_TOKEN`**: no app to create or install, but GitHub doesn't trigger your CI workflows on commits made with it

4343

4444The workflow examples in the fourth step authenticate with a custom app. That step also says what to change for the other two options.

from line 60

6060Create the trust configuration in your AWS account, following the [AWS guide to creating OIDC identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html):

6161

6262* Add a GitHub OIDC identity provider with provider URL `https://token.actions.githubusercontent.com` and audience `sts.amazonaws.com`

63* Create an IAM role trusted by that provider as a web identity, and attach the scoped invocation policy from [IAM configuration](/docs/en/amazon-bedrock.md#iam-configuration), which grants `bedrock:InvokeModel`, `bedrock:InvokeModelWithResponseStream`, `bedrock:ListInferenceProfiles`, and `bedrock:GetInferenceProfile`, along with two `aws-marketplace` subscription actions

63* Create an IAM role trusted by that provider as a web identity, and attach the scoped invocation policy from [IAM configuration](https://code.claude.com/docs/en/amazon-bedrock.md#iam-configuration), which grants `bedrock:InvokeModel`, `bedrock:InvokeModelWithResponseStream`, `bedrock:ListInferenceProfiles`, and `bedrock:GetInferenceProfile`, along with two `aws-marketplace` subscription actions

6464* Limit the role's trust policy to your repository with a subject condition such as `repo:your-org/your-repo:*`. See [GitHub's OIDC hardening guide](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) for the claim format

6565

6666Note the role's ARN. You add it as a secret in the next step.

from line 80

8080Create a Microsoft Entra application with a federated credential for your repository, following [Microsoft's guide to authenticating from GitHub Actions](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect):

8181

8282* Register a Microsoft Entra application and add a federated identity credential that trusts tokens GitHub issues to your repository. A user-assigned managed identity works in place of an application. Both have the client ID you note below

83* Assign the application the `Azure AI User` role on your Foundry resource. See [Azure RBAC configuration](/docs/en/microsoft-foundry.md#azure-rbac-configuration) for a narrower custom role

83* Assign the application the `Azure AI User` role on your Foundry resource. See [Azure RBAC configuration](https://code.claude.com/docs/en/microsoft-foundry.md#azure-rbac-configuration) for a narrower custom role

8484

8585Note the application's client ID, your tenant ID, and your subscription ID. You add them as secrets in the next step.

8686

from line 281

281281

282282> [!TIP]

283283>

284> Use a model ID that matches a Claude deployment in your Foundry resource. See [Claude Code on Microsoft Foundry](/docs/en/microsoft-foundry.md) for model configuration and version pinning.

284> Use a model ID that matches a Claude deployment in your Foundry resource. See [Claude Code on Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md) for model configuration and version pinning.

285285

286With any provider, you can bound run length and cost by adding `--max-turns` to `claude_args`. See [Manage costs](/docs/en/github-actions.md#manage-costs).

286With any provider, you can bound run length and cost by adding `--max-turns` to `claude_args`. See [Manage costs](https://code.claude.com/docs/en/github-actions.md#manage-costs).

287287

288288**5. Test the setup**

289289

from line 294

294294A failing run usually breaks in one of two places:

295295

296296* **Authentication errors**: usually an OIDC misconfiguration. Check that the workflow includes the `id-token: write` permission, that the trust configuration's repository condition matches your repository exactly, and that the secret names in your workflow match the ones you added

297* **Trigger and CI problems**: these behave the same as when the Claude Code GitHub Action calls the Claude API. See the main page's [troubleshooting section](/docs/en/github-actions.md#troubleshooting) and the Claude Code GitHub Action's [FAQ](https://github.com/anthropics/claude-code-action/blob/main/docs/faq.md)

297* **Trigger and CI problems**: these behave the same as when the Claude Code GitHub Action calls the Claude API. See the main page's [troubleshooting section](https://code.claude.com/docs/en/github-actions.md#troubleshooting) and the Claude Code GitHub Action's [FAQ](https://github.com/anthropics/claude-code-action/blob/main/docs/faq.md)

298298

299299## What's next

300300

301* [Claude Code GitHub Actions](/docs/en/github-actions.md) for examples, parameters, and best practices

302* [Claude Code on Amazon Bedrock](/docs/en/amazon-bedrock.md) for Bedrock model IDs and regions

303* [Claude Code on Google Cloud's Agent Platform](/docs/en/google-vertex-ai.md) for Agent Platform model IDs and regions

304* [Claude Code on Microsoft Foundry](/docs/en/microsoft-foundry.md) for Foundry model and endpoint configuration

301* [Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions.md) for examples, parameters, and best practices

302* [Claude Code on Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md) for Bedrock model IDs and regions

303* [Claude Code on Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md) for Agent Platform model IDs and regions

304* [Claude Code on Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md) for Foundry model and endpoint configuration

305305

github-enterprise-server Changed · +21 / -21 lines

from line 8

99GitHub Enterprise Server (GHES) support lets your organization use Claude Code with repositories hosted on your self-managed GitHub instance instead of github.com. Once an Owner connects your GHES instance, developers can run cloud sessions and get automated code reviews without any per-repository configuration. Plugin marketplaces hosted on your instance are also supported; credential requirements vary by surface, as described in [Plugin marketplaces on GHES](#plugin-marketplaces-on-ghes).

1010

11For repositories on github.com, see [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web.md) and [Code Review](/docs/en/code-review.md). To run Claude in your own CI infrastructure, see [GitHub Actions](/docs/en/github-actions.md).

11For repositories on github.com, see [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md) and [Code Review](https://code.claude.com/docs/en/code-review.md). To run Claude in your own CI infrastructure, see [GitHub Actions](https://code.claude.com/docs/en/github-actions.md).

1212

1313## What works with GitHub Enterprise Server

1414

from line 21

2121| Claude Security | ✅ Supported | Available in public beta for Enterprise plans at [claude.ai/security](https://claude.ai/security) |

2222| Teleport sessions | ✅ Supported | Move sessions between cloud and terminal with `--teleport` |

2323| Plugin marketplaces | ✅ Supported | Credential requirements differ by surface. See [Plugin marketplaces on GHES](#plugin-marketplaces-on-ghes) |

24| Contribution metrics | ❌ Not supported | Requires repositories hosted on github.com. The [analytics dashboard](/docs/en/analytics.md) still shows usage metrics for work in GHES repositories |

24| Contribution metrics | ❌ Not supported | Requires repositories hosted on github.com. The [analytics dashboard](https://code.claude.com/docs/en/analytics.md) still shows usage metrics for work in GHES repositories |

2525| GitHub Actions | ✅ Supported | Requires manual workflow setup; `/install-github-app` is github.com only |

2626| GitHub MCP server | ❌ Not supported | The GitHub MCP server does not work with GHES instances |

2727

from line 49

4949

5050**5. Enable Code Review**

5151

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

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

5353

5454### GitHub App permissions

5555

from line 79

7979

8080### Network requirements

8181

82For Anthropic-hosted sessions, your GHES instance must be reachable from Anthropic infrastructure so Claude can clone repositories and post review comments. If your GHES instance is behind a firewall, allowlist Anthropic's [outbound IP addresses](https://platform.claude.com/docs/en/api/ip-addresses#outbound-ip-addresses). Sessions in a [self-hosted environment](/docs/en/self-hosted-environments-deploy.md#configure-git) clone from inside your network instead, unless the runner opts into the [Anthropic git proxy](/docs/en/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy), which fetches from Anthropic's side and needs the same reachability.

82For Anthropic-hosted sessions, your GHES instance must be reachable from Anthropic infrastructure so Claude can clone repositories and post review comments. If your GHES instance is behind a firewall, allowlist Anthropic's [outbound IP addresses](https://platform.claude.com/docs/en/api/ip-addresses#outbound-ip-addresses). Sessions in a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#configure-git) clone from inside your network instead, unless the runner opts into the [Anthropic git proxy](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy), which fetches from Anthropic's side and needs the same reachability.

8383

84Hosted pre-session flows, such as the repository picker, run on Anthropic's side before a session starts. They need your GHES instance to be reachable from Anthropic infrastructure even when the session runs in a self-hosted environment. The [SCM connector](/docs/en/self-hosted-environments-reference.md#scm-connector-flags) isn't available, so those flows can't reach a GHES host that's only routable internally.

84Hosted pre-session flows, such as the repository picker, run on Anthropic's side before a session starts. They need your GHES instance to be reachable from Anthropic infrastructure even when the session runs in a self-hosted environment. The [SCM connector](https://code.claude.com/docs/en/self-hosted-environments-reference.md#scm-connector-flags) isn't available, so those flows can't reach a GHES host that's only routable internally.

8585

8686## Developer workflow

8787

from line 100

100100claude --cloud "Add retry logic to the payment webhook handler"

101101```

102102

103The session clones your repository from GHES and pushes changes back to a branch. Monitor progress at [claude.ai/code](https://claude.ai/code). See [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web.md) for the full cloud session workflow including diff review, auto-fix, and cloud scheduled tasks.

103The session clones your repository from GHES and pushes changes back to a branch. Monitor progress at [claude.ai/code](https://claude.ai/code). See [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md) for the full cloud session workflow including diff review, auto-fix, and cloud scheduled tasks.

104104

105105### Teleport sessions to your terminal

106106

107Pull a cloud session into your local terminal with `claude --teleport`. Teleport verifies you're in a checkout of the same GHES repository before fetching the branch and loading the session history. See [teleport requirements](/docs/en/claude-code-on-the-web.md#teleport-requirements) for details.

107Pull a cloud session into your local terminal with `claude --teleport`. Teleport verifies you're in a checkout of the same GHES repository before fetching the branch and loading the session history. See [teleport requirements](https://code.claude.com/docs/en/claude-code-on-the-web.md#teleport-requirements) for details.

108108

109109## Plugin marketplaces on GHES

110110

from line 138

138138

139139Claude Code runs git non-interactively and rejects SSH connections to hosts that are not in the machine's `known_hosts` file. An HTTPS URL with a git credential helper avoids the `known_hosts` requirement.

140140

141See [Create and distribute a plugin marketplace](/docs/en/plugins/create-marketplace.md) for the full guide to building marketplaces.

141See [Create and distribute a plugin marketplace](https://code.claude.com/docs/en/plugins/create-marketplace.md) for the full guide to building marketplaces.

142142

143143### Pre-register GHES marketplaces with managed settings

144144

145The `extraKnownMarketplaces` setting pre-registers a marketplace so developers get it without manual setup. It works from [any settings file](/docs/en/settings-reference.md#extraknownmarketplaces), including a repository's `.claude/settings.json`; managed settings deliver it organization-wide:

145The `extraKnownMarketplaces` setting pre-registers a marketplace so developers get it without manual setup. It works from [any settings file](https://code.claude.com/docs/en/settings-reference.md#extraknownmarketplaces), including a repository's `.claude/settings.json`; managed settings deliver it organization-wide:

146146

147147```json theme={null}

148148{

from line 162

162162* **Use a full git URL.** The `owner/repo` shorthand always resolves to github.com and cannot reference a GHES host.

163163* **Prefer HTTPS URLs.** SSH clones fail on machines that do not already trust your GHES host key. An HTTPS URL with your organization's standard git credential helper works on any machine with credentials configured.

164164* **Confirm each machine can clone from your GHES host.** If a machine lacks credentials, the marketplace is registered but never installed, and its plugins report as not found instead of prompting for credentials.

165* **Confirm the setting reaches each machine.** A managed settings file only takes effect on machines it's deployed to, for example through your device management system. See [Deploy managed settings](/docs/en/managed-settings.md#delivery-mechanisms) for file locations.

165* **Confirm the setting reaches each machine.** A managed settings file only takes effect on machines it's deployed to, for example through your device management system. See [Deploy managed settings](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms) for file locations.

166166

167167### Allowlist GHES marketplaces in managed settings

168168

169If your organization uses [managed settings](/docs/en/settings.md) to restrict which marketplaces developers can add, use the `hostPattern` source type to allow all marketplaces from your GHES instance without enumerating each repository. See [Delivery mechanisms](/docs/en/managed-settings.md#delivery-mechanisms) for file locations on each platform. Add the JSON to your `managed-settings.json` file or equivalent MDM policy:

169If your organization uses [managed settings](https://code.claude.com/docs/en/settings.md) to restrict which marketplaces developers can add, use the `hostPattern` source type to allow all marketplaces from your GHES instance without enumerating each repository. See [Delivery mechanisms](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms) for file locations on each platform. Add the JSON to your `managed-settings.json` file or equivalent MDM policy:

170170

171171```json theme={null}

172172{

from line 179

179179}

180180```

181181

182See the [strictKnownMarketplaces](/docs/en/settings-reference.md#strictknownmarketplaces) and [extraKnownMarketplaces](/docs/en/settings-reference.md#extraknownmarketplaces) settings reference for the complete schema.

182See the [strictKnownMarketplaces](https://code.claude.com/docs/en/settings-reference.md#strictknownmarketplaces) and [extraKnownMarketplaces](https://code.claude.com/docs/en/settings-reference.md#extraknownmarketplaces) settings reference for the complete schema.

183183

184184## Limitations

185185

from line 215

215215

216216### GHES instance not reachable

217217

218If reviews or Anthropic-hosted cloud sessions time out, your GHES instance may not be reachable from Anthropic infrastructure. Confirm your firewall allows inbound connections from Anthropic's [outbound IP addresses](https://platform.claude.com/docs/en/api/ip-addresses#outbound-ip-addresses). Sessions in a [self-hosted environment](/docs/en/self-hosted-environments) reach GHES from inside your network, so when one of them can't clone, check the runner's own network path instead. For the repository picker and other hosted pre-session flows, see [Network requirements](#network-requirements).

218If reviews or Anthropic-hosted cloud sessions time out, your GHES instance may not be reachable from Anthropic infrastructure. Confirm your firewall allows inbound connections from Anthropic's [outbound IP addresses](https://platform.claude.com/docs/en/api/ip-addresses#outbound-ip-addresses). Sessions in a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) reach GHES from inside your network, so when one of them can't clone, check the runner's own network path instead. For the repository picker and other hosted pre-session flows, see [Network requirements](#network-requirements).

219219

220220### Session start fails with `Unable to get organization UUID`

221221

222Claude Code couldn't read a claude.ai organization from your credentials. Sign in with `/login` using an account in your Team or Enterprise organization, since GitHub Enterprise Server support is limited to those plans. See [Unable to get organization UUID](/docs/en/claude-code-on-the-web.md#unable-to-get-organization-uuid) for the causes and the other messages this state produces.

222Claude Code couldn't read a claude.ai organization from your credentials. Sign in with `/login` using an account in your Team or Enterprise organization, since GitHub Enterprise Server support is limited to those plans. See [Unable to get organization UUID](https://code.claude.com/docs/en/claude-code-on-the-web.md#unable-to-get-organization-uuid) for the causes and the other messages this state produces.

223223

224224## Related resources

225225

226226These pages cover the features referenced throughout this guide in more depth:

227227

228* [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web.md): run Claude Code sessions on cloud infrastructure

229* [Code Review](/docs/en/code-review.md): automated PR reviews

230* [Plugin marketplaces](/docs/en/plugins/host-marketplace.md): build and distribute plugin catalogs

231* [Analytics](/docs/en/analytics.md): track Claude Code usage across your organization

232* [Managed settings](/docs/en/settings.md): organization-wide policy configuration

233* [Network configuration](/docs/en/network-config.md): firewall and IP allowlist requirements

228* [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md): run Claude Code sessions on cloud infrastructure

229* [Code Review](https://code.claude.com/docs/en/code-review.md): automated PR reviews

230* [Plugin marketplaces](https://code.claude.com/docs/en/plugins/host-marketplace.md): build and distribute plugin catalogs

231* [Analytics](https://code.claude.com/docs/en/analytics.md): track Claude Code usage across your organization

232* [Managed settings](https://code.claude.com/docs/en/settings.md): organization-wide policy configuration

233* [Network configuration](https://code.claude.com/docs/en/network-config.md): firewall and IP allowlist requirements

234234

glossary Changed · +83 / -83 lines

from line 8

99### AGENTS.md

1010

11A markdown file of project instructions you write for AI coding agents. If your repository has one and no [CLAUDE.md](#claude-md), Claude reads it as your project instructions without you adding a second file. You can change the **Project instructions** setting in `/config` to have Claude read both files or only `CLAUDE.md`. Reading `AGENTS.md` directly requires Claude Code v2.1.277 or later. In some sessions Claude [can't read `AGENTS.md`](/docs/en/memory#when-agents-md-support-is-unavailable), so [import it from a `CLAUDE.md`](/docs/en/memory#share-one-file-with-other-coding-tools) there instead.

11A markdown file of project instructions you write for AI coding agents. If your repository has one and no [CLAUDE.md](#claude-md), Claude reads it as your project instructions without you adding a second file. You can change the **Project instructions** setting in `/config` to have Claude read both files or only `CLAUDE.md`. Reading `AGENTS.md` directly requires Claude Code v2.1.277 or later. In some sessions Claude [can't read `AGENTS.md`](https://code.claude.com/docs/en/memory#when-agents-md-support-is-unavailable), so [import it from a `CLAUDE.md`](https://code.claude.com/docs/en/memory#share-one-file-with-other-coding-tools) there instead.

1212

13Learn more: [AGENTS.md](/docs/en/memory.md#agents-md)

13Learn more: [AGENTS.md](https://code.claude.com/docs/en/memory.md#agents-md)

1414

1515### Agent teams

1616

17Multiple independent Claude Code sessions coordinated by a team lead, with a shared task list and peer-to-peer messaging. Unlike [subagents](#subagent), which run within a single session and report only to the parent, teammates each have their own context window and you can interact with any of them directly. Agent teams are experimental and disabled by default; see [Enable agent teams](/docs/en/agent-teams.md#enable-agent-teams).

1818

19Learn more: [Run agent teams](/docs/en/agent-teams.md)

19Learn more: [Run agent teams](https://code.claude.com/docs/en/agent-teams.md)

2020

2121### Agentic coding

2222

2323A workflow where the AI can read files, run commands, and make changes autonomously while you watch, redirect, or step away, as opposed to chat-based assistants that only respond with text you must apply yourself. Claude Code is agentic because it has [tools](#tool) that let it act, not just advise.

2424

25Learn more: [How Claude Code works](/docs/en/how-claude-code-works.md)

25Learn more: [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md)

2626

2727### Agentic harness

2828

2929The tools, context management, and execution environment that turn a language model into a capable coding agent. Claude Code is the harness; Claude is the model inside it. The harness supplies file access, shell execution, permission gating, memory loading, and the loop that chains actions together.

3030

31Learn more: [How Claude Code works](/docs/en/how-claude-code-works.md)

31Learn more: [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md)

3232

3333### Agentic loop

3434

3535The cycle Claude works through for every task: gather context, take action, verify results, and repeat until done. Each tool use returns information that informs the next step. You can interrupt the loop at any point to redirect. Most extension points, including [hooks](#hook), [skills](#skill), and [MCP](#mcp-model-context-protocol), plug into specific phases of this loop.

3636

37Learn more: [How Claude Code works](/docs/en/how-claude-code-works.md#the-agentic-loop)

37Learn more: [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md#the-agentic-loop)

3838

3939### Artifact

4040

41A live, interactive web page Claude Code publishes from your session to a private URL on claude.ai, so you can see output visually or share it instead of reading terminal text. The page updates in place when the session republishes. Artifacts you create from Claude Code appear in the same gallery as artifacts created in claude.ai conversations. Sharing options depend on your plan: see [Share an artifact](/docs/en/artifacts.md#share-an-artifact).

4242

43Learn more: [Share session output as artifacts](/docs/en/artifacts.md)

43Learn more: [Share session output as artifacts](https://code.claude.com/docs/en/artifacts.md)

4444

4545### Auto memory

4646

4747Notes Claude writes for itself based on your corrections and preferences, stored per git repository under `~/.claude/projects/`. All worktrees of the same repository share one auto memory directory. The first 200 lines or 25 KB of the `MEMORY.md` index loads at the start of every session. Auto memory is the Claude-written counterpart to [CLAUDE.md](#claude-md), which you write.

4848

49Learn more: [Auto memory](/docs/en/memory.md#auto-memory)

49Learn more: [Auto memory](https://code.claude.com/docs/en/memory.md#auto-memory)

5050

5151### Auto mode

5252

53A [permission mode](#permission-mode) where a separate classifier model reviews actions instead of you, so Claude Code runs most of them without asking you. Claude Code still asks you before actions your explicit ask rules match. With Claude Code v2.1.283 or later, auto mode is the [built-in starting permission mode](/docs/en/permission-modes.md#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions, and on earlier versions only on Pro, Max, and Team plans. The classifier blocks scope escalation, untrusted infrastructure, and [prompt injection](#prompt-injection). Tool results are stripped from what it sees, so hostile content in a file or web page can't manipulate it directly.

53A [permission mode](#permission-mode) where a separate classifier model reviews actions instead of you, so Claude Code runs most of them without asking you. Claude Code still asks you before actions your explicit ask rules match. With Claude Code v2.1.283 or later, auto mode is the [built-in starting permission mode](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions, and on earlier versions only on Pro, Max, and Team plans. The classifier blocks scope escalation, untrusted infrastructure, and [prompt injection](#prompt-injection). Tool results are stripped from what it sees, so hostile content in a file or web page can't manipulate it directly.

5454

55Learn more: [Eliminate prompts with auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode)

55Learn more: [Eliminate prompts with auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode)

5656

5757## B

5858

from line 60

6060

6161With `--bare`, Claude Code starts without loading hooks, skills, custom commands, subagents, installed plugins, MCP servers, auto memory, or CLAUDE.md, apart from skills in a directory you pass with `--add-dir`. Recommended for CI and scripted calls where you need the same result on every machine.

6262

63Learn more: [Start faster with bare mode](/docs/en/headless.md#start-faster-with-bare-mode)

63Learn more: [Start faster with bare mode](https://code.claude.com/docs/en/headless.md#start-faster-with-bare-mode)

6464

6565### Bundled skills

6666

6767Prompt-based playbooks included with Claude Code, such as `/batch`, `/code-review`, `/debug`, and `/loop`. Unlike built-in commands, which execute fixed logic, bundled skills give Claude a detailed prompt and let it orchestrate the work, so they can spawn agents, read files, and adapt to your codebase.

6868

69Learn more: [Bundled skills](/docs/en/skills.md#bundled-skills)

69Learn more: [Bundled skills](https://code.claude.com/docs/en/skills.md#bundled-skills)

7070

7171## C

7272

from line 74

7474

7575An [MCP server](#mcp-model-context-protocol) that pushes events into your running session so Claude can react to things that happen while you're away from the terminal. Channels can be two-way: Claude reads an inbound event and replies back through the same channel. Telegram, Discord, and iMessage are included in the research preview.

7676

77Learn more: [Channels](/docs/en/channels.md)

77Learn more: [Channels](https://code.claude.com/docs/en/channels.md)

7878

7979### Checkpoint

8080

from line 82

8282

8383Checkpoints are saved with the conversation, so a resumed session can still `/rewind` to them. Rewinding doesn't undo a Bash command's changes to a file unless Claude had already used its file editing tools on that file in your conversation.

8484

85Learn more: [Checkpointing](/docs/en/checkpointing.md)

85Learn more: [Checkpointing](https://code.claude.com/docs/en/checkpointing.md)

8686

8787### `.claude` directory

8888

8989The directory where Claude Code reads project-scoped configuration: settings, hooks, skills, subagents, rules, and auto memory. A project has `.claude/` at its root; your user-level defaults are at `~/.claude/`.

9090

91Learn more: [The `.claude` directory](/docs/en/claude-directory)

91Learn more: [The `.claude` directory](https://code.claude.com/docs/en/claude-directory)

9292

9393### CLAUDE.md

9494

from line 96

9696

9797You can place CLAUDE.md at project scope in `./CLAUDE.md` or `./.claude/CLAUDE.md`, at user scope in `~/.claude/CLAUDE.md`, or as [managed policy](#managed-settings) for your organization. All discovered files are concatenated into context rather than overriding each other, ordered from broadest scope to most specific. Claude Code can also load a project's [AGENTS.md](#agents-md) files in place of CLAUDE.md.

9898

99Learn more: [CLAUDE.md files](/docs/en/memory.md#claude-md-files)

99Learn more: [CLAUDE.md files](https://code.claude.com/docs/en/memory.md#claude-md-files)

100100

101101### Cloud session

102102

103A Claude Code session that keeps running after you close your laptop, because it runs on cloud infrastructure instead of your machine. That infrastructure is Anthropic-managed by default, or a [self-hosted environment](/docs/en/self-hosted-environments) your organization operates. You start one from claude.ai/code, the Claude mobile app, the Desktop app with **Cloud** selected, `claude --cloud`, or a [cloud scheduled task](/docs/en/routines.md).

103A Claude Code session that keeps running after you close your laptop, because it runs on cloud infrastructure instead of your machine. That infrastructure is Anthropic-managed by default, or a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) your organization operates. You start one from claude.ai/code, the Claude mobile app, the Desktop app with **Cloud** selected, `claude --cloud`, or a [cloud scheduled task](https://code.claude.com/docs/en/routines.md).

104104

105105A session in your terminal, IDE, or the Desktop app with **Local** selected is a local session; to reach a local session from another device, use [Remote Control](#remote-control).

106106

107Learn more: [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web.md)

107Learn more: [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md)

108108

109109### Command

110110

111111A reusable instruction you invoke by typing `/name` in the prompt. Built-in commands such as `/clear`, `/model`, and `/compact` control the session. You can define your own commands as files in `.claude/commands/`, or install them from a [plugin](#plugin). [Skills](#skill) are the recommended way to package multi-step commands.

112112

113Two other uses of the word are unrelated: `claude` CLI subcommands such as `claude mcp add`, listed in the [CLI reference](/docs/en/cli-reference.md#cli-commands), and the `command` field of a stdio [MCP server](#mcp-server) entry, which specifies the executable Claude Code launches to start the server.

113Two other uses of the word are unrelated: `claude` CLI subcommands such as `claude mcp add`, listed in the [CLI reference](https://code.claude.com/docs/en/cli-reference.md#cli-commands), and the `command` field of a stdio [MCP server](#mcp-server) entry, which specifies the executable Claude Code launches to start the server.

114114

115Learn more: [Commands](/docs/en/commands.md) · [Skills](/docs/en/skills.md)

115Learn more: [Commands](https://code.claude.com/docs/en/commands.md) · [Skills](https://code.claude.com/docs/en/skills.md)

116116

117117### Compaction

118118

119119Automatic summarization of your conversation when the [context window](#context-window) approaches its limit. Older tool outputs are cleared first, then the conversation is summarized. Project-root CLAUDE.md and auto memory survive compaction and reload from disk; instructions given only in conversation may be lost. Run `/compact` to trigger manually, optionally with a focus like `/compact focus on the API changes`.

120120

121Learn more: [What survives compaction](/docs/en/context-window.md#what-survives-compaction) · [When context fills up](/docs/en/how-claude-code-works.md#when-context-fills-up)

121Learn more: [What survives compaction](https://code.claude.com/docs/en/context-window.md#what-survives-compaction) · [When context fills up](https://code.claude.com/docs/en/how-claude-code-works.md#when-context-fills-up)

122122

123123### Connector

124124

125125An [MCP server](#mcp-server) added to your claude.ai account rather than configured in Claude Code. When you sign in to Claude Code with that account, your connectors appear in `/mcp` alongside the servers you added locally. Organizations can also provision connectors and set per-tool controls on them.

126126

127Learn more: [Use MCP servers from claude.ai](/docs/en/mcp.md#use-mcp-servers-from-claude-ai)

127Learn more: [Use MCP servers from claude.ai](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai)

128128

129129### Context window

130130

131131The working memory for a session, holding conversation history, file contents, command outputs, CLAUDE.md, auto memory, loaded skills, and system instructions. As you work, context fills up until [compaction](#compaction) summarizes it. Run `/context` to see what's using space. For the underlying model concept, see the [platform glossary](https://platform.claude.com/docs/en/about-claude/glossary#context-window).

132132

133Learn more: [Explore the context window](/docs/en/context-window.md)

133Learn more: [Explore the context window](https://code.claude.com/docs/en/context-window.md)

134134

135135## D

136136

from line 138

138138

139139A phone-initiated task router that spawns a Claude Code session in the Desktop app when you send a coding task from the Claude mobile app. Your prompt routes to the right tool automatically. Available on Pro and Max plans.

140140

141Learn more: [Sessions from Dispatch](/docs/en/desktop.md#sessions-from-dispatch)

141Learn more: [Sessions from Dispatch](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch)

142142

143143## E

144144

from line 146

146146

147147A setting that controls adaptive reasoning, which lets the model decide whether and how much to think on each step. Higher effort means more thinking tokens and deeper reasoning; lower effort is faster and cheaper. Effort is supported on Fable models, on Opus 4.6 and later, on Sonnet 4.6 and later, and on Haiku 5.5.

148148

149Learn more: [Adjust effort level](/docs/en/model-config.md#adjust-effort-level)

149Learn more: [Adjust effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level)

150150

151151### Extended thinking

152152

153153Visible step-by-step reasoning the model performs before responding. You can adjust it with the [effort level](#effort-level), or cap thinking tokens with `MAX_THINKING_TOKENS` on models with a fixed thinking budget. Thinking appears in gray italic text in the terminal.

154154

155Learn more: [Use extended thinking](/docs/en/model-config.md#extended-thinking)

155Learn more: [Use extended thinking](https://code.claude.com/docs/en/model-config.md#extended-thinking)

156156

157157## F

158158

from line 160

160160

161161A block of YAML settings at the very top of a Markdown file, between an opening `---` line and a closing `---` line. Skills, subagents, output styles, and rules each read their configuration from frontmatter, such as a skill's `description` or a subagent's `tools`, and treat everything after the closing `---` as the instructions. The opening `---` must be the file's first line. Each file type accepts its own set of fields.

162162

163Learn more: [Skill frontmatter](/docs/en/skills.md#frontmatter-reference), [Subagent frontmatter](/docs/en/sub-agents.md#supported-frontmatter-fields), [Output style frontmatter](/docs/en/output-styles.md#frontmatter), [Rule frontmatter](/docs/en/memory.md#rules-frontmatter-reference)

163Learn more: [Skill frontmatter](https://code.claude.com/docs/en/skills.md#frontmatter-reference), [Subagent frontmatter](https://code.claude.com/docs/en/sub-agents.md#supported-frontmatter-fields), [Output style frontmatter](https://code.claude.com/docs/en/output-styles.md#frontmatter), [Rule frontmatter](https://code.claude.com/docs/en/memory.md#rules-frontmatter-reference)

164164

165165## H

166166

from line 174

174174* **Matcher**: filters which events fire it

175175* **Hook handler**: what runs

176176

177Learn more: [Get started with hooks](/docs/en/hooks-guide.md) · [Hooks reference](/docs/en/hooks.md)

177Learn more: [Get started with hooks](https://code.claude.com/docs/en/hooks-guide.md) · [Hooks reference](https://code.claude.com/docs/en/hooks.md)

178178

179179## M

180180

181181### Managed settings

182182

183Settings enforced org-wide by IT or DevOps, delivered from Anthropic's servers through the admin console or deployed to devices at an OS-level path outside `~/.claude`. User and project settings cannot override managed settings. Server-managed delivery applies on [eligible configurations](/docs/en/server-managed-settings.md#platform-availability); see [Security considerations](/docs/en/server-managed-settings.md#security-considerations). Use this for security policies, compliance requirements, or standardized tooling across a fleet.

183Settings enforced org-wide by IT or DevOps, delivered from Anthropic's servers through the admin console or deployed to devices at an OS-level path outside `~/.claude`. User and project settings cannot override managed settings. Server-managed delivery applies on [eligible configurations](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability); see [Security considerations](https://code.claude.com/docs/en/server-managed-settings.md#security-considerations). Use this for security policies, compliance requirements, or standardized tooling across a fleet.

184184

185Learn more: [Server-managed settings](/docs/en/server-managed-settings.md) · [Settings files](/docs/en/settings.md#where-settings-live)

185Learn more: [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) · [Settings files](https://code.claude.com/docs/en/settings.md#where-settings-live)

186186

187187### MCP (Model Context Protocol)

188188

189189An open standard for connecting AI tools to external data sources and services. MCP servers give Claude new tools for Slack, Jira, databases, browsers, and hundreds of other integrations. You connect servers via `/mcp` or by adding them to `.mcp.json`. For the protocol itself, see the [platform glossary](https://platform.claude.com/docs/en/about-claude/glossary#mcp-model-context-protocol).

190190

191Learn more: [Model Context Protocol](/docs/en/mcp.md)

191Learn more: [Model Context Protocol](https://code.claude.com/docs/en/mcp.md)

192192

193193### MCP server

194194

195195A program that gives Claude tools, prompts, or resources over [MCP](#mcp-model-context-protocol). You add servers with `claude mcp add`, in `.mcp.json`, through a [plugin](#plugin), or as a claude.ai [connector](#connector). A local stdio server runs as a process Claude Code starts from the `command` and `args` fields of its configuration, which have nothing to do with the [commands](#command) you type at the prompt.

196196

197Learn more: [Model Context Protocol](/docs/en/mcp.md)

197Learn more: [Model Context Protocol](https://code.claude.com/docs/en/mcp.md)

198198

199199### MCP Tool Search

200200

201201A context-saving mechanism that defers MCP tool schemas until needed. Only tool names and server instructions load at startup; Claude fetches the full schema on demand when it decides to use a specific tool. This keeps idle MCP servers from consuming much context.

202202

203Learn more: [Scale with MCP Tool Search](/docs/en/mcp.md#scale-with-mcp-tool-search)

203Learn more: [Scale with MCP Tool Search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search)

204204

205205## N

206206

207207### Non-interactive mode

208208

209A mode that executes a single prompt and exits without an interactive prompt, invoked with `-p` or `--print`. Used for CI, scripts, and piping. The run is still saved as a resumable session unless you pass `--no-session-persistence`. The [Agent SDK](/docs/en/agent-sdk/overview.md) is the Python and TypeScript equivalent. Formerly called headless mode.

209A mode that executes a single prompt and exits without an interactive prompt, invoked with `-p` or `--print`. Used for CI, scripts, and piping. The run is still saved as a resumable session unless you pass `--no-session-persistence`. The [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) is the Python and TypeScript equivalent. Formerly called headless mode.

210210

211Learn more: [Run Claude Code programmatically](/docs/en/headless.md)

211Learn more: [Run Claude Code programmatically](https://code.claude.com/docs/en/headless.md)

212212

213213## O

214214

from line 216

216216

217217A configuration that changes the instructions Claude Code gives Claude, to set response behavior, tone, or format. Unlike [CLAUDE.md](#claude-md), which adds project context alongside Claude Code's default instructions, a custom output style adds its own instructions and can leave out the default software engineering instructions.

218218

219Learn more: [Output styles](/docs/en/output-styles.md)

219Learn more: [Output styles](https://code.claude.com/docs/en/output-styles.md)

220220

221221## P

222222

from line 226

226226

227227The `default` mode is labeled Manual in the CLI, in the VS Code and JetBrains extensions, and in the desktop app, and Claude Code accepts `manual` as an alias for the value.

228228

229Learn more: [Choose a permission mode](/docs/en/permission-modes.md)

229Learn more: [Choose a permission mode](https://code.claude.com/docs/en/permission-modes.md)

230230

231231### Permission rule

232232

233233A settings entry that allows, asks about, or denies a tool invocation based on the tool name and argument pattern. Rules are evaluated deny→ask→allow, first match wins. Permission rules are fine-grained controls layered on top of the broader [permission mode](#permission-mode).

234234

235Learn more: [Configure permissions](/docs/en/permissions.md)

235Learn more: [Configure permissions](https://code.claude.com/docs/en/permissions.md)

236236

237237### Plan mode

238238

239239A [permission mode](#permission-mode) where Claude researches and proposes changes without editing your source files. It can read, search, and run exploration commands, then presents a plan for approval before touching anything. Enter plan mode with `/plan` or by pressing `Shift+Tab`.

240240

241Learn more: [Analyze before you edit with plan mode](/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode)

241Learn more: [Analyze before you edit with plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode)

242242

243243### Plugin

244244

245A bundle of skills, hooks, subagents, and MCP servers packaged as a single installable unit. Plugin skills are namespaced as `plugin-name:skill-name` so multiple plugins coexist. Distribute plugins across teams via a [marketplace](/docs/en/plugins/overview.md).

246246

247Learn more: [Plugins](/docs/en/plugins/overview.md)

247Learn more: [Plugins](https://code.claude.com/docs/en/plugins/overview.md)

248248

249249### Project trust

250250

251A dialog accepting a directory before Claude Code loads its configuration. Acceptance is saved per project directory, except your home directory, where trust is held for the current session only and the prompt reappears on each launch. Until you trust a directory, Claude Code holds back some of the content its repository supplies, such as project allow rules and marketplaces from `.claude/settings.json`. [What runs before you trust a folder](/docs/en/permissions.md#what-runs-before-you-trust-a-folder) lists each kind of content, including what a `-p` session runs without a dialog.

251A dialog accepting a directory before Claude Code loads its configuration. Acceptance is saved per project directory, except your home directory, where trust is held for the current session only and the prompt reappears on each launch. Until you trust a directory, Claude Code holds back some of the content its repository supplies, such as project allow rules and marketplaces from `.claude/settings.json`. [What runs before you trust a folder](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) lists each kind of content, including what a `-p` session runs without a dialog.

252252

253Learn more: [The `.claude` directory](/docs/en/claude-directory)

253Learn more: [The `.claude` directory](https://code.claude.com/docs/en/claude-directory)

254254

255255### Prompt injection

256256

257257Hostile instructions embedded in a file, web page, or tool result that attempt to redirect Claude toward actions you never asked for. Claude Code's defenses include the permission system, command injection detection, and trust verification. [Auto mode](#auto-mode) adds a server-side probe that scans tool results for suspicious content and a classifier that reviews actions with tool results stripped, so injected text can't manipulate it directly.

258258

259Learn more: [Protect against prompt injection](/docs/en/security.md#protect-against-prompt-injection)

259Learn more: [Protect against prompt injection](https://code.claude.com/docs/en/security.md#protect-against-prompt-injection)

260260

261261## R

262262

263263### Remote Control

264264

265A way to continue a local Claude Code session from your phone or browser via claude.ai. Your code execution and files stay on your machine; the interface is remote. Different from a [cloud session](/docs/en/claude-code-on-the-web.md), which runs in a cloud sandbox.

265A way to continue a local Claude Code session from your phone or browser via claude.ai. Your code execution and files stay on your machine; the interface is remote. Different from a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md), which runs in a cloud sandbox.

266266

267Learn more: [Remote Control](/docs/en/remote-control.md)

267Learn more: [Remote Control](https://code.claude.com/docs/en/remote-control.md)

268268

269269### Rules

270270

271271Modular instruction files in `.claude/rules/` that load alongside CLAUDE.md. A rule can be path-scoped with YAML `paths:` frontmatter so it only loads when Claude reads, writes, or edits a matching file, keeping context lean until it's relevant.

272272

273Learn more: [Organize rules with `.claude/rules/`](/docs/en/memory#organize-rules-with-claude/rules/)

273Learn more: [Organize rules with `.claude/rules/`](https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/)

274274

275275## S

276276

from line 278

278278

279279OS-level filesystem and network isolation for the Bash tool. Commands run inside a boundary you define upfront, so Claude can work freely within it without per-command approval prompts. Sandboxing is a separate layer from [permission rules](#permission-rule).

280280

281Learn more: [Sandboxing](/docs/en/sandboxing.md)

281Learn more: [Sandboxing](https://code.claude.com/docs/en/sandboxing.md)

282282

283283### Session

284284

285285A conversation tied to your current directory, with its own independent [context window](#context-window). Sessions can be resumed with `claude -c`, forked with `--fork-session` to preserve history under a new session ID, or run in parallel across terminals. Running `/clear` starts a new session; the previous one stays stored and is available via `/resume`. Each session's transcript is stored under `~/.claude/projects/`.

286286

287Learn more: [Work with sessions](/docs/en/how-claude-code-works.md#work-with-sessions)

287Learn more: [Work with sessions](https://code.claude.com/docs/en/how-claude-code-works.md#work-with-sessions)

288288

289289### Settings layers

290290

291The hierarchy Claude Code reads configuration from, in precedence order from highest to lowest: [managed policy](#managed-settings), settings you pass with the `--settings` flag, local settings at `.claude/settings.local.json`, project settings at `.claude/settings.json`, then user settings at `~/.claude/settings.json`. Arrays merge across layers; scalars at a higher layer override lower ones. See [Settings precedence](/docs/en/settings.md#settings-precedence).

292292

293Learn more: [Settings files](/docs/en/settings.md#where-settings-live)

293Learn more: [Settings files](https://code.claude.com/docs/en/settings.md#where-settings-live)

294294

295295### Skill

296296

from line 298

298298

299299Skills are the recommended successor to custom commands. A file at `.claude/commands/deploy.md` and one at `.claude/skills/deploy/SKILL.md` both create `/deploy` and work the same way; existing command files continue to work.

300300

301Learn more: [Extend Claude with skills](/docs/en/skills.md)

301Learn more: [Extend Claude with skills](https://code.claude.com/docs/en/skills.md)

302302

303303### Subagent

304304

305A specialized AI assistant that runs in its own context window with a custom system prompt, specific tool access, and independent permissions. It works on a delegated task and returns a summary to the main conversation. Use subagents to keep large explorations out of your primary context or to run parallel research. A subagent stays inside the session that spawned it. To pass findings between separate sessions you run yourself, use [cross-session messaging](/docs/en/cross-session-messaging.md).

306306

307307Built-in subagents include Explore, Plan, and general-purpose.

308308

309Learn more: [Create custom subagents](/docs/en/sub-agents.md)

309Learn more: [Create custom subagents](https://code.claude.com/docs/en/sub-agents.md)

310310

311311### Surface

312312

313Any place you access Claude Code: the CLI, VS Code, JetBrains, Desktop, or claude.ai. All surfaces share the same engine. Sessions on your machine read your local CLAUDE.md, settings, and skills; [cloud sessions](/docs/en/cloud-environments.md#what-carries-over-from-your-setup) start from a fresh clone of your repository and don't read `~/.claude/` on your machine. Slack and the Chrome extension are integrations that connect to a surface rather than surfaces themselves.

313Any place you access Claude Code: the CLI, VS Code, JetBrains, Desktop, or claude.ai. All surfaces share the same engine. Sessions on your machine read your local CLAUDE.md, settings, and skills; [cloud sessions](https://code.claude.com/docs/en/cloud-environments.md#what-carries-over-from-your-setup) start from a fresh clone of your repository and don't read `~/.claude/` on your machine. Slack and the Chrome extension are integrations that connect to a surface rather than surfaces themselves.

314314

315Learn more: [Platforms and integrations](/docs/en/platforms.md)

315Learn more: [Platforms and integrations](https://code.claude.com/docs/en/platforms.md)

316316

317317### System prompt

318318

319The instructions Claude Code sends ahead of your conversation on every request, covering how Claude uses tools, behaves safely, and formats its responses. You can add to the system prompt with `--append-system-prompt` or replace it with `--system-prompt`. The system prompt is the first layer of the [prompt cache](/docs/en/prompt-caching.md#how-the-cache-is-organized).

319The instructions Claude Code sends ahead of your conversation on every request, covering how Claude uses tools, behaves safely, and formats its responses. You can add to the system prompt with `--append-system-prompt` or replace it with `--system-prompt`. The system prompt is the first layer of the [prompt cache](https://code.claude.com/docs/en/prompt-caching.md#how-the-cache-is-organized).

320320

321321Your [CLAUDE.md](#claude-md) files and the instructions of your [output style](#output-style) aren't part of the system prompt. Claude Code delivers them in the conversation as [system reminders](#system-reminder).

322322

323Learn more: [System prompt flags](/docs/en/cli-reference.md#system-prompt-flags)

323Learn more: [System prompt flags](https://code.claude.com/docs/en/cli-reference.md#system-prompt-flags)

324324

325325### System reminder

326326

from line 335

335335

336336In a logged API request, a system reminder appears wrapped in `<system-reminder>` tags inside a user message, or on some models as a separate message with the `system` role.

337337

338Learn more: [Context Claude Code adds outside the system prompt](/docs/en/agent-sdk/modifying-system-prompts.md#context-claude-code-adds-outside-the-system-prompt)

338Learn more: [Context Claude Code adds outside the system prompt](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md#context-claude-code-adds-outside-the-system-prompt)

339339

340340## T

341341

from line 343

343343

344344A command, `/teleport`, that pulls a cloud Claude Code session into your local terminal. Claude fetches the branch, loads the conversation history, and resumes from the cloud session's last state. The reverse direction is `--cloud`, which sends a local task to run in the cloud.

345345

346Learn more: [Continue a cloud session in your terminal](/docs/en/claude-code-on-the-web.md#from-cloud-to-terminal)

346Learn more: [Continue a cloud session in your terminal](https://code.claude.com/docs/en/claude-code-on-the-web.md#from-cloud-to-terminal)

347347

348348### Tool

349349

350350An action Claude can take: read a file, edit code, run a shell command, search the web, spawn a subagent. Tools are what make Claude Code agentic. Without them, Claude can only respond with text. Each tool use returns a result that informs Claude's next decision in the [agentic loop](#agentic-loop).

351351

352Learn more: [Tools available to Claude](/docs/en/tools-reference.md)

352Learn more: [Tools available to Claude](https://code.claude.com/docs/en/tools-reference.md)

353353

354354### Transcript

355355

356The stored record of a [session](#session). The conversation is what you and Claude exchange; the transcript is that conversation kept as a file, by default at `~/.claude/projects/<project>/<session-id>.jsonl`. Claude Code reads the file back when you resume, which is how a conversation continues after the session ends. For the on-screen view of the same conversation, see the [transcript viewer](/docs/en/interactive-mode.md#transcript-viewer).

357357

358Learn more: [Where transcripts are stored](/docs/en/sessions.md#where-transcripts-are-stored)

358Learn more: [Where transcripts are stored](https://code.claude.com/docs/en/sessions.md#where-transcripts-are-stored)

359359

360360### Turn

361361

362362One complete response from Claude within a [session](#session). A turn begins when you send a message and ends when Claude finishes responding, with any number of [tool](#tool) calls in between. [Stop hooks](#hook) fire at the end of each turn. A session consists of many turns, and the [agentic loop](#agentic-loop) describes what happens inside one.

363363

364Learn more: [How Claude Code works](/docs/en/how-claude-code-works.md#the-agentic-loop)

364Learn more: [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works.md#the-agentic-loop)

365365

366366## V

367367

368368### Verification loop

369369

370How a session knows the work is actually done instead of accepting a result that looks plausible. You give Claude a check it can run, such as a test suite, a build, or a screenshot comparison, and Claude iterates until the check passes instead of stopping after one attempt. A verification loop is the prerequisite for [`/goal`](/docs/en/goal), unattended runs, and [dynamic workflows](/docs/en/workflows.md): without one, the only thing deciding the agent is finished is the agent itself.

370How a session knows the work is actually done instead of accepting a result that looks plausible. You give Claude a check it can run, such as a test suite, a build, or a screenshot comparison, and Claude iterates until the check passes instead of stopping after one attempt. A verification loop is the prerequisite for [`/goal`](https://code.claude.com/docs/en/goal), unattended runs, and [dynamic workflows](https://code.claude.com/docs/en/workflows.md): without one, the only thing deciding the agent is finished is the agent itself.

371371

372Learn more: [Give Claude a way to verify its work](/docs/en/best-practices.md#give-claude-a-way-to-verify-its-work)

372Learn more: [Give Claude a way to verify its work](https://code.claude.com/docs/en/best-practices.md#give-claude-a-way-to-verify-its-work)

373373

374374## W

375375

from line 377

377377

378378An isolation mode that runs Claude in a separate git worktree under `.claude/worktrees/`, enabled with the `-w` flag or `isolation: worktree` in subagent config. Changes stay on a separate branch in a separate directory, so parallel agents each edit their own copy of the files.

379379

380Learn more: [Run parallel sessions with git worktrees](/docs/en/worktrees.md)

380Learn more: [Run parallel sessions with git worktrees](https://code.claude.com/docs/en/worktrees.md)

381381

382382***

383383

goal Changed · +21 / -21 lines

from line 18

1818| Approach | Next turn starts when | Stops when |

1919| :- | :- | :- |

2020| `/goal` | The previous turn finishes, or, in an interactive session, an [idle check-in](#background-work-defers-evaluation) or an [automatic retry](#other-errors-retry-or-pause-the-goal) comes due | A model confirms the condition is met or judges it impossible, or a turn fails on [an error you have to fix](#errors-you-have-to-fix-clear-the-goal), or you run [`/goal clear`](#clear-a-goal) |

21| [`/loop`](/docs/en/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) | A time interval elapses | You stop it, or Claude decides the work is done |

22| [Stop hook](/docs/en/hooks-guide.md#prompt-based-hooks) | The previous turn finishes | Your own script or prompt decides |

21| [`/loop`](https://code.claude.com/docs/en/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) | A time interval elapses | You stop it, or Claude decides the work is done |

22| [Stop hook](https://code.claude.com/docs/en/hooks-guide.md#prompt-based-hooks) | The previous turn finishes | Your own script or prompt decides |

2323

2424`/goal` and a Stop hook both fire after every turn. `/goal` is a session-scoped shortcut: you type a condition and it's active for the current session only. A Stop hook lives in your settings file, applies to every session in its scope, and can run a script for deterministic checks or a prompt for model-evaluated ones.

2525

26[Auto mode](/docs/en/auto-mode-config.md) on its own approves tool calls within a single turn but doesn't start a new one. Claude stops when it judges the work done. `/goal` adds a separate evaluator that checks your condition after every turn, so completion is decided by a fresh model rather than the one doing the work. The two are complementary: auto mode removes per-tool prompts, and `/goal` removes per-turn prompts.

26[Auto mode](https://code.claude.com/docs/en/auto-mode-config.md) on its own approves tool calls within a single turn but doesn't start a new one. Claude stops when it judges the work done. `/goal` adds a separate evaluator that checks your condition after every turn, so completion is decided by a fresh model rather than the one doing the work. The two are complementary: auto mode removes per-tool prompts, and `/goal` removes per-turn prompts.

2727

2828> [!TIP]

2929>

30> The approaches above keep the current session running. You can also schedule work that runs independent of any open session, such as nightly tests or morning triage. See [scheduling options](/docs/en/scheduled-tasks.md#compare-scheduling-options) for cloud and Desktop scheduled tasks.

30> The approaches above keep the current session running. You can also schedule work that runs independent of any open session, such as nightly tests or morning triage. See [scheduling options](https://code.claude.com/docs/en/scheduled-tasks.md#compare-scheduling-options) for cloud and Desktop scheduled tasks.

3131

3232## Use `/goal`

3333

from line 43

4343

4444Setting a goal starts a turn immediately, with the condition itself as the directive. You don't need to send a separate prompt. While the goal is active, a `◎ /goal active` indicator shows how long the goal has been running.

4545

46A goal doesn't change your permission mode. To let goal turns run unattended, run `/goal` in [auto mode](/docs/en/auto-mode-config.md). In [Manual mode](/docs/en/permission-modes.md), Claude still asks before tool calls that your settings don't already allow, such as the test command above.

46A goal doesn't change your permission mode. To let goal turns run unattended, run `/goal` in [auto mode](https://code.claude.com/docs/en/auto-mode-config.md). In [Manual mode](https://code.claude.com/docs/en/permission-modes.md), Claude still asks before tool calls that your settings don't already allow, such as the test command above.

4747

4848While the goal is active, the transcript shows each verdict the evaluator returns, and you can press Ctrl+O to see the reason behind it. The status view also shows the most recent reason, so you can see what Claude is working toward next.

4949

from line 95

9595

9696### Resume with an active goal

9797

98When you resume a session, Claude Code restores a goal that was still active when the session ended. Claude Code restores it on every resume route: `--continue`, `--resume` with a session ID, name, or [transcript file path](/docs/en/sessions.md#resume-a-session), and the [session picker](/docs/en/sessions.md#use-the-session-picker). Before v2.1.239, Claude Code restored the goal on every route except the `claude --resume` picker.

98When you resume a session, Claude Code restores a goal that was still active when the session ended. Claude Code restores it on every resume route: `--continue`, `--resume` with a session ID, name, or [transcript file path](https://code.claude.com/docs/en/sessions.md#resume-a-session), and the [session picker](https://code.claude.com/docs/en/sessions.md#use-the-session-picker). Before v2.1.239, Claude Code restored the goal on every route except the `claude --resume` picker.

9999

100100Claude Code carries the condition over but resets the turn count, timer, and token-spend baseline. It doesn't restore a goal that was already achieved or cleared.

101101

102102### Run non-interactively

103103

104`/goal` works in [non-interactive mode](/docs/en/headless.md), in the [desktop app](/docs/en/desktop.md), and through [Remote Control](/docs/en/remote-control.md). Setting a goal with `-p` runs the loop to completion in a single invocation:

104`/goal` works in [non-interactive mode](https://code.claude.com/docs/en/headless.md), in the [desktop app](https://code.claude.com/docs/en/desktop.md), and through [Remote Control](https://code.claude.com/docs/en/remote-control.md). Setting a goal with `-p` runs the loop to completion in a single invocation:

105105

106106```bash theme={null}

107107claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"

from line 113

113113

114114## How evaluation works

115115

116`/goal` is a wrapper around a session-scoped [prompt-based Stop hook](/docs/en/hooks.md#prompt-based-hooks). Each time Claude finishes a turn, Claude Code sends the condition and the conversation so far to your configured [small fast model](/docs/en/model-config.md). The model returns one of three verdicts, each with a short reason:

116`/goal` is a wrapper around a session-scoped [prompt-based Stop hook](https://code.claude.com/docs/en/hooks.md#prompt-based-hooks). Each time Claude finishes a turn, Claude Code sends the condition and the conversation so far to your configured [small fast model](https://code.claude.com/docs/en/model-config.md). The model returns one of three verdicts, each with a short reason:

117117

118118* **Not yet met**: Claude keeps working and takes the reason as guidance for the next turn.

119119* **Met**: Claude Code clears the goal and records an achieved entry in the transcript.

120120* **Impossible**: the evaluator judged that the condition can never be satisfied. Claude Code clears the goal and records a failed entry in the transcript along with the reason. You don't need to clear it yourself.

121121

122If Claude keeps answering the evaluator without making progress (no tool use for several turns in a row), Claude Code stops the loop, prints a warning, and returns control to you with the goal still set. Evaluation resumes after your next prompt. The [hooks guide](/docs/en/hooks-guide.md#stop-hook-hits-the-block-cap) explains the underlying mechanism.

122If Claude keeps answering the evaluator without making progress (no tool use for several turns in a row), Claude Code stops the loop, prints a warning, and returns control to you with the goal still set. Evaluation resumes after your next prompt. The [hooks guide](https://code.claude.com/docs/en/hooks-guide.md#stop-hook-hits-the-block-cap) explains the underlying mechanism.

123123

124124### When a turn fails

125125

from line 129

129129

130130If a turn fails on an error that won't clear until you fix it, Claude Code clears the goal and prints a warning naming the cause. The warning starts with `Goal cleared after an unrecoverable error` and ends with `Run /goal again to continue`. Fix the cause, then [set the goal again](#set-a-goal) with `/goal <condition>`. Four kinds of failure clear the goal:

131131

132* An authentication failure, when Claude Code manages its own credentials. When a host manages them for you, such as the desktop app or a [cloud session](/docs/en/claude-code-on-the-web.md), Claude Code leaves the goal active because the host restores access on its own.

132* An authentication failure, when Claude Code manages its own credentials. When a host manages them for you, such as the desktop app or a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md), Claude Code leaves the goal active because the host restores access on its own.

133133* An exhausted credit balance

134* A context overflow that [auto-compaction](/docs/en/model-config.md#set-the-auto-compact-window) couldn't clear

134* A context overflow that [auto-compaction](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window) couldn't clear

135135* A model that isn't available

136136

137137#### Other errors retry or pause the goal

from line 139

139139After any other failure the goal stays set. In an interactive session on Claude Code v2.1.269 or later, Claude Code also prints a line naming the cause and either retries on its own or waits for you:

140140

141141* **Retry**: after a failure that tends to clear on its own, such as an overloaded server or a dropped connection, a notice starting with `Goal still active` shows the wait before the next attempt. After three automatic retries, the goal pauses instead.

142* **Pause**: after a failure that a retry would only repeat, such as an API rate limit, a claude.ai [usage limit](/docs/en/errors.md#youve-hit-your-session-limit), or a hook that ended the turn, a notice starting with `Goal paused` names the cause. If the session is [waiting to continue automatically when a usage limit resets](/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset), Claude resumes work toward the goal then.

142* **Pause**: after a failure that a retry would only repeat, such as an API rate limit, a claude.ai [usage limit](https://code.claude.com/docs/en/errors.md#youve-hit-your-session-limit), or a hook that ended the turn, a notice starting with `Goal paused` names the cause. If the session is [waiting to continue automatically when a usage limit resets](https://code.claude.com/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset), Claude resumes work toward the goal then.

143143

144Send a message at any time to start the next turn immediately. To turn automatic retries off, set [`CLAUDE_CODE_GOAL_CHECKIN_MINUTES`](/docs/en/env-vars) to `0`, which also turns [check-ins](#background-work-defers-evaluation) off.

144Send a message at any time to start the next turn immediately. To turn automatic retries off, set [`CLAUDE_CODE_GOAL_CHECKIN_MINUTES`](https://code.claude.com/docs/en/env-vars) to `0`, which also turns [check-ins](#background-work-defers-evaluation) off.

145145

146146### Background work defers evaluation

147147

from line 154

154154

155155Before v2.1.239, only idle check-ins backed off this way; a check-in delivered at a turn end recurred at the first interval.

156156

157To change the first interval, set [`CLAUDE_CODE_GOAL_CHECKIN_MINUTES`](/docs/en/env-vars). Claude Code uses your value in place of the 30-minute interval and scales the later intervals with it. Set it to `0` to turn off check-ins and [automatic retries](#other-errors-retry-or-pause-the-goal).

157To change the first interval, set [`CLAUDE_CODE_GOAL_CHECKIN_MINUTES`](https://code.claude.com/docs/en/env-vars). Claude Code uses your value in place of the 30-minute interval and scales the later intervals with it. Set it to `0` to turn off check-ins and [automatic retries](#other-errors-retry-or-pause-the-goal).

158158

159159Check-ins require Claude Code v2.1.234 or later.

160160

161161### Evaluation model and cost

162162

163To evaluate on a different model, set [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/docs/en/model-config#environment-variables).

163To evaluate on a different model, set [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables).

164164

165165> [!WARNING]

166166>

167> Claude Code reads `ANTHROPIC_DEFAULT_HAIKU_MODEL` everywhere it uses the small fast model, not only for `/goal` evaluation. When you set it, Claude Code also resolves the [`haiku` alias](/docs/en/model-config#model-aliases) to that model and runs [background functionality](/docs/en/costs.md#background-token-usage), such as conversation summarization, on it.

167> Claude Code reads `ANTHROPIC_DEFAULT_HAIKU_MODEL` everywhere it uses the small fast model, not only for `/goal` evaluation. When you set it, Claude Code also resolves the [`haiku` alias](https://code.claude.com/docs/en/model-config#model-aliases) to that model and runs [background functionality](https://code.claude.com/docs/en/costs.md#background-token-usage), such as conversation summarization, on it.

168168

169169The evaluator runs on whichever provider your session is configured for. It does not call tools, so it can only judge what Claude has already surfaced in the conversation.

170170

from line 174

174174

175175## Requirements

176176

177Claude Code makes `/goal` available under the same [workspace trust rule as hooks in settings files](/docs/en/permissions.md#what-runs-before-you-trust-a-folder), because the evaluator is part of the hooks system. `/goal` is also unavailable when [`disableAllHooks`](/docs/en/hooks#disable-or-remove-hooks) is `true` after settings precedence applies, or when [`allowManagedHooksOnly`](/docs/en/settings-reference#allowmanagedhooksonly) is set in managed settings. In each case, the command tells you why instead of silently doing nothing.

177Claude Code makes `/goal` available under the same [workspace trust rule as hooks in settings files](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder), because the evaluator is part of the hooks system. `/goal` is also unavailable when [`disableAllHooks`](https://code.claude.com/docs/en/hooks#disable-or-remove-hooks) is `true` after settings precedence applies, or when [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) is set in managed settings. In each case, the command tells you why instead of silently doing nothing.

178178

179179## See also

180180

181* [Run a prompt repeatedly with `/loop`](/docs/en/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop): re-run on a time interval instead of toward a condition

182* [Prompt-based hooks](/docs/en/hooks-guide.md#prompt-based-hooks): write your own Stop hook when you need custom evaluation logic

183* [Auto mode](/docs/en/auto-mode-config.md): approve tool calls automatically so each goal turn runs unattended

184* [Scheduling comparison](/docs/en/scheduled-tasks.md#compare-scheduling-options): run work on a schedule independent of any open session

181* [Run a prompt repeatedly with `/loop`](https://code.claude.com/docs/en/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop): re-run on a time interval instead of toward a condition

182* [Prompt-based hooks](https://code.claude.com/docs/en/hooks-guide.md#prompt-based-hooks): write your own Stop hook when you need custom evaluation logic

183* [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): approve tool calls automatically so each goal turn runs unattended

184* [Scheduling comparison](https://code.claude.com/docs/en/scheduled-tasks.md#compare-scheduling-options): run work on a schedule independent of any open session

185185

google-vertex-ai Changed · +23 / -23 lines

from line 33

3333

3434**3. Follow the wizard prompts**

3535

36Choose how you authenticate to Google Cloud: Application Default Credentials from `gcloud`, a service account key file, or credentials already in your environment. The wizard asks for your project and region, verifies which Claude models your project can invoke, and lets you pin them. It saves the result to the `env` block of your [user settings file](/docs/en/settings.md), so you don't need to export environment variables yourself.

36Choose how you authenticate to Google Cloud: Application Default Credentials from `gcloud`, a service account key file, or credentials already in your environment. The wizard asks for your project and region, verifies which Claude models your project can invoke, and lets you pin them. It saves the result to the `env` block of your [user settings file](https://code.claude.com/docs/en/settings.md), so you don't need to export environment variables yourself.

3737

38After you've signed in, run `/setup-vertex` any time to reopen the wizard and change your credentials, project, region, or model pins. The model pin step starts from your currently pinned models. The wizard writes to `~/.claude/settings.json`, or to `$CLAUDE_CONFIG_DIR/settings.json` when [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars#variables) is set.

3939

4040## Region configuration

4141

from line 84

8484

8585#### Advanced credential configuration

8686

87Claude Code supports automatic credential refresh for GCP through the `gcpAuthRefresh` setting. Add it to your Claude Code [settings file](/docs/en/settings.md), for example `~/.claude/settings.json`. When Claude Code detects that your GCP credentials are expired or cannot be loaded, it runs the configured command to obtain new credentials before retrying the request.

87Claude Code supports automatic credential refresh for GCP through the `gcpAuthRefresh` setting. Add it to your Claude Code [settings file](https://code.claude.com/docs/en/settings.md), for example `~/.claude/settings.json`. When Claude Code detects that your GCP credentials are expired or cannot be loaded, it runs the configured command to obtain new credentials before retrying the request.

8888

8989```json theme={null}

9090{

from line 99

9999

100100If the check doesn't finish within five seconds, Claude Code also skips the command and runs it only after a request fails with a credential error. Before v2.1.261, a check that timed out counted as an expired credential, so the command could open your browser at startup even though your credentials were still valid.

101101

102Claude Code shows you the command's output, but can't send the command interactive input. This works well for browser-based authentication flows where the CLI shows a URL and you complete authentication in the browser. The refresh command times out after three minutes if authentication does not complete. If you set `gcpAuthRefresh` in project settings such as `.claude/settings.json`, 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), which includes `-p` sessions in folders you've never trusted.

102Claude Code shows you the command's output, but can't send the command interactive input. This works well for browser-based authentication flows where the CLI shows a URL and you complete authentication in the browser. The refresh command times out after three minutes if authentication does not complete. If you set `gcpAuthRefresh` in project settings such as `.claude/settings.json`, Claude Code runs it under the same [workspace trust rule as hooks in settings files](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder), which includes `-p` sessions in folders you've never trusted.

103103

104104### 4. Configure Claude Code

105105

from line 119

119119export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

120120```

121121

122Most model versions have a corresponding `VERTEX_REGION_CLAUDE_*` variable. See the [Environment variables reference](/docs/en/env-vars.md#variables) for the full list. Check [Google Cloud's Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) to determine which models support global endpoints versus regional only.

122Most model versions have a corresponding `VERTEX_REGION_CLAUDE_*` variable. See the [Environment variables reference](https://code.claude.com/docs/en/env-vars.md#variables) for the full list. Check [Google Cloud's Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) to determine which models support global endpoints versus regional only.

123123

124124If a region value isn't shaped like a region or location name, Claude Code treats it as unset. For example, Claude Code treats a value containing a slash, dot, or space as unset. Claude Code falls back to a different source for each variable:

125125

from line 126

126126* `VERTEX_REGION_CLAUDE_*`: Claude Code falls back to `CLOUD_ML_REGION`.

127127* `CLOUD_ML_REGION`: Claude Code falls back to `us-east5`.

128128

129[Prompt caching](/docs/en/prompt-caching.md) is enabled automatically. To disable it, set `DISABLE_PROMPT_CACHING=1`. To request a 1-hour cache TTL instead of the 5-minute default, set `ENABLE_PROMPT_CACHING_1H=1`; cache writes with a 1-hour TTL are billed at a higher rate. To set different TTLs for your main conversation and for the requests Claude Code makes outside it, [choose the TTL yourself](/docs/en/prompt-caching.md#choose-the-ttl-yourself).

129[Prompt caching](https://code.claude.com/docs/en/prompt-caching.md) is enabled automatically. To disable it, set `DISABLE_PROMPT_CACHING=1`. To request a 1-hour cache TTL instead of the 5-minute default, set `ENABLE_PROMPT_CACHING_1H=1`; cache writes with a 1-hour TTL are billed at a higher rate. To set different TTLs for your main conversation and for the requests Claude Code makes outside it, [choose the TTL yourself](https://code.claude.com/docs/en/prompt-caching.md#choose-the-ttl-yourself).

130130

131131To raise your rate limits, contact Google Cloud support. When using Google Cloud's Agent Platform, the `/logout` command is unavailable since authentication is handled through Google Cloud credentials.

132132

133Claude Code decides between [MCP tool search](/docs/en/mcp.md#scale-with-mcp-tool-search) and upfront loading by model generation:

133Claude Code decides between [MCP tool search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search) and upfront loading by model generation:

134134

135135* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later**: Claude Code enables tool search by default.

136136* **Earlier models**: Claude Code loads MCP tool definitions upfront, because their Agent Platform serving stacks reject the required beta header. Setting `ENABLE_TOOL_SEARCH=true` doesn't override this.

from line 153

153153export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

154154```

155155

156For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/docs/en/model-config.md#pin-models-for-third-party-deployments) for the full list of environment variables.

156For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](https://code.claude.com/docs/en/model-config.md#pin-models-for-third-party-deployments) for the full list of environment variables.

157157

158158Claude Code uses these default models when no pinning variables are set:

159159

from line 164

164164

165165Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Google Cloud's Agent Platform, Claude Code uses the default Sonnet model for background tasks because Haiku may not be enabled in every project or region. Two selections change which model carries them:

166166

167* When you select a primary model with `--model`, `ANTHROPIC_MODEL`, or the `model` setting, background tasks use that model. When Claude Code starts the session on the model you set with [`ANTHROPIC_DEFAULT_MODEL`](/docs/en/model-config#set-a-default-model-for-new-sessions), background tasks use that model too. Setting `ANTHROPIC_DEFAULT_OPUS_MODEL` without `ANTHROPIC_DEFAULT_SONNET_MODEL` also counts as a selection, because the built-in Sonnet model may not be enabled in a project that steers its own Opus.

167* When you select a primary model with `--model`, `ANTHROPIC_MODEL`, or the `model` setting, background tasks use that model. When Claude Code starts the session on the model you set with [`ANTHROPIC_DEFAULT_MODEL`](https://code.claude.com/docs/en/model-config#set-a-default-model-for-new-sessions), background tasks use that model too. Setting `ANTHROPIC_DEFAULT_OPUS_MODEL` without `ANTHROPIC_DEFAULT_SONNET_MODEL` also counts as a selection, because the built-in Sonnet model may not be enabled in a project that steers its own Opus.

168168* To use Haiku for background tasks, set `ANTHROPIC_DEFAULT_HAIKU_MODEL` to a model ID that is available in your project.

169169

170170> [!WARNING]

from line 182

182182

183183### 6. Verify your configuration

184184

185Start Claude Code and run `/status` to confirm the setup. The `API provider` line shows `Google Vertex AI`, and the `GCP project`, `Default region`, and `Model` lines show your project ID, region, and resolved model. If the provider line is missing, the environment variables aren't reaching the process. Confirm they are exported in the shell where you launched `claude`, or set them in the `env` block of your [settings file](/docs/en/settings.md).

186186

187187## Startup model checks

188188

189189When Claude Code starts with Google Cloud's Agent Platform configured, it verifies that the models it intends to use are accessible in your project.

190190

191If you have pinned a model version that is older than the current Claude Code default, and your project can invoke the newer version, Claude Code prompts you to update the pin. Accepting writes the new model ID to your [user settings file](/docs/en/settings.md) and restarts Claude Code. Declining is remembered until the next default version change.

191If you have pinned a model version that is older than the current Claude Code default, and your project can invoke the newer version, Claude Code prompts you to update the pin. Accepting writes the new model ID to your [user settings file](https://code.claude.com/docs/en/settings.md) and restarts Claude Code. Declining is remembered until the next default version change.

192192

193193If you have not pinned a model and the current default is unavailable in your project, Claude Code falls back for the current session and shows a notice. It tries earlier versions of the default model first and, when the default is an Opus model and no Opus version is available, falls back to the default Sonnet model. The fallback is not persisted. Enable the newer model in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) or [pin a version](#5-pin-model-versions) to make the choice permanent.

194194

195When you start the session on a specific Sonnet or Opus version, for example with `--model`, `ANTHROPIC_MODEL`, or the [`model` setting](/docs/en/settings-reference#model), that version acts as the session's pinned default for the matching `sonnet` or `opus` alias. Claude Code skips the availability check for the built-in default your model replaces and starts on the model you configured, with no fallback notice.

195When you start the session on a specific Sonnet or Opus version, for example with `--model`, `ANTHROPIC_MODEL`, or the [`model` setting](https://code.claude.com/docs/en/settings-reference#model), that version acts as the session's pinned default for the matching `sonnet` or `opus` alias. Claude Code skips the availability check for the built-in default your model replaces and starts on the model you configured, with no fallback notice.

196196

197197Model aliases such as `opus` don't act as pins, and neither does a model ID Claude Code doesn't recognize.

198198

199When these checks find a model your project can't invoke, Claude Code remembers the refusal on this machine for up to a day, and launches during that time skip the remembered model without asking Agent Platform again. Claude Code checks a remembered refusal of a current default model again at launch once ten minutes have passed since the last check, so a default your administrator re-enables comes back. To turn the memory off, set [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/en/env-vars).

200200

201201### When your organization enforces a model allowlist

202202

203If you set [`enforceAvailableModels`](/docs/en/model-config#enforce-the-allowlist-for-the-default-model) in managed settings, the startup model checks use only models your `availableModels` list permits. This requires Claude Code v2.1.287 or later. A list without `enforceAvailableModels` doesn't restrict these checks.

203If you set [`enforceAvailableModels`](https://code.claude.com/docs/en/model-config#enforce-the-allowlist-for-the-default-model) in managed settings, the startup model checks use only models your `availableModels` list permits. This requires Claude Code v2.1.287 or later. A list without `enforceAvailableModels` doesn't restrict these checks.

204204

205205The checks compare each entry with the model ID they would send to Agent Platform, so write the list in those IDs. This example permits Opus 4.8 and Sonnet 4.5:

206206

from line 211

211211}

212212```

213213

214For aliases, version prefixes, and `modelOverrides` entries, see [Pin models for third-party deployments](/docs/en/model-config.md#pin-models-for-third-party-deployments).

214For aliases, version prefixes, and `modelOverrides` entries, see [Pin models for third-party deployments](https://code.claude.com/docs/en/model-config.md#pin-models-for-third-party-deployments).

215215

216216### When a model is disabled mid-session

217217

218218If your project loses access to the model your session is running on, for example because an administrator disables it in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden), Claude Code switches the session to another model instead of failing each request, and shows `Switched to <fallback> because <model> is not available`. It tries the same models as the startup fallback: earlier versions of the same tier first and, for an Opus session with no Opus version available, the default Sonnet model.

219219

220The switch applies only to a tier you haven't pinned, the same condition as the startup fallback. A session on a specific version you picked keeps its model and, without a fallback model chain, the request fails instead. In [auto mode](/docs/en/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry), Claude Code switches only to a model auto mode supports on Agent Platform. If none of those models is available either, the request fails.

220The switch applies only to a tier you haven't pinned, the same condition as the startup fallback. A session on a specific version you picked keeps its model and, without a fallback model chain, the request fails instead. In [auto mode](https://code.claude.com/docs/en/permission-modes.md#enable-auto-mode-on-bedrock-agent-platform-or-foundry), Claude Code switches only to a model auto mode supports on Agent Platform. If none of those models is available either, the request fails.

221221

222A [fallback model chain](/docs/en/model-config.md#fallback-model-chains) you configure replaces the tier switch: on these refusals Claude Code switches to your configured fallback instead. To have refused requests fail rather than switch, set [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](/docs/en/env-vars). A fallback chain you configured still switches on these refusals; remove the chain as well if you want every refused request to fail.

222A [fallback model chain](https://code.claude.com/docs/en/model-config.md#fallback-model-chains) you configure replaces the tier switch: on these refusals Claude Code switches to your configured fallback instead. To have refused requests fail rather than switch, set [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](https://code.claude.com/docs/en/env-vars). A fallback chain you configured still switches on these refusals; remove the chain as well if you want every refused request to fail.

223223

224224## IAM configuration

225225

from line 237

237237

238238## 1M token context window

239239

240Fable models, Sonnet 5 and later, and Opus 4.7 and later run with the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) by default on Google Cloud's Agent Platform, with no `[1m]` suffix needed. To keep a 200K window instead, set [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/en/model-config#turn-off-1m-context).

241241

242Opus 4.6 and Sonnet 4.6 reach the 1M window when you select their `[1m]` variant. The [setup wizard](#sign-in-with-agent-platform) offers a 1M context option when it pins models. To enable it for a manually pinned model instead, append `[1m]` to the model ID. See [Pin models for third-party deployments](/docs/en/model-config.md#pin-models-for-third-party-deployments) for details, including how to use the 1M window without changing the pin.

242Opus 4.6 and Sonnet 4.6 reach the 1M window when you select their `[1m]` variant. The [setup wizard](#sign-in-with-agent-platform) offers a 1M context option when it pins models. To enable it for a manually pinned model instead, append `[1m]` to the model ID. See [Pin models for third-party deployments](https://code.claude.com/docs/en/model-config.md#pin-models-for-third-party-deployments) for details, including how to use the 1M window without changing the pin.

243243

244244Before v2.1.287, the Fable models and Opus 4.7 and later ran with a 200K window by default on Google Cloud's Agent Platform and reached the 1M window through a `[1m]` suffix.

245245

from line 261

261261* Verify the model is available in the location you specified. Some models are offered only on `global` or multi-region locations such as `eu` and `us`, not in specific regions

262262* If using `CLOUD_ML_REGION=global`, check that your models support global endpoints in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) under "Supported features". For models that don't support global endpoints, either:

263263 * Specify a supported model via `ANTHROPIC_MODEL` or `ANTHROPIC_DEFAULT_HAIKU_MODEL`, or

264 * Set a region or multi-region location using the model's `VERTEX_REGION_CLAUDE_*` variable, listed in the [environment variables reference](/docs/en/env-vars.md#variables)

264 * Set a region or multi-region location using the model's `VERTEX_REGION_CLAUDE_*` variable, listed in the [environment variables reference](https://code.claude.com/docs/en/env-vars.md#variables)

265265

266266If you encounter 429 errors:

267267

headless Changed · +67 / -67 lines

from line 2

33> Use the Agent SDK to run Claude Code programmatically from the CLI, Python, or TypeScript.

5The [Agent SDK](/docs/en/agent-sdk/overview.md) gives you the same tools, agent loop, and context management that power Claude Code. It's available as a CLI for scripts and CI/CD, or as [Python](/docs/en/agent-sdk/python.md) and [TypeScript](/docs/en/agent-sdk/typescript.md) packages for full programmatic control.

5The [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) gives you the same tools, agent loop, and context management that power Claude Code. It's available as a CLI for scripts and CI/CD, or as [Python](https://code.claude.com/docs/en/agent-sdk/python.md) and [TypeScript](https://code.claude.com/docs/en/agent-sdk/typescript.md) packages for full programmatic control.

7To run Claude Code in non-interactive mode, pass `-p` with your prompt and the [CLI options](/docs/en/cli-reference.md) you need:

7To run Claude Code in non-interactive mode, pass `-p` with your prompt and the [CLI options](https://code.claude.com/docs/en/cli-reference.md) you need:

99```bash theme={null}

1010claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

1111```

1212

13This page covers using the Agent SDK via the CLI (`claude -p`). For the Python and TypeScript SDK packages with structured outputs, tool approval callbacks, and native message objects, see the [full Agent SDK documentation](/docs/en/agent-sdk/overview.md).

1414

1515## Basic usage

1616

17Add the `-p` (or `--print`) flag to any `claude` command to run it non-interactively. Not every [CLI option](/docs/en/cli-reference.md) combines with `-p`. Claude Code rejects `--bg`, and rejects `--cloud` with a task description, with an error naming the conflict; `--cloud` with a session ID and `-p` instead [queues a message into that cloud session](/docs/en/claude-code-on-the-web.md#send-follow-ups-from-the-cli) and exits. Options you'll combine with `-p` often include:

17Add the `-p` (or `--print`) flag to any `claude` command to run it non-interactively. Not every [CLI option](https://code.claude.com/docs/en/cli-reference.md) combines with `-p`. Claude Code rejects `--bg`, and rejects `--cloud` with a task description, with an error naming the conflict; `--cloud` with a session ID and `-p` instead [queues a message into that cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md#send-follow-ups-from-the-cli) and exits. Options you'll combine with `-p` often include:

1818

1919* `--continue` for [continuing conversations](#continue-conversations)

2020* `--allowedTools` for [auto-approving tools](#auto-approve-tools)

from line 30

3030

3131### Start faster with bare mode

3232

33Add `--bare` to reduce startup time by skipping auto-discovery of hooks, skills, custom commands, [subagents](/docs/en/sub-agents.md), installed plugins, MCP servers, auto memory, and CLAUDE.md. Without it, `claude -p` discovers and loads them as an interactive session would, including anything configured in the working directory or `~/.claude`.

33Add `--bare` to reduce startup time by skipping auto-discovery of hooks, skills, custom commands, [subagents](https://code.claude.com/docs/en/sub-agents.md), installed plugins, MCP servers, auto memory, and CLAUDE.md. Without it, `claude -p` discovers and loads them as an interactive session would, including anything configured in the working directory or `~/.claude`.

3434

35Bare mode is useful for CI and scripts where you need the same result on every machine. A hook in a teammate's `~/.claude` or an MCP server in the project's `.mcp.json` won't run, because bare mode never reads them. A directory you name with `--add-dir` is a partial exception: bare mode loads skills from its `.claude/skills/` folder, but still skips its `.claude/commands/` and `.claude/agents/` folders. [Skills from additional directories](/docs/en/skills.md#skills-from-additional-directories) covers what does and doesn't load.

35Bare mode is useful for CI and scripts where you need the same result on every machine. A hook in a teammate's `~/.claude` or an MCP server in the project's `.mcp.json` won't run, because bare mode never reads them. A directory you name with `--add-dir` is a partial exception: bare mode loads skills from its `.claude/skills/` folder, but still skips its `.claude/commands/` and `.claude/agents/` folders. [Skills from additional directories](https://code.claude.com/docs/en/skills.md#skills-from-additional-directories) covers what does and doesn't load.

3636

37Without `--bare`, a `-p` session runs the hooks in a project's `.claude/settings.json` and connects the servers in its `.mcp.json`, even in a folder you've never trusted. A `-p` session shows no workspace trust dialog and no per-server approval prompt. [What runs before you trust a folder](/docs/en/permissions.md#what-runs-before-you-trust-a-folder) covers each kind of repository content under `-p` and how to keep it out.

37Without `--bare`, a `-p` session runs the hooks in a project's `.claude/settings.json` and connects the servers in its `.mcp.json`, even in a folder you've never trusted. A `-p` session shows no workspace trust dialog and no per-server approval prompt. [What runs before you trust a folder](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) covers each kind of repository content under `-p` and how to keep it out.

3838

3939This example runs a one-off summarize task in bare mode and pre-approves the Read tool so the call completes without a permission prompt. Set `ANTHROPIC_API_KEY` before running it, because bare mode doesn't use your subscription login:

4040

from line 51

5151| System prompt additions | `--append-system-prompt`, `--append-system-prompt-file` |

5252| Settings | `--settings <file-or-json>` |

5353| MCP servers | `--mcp-config <file-or-json>` |

54| [Custom agents](/docs/en/sub-agents.md#choose-the-subagent-scope) | `--agents <file-or-json>` |

54| [Custom agents](https://code.claude.com/docs/en/sub-agents.md#choose-the-subagent-scope) | `--agents <file-or-json>` |

5555| A plugin | `--plugin-dir <path>`, `--plugin-url <url>` |

5656

5757Bare mode also limits what happens while the session runs:

5858

5959* **MCP servers**: only servers supplied on the command line connect, for example with `--mcp-config`. In an interactive session, Claude Code also skips the automatic IDE connection unless you pass `--ide`.

60* **System reminders**: Claude gets your prompts and the tool results without the [system reminders](/docs/en/glossary.md#system-reminder) Claude Code would add alongside them. For example, Claude isn't told when a file it read earlier changes on disk, and it doesn't get the list of available skills, including skills from an `--add-dir` folder.

61* **Background tasks**: Claude can't run background commands or background subagents, and the other features that [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/en/env-vars) turns off are off too. A command that reaches its [timeout](/docs/en/tools-reference.md#timeout-and-output-limits) stops instead of [moving to the background](/docs/en/tools-reference.md#background-commands).

60* **System reminders**: Claude gets your prompts and the tool results without the [system reminders](https://code.claude.com/docs/en/glossary.md#system-reminder) Claude Code would add alongside them. For example, Claude isn't told when a file it read earlier changes on disk, and it doesn't get the list of available skills, including skills from an `--add-dir` folder.

61* **Background tasks**: Claude can't run background commands or background subagents, and the other features that [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/en/env-vars) turns off are off too. A command that reaches its [timeout](https://code.claude.com/docs/en/tools-reference.md#timeout-and-output-limits) stops instead of [moving to the background](https://code.claude.com/docs/en/tools-reference.md#background-commands).

6262

6363Before v2.1.286, these limits held only partly: an interactive `--bare` session connected the MCP servers that a normal session would, every `--bare` session sent system reminders, and background tasks stayed available.

6464

from line 70

7070

7171After Claude finishes its turn and stdin has closed, a `claude -p` run can stay open to wait for background work that Claude started.

7272

73Unless a background command that the main conversation started is still running, Claude Code stops whatever is still running after 10 minutes of continuous idle waiting by default and drops its partial result. To change the 10-minute cap, set [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](/docs/en/env-vars), or set it to `0` to wait without one.

73Unless a background command that the main conversation started is still running, Claude Code stops whatever is still running after 10 minutes of continuous idle waiting by default and drops its partial result. To change the 10-minute cap, set [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](https://code.claude.com/docs/en/env-vars), or set it to `0` to wait without one.

7474

7575The run waits for background work such as background commands, subagents and workflows, Monitor watches, and pending `/loop` wakeups:

7676

77* **[Background commands](/docs/en/tools-reference.md#background-commands)**: for a command that the main conversation started, for example a dev server or a watch build, the run waits until the command exits or reaches its [time limit](/docs/en/tools-reference.md#time-limit-for-background-commands). Claude then takes one more turn with the outcome. While the command runs, the 10-minute cap doesn't end the wait.

78* **Background [subagents](/docs/en/sub-agents.md) and workflows**: the run stays open until that work completes, because its result is part of the final output.

79* **[Monitor](/docs/en/tools-reference.md#monitor-tool) watches**: the run waits until the watch times out or the 10-minute cap ends the wait, whichever comes first. While it waits, Claude keeps responding to what the watch reports. By default, a watch times out five minutes after Claude starts it.

80* **Pending wakeups**: in a run whose prompt you passed as text rather than with `--input-format stream-json`, when Claude has scheduled a [self-paced `/loop` wakeup](/docs/en/scheduled-tasks#let-claude-choose-the-interval), the run waits for each wakeup to fire and runs its iteration until the [loop ends](/docs/en/scheduled-tasks.md#stop-a-loop), even past the 10-minute cap.

77* **[Background commands](https://code.claude.com/docs/en/tools-reference.md#background-commands)**: for a command that the main conversation started, for example a dev server or a watch build, the run waits until the command exits or reaches its [time limit](https://code.claude.com/docs/en/tools-reference.md#time-limit-for-background-commands). Claude then takes one more turn with the outcome. While the command runs, the 10-minute cap doesn't end the wait.

78* **Background [subagents](https://code.claude.com/docs/en/sub-agents.md) and workflows**: the run stays open until that work completes, because its result is part of the final output.

79* **[Monitor](https://code.claude.com/docs/en/tools-reference.md#monitor-tool) watches**: the run waits until the watch times out or the 10-minute cap ends the wait, whichever comes first. While it waits, Claude keeps responding to what the watch reports. By default, a watch times out five minutes after Claude starts it.

80* **Pending wakeups**: in a run whose prompt you passed as text rather than with `--input-format stream-json`, when Claude has scheduled a [self-paced `/loop` wakeup](https://code.claude.com/docs/en/scheduled-tasks#let-claude-choose-the-interval), the run waits for each wakeup to fire and runs its iteration until the [loop ends](https://code.claude.com/docs/en/scheduled-tasks.md#stop-a-loop), even past the 10-minute cap.

8181

8282When stderr is a terminal and the run has waited five seconds, Claude Code prints a line to stderr that starts with `Waiting for background work to finish` and names the work. With [`json` or `stream-json` output](#get-structured-output), the line prints only when stdout isn't a terminal, so the JSON your script reads never carries it.

8383

84If the run reaches its [`--max-budget-usd`](/docs/en/cli-reference#cli-flags) cap, Claude Code stops the remaining background work instead of waiting.

84If the run reaches its [`--max-budget-usd`](https://code.claude.com/docs/en/cli-reference#cli-flags) cap, Claude Code stops the remaining background work instead of waiting.

8585

8686When background work starts another turn, the run prints each turn's result with the default `text` output and the last turn's result with `json` output. Before v2.1.295, the run printed only the last turn's result with `text` output too.

8787

from line 89

8989

9090A `claude -p` run doesn't wait for MCP work in the background:

9191

92* **[MCP tasks](/docs/en/mcp.md#mcp-tasks-that-run-on-the-server)**: on a remote server the job goes on. To follow it again, [resume that session](/docs/en/mcp.md#exit-clear-or-resume-while-an-mcp-task-runs), not as a one-shot `claude -p "<prompt>"` run.

93* **MCP calls that [automatic backgrounding](/docs/en/mcp.md#automatic-backgrounding-of-long-tool-calls) moved**: the call's result is lost.

92* **[MCP tasks](https://code.claude.com/docs/en/mcp.md#mcp-tasks-that-run-on-the-server)**: on a remote server the job goes on. To follow it again, [resume that session](https://code.claude.com/docs/en/mcp.md#exit-clear-or-resume-while-an-mcp-task-runs), not as a one-shot `claude -p "<prompt>"` run.

93* **MCP calls that [automatic backgrounding](https://code.claude.com/docs/en/mcp.md#automatic-backgrounding-of-long-tool-calls) moved**: the call's result is lost.

9494

9595### Stop a run with SIGTERM

9696

9797If you stop a `claude -p` run with SIGTERM, for example with `kill` or from a process supervisor, Claude Code exits with code 143. Claude Code leaves the turn that was in progress unfinished and records no result for it. To end the turn instead, send SIGINT, or call the Agent SDK's `interrupt()`, before you stop the process.

9898

99On SIGTERM, Claude Code terminates the process tree of any Bash command that is still running. Claude Code then runs [`SessionEnd` hooks](/docs/en/hooks#sessionend) and exits. While exiting, Claude Code starts no new tool call, sends no new model request, and runs no hook other than `SessionEnd`. If the run was in the middle of a command or waiting on a permission prompt when the signal arrived, Claude Code handles that step as follows:

99On SIGTERM, Claude Code terminates the process tree of any Bash command that is still running. Claude Code then runs [`SessionEnd` hooks](https://code.claude.com/docs/en/hooks#sessionend) and exits. While exiting, Claude Code starts no new tool call, sends no new model request, and runs no hook other than `SessionEnd`. If the run was in the middle of a command or waiting on a permission prompt when the signal arrived, Claude Code handles that step as follows:

100100

101101* **Running a command**: Claude Code records the command as killed in the session.

102102* **Waiting for an answer to a permission prompt**: if you send SIGTERM to the process, Claude Code leaves the prompt unanswered. If your program closes the session through the Agent SDK, the SDK ends Claude Code's input before sending any signal, and Claude Code cancels the prompt as soon as the input ends.

103103

104When you [resume the session](#continue-conversations), Claude Code leaves the interrupted turn as it is, and your next prompt drives the conversation. To have Claude Code continue the interrupted turn on resume instead, set [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](/docs/en/env-vars).

105105

106106### If the working directory is deleted

107107

108If the working directory of a `claude -p` or Agent SDK session is deleted mid-session, the session keeps running. When a turn starts while the directory is missing, Claude Code emits a [warning message](/docs/en/agent-sdk/typescript.md#sdkinformationalmessage) in `stream-json` output, and shell commands fail until the directory exists again.

108If the working directory of a `claude -p` or Agent SDK session is deleted mid-session, the session keeps running. When a turn starts while the directory is missing, Claude Code emits a [warning message](https://code.claude.com/docs/en/agent-sdk/typescript.md#sdkinformationalmessage) in `stream-json` output, and shell commands fail until the directory exists again.

109109

110110## Examples

111111

from line 121

121121cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

122122```

123123

124With `--output-format json`, the response payload includes `total_cost_usd` and a per-model cost breakdown, so scripted callers can track spend without consulting the [usage dashboard](/docs/en/costs.md). When you continue an earlier conversation with `--continue` or `--resume`, the run reports the conversation's whole total, [earlier runs' spend included](/docs/en/agent-sdk/cost-tracking.md#accumulate-costs-across-multiple-calls). Both figures are [client-side estimates](/docs/en/agent-sdk/cost-tracking.md) and can differ from your actual bill.

124With `--output-format json`, the response payload includes `total_cost_usd` and a per-model cost breakdown, so scripted callers can track spend without consulting the [usage dashboard](https://code.claude.com/docs/en/costs.md). When you continue an earlier conversation with `--continue` or `--resume`, the run reports the conversation's whole total, [earlier runs' spend included](https://code.claude.com/docs/en/agent-sdk/cost-tracking.md#accumulate-costs-across-multiple-calls). Both figures are [client-side estimates](https://code.claude.com/docs/en/agent-sdk/cost-tracking.md) and can differ from your actual bill.

125125

126126> [!NOTE]

127127>

from line 207

207207 jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

208208```

209209

210For programmatic streaming with callbacks and message objects, see [Stream responses in real-time](/docs/en/agent-sdk/streaming-output.md) in the Agent SDK documentation.

210For programmatic streaming with callbacks and message objects, see [Stream responses in real-time](https://code.claude.com/docs/en/agent-sdk/streaming-output.md) in the Agent SDK documentation.

211211

212212#### Follow subagent messages

213213

214Messages from [subagents](/docs/en/sub-agents.md) and from skills that [run in a subagent](/docs/en/skills.md#run-skills-in-a-subagent) appear in the stream as `assistant` and `user` messages. Their `parent_tool_use_id` field says which run each one belongs to. Messages from the main conversation carry `null` in that field.

214Messages from [subagents](https://code.claude.com/docs/en/sub-agents.md) and from skills that [run in a subagent](https://code.claude.com/docs/en/skills.md#run-skills-in-a-subagent) appear in the stream as `assistant` and `user` messages. Their `parent_tool_use_id` field says which run each one belongs to. Messages from the main conversation carry `null` in that field.

215215

216The first message from a forked skill, or from a subagent running in the [foreground](/docs/en/sub-agents.md#run-subagents-in-foreground-or-background), is a `user` message carrying the prompt or skill content that drives it. After that first message, Claude Code emits:

216The first message from a forked skill, or from a subagent running in the [foreground](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background), is a `user` message carrying the prompt or skill content that drives it. After that first message, Claude Code emits:

217217

218218* **By default**: the run's `tool_use` and `tool_result` blocks.

219* **With [`--forward-subagent-text`](/docs/en/cli-reference#cli-flags) or [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/en/env-vars)**: the run's text and thinking blocks too, so you can reconstruct each run's transcript.

219* **With [`--forward-subagent-text`](https://code.claude.com/docs/en/cli-reference#cli-flags) or [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](https://code.claude.com/docs/en/env-vars)**: the run's text and thinking blocks too, so you can reconstruct each run's transcript.

220220

221When you enable either option, Claude Code forwards messages from [subagents at every nesting depth](/docs/en/sub-agents.md#let-subagents-spawn-their-own-subagents), whether each one was spawned with the Agent tool or started as a forked skill. In `parent_tool_use_id`, the nested subagent's messages carry the ID of the Agent or Skill tool call that started it, so you can rebuild the full nesting tree by following those IDs.

221When you enable either option, Claude Code forwards messages from [subagents at every nesting depth](https://code.claude.com/docs/en/sub-agents.md#let-subagents-spawn-their-own-subagents), whether each one was spawned with the Agent tool or started as a forked skill. In `parent_tool_use_id`, the nested subagent's messages carry the ID of the Agent or Skill tool call that started it, so you can rebuild the full nesting tree by following those IDs.

222222

223223A run that Claude starts with a tool call carries that tool call's ID. A forked skill that you start by passing `/<skill-name>` as the prompt has no tool call, so its messages carry a `forked-command-` value instead and arrive after it finishes. Find how the run started in the first column:

224224

from line 239

239239

240240#### Handle API retries

241241

242When an API request fails with a retryable error, Claude Code emits a `system/api_retry` event before retrying. On v2.1.246 or later, when a `401` or `403` rejects an [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) credential, Claude Code makes the first two retries quietly with no event, then emits the event as usual from the third consecutive retry onward. The quiet retries still count toward `attempt`. You can use the event to show retry progress in your own interface.

242When an API request fails with a retryable error, Claude Code emits a `system/api_retry` event before retrying. On v2.1.246 or later, when a `401` or `403` rejects an [`apiKeyHelper`](https://code.claude.com/docs/en/settings-reference#apikeyhelper) credential, Claude Code makes the first two retries quietly with no event, then emits the event as usual from the third consecutive retry onward. The quiet retries still count toward `attempt`. You can use the event to show retry progress in your own interface.

243243

244244| Field | Type | Description |

245245| - | - | - |

from line 249

249249| `max_retries` | integer | total retries permitted for this failure's cause |

250250| `retry_delay_ms` | integer | milliseconds until the next attempt |

251251| `error_status` | integer or null | HTTP status code of the failed attempt, or `null` when the attempt got no HTTP response from the API |

252| `no_response` | object, optional | present only when the failed attempt got [no response headers in time](/docs/en/errors.md#no-response-from-api). `waited_ms` is how long that attempt waited and `retry_wait_ms` is how long the retry will wait. Requires Claude Code v2.1.261 or later |

252| `no_response` | object, optional | present only when the failed attempt got [no response headers in time](https://code.claude.com/docs/en/errors.md#no-response-from-api). `waited_ms` is how long that attempt waited and `retry_wait_ms` is how long the retry will wait. Requires Claude Code v2.1.261 or later |

253253| `error` | string | error category: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, or `unknown` |

254254| `uuid` | string | unique event identifier |

255255| `session_id` | string | session the event belongs to |

from line 258

258258

259259The `system/init` event reports session metadata including the model, tools, MCP servers, and loaded plugins. It is the first event in the stream unless startup events precede it:

260260

261* `plugin_install` events, when [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/en/env-vars) is set.

262* [`hook_started`, `hook_progress`, and `hook_response` events](/docs/en/agent-sdk/typescript#sdkhookstartedmessage), while a configured [`SessionStart`](/docs/en/hooks#sessionstart) or [`Setup`](/docs/en/hooks#setup) hook runs. These stream as the hook produces them.

261* `plugin_install` events, when [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](https://code.claude.com/docs/en/env-vars) is set.

262* [`hook_started`, `hook_progress`, and `hook_response` events](https://code.claude.com/docs/en/agent-sdk/typescript#sdkhookstartedmessage), while a configured [`SessionStart`](https://code.claude.com/docs/en/hooks#sessionstart) or [`Setup`](https://code.claude.com/docs/en/hooks#setup) hook runs. These stream as the hook produces them.

263263

264The event also carries an optional `capabilities` array of strings naming the protocol behaviors this Claude Code version implements, such as `interrupt_receipt_v1` or `interrupt_cancel_queued_v1`. Check it to feature-detect instead of comparing version strings, and ignore values you don't recognize. See [`SDKSystemMessage`](/docs/en/agent-sdk/typescript#sdksystemmessage) for the capability list.

264The event also carries an optional `capabilities` array of strings naming the protocol behaviors this Claude Code version implements, such as `interrupt_receipt_v1` or `interrupt_cancel_queued_v1`. Check it to feature-detect instead of comparing version strings, and ignore values you don't recognize. See [`SDKSystemMessage`](https://code.claude.com/docs/en/agent-sdk/typescript#sdksystemmessage) for the capability list.

265265

266266#### Fail CI when a plugin or MCP server doesn't load

267267

from line 274

274274

275275When a `--plugin-dir` directory or archive itself fails to load, its `plugin_errors` entry includes the resolved absolute path as `path`. Use it to tell which of several `--plugin-dir` values failed. The `path` field requires Claude Code v2.1.283 or later.

276276

277Use the MCP server fields the same way. When you pass [`--mcp-config`](/docs/en/cli-reference#cli-flags) with `-p`, Claude Code waits for still-pending servers before running the first turn, up to the [`MCP_TIMEOUT`](/docs/en/env-vars) startup timeout, 30 seconds by default. A remote server with a [cached tool list](/docs/en/agent-sdk/mcp.md#connection-timing) skips the wait, shows `pending` in `system/init`, and connects on its first tool call. In a [self-hosted environment](/docs/en/self-hosted-environments-configuration.md#connection-timing), a shorter wait applies instead. The wait requires Claude Code v2.1.221 or later.

277Use the MCP server fields the same way. When you pass [`--mcp-config`](https://code.claude.com/docs/en/cli-reference#cli-flags) with `-p`, Claude Code waits for still-pending servers before running the first turn, up to the [`MCP_TIMEOUT`](https://code.claude.com/docs/en/env-vars) startup timeout, 30 seconds by default. A remote server with a [cached tool list](https://code.claude.com/docs/en/agent-sdk/mcp.md#connection-timing) skips the wait, shows `pending` in `system/init`, and connects on its first tool call. In a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#connection-timing), a shorter wait applies instead. The wait requires Claude Code v2.1.221 or later.

278278

279279Claude Code validates each `--mcp-config` entry at startup and skips entries that fail validation, for example a `url` entry with no `type`. The run continues and exits cleanly, so check these fields to catch a server that never loaded:

280280

from line 287

287287

288288#### Track plugin installs

289289

290When [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/en/env-vars) is set, Claude Code emits `system/plugin_install` events while marketplace plugins install before the first turn. Use these to surface install progress in your own UI.

290When [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](https://code.claude.com/docs/en/env-vars) is set, Claude Code emits `system/plugin_install` events while marketplace plugins install before the first turn. Use these to surface install progress in your own UI.

291291

292292| Field | Type | Description |

293293| - | - | - |

from line 301

301301

302302### Auto-approve tools

303303

304Use `--allowedTools` to let Claude use certain tools without prompting. Listing `Read` and `Edit` lets Claude read and edit files without asking for permission, apart from reads from [network paths](/docs/en/permissions.md#network-paths). Listing `Bash` does the same for shell commands, except in a run that starts in [auto mode](/docs/en/permission-modes.md#how-auto-mode-evaluates-actions), where Claude Code drops a bare `Bash` entry as a broad allow rule and auto mode evaluates each command instead. This example runs a test suite and fixes failures with those three tools listed:

304Use `--allowedTools` to let Claude use certain tools without prompting. Listing `Read` and `Edit` lets Claude read and edit files without asking for permission, apart from reads from [network paths](https://code.claude.com/docs/en/permissions.md#network-paths). Listing `Bash` does the same for shell commands, except in a run that starts in [auto mode](https://code.claude.com/docs/en/permission-modes.md#how-auto-mode-evaluates-actions), where Claude Code drops a bare `Bash` entry as a broad allow rule and auto mode evaluates each command instead. This example runs a test suite and fixes failures with those three tools listed:

305305

306306```bash theme={null}

307307claude -p "Run the test suite and fix any failures" \

from line 308

308308 --allowedTools "Bash,Read,Edit"

309309```

310310

311Calls to tools you didn't list run if they need no approval. In a [Manual mode](/docs/en/permission-modes.md#available-modes) `claude -p` run, a call that needs approval is denied unless something approves it, such as a [`PermissionRequest` hook](/docs/en/hooks#permissionrequest) or a [`--permission-prompt-tool`](/docs/en/cli-reference#cli-flags). With Claude Code v2.1.302 or later, `claude -p` runs start in Manual mode when [nothing sets a permission mode](/docs/en/permission-modes.md#which-mode-a-non-interactive-run-starts-in).

311Calls to tools you didn't list run if they need no approval. In a [Manual mode](https://code.claude.com/docs/en/permission-modes.md#available-modes) `claude -p` run, a call that needs approval is denied unless something approves it, such as a [`PermissionRequest` hook](https://code.claude.com/docs/en/hooks#permissionrequest) or a [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags). With Claude Code v2.1.302 or later, `claude -p` runs start in Manual mode when [nothing sets a permission mode](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-non-interactive-run-starts-in).

312312

313To set a baseline for the whole session instead of listing individual tools, pass a [permission mode](/docs/en/permission-modes.md) with `--permission-mode`, such as `auto`, `dontAsk`, or `acceptEdits`:

313To set a baseline for the whole session instead of listing individual tools, pass a [permission mode](https://code.claude.com/docs/en/permission-modes.md) with `--permission-mode`, such as `auto`, `dontAsk`, or `acceptEdits`:

314314

315315* **`auto`**: pass `--permission-mode auto` to have a classifier review most actions instead of you

316* **`dontAsk`**: Claude Code denies every call that would otherwise prompt, which is useful for locked-down CI runs, though a [mod](/docs/en/plugins/mods/overview.md) you installed can still approve some of those calls. To check which calls a mod can approve, see [Extend permissions with hooks](/docs/en/permissions.md#precedence-among-rules-hooks-and-mods).

316* **`dontAsk`**: Claude Code denies every call that would otherwise prompt, which is useful for locked-down CI runs, though a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) you installed can still approve some of those calls. To check which calls a mod can approve, see [Extend permissions with hooks](https://code.claude.com/docs/en/permissions.md#precedence-among-rules-hooks-and-mods).

317317

318 Actions that need no approval in Manual mode still run, such as file reads in your working directories and the [read-only command set](/docs/en/permissions.md#read-only-commands). Actions covered by your `--allowedTools` entries or `permissions.allow` rules also run. `AskUserQuestion`, connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools), MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool), and [reads from network paths](/docs/en/permissions.md#network-paths) are denied even when an allow rule matches

319* **`acceptEdits`**: Claude writes files without prompting, and Claude Code auto-approves common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp`. The [actions no mode auto-approves](/docs/en/permission-modes.md#actions-no-mode-auto-approves) still apply. Apart from the read-only command set, other shell commands and network requests still need an `--allowedTools` entry or a `permissions.allow` rule. See [what `acceptEdits` auto-approves](/docs/en/permission-modes#auto-approve-file-edits-with-acceptedits-mode) for the full list

318 Actions that need no approval in Manual mode still run, such as file reads in your working directories and the [read-only command set](https://code.claude.com/docs/en/permissions.md#read-only-commands). Actions covered by your `--allowedTools` entries or `permissions.allow` rules also run. `AskUserQuestion`, connector tools [your organization set to `ask`](https://code.claude.com/docs/en/mcp#organization-controls-on-connector-tools), MCP tools marked [`requiresUserInteraction`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool), and [reads from network paths](https://code.claude.com/docs/en/permissions.md#network-paths) are denied even when an allow rule matches

319* **`acceptEdits`**: Claude writes files without prompting, and Claude Code auto-approves common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp`. The [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves) still apply. Apart from the read-only command set, other shell commands and network requests still need an `--allowedTools` entry or a `permissions.allow` rule. See [what `acceptEdits` auto-approves](https://code.claude.com/docs/en/permission-modes#auto-approve-file-edits-with-acceptedits-mode) for the full list

320320

321321This example applies lint fixes with `acceptEdits` as the baseline:

322322

from line 326

326326

327327### Turn off permission prompts in unattended runs

328328

329Pass `--permission-prompts none` when nobody is available to answer permission prompts, for example in a scheduled job. The flag matters most when your run has a permission host: an Agent SDK app with a [`canUseTool` callback](/docs/en/agent-sdk/user-input), or an MCP tool you pass with [`--permission-prompt-tool`](/docs/en/cli-reference#cli-flags). Without the flag, your run waits for that host to answer each permission request.

329Pass `--permission-prompts none` when nobody is available to answer permission prompts, for example in a scheduled job. The flag matters most when your run has a permission host: an Agent SDK app with a [`canUseTool` callback](https://code.claude.com/docs/en/agent-sdk/user-input), or an MCP tool you pass with [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags). Without the flag, your run waits for that host to answer each permission request.

330330

331With the flag, your run doesn't consult the host or wait on it. Anything that would prompt is denied unless a `PermissionRequest` hook allows it, Claude is told that nobody can approve the request and not to retry it, and the run continues. In a `-p` run with no host, these requests are denied either way, and the flag also tells Claude not to retry them. Permission rules, [`PermissionRequest` hooks](/docs/en/hooks#permissionrequest), and the permission mode you set still decide every call first; Claude Code denies only the requests that nothing else resolves.

331With the flag, your run doesn't consult the host or wait on it. Anything that would prompt is denied unless a `PermissionRequest` hook allows it, Claude is told that nobody can approve the request and not to retry it, and the run continues. In a `-p` run with no host, these requests are denied either way, and the flag also tells Claude not to retry them. Permission rules, [`PermissionRequest` hooks](https://code.claude.com/docs/en/hooks#permissionrequest), and the permission mode you set still decide every call first; Claude Code denies only the requests that nothing else resolves.

332332

333This example runs an unattended task in [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode). The classifier reviews each action as usual, and Claude Code denies anything that would have fallen back to a prompt:

333This example runs an unattended task in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode). The classifier reviews each action as usual, and Claude Code denies anything that would have fallen back to a prompt:

334334

335335```bash theme={null}

336336claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

337337```

338338

339With `--permission-prompts none`, Claude Code removes the tools that need an answer from a person, such as [`AskUserQuestion`](/docs/en/tools-reference#askuserquestion-tool-behavior), so Claude can't call them. Any [MCP elicitation request](/docs/en/mcp.md#respond-to-mcp-elicitation-requests) that no [`Elicitation` hook](/docs/en/hooks#elicitation) answers is cancelled.

339With `--permission-prompts none`, Claude Code removes the tools that need an answer from a person, such as [`AskUserQuestion`](https://code.claude.com/docs/en/tools-reference#askuserquestion-tool-behavior), so Claude can't call them. Any [MCP elicitation request](https://code.claude.com/docs/en/mcp.md#respond-to-mcp-elicitation-requests) that no [`Elicitation` hook](https://code.claude.com/docs/en/hooks#elicitation) answers is cancelled.

340340

341341With `--output-format stream-json`, denials appear as `permission_denied` system messages, and the final result message lists them in `permission_denials`.

342342

from line 353

353353 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

354354```

355355

356The `--allowedTools` flag uses [permission rule syntax](/docs/en/settings-reference.md#permission-rule-syntax). The trailing ` *` enables prefix matching, so `Bash(git diff *)` allows any command starting with `git diff`. The space before `*` is important: without it, `Bash(git diff*)` would also match `git diff-index`.

356The `--allowedTools` flag uses [permission rule syntax](https://code.claude.com/docs/en/settings-reference.md#permission-rule-syntax). The trailing ` *` enables prefix matching, so `Bash(git diff *)` allows any command starting with `git diff`. The space before `*` is important: without it, `Bash(git diff*)` would also match `git diff-index`.

357357

358358> [!NOTE]

359359>

360360> Command support differs in `-p` mode:

361361>

362> * User-invoked [skills](/docs/en/skills.md) and custom commands work. Include `/skill-name` in the prompt string and Claude Code expands it before running.

362> * User-invoked [skills](https://code.claude.com/docs/en/skills.md) and custom commands work. Include `/skill-name` in the prompt string and Claude Code expands it before running.

363363> * Built-in commands that only run in the terminal interface, such as `/login`, aren't available.

364> * `/model`, `/effort`, `/fast`, `/color`, and `/rename` accept the value as an argument, for example `/model sonnet`, and `/mcp` with no argument prints a text summary of server status. These forms follow each command's [availability notes](/docs/en/commands.md#all-commands).

365365> * To change a setting, pass `key=value` to `/config`, for example `/config thinking=false`.

366> * `/output-style <style>` switches [output styles](/docs/en/output-styles.md) and `/output-style` alone lists them. Requires Claude Code v2.1.269 or later.

366> * `/output-style <style>` switches [output styles](https://code.claude.com/docs/en/output-styles.md) and `/output-style` alone lists them. Requires Claude Code v2.1.269 or later.

367367

368368### Customize the system prompt

369369

from line 377

377377

378378In the script, `"$1"` stands for the first argument you pass on the command line. Run `bash review.sh 123` and the shell replaces `"$1"` with `123`, so the script fetches the diff for PR 123. Claude Code prints the review as JSON, with the text in the `result` field.

379379

380See [system prompt flags](/docs/en/cli-reference.md#system-prompt-flags) for more options including `--system-prompt` to fully replace the default prompt. If you replace it, the run also starts without the [git status snapshot](/docs/en/settings-reference.md#includegitinstructions).

380See [system prompt flags](https://code.claude.com/docs/en/cli-reference.md#system-prompt-flags) for more options including `--system-prompt` to fully replace the default prompt. If you replace it, the run also starts without the [git status snapshot](https://code.claude.com/docs/en/settings-reference.md#includegitinstructions).

381381

382382### Continue conversations

383383

384Use `--continue` to continue the most recent conversation, or `--resume` with a session ID to continue a specific conversation. On Claude Code v2.1.257 or later, when you pass `--continue`, Claude Code opens a [background session](/docs/en/sessions.md#where-the-session-picker-looks) that has finished, but not one that is still running. This example runs a review, then sends follow-up prompts:

384Use `--continue` to continue the most recent conversation, or `--resume` with a session ID to continue a specific conversation. On Claude Code v2.1.257 or later, when you pass `--continue`, Claude Code opens a [background session](https://code.claude.com/docs/en/sessions.md#where-the-session-picker-looks) that has finished, but not one that is still running. This example runs a review, then sends follow-up prompts:

385385

386386```bash theme={null}

387387# First request

from line 399

399399claude -p "Continue that review" --resume "$session_id"

400400```

401401

402You can run the two commands from different directories: Claude Code [finds the session by its ID](/docs/en/sessions.md#where-the-session-picker-looks) in any project on this machine.

402You can run the two commands from different directories: Claude Code [finds the session by its ID](https://code.claude.com/docs/en/sessions.md#where-the-session-picker-looks) in any project on this machine.

403403

404In place of the session ID, you can pass `--resume` the absolute path to a session's `.jsonl` [transcript file](/docs/en/sessions.md#where-transcripts-are-stored), and Claude Code continues the conversation stored in that file.

404In place of the session ID, you can pass `--resume` the absolute path to a session's `.jsonl` [transcript file](https://code.claude.com/docs/en/sessions.md#where-transcripts-are-stored), and Claude Code continues the conversation stored in that file.

405405

406406## Next steps

407407

408* [Agent SDK quickstart](/docs/en/agent-sdk/quickstart.md): build your first agent with Python or TypeScript

409* [CLI reference](/docs/en/cli-reference.md): all CLI flags and options

410* [GitHub Actions](/docs/en/github-actions.md): use the Agent SDK in GitHub workflows

411* [GitLab CI/CD](/docs/en/gitlab-ci-cd.md): use the Agent SDK in GitLab pipelines

408* [Agent SDK quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart.md): build your first agent with Python or TypeScript

409* [CLI reference](https://code.claude.com/docs/en/cli-reference.md): all CLI flags and options

410* [GitHub Actions](https://code.claude.com/docs/en/github-actions.md): use the Agent SDK in GitHub workflows

411* [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md): use the Agent SDK in GitLab pipelines

412412

hipaa-setup Changed · +34 / -34 lines

from line 6

77> [!NOTE]

88>

9> "(local mode)" means a local session, not a [cloud session](/docs/en/claude-code-on-the-web.md). Local sessions run in one of these places:

9> "(local mode)" means a local session, not a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md). Local sessions run in one of these places:

1010>

1111> * Claude Code in the terminal

1212> * Claude Code in the Code tab of Claude Desktop

from line 39

3939| How Claude Code connects | Eligible for the HIPAA configuration |

4040| :- | :- |

4141| A Claude Enterprise account, connecting directly to the Claude API | Yes |

42| Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS, or a [Claude apps gateway](/docs/en/claude-apps-gateway) | No |

43| An [LLM gateway](/docs/en/llm-gateway) or any other custom `ANTHROPIC_BASE_URL` | No |

42| Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS, or a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) | No |

43| An [LLM gateway](https://code.claude.com/docs/en/llm-gateway) or any other custom `ANTHROPIC_BASE_URL` | No |

4444| `ANTHROPIC_AUTH_TOKEN` or `apiKeyHelper`, on a computer with no Claude Enterprise sign-in | No |

45| A Claude Console API key or [federation credentials](/docs/en/authentication.md#anthropic-profiles-and-federation-credentials) | No. These sessions belong to a Claude Console organization, which has its own agreement and settings |

45| A Claude Console API key or [federation credentials](https://code.claude.com/docs/en/authentication.md#anthropic-profiles-and-federation-credentials) | No. These sessions belong to a Claude Console organization, which has its own agreement and settings |

4646

4747#### Check how a computer connects

4848

from line 58

5858

5959### Update Claude Code and Claude Desktop

6060

61The HIPAA configuration requires Claude Code v2.1.285 or later and Claude Desktop v2.19675.0 or later. If your organization uses both the terminal and the [Claude Desktop app](/docs/en/desktop.md), update both.

6262

6363To read the installed Claude Code version, run this command in a terminal. It's the same in Bash, Zsh, and PowerShell:

6464

from line 68

6868

6969A supported installation prints `2.1.285 (Claude Code)` or a higher number.

7070

71To read the installed Claude Desktop version, see [Check your version](/docs/en/desktop.md#check-your-version).

71To read the installed Claude Desktop version, see [Check your version](https://code.claude.com/docs/en/desktop.md#check-your-version).

7272

7373#### What developers see on an older version

7474

from line 76

7676

7777| App | What a developer sees on an older version |

7878| :- | :- |

79| Claude Code | Each request fails with an [`API Error`](/docs/en/errors#claude-code-does-not-support-this-model) that says the version is older than the minimum version your organization's policy requires |

79| Claude Code | Each request fails with an [`API Error`](https://code.claude.com/docs/en/errors#claude-code-does-not-support-this-model) that says the version is older than the minimum version your organization's policy requires |

8080| Claude Desktop | An **Update required** dialog that tells the developer to update Claude Desktop to continue using the **Code** tab |

8181

82To keep developers on a supported version, [keep Claude Code updated](/docs/en/setup.md#update-claude-code). For Claude Desktop, see [Update Claude Desktop](https://claude.com/docs/cowork/hipaa-setup#update-claude-desktop).

82To keep developers on a supported version, [keep Claude Code updated](https://code.claude.com/docs/en/setup.md#update-claude-code). For Claude Desktop, see [Update Claude Desktop](https://claude.com/docs/cowork/hipaa-setup#update-claude-desktop).

8383

8484### Allow network access

8585

from line 91

9191| `claude.ai`, `claude.com`, `platform.claude.com` | Sign-in and token refresh |

9292| `sso.claude.com` | Sign-in, when your organization uses single sign-on |

9393| `downloads.claude.ai` | The native installer and its updates |

94| `mcp-proxy.anthropic.com` | [Connectors from claude.ai](/docs/en/mcp.md#use-mcp-servers-from-claude-ai) |

94| `mcp-proxy.anthropic.com` | [Connectors from claude.ai](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai) |

9595

9696This table lists the hosts a native install of Claude Code needs in the terminal to sign in, run, and update. These pages list the rest:

9797

98* **Other install methods and optional features**: [Network access requirements](/docs/en/network-config.md#network-access-requirements) lists the hosts that npm and Homebrew installs check for updates, and the hosts for features such as plugin installs

99* **The Code tab and Cowork**: [Desktop network access requirements](/docs/en/desktop.md#network-access-requirements) lists the additional hosts Claude Desktop needs

100* **Proxies that inspect TLS**: [Custom CA certificates](/docs/en/network-config.md#custom-ca-certificates) shows how to trust your proxy's certificate

98* **Other install methods and optional features**: [Network access requirements](https://code.claude.com/docs/en/network-config.md#network-access-requirements) lists the hosts that npm and Homebrew installs check for updates, and the hosts for features such as plugin installs

99* **The Code tab and Cowork**: [Desktop network access requirements](https://code.claude.com/docs/en/desktop.md#network-access-requirements) lists the additional hosts Claude Desktop needs

100* **Proxies that inspect TLS**: [Custom CA certificates](https://code.claude.com/docs/en/network-config.md#custom-ca-certificates) shows how to trust your proxy's certificate

101101

102102Sessions that go through a corporate HTTPS proxy are still eligible for the HIPAA configuration, as long as the proxy can reach the hosts in the table.

103103

from line 107

107107

108108### Deploy managed settings

109109

110You can use [managed settings](/docs/en/managed-settings.md) to direct developers to sign in with a Claude Enterprise account, to block cloud providers and gateways, and to set how many days every computer keeps local session data. The settings apply whether or not the HIPAA configuration is in effect.

110You can use [managed settings](https://code.claude.com/docs/en/managed-settings.md) to direct developers to sign in with a Claude Enterprise account, to block cloud providers and gateways, and to set how many days every computer keeps local session data. The settings apply whether or not the HIPAA configuration is in effect.

111111

112112The settings in this section are a sample that we recommend as a starting point. Your organization is responsible for deciding what its own environment needs and for confirming that its configuration meets those needs.

113113

114The following sample sets four keys that you could add to the [managed settings](/docs/en/managed-settings.md#choose-a-delivery-mechanism) your organization deploys:

114The following sample sets four keys that you could add to the [managed settings](https://code.claude.com/docs/en/managed-settings.md#choose-a-delivery-mechanism) your organization deploys:

115115

116116```json theme={null}

117117{

from line 130

130130

131131| Key | Set it to | What Claude Code enforces |

132132| :- | :- | :- |

133| [`forceLoginMethod`](/docs/en/settings-reference#forceloginmethod) | `"claudeai"` | Claude Code directs developers to claude.ai sign-in instead of Claude Console |

134| [`forceLoginOrgUUID`](/docs/en/settings-reference#forceloginorguuid) | Your organization ID, which an [Owner](/docs/en/server-managed-settings.md#access-control) can copy from [claude.ai admin settings](https://claude.ai/admin-settings/organization) | Claude Code exits at startup when the claude.ai sign-in belongs to another organization |

135| [`allowedProviders`](/docs/en/settings-reference#allowedproviders) | `["anthropic"]` | Claude Code refuses to start on a cloud provider or a gateway |

136| [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) | The number of days your records policy lets a computer keep session data | Every computer deletes old session data after the same number of days |

133| [`forceLoginMethod`](https://code.claude.com/docs/en/settings-reference#forceloginmethod) | `"claudeai"` | Claude Code directs developers to claude.ai sign-in instead of Claude Console |

134| [`forceLoginOrgUUID`](https://code.claude.com/docs/en/settings-reference#forceloginorguuid) | Your organization ID, which an [Owner](https://code.claude.com/docs/en/server-managed-settings.md#access-control) can copy from [claude.ai admin settings](https://claude.ai/admin-settings/organization) | Claude Code exits at startup when the claude.ai sign-in belongs to another organization |

135| [`allowedProviders`](https://code.claude.com/docs/en/settings-reference#allowedproviders) | `["anthropic"]` | Claude Code refuses to start on a cloud provider or a gateway |

136| [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) | The number of days your records policy lets a computer keep session data | Every computer deletes old session data after the same number of days |

137137

138138> [!WARNING]

139139>

from line 145

145145

146146#### Confirm the settings loaded

147147

148On a computer that has the settings, run `claude`, sign in with a Claude Enterprise account, and enter `/status`. The `Setting sources` line lists `Enterprise managed settings` followed by the source in parentheses, such as `(file)`, and the `Allowed providers` line reads `Anthropic API (managed allowedProviders)`. If `Setting sources` doesn't list it, or the `Allowed providers` line is missing, see [Check that a policy is in force](/docs/en/managed-settings.md#check-that-a-policy-is-in-force).

148On a computer that has the settings, run `claude`, sign in with a Claude Enterprise account, and enter `/status`. The `Setting sources` line lists `Enterprise managed settings` followed by the source in parentheses, such as `(file)`, and the `Allowed providers` line reads `Anthropic API (managed allowedProviders)`. If `Setting sources` doesn't list it, or the `Allowed providers` line is missing, see [Check that a policy is in force](https://code.claude.com/docs/en/managed-settings.md#check-that-a-policy-is-in-force).

149149

150150#### Sessions the managed settings keys don't block

151151

152152Even with these keys deployed, some sessions can still run without the HIPAA configuration:

153153

154* **Claude Console sign-ins and federation credentials**: `forceLoginOrgUUID` checks only claude.ai sign-ins. [Restrict login to your organization](/docs/en/authentication.md#restrict-login-to-your-organization) lists what Claude Code checks for each sign-in path and credential.

155* **Server-managed settings**: if your organization also uses [server-managed settings](/docs/en/server-managed-settings.md), have an Owner add the same keys there. [How Claude Code combines managed sources](/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) explains which source applies.

156* **Versions older than v2.1.285**: these versions ignore `allowedProviders`, so they can still start on a cloud provider or a gateway. To make v2.1.163 through v2.1.284 refuse to start, you can add [`requiredMinimumVersion`](/docs/en/settings-reference#requiredminimumversion) set to `"2.1.285"` to the same managed settings as the [sample keys](#deploy-managed-settings). Versions before v2.1.163 ignore `requiredMinimumVersion` as well as `allowedProviders`, so [update those computers](#update-claude-code-and-claude-desktop).

154* **Claude Console sign-ins and federation credentials**: `forceLoginOrgUUID` checks only claude.ai sign-ins. [Restrict login to your organization](https://code.claude.com/docs/en/authentication.md#restrict-login-to-your-organization) lists what Claude Code checks for each sign-in path and credential.

155* **Server-managed settings**: if your organization also uses [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), have an Owner add the same keys there. [How Claude Code combines managed sources](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) explains which source applies.

156* **Versions older than v2.1.285**: these versions ignore `allowedProviders`, so they can still start on a cloud provider or a gateway. To make v2.1.163 through v2.1.284 refuse to start, you can add [`requiredMinimumVersion`](https://code.claude.com/docs/en/settings-reference#requiredminimumversion) set to `"2.1.285"` to the same managed settings as the [sample keys](#deploy-managed-settings). Versions before v2.1.163 ignore `requiredMinimumVersion` as well as `allowedProviders`, so [update those computers](#update-claude-code-and-claude-desktop).

157157

158158To find out whether your BAA covers a session that runs without the HIPAA configuration, see [Use Claude Code (local mode) and Cowork (local mode) on a HIPAA-ready Enterprise plan](https://support.claude.com/en/articles/17318731).

159159

from line 196

196196| What a developer notices | Why |

197197| :- | :- |

198198| The WebFetch tool is unavailable | WebFetch is off. Web search still works |

199| `--cloud`, `/teleport`, and [Remote Control](/docs/en/remote-control.md) are refused | [Cloud sessions](/docs/en/claude-code-on-the-web.md) and Remote Control are off |

199| `--cloud`, `/teleport`, and [Remote Control](https://code.claude.com/docs/en/remote-control.md) are refused | [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) and Remote Control are off |

200200| `/feedback` and `/bug` are unavailable | Feedback submission is off |

201| Claude can't publish an [artifact](/docs/en/artifacts.md) | Artifact publishing is off |

202| MCP tools load into context upfront | [MCP tool search](/docs/en/mcp.md#configure-tool-search) is off. Neither `ENABLE_TOOL_SEARCH` nor managed settings turns it back on |

201| Claude can't publish an [artifact](https://code.claude.com/docs/en/artifacts.md) | Artifact publishing is off |

202| MCP tools load into context upfront | [MCP tool search](https://code.claude.com/docs/en/mcp.md#configure-tool-search) is off. Neither `ENABLE_TOOL_SEARCH` nor managed settings turns it back on |

203203| An MCP server or hook that reads `ANTHROPIC_API_KEY` stops authenticating | Claude Code [removes Anthropic credentials](#anthropic-credentials-in-commands-hooks-and-mcp-servers) from the processes it starts |

204204| Restrictions remain after `/login` to a different organization | The HIPAA status lasts until Claude Code restarts |

205205

from line 209

209209

210210The HIPAA configuration doesn't remove cloud provider or GitHub credentials, so a command that pushes to GitHub or calls another service still works with that developer's access. Your BAA with Anthropic doesn't cover the data it sends there. See the [Implementation Guide](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide) for the full list of Eligible Services.

211211

212To limit which commands and hosts Claude can use, see [permission rules](/docs/en/permissions.md) and the [sandbox](/docs/en/sandboxing.md).

212To limit which commands and hosts Claude can use, see [permission rules](https://code.claude.com/docs/en/permissions.md) and the [sandbox](https://code.claude.com/docs/en/sandboxing.md).

213213

214214## Manage local session data

215215

from line 217

217217

218218### Claude Code data

219219

220[Application data](/docs/en/claude-directory.md#application-data) lists what Claude Code (local mode) stores on a computer, what its retention sweep deletes after `cleanupPeriodDays`, and what stays until someone deletes it. The same page states what differs in an organization with the HIPAA configuration applied.

220[Application data](https://code.claude.com/docs/en/claude-directory.md#application-data) lists what Claude Code (local mode) stores on a computer, what its retention sweep deletes after `cleanupPeriodDays`, and what stays until someone deletes it. The same page states what differs in an organization with the HIPAA configuration applied.

221221

222222The retention sweep runs only when someone starts Claude Code, so a computer where nobody starts it keeps its data.

223223

from line 225

225225

226226The Code tab stores data in these places:

227227

228* **Transcripts**: in `~/.claude/projects/`, alongside terminal transcripts. [Cleaned up automatically](/docs/en/claude-directory.md#cleaned-up-automatically) states when the retention sweep deletes them.

228* **Transcripts**: in `~/.claude/projects/`, alongside terminal transcripts. [Cleaned up automatically](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically) states when the retention sweep deletes them.

229229* **The Claude Desktop data folder**: `~/Library/Application Support/Claude` on macOS. On Windows, `%APPDATA%\Claude`, or `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude` for the installer downloaded from Anthropic, so check both. With the HIPAA configuration applied, Claude Desktop deletes local Code tab sessions that have been inactive for longer than `cleanupPeriodDays`, including starred ones. It deletes them only while it's running. Claude Desktop handles a deleted session's worktree in one of these ways:

230230 * **No uncommitted changes, the session isn't starred or pinned, and no other session is using the worktree**: Claude Desktop removes the worktree

231231 * **Any other case**: the worktree stays on the computer

from line 254

254254

255255Either command deletes every project's transcripts and auto memory, the entries in `tasks/`, `debug/`, and `file-history/`, `history.jsonl`, and the project entries in `~/.claude.json`. Without `--yes`, it prints the plan and asks first.

256256

257The purge leaves other paths that can hold session content, such as pasted text in `paste-cache/`. [Clear local data](/docs/en/claude-directory.md#clear-local-data) lists the paths you can delete by hand. To clear a computer completely, for example before you reassign it, [wipe it](#offboard-a-developer).

257The purge leaves other paths that can hold session content, such as pasted text in `paste-cache/`. [Clear local data](https://code.claude.com/docs/en/claude-directory.md#clear-local-data) lists the paths you can delete by hand. To clear a computer completely, for example before you reassign it, [wipe it](#offboard-a-developer).

258258

259259### Offboard a developer

260260

from line 263

263263## Related resources

264264

265265* [Set up Cowork (local mode) for a HIPAA-ready organization](https://claude.com/docs/cowork/hipaa-setup)

266* [Deploy managed settings](/docs/en/managed-settings.md)

266* [Deploy managed settings](https://code.claude.com/docs/en/managed-settings.md)

267267* [HIPAA settings example](https://github.com/anthropics/claude-code/tree/main/examples/settings)

268* [Enterprise network configuration](/docs/en/network-config.md)

269* [Zero data retention](/docs/en/zero-data-retention.md)

270* [Legal and compliance](/docs/en/legal-and-compliance.md)

271* [Data usage](/docs/en/data-usage.md)

268* [Enterprise network configuration](https://code.claude.com/docs/en/network-config.md)

269* [Zero data retention](https://code.claude.com/docs/en/zero-data-retention.md)

270* [Legal and compliance](https://code.claude.com/docs/en/legal-and-compliance.md)

271* [Data usage](https://code.claude.com/docs/en/data-usage.md)

272272

hooks Changed · +193 / -193 lines

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.

from line 4

55> [!TIP]

66>

7> For a quickstart guide with examples, see [Automate actions with hooks](/docs/en/hooks-guide.md).

9Hooks are user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that execute automatically at specific points in Claude Code's lifecycle. Claude Code fires the same hook events wherever it runs: sessions in the terminal, IDE extensions, the [Desktop app](/docs/en/desktop-quickstart.md), and [cloud sessions](/docs/en/claude-code-on-the-web.md). Use this reference to look up event schemas, configuration options, JSON input/output formats, and advanced features like async hooks, HTTP hooks, and MCP tool hooks.

11A plugin can also register hooks as JavaScript functions that Claude Code calls in its own process, which can draw in the interface as well as act on events. A plugin that does is a [mod](/docs/en/plugins/mods/overview.md), and those function hooks are covered in [React to events](/docs/en/plugins/mods/events.md) rather than here. The hooks on this page keep working alongside mods.

7> For a quickstart guide with examples, see [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide.md).

9Hooks are user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that execute automatically at specific points in Claude Code's lifecycle. Claude Code fires the same hook events wherever it runs: sessions in the terminal, IDE extensions, the [Desktop app](https://code.claude.com/docs/en/desktop-quickstart.md), and [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md). Use this reference to look up event schemas, configuration options, JSON input/output formats, and advanced features like async hooks, HTTP hooks, and MCP tool hooks.

11A plugin can also register hooks as JavaScript functions that Claude Code calls in its own process, which can draw in the interface as well as act on events. A plugin that does is a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md), and those function hooks are covered in [React to events](https://code.claude.com/docs/en/plugins/mods/events.md) rather than here. The hooks on this page keep working alongside mods.

1212

1313## Hook lifecycle

1414

from line 18

1818

1919* per session: `SessionStart` and `SessionEnd`

2020* per turn: `UserPromptSubmit`, `Stop`, and `StopFailure`

21* on every tool call inside the agentic loop: `PreToolUse` and `PostToolUse`, except [`EndConversation`](/docs/en/tools-reference#endconversation-tool-behavior) calls, which skip both

21* on every tool call inside the agentic loop: `PreToolUse` and `PostToolUse`, except [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior) calls, which skip both

2222

2323![Hook lifecycle diagram showing optional Setup feeding into SessionStart, then a per-turn loop containing UserPromptSubmit, UserPromptExpansion for slash commands, the nested agentic loop (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted), and Stop or StopFailure, followed by TeammateIdle, PreCompact, PostCompact, and SessionEnd, with Elicitation and ElicitationResult nested inside MCP tool execution, PermissionDenied as a side branch from PermissionRequest for auto-mode denials, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, FileChanged, and DirectoryAdded as standalone async events, PreModelSwitch as a standalone sequential event that runs before a requested model switch, PostModelSwitch as a standalone async event that runs after the session's model changes, and MessageDisplay as a display-only event that runs while assistant message text streams](https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle.svg?fit=max\&auto=format\&n=x7pO8l4XcvAXCoVc\&q=85\&s=81b9256c1bbe8832553485f5d9e9c746)

2424

from line 28

2828| :- | :- |

2929| `SessionStart` | When a session begins or resumes |

3030| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |

31| `UserPromptSubmit` | When a prompt is submitted, before Claude processes it. Also fires on [turns Claude Code starts on its own](/docs/en/hooks.md#userpromptsubmit) |

31| `UserPromptSubmit` | When a prompt is submitted, before Claude processes it. Also fires on [turns Claude Code starts on its own](https://code.claude.com/docs/en/hooks.md#userpromptsubmit) |

3232| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |

3333| `PreToolUse` | Before a tool call executes. Can block it |

3434| `PermissionRequest` | When a tool call needs a permission decision |

from line 44

4444| `TaskCompleted` | When a task is being marked as completed |

4545| `Stop` | When Claude finishes responding |

4646| `StopFailure` | When the turn ends due to an API error |

47| `TeammateIdle` | When an [agent team](/docs/en/agent-teams.md) teammate is about to go idle |

47| `TeammateIdle` | When an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate is about to go idle |

4848| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

4949| `ConfigChange` | When a configuration file changes during a session |

5050| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

from line 208

208208}

209209```

210210

211If the command had been a safer `rm` variant like `rm file.txt`, the script would hit `exit 0` instead. Exit code 0 with no output means the hook has no decision to report, so the tool call continues through the normal [permission flow](/docs/en/permissions.md). The hook can deny the call, but staying silent doesn't approve it.

211If the command had been a safer `rm` variant like `rm file.txt`, the script would hit `exit 0` instead. Exit code 0 with no output means the hook has no decision to report, so the tool call continues through the normal [permission flow](https://code.claude.com/docs/en/permissions.md). The hook can deny the call, but staying silent doesn't approve it.

212212

213213**5. Claude Code acts on the result**

214214

from line 240

240240| `.claude/settings.json` | Single project | Yes, can be committed to the repo |

241241| `.claude/settings.local.json` | Single project | No, gitignored when Claude Code saves a setting to it |

242242| Managed policy settings | Organization-wide | Yes, admin-controlled |

243| [Plugin](/docs/en/plugins/overview.md) `hooks/hooks.json` | When plugin is enabled | Yes, bundled with the plugin |

244| [Skill](/docs/en/skills.md) frontmatter | The rest of the session once the skill is invoked. See [Hooks in skills and agents](#hooks-in-skills-and-agents) | Yes, defined in the skill file |

245| [Subagent](/docs/en/sub-agents.md) frontmatter | While that subagent is running | Yes, defined in the subagent file |

246

247[Cloud sessions](/docs/en/claude-code-on-the-web.md) don't read your local `~/.claude/settings.json`. In a [self-hosted environment](/docs/en/self-hosted-environments-configuration.md#permissions-and-tool-approval), Claude Code also runs the hooks the operator seeded from the runner host's `~/.claude/`, and it runs the hooks in the runner image's managed settings file when that file is among the [managed sources Claude Code applies](/docs/en/managed-settings.md#how-claude-code-combines-managed-sources), which by default means only when neither server-managed settings nor an MDM-delivered Claude Code policy supplies the managed tier. See [what carries over from your setup](/docs/en/cloud-environments.md#what-carries-over-from-your-setup) for which settings files and plugins, and so which hooks, reach a cloud session.

248

249For details on settings file resolution, see [settings](/docs/en/settings.md).

250

251Hooks from settings files, managed policy settings, and plugins also run inside [subagents](/docs/en/sub-agents.md). When a subagent calls a tool, tool events such as `PreToolUse` and `PostToolUse` fire the same configured hooks as in the main conversation, and the input carries the `agent_id` and `agent_type` [common input fields](#common-input-fields) that identify the subagent.

252

253Administrators can use [`allowManagedHooksOnly`](/docs/en/settings-reference#allowmanagedhooksonly) in [managed settings](/docs/en/managed-settings.md) to restrict which hooks run:

243| [Plugin](https://code.claude.com/docs/en/plugins/overview.md) `hooks/hooks.json` | When plugin is enabled | Yes, bundled with the plugin |

244| [Skill](https://code.claude.com/docs/en/skills.md) frontmatter | The rest of the session once the skill is invoked. See [Hooks in skills and agents](#hooks-in-skills-and-agents) | Yes, defined in the skill file |

245| [Subagent](https://code.claude.com/docs/en/sub-agents.md) frontmatter | While that subagent is running | Yes, defined in the subagent file |

246

247[Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) don't read your local `~/.claude/settings.json`. In a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments-configuration.md#permissions-and-tool-approval), Claude Code also runs the hooks the operator seeded from the runner host's `~/.claude/`, and it runs the hooks in the runner image's managed settings file when that file is among the [managed sources Claude Code applies](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources), which by default means only when neither server-managed settings nor an MDM-delivered Claude Code policy supplies the managed tier. See [what carries over from your setup](https://code.claude.com/docs/en/cloud-environments.md#what-carries-over-from-your-setup) for which settings files and plugins, and so which hooks, reach a cloud session.

248

249For details on settings file resolution, see [settings](https://code.claude.com/docs/en/settings.md).

250

251Hooks from settings files, managed policy settings, and plugins also run inside [subagents](https://code.claude.com/docs/en/sub-agents.md). When a subagent calls a tool, tool events such as `PreToolUse` and `PostToolUse` fire the same configured hooks as in the main conversation, and the input carries the `agent_id` and `agent_type` [common input fields](#common-input-fields) that identify the subagent.

252

253Administrators can use [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) in [managed settings](https://code.claude.com/docs/en/managed-settings.md) to restrict which hooks run:

254254

255255* Your user, project, local, and plugin hooks are blocked. Hooks from plugins force-enabled in managed settings `enabledPlugins` are exempt

256* Claude Code also narrows your [`statusLine`](/docs/en/statusline), [`fileSuggestion`](/docs/en/settings-reference#filesuggestion), and [`subagentStatusLine`](/docs/en/statusline#subagent-status-lines) settings to managed settings

257* Claude Code also disables plugins with a [`command` source](/docs/en/plugins/marketplace-reference#command-plugin-source), including plugins force-enabled in managed settings `enabledPlugins`, unless [`disableCommandPluginSources`](/docs/en/settings-reference#disablecommandpluginsources) is explicitly set to `false`. `command` sources require Claude Code v2.1.229 or later

258* Claude Code also blocks marketplace [`headersHelper` commands](/docs/en/plugins/host-marketplace#authenticate-archive-downloads) unless [`disableCommandPluginSources`](/docs/en/settings-reference#disablecommandpluginsources) is explicitly set to `false`, except for a marketplace that managed settings themselves declare

259

260See [what runs under `allowManagedHooksOnly`](/docs/en/settings-reference#what-runs-under-allowmanagedhooksonly).

256* Claude Code also narrows your [`statusLine`](https://code.claude.com/docs/en/statusline), [`fileSuggestion`](https://code.claude.com/docs/en/settings-reference#filesuggestion), and [`subagentStatusLine`](https://code.claude.com/docs/en/statusline#subagent-status-lines) settings to managed settings

257* Claude Code also disables plugins with a [`command` source](https://code.claude.com/docs/en/plugins/marketplace-reference#command-plugin-source), including plugins force-enabled in managed settings `enabledPlugins`, unless [`disableCommandPluginSources`](https://code.claude.com/docs/en/settings-reference#disablecommandpluginsources) is explicitly set to `false`. `command` sources require Claude Code v2.1.229 or later

258* Claude Code also blocks marketplace [`headersHelper` commands](https://code.claude.com/docs/en/plugins/host-marketplace#authenticate-archive-downloads) unless [`disableCommandPluginSources`](https://code.claude.com/docs/en/settings-reference#disablecommandpluginsources) is explicitly set to `false`, except for a marketplace that managed settings themselves declare

259

260See [what runs under `allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#what-runs-under-allowmanagedhooksonly).

261261

262262Hook entries merge across settings levels rather than replacing each other: user, project, and local settings add their own hooks without removing managed ones, and the [`disableAllHooks`](#disable-or-remove-hooks) setting can't disable managed hooks from outside managed settings.

263263

264The [HTTP hook allowlists](/docs/en/settings-reference.md#hook-and-skill-settings) apply to hooks from every source, including managed policy settings:

264The [HTTP hook allowlists](https://code.claude.com/docs/en/settings-reference.md#hook-and-skill-settings) apply to hooks from every source, including managed policy settings:

265265

266266* `allowedHttpHookUrls`: when defined at any settings level, Claude Code runs an HTTP hook handler only if its URL matches the merged allowlist

267267* `httpHookAllowedEnvVars`: when defined, Claude Code interpolates only the environment variables on that list into hook headers

from line 332

332332

333333If you add a `matcher` field to an event without matcher support, it is silently ignored.

334334

335For tool events, you can filter more narrowly by setting the [`if` field](#common-fields) on individual hook handlers. `if` uses [permission rule syntax](/docs/en/permissions.md) to match against the tool name and arguments together, so `"Bash(git *)"` runs when any subcommand of the Bash input matches `git *` and `"Edit(*.ts)"` runs only for TypeScript files.

335For tool events, you can filter more narrowly by setting the [`if` field](#common-fields) on individual hook handlers. `if` uses [permission rule syntax](https://code.claude.com/docs/en/permissions.md) to match against the tool name and arguments together, so `"Bash(git *)"` runs when any subcommand of the Bash input matches `git *` and `"Edit(*.ts)"` runs only for TypeScript files.

336336

337337#### Match MCP tools

338338

339[MCP](/docs/en/mcp.md) server tools appear as regular tools in tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`), so you can match them the same way you match any other tool name.

339[MCP](https://code.claude.com/docs/en/mcp.md) server tools appear as regular tools in tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`), so you can match them the same way you match any other tool name.

340340

341341MCP tools follow the naming pattern `mcp__<server>__<tool>`, for example:

342342

from line 350

350350* `mcp__brave-search__.*` matches all tools from a server whose name contains a hyphen

351351* `mcp__.*__write.*` matches any tool whose name starts with `write` from any server

352352

353Tools from a [plugin-bundled MCP server](/docs/en/mcp.md#plugin-provided-mcp-servers) use a scoped server segment that includes the plugin name: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. A matcher written against the bare server key never fires for these tools. For a plugin named `my-plugin` that bundles a server under the key `db`, a `query` tool appears as `mcp__plugin_my-plugin_db__query`, so the matcher for every tool from that server is `mcp__plugin_my-plugin_db__.*`. Use the same scoped tool name in a handler's [`if` field](#common-fields). See [Plugin-provided MCP servers](/docs/en/mcp.md#plugin-provided-mcp-servers) for how the scoped name is built.

353Tools from a [plugin-bundled MCP server](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers) use a scoped server segment that includes the plugin name: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. A matcher written against the bare server key never fires for these tools. For a plugin named `my-plugin` that bundles a server under the key `db`, a `query` tool appears as `mcp__plugin_my-plugin_db__query`, so the matcher for every tool from that server is `mcp__plugin_my-plugin_db__.*`. Use the same scoped tool name in a handler's [`if` field](#common-fields). See [Plugin-provided MCP servers](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers) for how the scoped name is built.

354354

355355This example logs all memory server operations and validates write operations from any MCP server:

356356

from line 387

387387

388388* **[Command hooks](#command-hook-fields)** (`type: "command"`): run a shell command. Your script receives the event's [JSON input](#hook-input-and-output) on stdin and communicates results back through exit codes and stdout.

389389* **[HTTP hooks](#http-hook-fields)** (`type: "http"`): send the event's JSON input as an HTTP POST request to a URL. The endpoint communicates results back through the response body using the same [JSON output format](#json-output) as command hooks.

390* **[MCP tool hooks](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): call a tool on a configured [MCP server](/docs/en/mcp.md). The tool's text output is treated like command-hook stdout.

390* **[MCP tool hooks](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): call a tool on a configured [MCP server](https://code.claude.com/docs/en/mcp.md). The tool's text output is treated like command-hook stdout.

391391* **[Prompt hooks](#prompt-and-agent-hook-fields)** (`type: "prompt"`): send a prompt to a Claude model for single-turn evaluation. The model returns its decision as JSON. See [Prompt-based hooks](#prompt-based-hooks).

392392* **[Agent hooks](#prompt-and-agent-hook-fields)** (`type: "agent"`): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision. Agent hooks are experimental and may change. See [Agent-based hooks](#agent-based-hooks).

393393

from line 395

395395

396396If you define the same handler in more than one settings file, it runs once. A plugin's or skill's copy of the same handler stays separate.

397397

398Handlers run in the current directory with Claude Code's environment. If the current directory no longer exists, for example a worktree or temp directory that another shell deleted mid-session, Claude Code runs command hooks from the first of these that still exists: the directory the session started in, the project root, your home directory, or the system temp directory. Claude Code records a warning naming the fallback directory in the [debug log](#debug-hooks). For a worktree session that you start from the desktop app, see [What worktrees share with the main checkout](/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout).

399

400The `$CLAUDE_CODE_REMOTE` environment variable is `"true"` in remote web environments and not set in the local CLI. Claude Code v2.1.199 and later sets [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/en/env-vars) to the [Remote Control](/docs/en/remote-control.md) session ID while the local session has an active Remote Control connection.

398Handlers run in the current directory with Claude Code's environment. If the current directory no longer exists, for example a worktree or temp directory that another shell deleted mid-session, Claude Code runs command hooks from the first of these that still exists: the directory the session started in, the project root, your home directory, or the system temp directory. Claude Code records a warning naming the fallback directory in the [debug log](#debug-hooks). For a worktree session that you start from the desktop app, see [What worktrees share with the main checkout](https://code.claude.com/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout).

399

400The `$CLAUDE_CODE_REMOTE` environment variable is `"true"` in remote web environments and not set in the local CLI. Claude Code v2.1.199 and later sets [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](https://code.claude.com/docs/en/env-vars) to the [Remote Control](https://code.claude.com/docs/en/remote-control.md) session ID while the local session has an active Remote Control connection.

401401

402402#### Common fields

403403

from line 406

406406| Field | Required | Description |

407407| :- | :- | :- |

408408| `type` | yes | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"`, or `"agent"` |

409| `if` | no | [Permission rule syntax](/docs/en/permissions.md#permission-rule-syntax) to filter when this hook runs, such as `"Bash(git *)"` or `"Edit(*.ts)"`. The hook command only runs if the tool call matches the pattern. See the [Bash matching table](#bash-if-matching) for how Bash patterns evaluate against subcommands, `$()`, and backticks. Only evaluated on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, and `PermissionDenied`. On other events, a hook with `if` set never runs |

409| `if` | no | [Permission rule syntax](https://code.claude.com/docs/en/permissions.md#permission-rule-syntax) to filter when this hook runs, such as `"Bash(git *)"` or `"Edit(*.ts)"`. The hook command only runs if the tool call matches the pattern. See the [Bash matching table](#bash-if-matching) for how Bash patterns evaluate against subcommands, `$()`, and backticks. Only evaluated on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, and `PermissionDenied`. On other events, a hook with `if` set never runs |

410410| `timeout` | no | Seconds before canceling. Claude Code doesn't enforce it on a command hook you run with [`async: true`](#run-hooks-in-the-background). Defaults: 600 for `command`, `http`, and `mcp_tool`; 30 for `prompt`; 60 for `agent`. Claude Code lowers the `command`, `http`, and `mcp_tool` default to 30 on [`UserPromptSubmit`](#userpromptsubmit), [`PreModelSwitch`](#premodelswitch), and [`PostModelSwitch`](#postmodelswitch), and to 10 on [`MessageDisplay`](#messagedisplay). [`SessionEnd`](#sessionend) hooks share a 1.5-second budget; if your settings set a longer per-hook `timeout`, Claude Code raises the budget to match, up to 60 seconds |

411411| `statusMessage` | no | Custom spinner message displayed while the hook runs |

412412| `once` | no | If `true`, Claude Code removes the hook after its first successful run. A run that fails, blocks with exit code 2, or times out leaves the hook in place, so it runs again on the next matching event. Only honored for hooks declared in [skill frontmatter](#hooks-in-skills-and-agents); ignored in settings files and agent frontmatter |

from line 427

429429

430When Claude Code can't determine which commands the Bash input runs, it runs your hook regardless of the pattern. Because the `if` filter is best-effort, use the [permission system](/docs/en/permissions.md) rather than a hook to enforce a hard allow or deny.

430When Claude Code can't determine which commands the Bash input runs, it runs your hook regardless of the pattern. Because the `if` filter is best-effort, use the [permission system](https://code.claude.com/docs/en/permissions.md) rather than a hook to enforce a hard allow or deny.

431431

432432#### Command hook fields

433433

from line 438

438438| `command` | yes | Shell command to execute. With `args`, the executable to spawn directly. See [Exec form and shell form](#exec-form-and-shell-form) |

439439| `args` | no | Argument list. When present, `command` is resolved as an executable and spawned directly with `args` as the argument vector, with no shell involved. See [Exec form and shell form](#exec-form-and-shell-form) |

440440| `async` | no | If `true`, runs in the background without blocking. See [Run hooks in the background](#run-hooks-in-the-background) |

441| `asyncRewake` | no | If `true`, runs in the background and wakes Claude on exit code 2. The hook's stderr, or stdout if stderr is empty, is shown to Claude as a [system reminder](/docs/en/glossary.md#system-reminder) so it can react to a long-running background failure |

441| `asyncRewake` | no | If `true`, runs in the background and wakes Claude on exit code 2. The hook's stderr, or stdout if stderr is empty, is shown to Claude as a [system reminder](https://code.claude.com/docs/en/glossary.md#system-reminder) so it can react to a long-running background failure |

442442| `shell` | no | Shell to use for this hook. Accepts `"bash"` or `"powershell"`. Defaults to `"bash"`, or to `"powershell"` on Windows when Git Bash isn't installed. Setting `"powershell"` runs the command via PowerShell on Windows. Does not require `CLAUDE_CODE_USE_POWERSHELL_TOOL` since hooks spawn PowerShell directly. Ignored when `args` is set |

443443| `onFailure` | no | Whether the action that triggered the hook goes ahead when the hook fails: `"continue"` or `"block"`. See [Block the action when a hook fails](#block-the-action-when-a-hook-fails) for `"block"` and for leaving the field unset. Requires Claude Code v2.1.295 or later |

444444

from line 475

475475

476476Both forms support the same [path placeholders](#reference-scripts-by-path), and both export them as the environment variables `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, and `CLAUDE_PLUGIN_DATA` on the spawned process, so a script can read `process.env.CLAUDE_PLUGIN_ROOT` regardless of how it was launched.

477477

478Plugin hooks additionally substitute [`${user_config.*}`](/docs/en/plugins/manifest-reference#user-configuration) values, in exec form only: the value is substituted into `command` and into each `args` element as a plain string, so no shell re-parses it.

479

480A shell-form plugin hook whose `command` references `${user_config.*}` fails with an [error](/docs/en/errors.md#plugin-command-references-user-config) instead of running. To use an option value from a shell-form hook, read the `$CLAUDE_PLUGIN_OPTION_<KEY>` environment variable, such as `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL` for a `webhook_url` option, or set `args` to switch the hook to exec form. Before v2.1.207, shell-form plugin hook commands also substituted `${user_config.*}`.

478Plugin hooks additionally substitute [`${user_config.*}`](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration) values, in exec form only: the value is substituted into `command` and into each `args` element as a plain string, so no shell re-parses it.

479

480A shell-form plugin hook whose `command` references `${user_config.*}` fails with an [error](https://code.claude.com/docs/en/errors.md#plugin-command-references-user-config) instead of running. To use an option value from a shell-form hook, read the `$CLAUDE_PLUGIN_OPTION_<KEY>` environment variable, such as `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL` for a `webhook_url` option, or set `args` to switch the hook to exec form. Before v2.1.207, shell-form plugin hook commands also substituted `${user_config.*}`.

481481

482482> [!NOTE]

483483>

from line 529

529529

530530| Field | Required | Description |

531531| :- | :- | :- |

532| `server` | yes | Name of a configured MCP server. For a [plugin-bundled server](/docs/en/mcp.md#plugin-provided-mcp-servers), this is the scoped name `plugin:<plugin-name>:<server-name>`, such as `plugin:my-plugin:db`, not the bare server key |

532| `server` | yes | Name of a configured MCP server. For a [plugin-bundled server](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers), this is the scoped name `plugin:<plugin-name>:<server-name>`, such as `plugin:my-plugin:db`, not the bare server key |

533533| `tool` | yes | Name of the tool to call on that server |

534534| `input` | no | Arguments passed to the tool. String values support `${path}` substitution from the hook's [JSON input](#hook-input-and-output), such as `"${tool_input.file_path}"` |

535535

from line 561

561561

562562##### When the server is still connecting

563563

564On events where a hook can block or change the result, such as `PreToolUse` or `Stop`, Claude Code waits for a connecting server before it calls the tool, for at most [`MCP_TIMEOUT`](/docs/en/env-vars) and within the hook's own [`timeout`](#common-fields). On observational events, such as `Notification` or `SessionEnd`, it doesn't wait.

565

566A server showing the [`cached` status](/docs/en/mcp#server-status-detail) connects when the hook calls its tool. If the server isn't connected at that point, the hook produces a non-blocking error and execution continues. The hook never starts an OAuth flow, so [authenticate the server from `/mcp`](/docs/en/mcp#authenticate-with-remote-mcp-servers) first.

564On events where a hook can block or change the result, such as `PreToolUse` or `Stop`, Claude Code waits for a connecting server before it calls the tool, for at most [`MCP_TIMEOUT`](https://code.claude.com/docs/en/env-vars) and within the hook's own [`timeout`](#common-fields). On observational events, such as `Notification` or `SessionEnd`, it doesn't wait.

565

566A server showing the [`cached` status](https://code.claude.com/docs/en/mcp#server-status-detail) connects when the hook calls its tool. If the server isn't connected at that point, the hook produces a non-blocking error and execution continues. The hook never starts an OAuth flow, so [authenticate the server from `/mcp`](https://code.claude.com/docs/en/mcp#authenticate-with-remote-mcp-servers) first.

567567

568568##### Events that fire before MCP servers are available

569569

from line 576

576576| Field | Required | Description |

577577| :- | :- | :- |

578578| `prompt` | yes | Prompt text to send to the model. Use `$ARGUMENTS` as a placeholder for the hook input JSON. Escape with a backslash to include literal text: `\$1.00` renders as `$1.00` |

579| `model` | no | Model to use for evaluation. Defaults to the model Claude Code uses for [background functionality](/docs/en/costs.md#background-token-usage) |

579| `model` | no | Model to use for evaluation. Defaults to the model Claude Code uses for [background functionality](https://code.claude.com/docs/en/costs.md#background-token-usage) |

580580

581581### Reference scripts by path

582582

583583Use these placeholders to reference hook scripts relative to the project or plugin root, regardless of the working directory when the hook runs:

584584

585* `${CLAUDE_PROJECT_DIR}`: the project root where the session started. Claude Code also sets this variable in the environment of [stdio MCP servers](/docs/en/mcp.md#option-3-add-a-local-stdio-server) and plugin LSP servers.

586* `${CLAUDE_PLUGIN_ROOT}`: the plugin's installation directory, for scripts bundled with a [plugin](/docs/en/plugins/overview.md). See [plugin environment variables](/docs/en/plugins/manifest-reference.md#environment-variables) for how the path behaves across updates.

587* `${CLAUDE_PLUGIN_DATA}`: the plugin's [persistent data directory](/docs/en/plugins/components.md#path-variables-and-persistent-data), for dependencies and state that should survive plugin updates.

585* `${CLAUDE_PROJECT_DIR}`: the project root where the session started. Claude Code also sets this variable in the environment of [stdio MCP servers](https://code.claude.com/docs/en/mcp.md#option-3-add-a-local-stdio-server) and plugin LSP servers.

586* `${CLAUDE_PLUGIN_ROOT}`: the plugin's installation directory, for scripts bundled with a [plugin](https://code.claude.com/docs/en/plugins/overview.md). See [plugin environment variables](https://code.claude.com/docs/en/plugins/manifest-reference.md#environment-variables) for how the path behaves across updates.

587* `${CLAUDE_PLUGIN_DATA}`: the plugin's [persistent data directory](https://code.claude.com/docs/en/plugins/components.md#path-variables-and-persistent-data), for dependencies and state that should survive plugin updates.

588588

589589> [!NOTE]

590590>

591> **Worktrees are different.** If Claude enters a [worktree](/docs/en/worktrees.md) during the session, Claude Code keeps `${CLAUDE_PROJECT_DIR}` where it was and passes the worktree path to your hooks a different way:

591> **Worktrees are different.** If Claude enters a [worktree](https://code.claude.com/docs/en/worktrees.md) during the session, Claude Code keeps `${CLAUDE_PROJECT_DIR}` where it was and passes the worktree path to your hooks a different way:

592592>

593593> * **`${CLAUDE_PROJECT_DIR}` stays put**: it still points at the project root where the session started, so a command such as `${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh` still runs the script in the main checkout.

594594> * **`cwd` follows Claude**: the `cwd` field in the hook's [input JSON](#common-input-fields) is the worktree root after Claude enters a worktree, and the new directory after Claude runs `cd`. Read it when a hook needs to know which directory Claude is working in.

595595>

596> For a worktree session that you start from the desktop app, see [What worktrees share with the main checkout](/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout) for where `${CLAUDE_PROJECT_DIR}` points.

596> For a worktree session that you start from the desktop app, see [What worktrees share with the main checkout](https://code.claude.com/docs/en/worktrees.md#what-worktrees-share-with-the-main-checkout) for where `${CLAUDE_PROJECT_DIR}` points.

597597

598598Prefer [exec form](#exec-form-and-shell-form) for any hook that references a path placeholder. In shell form, wrap each placeholder in double quotes.

599599

from line 647

647647}

648648```

649649

650See the [plugin components reference](/docs/en/plugins/components.md#hooks) for details on creating plugin hooks.

650See the [plugin components reference](https://code.claude.com/docs/en/plugins/components.md#hooks) for details on creating plugin hooks.

651651

652652### Hooks in skills and agents

653653

654In addition to settings files and plugins, hooks can be defined directly in [skills](/docs/en/skills.md) and [subagents](/docs/en/sub-agents.md) using frontmatter, in the same configuration format as settings-based hooks. How long Claude Code keeps them registered depends on the component:

654In addition to settings files and plugins, hooks can be defined directly in [skills](https://code.claude.com/docs/en/skills.md) and [subagents](https://code.claude.com/docs/en/sub-agents.md) using frontmatter, in the same configuration format as settings-based hooks. How long Claude Code keeps them registered depends on the component:

655655

656656* **Subagent hooks**: Claude Code runs them only while that subagent is running and removes them when it finishes. Claude Code converts a `Stop` hook here to `SubagentStop`, the event it fires when a subagent completes.

657657* **Skill hooks**: Claude Code registers them when you or Claude invoke the skill and keeps running them for the rest of the session, on turns after the skill's own turn as well. To have Claude Code remove a hook after its first successful run instead, set [`once: true`](#common-fields) on it.

from line 675

675675

676676Frontmatter hooks in a project skill follow the same [workspace trust rule as hooks in settings files](#workspace-trust). Claude Code registers them when you or Claude invoke the skill, including in a `-p` run in a folder you haven't trusted.

677677

678Frontmatter hooks in a project subagent run only after you accept the [workspace trust dialog](/docs/en/permissions.md#project-allow-rules-and-workspace-trust) for the folder the agent file came from. A `-p` session doesn't count as accepting it. [What runs before you trust a folder](/docs/en/permissions.md#what-runs-before-you-trust-a-folder) compares this with the settings-file rule, and the subagents page lists [which scopes are exempt](/docs/en/sub-agents.md#hooks-in-subagent-frontmatter). Before v2.1.218, these hooks could run from folders you hadn't trusted.

678Frontmatter hooks in a project subagent run only after you accept the [workspace trust dialog](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust) for the folder the agent file came from. A `-p` session doesn't count as accepting it. [What runs before you trust a folder](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) compares this with the settings-file rule, and the subagents page lists [which scopes are exempt](https://code.claude.com/docs/en/sub-agents.md#hooks-in-subagent-frontmatter). Before v2.1.218, these hooks could run from folders you hadn't trusted.

679679

680680#### Limits on skill hooks

681681

682When a skill's frontmatter hooks don't fire after you or Claude invoke the skill, run [`/hooks`](#the-%2Fhooks-menu) in that session. If it lists them, see [Hook not firing](/docs/en/hooks-guide.md#hook-not-firing). If it lists none of them, the skill may be under a plugin-only lock or past a hook limit, and runs without any of its frontmatter hooks. Check for each case:

683

684* **Plugin-only lock**: your organization's administrator can lock hooks to plugins and managed settings with the [`strictPluginOnlyCustomization`](/docs/en/settings-reference#strictpluginonlycustomization-hooks) managed setting. A skill keeps its frontmatter hooks under that lock only if it's a plugin skill, a [bundled skill](/docs/en/skills.md#bundled-skills), or a skill in the [managed settings directory](/docs/en/managed-settings.md#delivery-mechanisms). The hooks in your own settings files don't run either.

685 * **Check**: type `/status` in a Claude Code session. If the [`Setting sources` line](/docs/en/settings#check-what-your-organization-enforces) includes `Enterprise managed settings`, ask your administrator whether `strictPluginOnlyCustomization` locks hooks.

686 * **Fix**: move the skill into a [plugin](/docs/en/plugins/create.md#convert-an-existing-claude-setup), because plugin skills keep their frontmatter hooks. List the plugin in a [marketplace](/docs/en/plugins/create-marketplace.md#create-a-marketplace), then install it from there. If Claude Code refuses the marketplace with [`is blocked by enterprise policy`](/docs/en/plugins/troubleshooting#marketplace-source-is-blocked-by-enterprise-policy), ask your administrator to allow that marketplace.

682When a skill's frontmatter hooks don't fire after you or Claude invoke the skill, run [`/hooks`](#the-%2Fhooks-menu) in that session. If it lists them, see [Hook not firing](https://code.claude.com/docs/en/hooks-guide.md#hook-not-firing). If it lists none of them, the skill may be under a plugin-only lock or past a hook limit, and runs without any of its frontmatter hooks. Check for each case:

683

684* **Plugin-only lock**: your organization's administrator can lock hooks to plugins and managed settings with the [`strictPluginOnlyCustomization`](https://code.claude.com/docs/en/settings-reference#strictpluginonlycustomization-hooks) managed setting. A skill keeps its frontmatter hooks under that lock only if it's a plugin skill, a [bundled skill](https://code.claude.com/docs/en/skills.md#bundled-skills), or a skill in the [managed settings directory](https://code.claude.com/docs/en/managed-settings.md#delivery-mechanisms). The hooks in your own settings files don't run either.

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

686 * **Fix**: move the skill into a [plugin](https://code.claude.com/docs/en/plugins/create.md#convert-an-existing-claude-setup), because plugin skills keep their frontmatter hooks. List the plugin in a [marketplace](https://code.claude.com/docs/en/plugins/create-marketplace.md#create-a-marketplace), then install it from there. If Claude Code refuses the marketplace with [`is blocked by enterprise policy`](https://code.claude.com/docs/en/plugins/troubleshooting#marketplace-source-is-blocked-by-enterprise-policy), ask your administrator to allow that marketplace.

687687* **Hook limit**: in Claude Code v2.1.304 or later, each source of skills has its own limit per session. Your project, your personal skills folder, and each plugin count as separate sources. The skills from one source can register at most 1,024 hooks. Those hooks' matchers can total at most 16,384 characters. A matcher with several hooks under it counts once for each hook.

688688 * **Check**: repeat the session where the hook didn't fire, with debug logging on:

689 1. Start a new session from your shell with `claude --debug`. If you don't start sessions from a shell, type [`/debug`](/docs/en/commands#all-commands) first in the new session instead.

689 1. Start a new session from your shell with `claude --debug`. If you don't start sessions from a shell, type [`/debug`](https://code.claude.com/docs/en/commands#all-commands) first in the new session instead.

690690 2. Invoke the same skills in the same order, including the ones Claude invoked, because both totals build up skill by skill. Ask Claude to invoke any skill you can't type as a command.

691691 3. Search the [debug log](#debug-hooks) for `registers none of its hooks`. A line containing that text names the skill that went past the limit.

692692 * **Fix**: declare fewer hooks or shorter matchers in that skill or in the other skills from its source, then start a new session. If those skills aren't yours to edit, ask their author for that change. Until then, start a new session and invoke the skill you need before any other skill from its source.

693693

694If neither case is yours, check for [frontmatter that didn't parse](/docs/en/skills.md#skill-not-triggering).

694If neither case is yours, check for [frontmatter that didn't parse](https://code.claude.com/docs/en/skills.md#skill-not-triggering).

695695

696696### The `/hooks` menu

697697

from line 705

705705

706706To remove a hook defined in a settings file, delete its entry from that file.

707707

708To temporarily disable all hooks without removing them, set `"disableAllHooks": true` in your settings file. Claude Code reads the value left after [settings precedence](/docs/en/settings.md#settings-precedence) applies, so a `"disableAllHooks": false` in a project's `.claude/settings.json` overrides a `true` in your user settings. To turn hooks off for one run whatever the project's settings say, pass `--settings '{"disableAllHooks": true}'`, which takes precedence over project and local settings. There is no way to disable an individual hook while keeping it in the configuration.

709

710The `disableAllHooks` setting respects the managed settings hierarchy. If an administrator has configured hooks through managed policy settings, `disableAllHooks` set in user, project, or local settings can't disable those managed hooks. Only `disableAllHooks` set at the managed settings level can disable managed hooks. For the full reach of each level, see [`disableAllHooks`](/docs/en/settings-reference#disableallhooks).

708To temporarily disable all hooks without removing them, set `"disableAllHooks": true` in your settings file. Claude Code reads the value left after [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) applies, so a `"disableAllHooks": false` in a project's `.claude/settings.json` overrides a `true` in your user settings. To turn hooks off for one run whatever the project's settings say, pass `--settings '{"disableAllHooks": true}'`, which takes precedence over project and local settings. There is no way to disable an individual hook while keeping it in the configuration.

709

711711

712712Direct edits to hooks in settings files are normally picked up automatically by the file watcher.

713713

from line 726

726726| Field | Description |

727727| :- | :- |

728728| `session_id` | Current session identifier |

729| `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), so you can correlate hook output with telemetry for a single prompt. Absent until the first user input |

729| `prompt_id` | UUID identifying the user prompt currently being processed. Matches the [`prompt.id` attribute on OpenTelemetry events](https://code.claude.com/docs/en/monitoring-usage#event-correlation-attributes), so you can correlate hook output with telemetry for a single prompt. Absent until the first user input |

730730| `transcript_path` | Path to conversation JSON. The transcript file is written asynchronously and may lag the in-memory conversation, so it may not yet include the current turn's most recent messages when a hook fires. Hooks that need the final assistant text of the current turn should use `last_assistant_message` on [Stop](#stop) and [SubagentStop](#subagentstop) instead of reading the transcript |

731731| `cwd` | Current working directory when the hook is invoked |

732| `scratchpad_dir` | Path to the session's [scratchpad directory](/docs/en/claude-directory.md#session-scratchpad-directory), where Claude keeps temporary working files. Absent when the session has no scratchpad or the temp directory is unavailable. Requires Claude Code v2.1.257 or later |

733| `permission_mode` | Current [permission mode](/docs/en/permissions.md#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"`, or `"bypassPermissions"`. The mode labeled **Manual** arrives as `"default"`, never as `"manual"`, so scripts that match `"default"` keep working. Not all events receive this field. Check the JSON example in each [hook event](#hook-events) section |

734| `effort` | Object with a `level` field holding the [effort level](/docs/en/model-config.md#adjust-effort-level) in effect when the hook runs: `"low"`, `"medium"`, `"high"`, `"xhigh"`, or `"max"`. If you set a level the active model doesn't support, `level` reports the level Claude Code ran instead; [Adjust effort level](/docs/en/model-config.md#adjust-effort-level) says how it picks that level. The object matches the [status line](/docs/en/statusline.md#available-data) `effort` field. Present for events that fire within a tool-use context, such as `PreToolUse`, `PostToolUse`, `Stop`, and `SubagentStop`, when the current model supports the effort parameter. The level is also available to hook commands and the Bash tool as the `$CLAUDE_EFFORT` environment variable. |

732| `scratchpad_dir` | Path to the session's [scratchpad directory](https://code.claude.com/docs/en/claude-directory.md#session-scratchpad-directory), where Claude keeps temporary working files. Absent when the session has no scratchpad or the temp directory is unavailable. Requires Claude Code v2.1.257 or later |

733| `permission_mode` | Current [permission mode](https://code.claude.com/docs/en/permissions.md#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"`, or `"bypassPermissions"`. The mode labeled **Manual** arrives as `"default"`, never as `"manual"`, so scripts that match `"default"` keep working. Not all events receive this field. Check the JSON example in each [hook event](#hook-events) section |

734| `effort` | Object with a `level` field holding the [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) in effect when the hook runs: `"low"`, `"medium"`, `"high"`, `"xhigh"`, or `"max"`. If you set a level the active model doesn't support, `level` reports the level Claude Code ran instead; [Adjust effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level) says how it picks that level. The object matches the [status line](https://code.claude.com/docs/en/statusline.md#available-data) `effort` field. Present for events that fire within a tool-use context, such as `PreToolUse`, `PostToolUse`, `Stop`, and `SubagentStop`, when the current model supports the effort parameter. The level is also available to hook commands and the Bash tool as the `$CLAUDE_EFFORT` environment variable. |

735735| `hook_event_name` | Name of the event that fired |

736736

737`agent_id` and `agent_type` tell your script which agent a hook fired in, such as a subagent, an [in-process teammate](/docs/en/agent-teams.md#choose-a-display-mode), or the agent you chose with `--agent`:

737`agent_id` and `agent_type` tell your script which agent a hook fired in, such as a subagent, an [in-process teammate](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode), or the agent you chose with `--agent`:

738738

739739| Field | Description |

740740| :- | :- |

from line 745

745745

746746There is no `$CLAUDE_MODEL` environment variable. The hook can read `$ANTHROPIC_MODEL` if you set it in your shell, but that value doesn't change when you switch models with `/model` during a session.

747747

748A hook process inherits the parent environment, apart from the `OTEL_*` exporter variables that Claude Code [removes from every subprocess it spawns](/docs/en/monitoring-usage.md#administrator-configuration) and, when [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/en/env-vars#variables) is set to `1`, the variables it strips. In a session that [gets the HIPAA configuration](/docs/en/hipaa-setup.md#check-how-developers-sign-in-and-connect), Claude Code also [removes Anthropic credentials](/docs/en/hipaa-setup.md#anthropic-credentials-in-commands-hooks-and-mcp-servers) from the hook's environment.

748A hook process inherits the parent environment, apart from the `OTEL_*` exporter variables that Claude Code [removes from every subprocess it spawns](https://code.claude.com/docs/en/monitoring-usage.md#administrator-configuration) and, when [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](https://code.claude.com/docs/en/env-vars#variables) is set to `1`, the variables it strips. In a session that [gets the HIPAA configuration](https://code.claude.com/docs/en/hipaa-setup.md#check-how-developers-sign-in-and-connect), Claude Code also [removes Anthropic credentials](https://code.claude.com/docs/en/hipaa-setup.md#anthropic-credentials-in-commands-hooks-and-mcp-servers) from the hook's environment.

749749

750750For example, a `PreToolUse` hook for a Bash command receives this on stdin:

751751

from line 872

872872

873873Apart from a command hook you run with [`async: true`](#run-hooks-in-the-background), Claude Code cancels a `command`, `http`, or `mcp_tool` hook that reaches its [`timeout`](#common-fields), discarding the hook's output, so on most events a timed-out hook renders no decision. On [`PreModelSwitch`](#premodelswitch), a hook canceled at its timeout blocks the model switch.

874874

875On `PreToolUse`, a timed-out `command`, `http`, or `mcp_tool` hook doesn't block the tool call, except for hooks [whose failure blocks the action](#block-the-action-when-a-hook-fails). The call continues through the normal [permission flow](/docs/en/permissions.md), so don't count on a stalled hook to act as a gate. To block the call when a `command` or `http` hook times out, set [`onFailure: "block"`](#block-the-action-when-a-hook-fails). An [Agent SDK callback hook](/docs/en/agent-sdk/hooks.md) that exceeds its timeout [blocks the tool call](#pretooluse).

875On `PreToolUse`, a timed-out `command`, `http`, or `mcp_tool` hook doesn't block the tool call, except for hooks [whose failure blocks the action](#block-the-action-when-a-hook-fails). The call continues through the normal [permission flow](https://code.claude.com/docs/en/permissions.md), so don't count on a stalled hook to act as a gate. To block the call when a `command` or `http` hook times out, set [`onFailure: "block"`](#block-the-action-when-a-hook-fails). An [Agent SDK callback hook](https://code.claude.com/docs/en/agent-sdk/hooks.md) that exceeds its timeout [blocks the tool call](#pretooluse).

876876

877877#### Hooks that start a background process

878878

from line 960

960960To find out why the hook failed, check the [debug log](#debug-hooks). Pick the fix that matches your hook:

961961

962962* **The action should go ahead when the hook fails**: add [`"onFailure": "continue"`](#block-the-action-when-a-hook-fails) to the hook

963* **The hook is written for Bash**: a [shell-form](#exec-form-and-shell-form) hook with no `shell` set runs in PowerShell when Git Bash isn't installed, where a script written for Bash may not run as written. Install [Git for Windows](https://git-scm.com/downloads/win), or set [`CLAUDE_CODE_GIT_BASH_PATH`](/docs/en/env-vars) if Git Bash is installed where Claude Code doesn't find it, then start a new session

963* **The hook is written for Bash**: a [shell-form](#exec-form-and-shell-form) hook with no `shell` set runs in PowerShell when Git Bash isn't installed, where a script written for Bash may not run as written. Install [Git for Windows](https://git-scm.com/downloads/win), or set [`CLAUDE_CODE_GIT_BASH_PATH`](https://code.claude.com/docs/en/env-vars) if Git Bash is installed where Claude Code doesn't find it, then start a new session

964964* **The hook runs one `.exe`, not a `.cmd` or `.bat` file**: put the program in `command` and its arguments in `args` to use exec form, and add `"onFailure": "block"`. Claude Code then starts the program with no shell. Without `"onFailure": "block"`, the call can go ahead when the program fails, is missing, or times out

965965* **The hook exits 1 to warn but must block when it crashes**: with `"onFailure": "continue"`, the call goes ahead on exit code 1, warning or crash alike. Add `"onFailure": "block"` instead, and end the script with exit code 0 where it warns, so those calls go ahead. To show the warning on `PreToolUse` after exit code 0, print it to stdout in the [`systemMessage`](#json-output) field of one JSON object

966966* **A PowerShell guard hook that must block on failure**: with `onFailure` unset, it stops doing so once Git for Windows is installed and Claude Code finds Git Bash. Add `"onFailure": "block"` so a failure or a timeout blocks the call with or without Git Bash. Also set `"shell": "powershell"` so the hook keeps running in PowerShell from then on instead of in Git Bash

from line 1032

10321032>

10331033> Choose one approach per hook: either use exit codes alone for signaling, or exit 0 and print JSON for structured control. If you mix them, exit 2 keeps its [blocking effect](#exit-code-2-behavior-per-event), and Claude Code still reads the JSON fields, with the one elicitation exception noted under [Exit code 2](#exit-code-2).

10341034

1035Print nothing but the JSON object to stdout. For a hook that isn't [async](#how-async-hooks-execute), other text there, such as a line your shell profile echoes at startup, keeps Claude Code from reading the object as JSON, and [Hook JSON has no effect](/docs/en/hooks-guide.md#hook-json-has-no-effect) shows how to find and silence that text.

1035Print nothing but the JSON object to stdout. For a hook that isn't [async](#how-async-hooks-execute), other text there, such as a line your shell profile echoes at startup, keeps Claude Code from reading the object as JSON, and [Hook JSON has no effect](https://code.claude.com/docs/en/hooks-guide.md#hook-json-has-no-effect) shows how to find and silence that text.

10361036

10371037A hook's `additionalContext`, `systemMessage`, and `initialUserMessage` strings, and its plain stdout, are capped at 10,000 characters:

10381038

10391039* **Scope**: Claude Code measures each string on its own, even when several hooks run for the same event. For JSON output, each field is measured separately; plain stdout is measured whole.

1040* **Over the limit**: Claude Code saves the output to a file in the session directory and replaces it with the file path and a preview of up to the first 2,000 characters. A large valid Bash result is handled the same way, described under [Output limits](/docs/en/tools-reference.md#output-limits). Unlike that Bash ceiling, this cap has no setting or environment variable to raise it.

1040* **Over the limit**: Claude Code saves the output to a file in the session directory and replaces it with the file path and a preview of up to the first 2,000 characters. A large valid Bash result is handled the same way, described under [Output limits](https://code.claude.com/docs/en/tools-reference.md#output-limits). Unlike that Bash ceiling, this cap has no setting or environment variable to raise it.

10411041* **Reading the file**: Claude Code doesn't ask Claude to read the file, so keep anything Claude must always see within the cap.

10421042

10431043The JSON object supports three kinds of fields:

from line 1051

10511051| `continue` | `true` | If `false`, Claude stops processing entirely after the hook runs. Takes precedence over any event-specific decision fields |

10521052| `stopReason` | none | Message shown to the user when `continue` is `false`. It stays in the conversation, so Claude sees it if the conversation continues |

10531053| `suppressOutput` | `false` | Has no effect: Claude Code accepts the field but doesn't act on it. A successful hook's stdout is never shown in the transcript and is recorded in the debug log |

1054| `systemMessage` | none | Warning message shown to the user. In [Agent SDK](/docs/en/agent-sdk/overview.md) and [`--output-format stream-json`](/docs/en/headless) output, it can arrive as an [`SDKInformationalMessage`](/docs/en/agent-sdk/typescript#sdkinformationalmessage) |

1054| `systemMessage` | none | Warning message shown to the user. In [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) and [`--output-format stream-json`](https://code.claude.com/docs/en/headless) output, it can arrive as an [`SDKInformationalMessage`](https://code.claude.com/docs/en/agent-sdk/typescript#sdkinformationalmessage) |

10551055| `terminalSequence` | none | A terminal escape sequence for Claude Code to emit on your behalf, such as a desktop notification, window title, or bell. Restricted to OSC `0`/`1`/`2`/`9`/`99`/`777` and BEL. If the value contains anything outside the allowlist, the field is ignored. Use this instead of writing to `/dev/tty`, which is unavailable to hooks |

10561056

10571057To stop Claude entirely:

from line 1097

10971097

10981098#### Add context for Claude

10991099

1100The `additionalContext` field passes a string from your hook into Claude's context window. Claude Code wraps the string in a [system reminder](/docs/en/glossary.md#system-reminder) and inserts it into the conversation at the point where the hook fired. Claude reads the reminder on the next model request, but it doesn't appear as a chat message in the interface.

1100The `additionalContext` field passes a string from your hook into Claude's context window. Claude Code wraps the string in a [system reminder](https://code.claude.com/docs/en/glossary.md#system-reminder) and inserts it into the conversation at the point where the hook fired. Claude reads the reminder on the next model request, but it doesn't appear as a chat message in the interface.

11011101

11021102Return `additionalContext` inside `hookSpecificOutput` alongside the event name:

11031103

from line 1130

11301130* **Conditional project rules**: which test command applies to the file just edited, which directories are read-only in this worktree

11311131* **External data**: open issues assigned to you, recent CI results, content fetched from an internal service

11321132

1133For instructions that never change, prefer [CLAUDE.md](/docs/en/memory.md). It loads without running a script and is the standard place for static project conventions.

1133For instructions that never change, prefer [CLAUDE.md](https://code.claude.com/docs/en/memory.md). It loads without running a script and is the standard place for static project conventions.

11341134

11351135Write the text as factual statements rather than imperative system instructions. Phrasing such as "The deployment target is production" or "This repo uses `bun test`" reads as project information. Text framed as out-of-band system commands can trigger Claude's prompt-injection defenses, which causes Claude to surface the text to you instead of treating it as context.

11361136

from line 1210

12101210}

12111211```

12121212

1213For extended examples including Bash command validation, prompt filtering, and auto-approval scripts, see [What you can automate](/docs/en/hooks-guide.md#what-you-can-automate) in the guide and the [Bash command validator reference implementation](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py).

1213For extended examples including Bash command validation, prompt filtering, and auto-approval scripts, see [What you can automate](https://code.claude.com/docs/en/hooks-guide.md#what-you-can-automate) in the guide and the [Bash command validator reference implementation](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py).

12141214

12151215## Hook events

12161216

from line 1218

12181218

12191219### SessionStart

12201220

1221Runs when Claude Code starts a new session or resumes an existing session. Useful for loading development context like existing issues or recent changes to your codebase, or setting up environment variables. For static context that doesn't require a script, use [CLAUDE.md](/docs/en/memory.md) instead.

12221222

12231223SessionStart runs on every session, so keep these hooks fast. Only `type: "command"` and `type: "mcp_tool"` hooks are supported. See [MCP tool hook fields](#mcp-tool-hook-fields) for when `mcp_tool` hooks run.

12241224

from line 1230

12301230| `resume` | `--resume`, `--continue`, or `/resume` |

12311231| `clear` | `/clear` |

12321232| `compact` | Auto or manual compaction |

1233| `fork` | A new session forked from an existing one: `--fork-session` with `--resume` or `--continue`, the `/fork` background copy, `/branch`, or a conversation you [move to the background](/docs/en/agent-view.md#from-inside-a-session) |

12341234

12351235When you start an interactive session, resume a conversation at launch with `--continue` or `--resume`, or run `/clear`, SessionStart hooks run in the background. You can type right away, and a conversation you resumed appears without waiting for the hooks. Claude's first response still waits for the hooks to finish, so their context reaches Claude.

12361236

from line 1251

12511251| `agent_type` | The agent name, present when you start Claude Code with `claude --agent <name>` |

12521252| `session_title` | The session's custom title, present when one is set, for example with `--name`, `/rename`, a hook's `sessionTitle` output, or the Agent SDK's `renameSession()`. A hook that emits `sessionTitle` can check this field first to avoid overwriting an existing custom title |

12531253

1254A session you haven't named can still have a [generated title](/docs/en/sessions.md#name-your-sessions). That title isn't a custom title and doesn't appear in `session_title`.

1254A session you haven't named can still have a [generated title](https://code.claude.com/docs/en/sessions.md#name-your-sessions). That title isn't a custom title and doesn't appear in `session_title`.

12551255

12561256When `source` is `"resume"` or `"fork"` and the transcript contains at least one response from Claude, SessionStart hooks also receive the four fields below. Your hook can use them to report what resuming a stale conversation costs before the first request, for example in a [`systemMessage`](#json-output). These fields require Claude Code v2.1.251 or later.

12571257

from line 1259

12591259| :- | :- |

12601260| `seconds_since_last_response` | Wall-clock seconds since the last response in the resumed transcript |

12611261| `context_tokens` | Tokens the first request of the resumed session re-sends as its prompt |

1262| `prompt_cache_likely_expired` | `true` when the last response is older than the session's [prompt cache lifetime](/docs/en/prompt-caching.md#cache-lifetime) or a later compaction replaced the cached conversation |

1262| `prompt_cache_likely_expired` | `true` when the last response is older than the session's [prompt cache lifetime](https://code.claude.com/docs/en/prompt-caching.md#cache-lifetime) or a later compaction replaced the cached conversation |

12631263| `estimated_cache_write_usd` | Estimated cost in US dollars of writing `context_tokens` to the prompt cache on the session's model, excluding the response |

12641264

12651265This example shows the input for a session resumed 90 minutes after its last response:

from line 1286

12861286| Field | Description |

12871287| :- | :- |

12881288| `additionalContext` | String added to Claude's context at the start of the conversation, before the first prompt. See [Add context for Claude](#add-context-for-claude) for how the text is delivered and what to put in it |

1289| `initialUserMessage` | String used as the first user message of the session, in [non-interactive mode](/docs/en/headless.md) with the `-p` flag. It becomes the first turn even if you pass no prompt. A prompt you do pass follows as the next turn |

1289| `initialUserMessage` | String used as the first user message of the session, in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag. It becomes the first turn even if you pass no prompt. A prompt you do pass follows as the next turn |

12901290| `sessionTitle` | Sets the session title, with the same effect as `/rename`. Applies when `source` is `"startup"`, `"resume"`, or `"fork"` |

12911291| `watchPaths` | Array of absolute paths to watch for [FileChanged](#filechanged) events during this session |

1292| `reloadSkills` | Boolean. When `true`, Claude Code re-scans the [skill](/docs/en/skills.md) and command directories after the SessionStart hooks complete. See [Reload skills that a hook installs](#reload-skills-that-a-hook-installs) |

1292| `reloadSkills` | Boolean. When `true`, Claude Code re-scans the [skill](https://code.claude.com/docs/en/skills.md) and command directories after the SessionStart hooks complete. See [Reload skills that a hook installs](#reload-skills-that-a-hook-installs) |

12931293

12941294This output adds context and names the session:

12951295

from line 1365

13651365

13661366##### Persisted variables in PowerShell commands

13671367

1368[PowerShell](/docs/en/tools-reference.md#powershell-tool) commands receive the variables from `CLAUDE_ENV_FILE` too, in Claude Code v2.1.296 or later, but PowerShell never runs the file. Claude Code reads the assignments out of it and copies them into the PowerShell command's environment instead. It does so only when every line is one of the following, across what every hook in this session wrote and any script you [set `CLAUDE_ENV_FILE` to](/docs/en/env-vars) before launch:

1368[PowerShell](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) commands receive the variables from `CLAUDE_ENV_FILE` too, in Claude Code v2.1.296 or later, but PowerShell never runs the file. Claude Code reads the assignments out of it and copies them into the PowerShell command's environment instead. It does so only when every line is one of the following, across what every hook in this session wrote and any script you [set `CLAUDE_ENV_FILE` to](https://code.claude.com/docs/en/env-vars) before launch:

13691369

13701370* A blank line or a `#` comment

13711371* One assignment at the start of the line, written `export NAME=value`, `declare -x NAME=value`, or `NAME=value`, with a value Bash would use exactly as written, made of any mix of these parts: unquoted text that uses only letters, digits, and the characters `_ @ % + = : , . / -`, text in single quotes, and text in double quotes where any `$`, backtick, or `"` inside is escaped with a backslash

13721372

1373If any line is of another kind, such as `export PATH="$PATH:./node_modules/.bin"` with its unescaped `$PATH`, a `source` command, or the `$'...'` strings that `direnv export bash` prints, PowerShell commands receive none of the variables, and `claude --debug` logs `Session environment is not all plain assignments`. Bash commands still receive all of them. On Windows, PowerShell commands also don't receive a variable whose value contains `/` or `\`, because Git Bash and Windows write paths differently. A [sandboxed](/docs/en/sandboxing.md) PowerShell command receives none of the variables.

1373If any line is of another kind, such as `export PATH="$PATH:./node_modules/.bin"` with its unescaped `$PATH`, a `source` command, or the `$'...'` strings that `direnv export bash` prints, PowerShell commands receive none of the variables, and `claude --debug` logs `Session environment is not all plain assignments`. Bash commands still receive all of them. On Windows, PowerShell commands also don't receive a variable whose value contains `/` or `\`, because Git Bash and Windows write paths differently. A [sandboxed](https://code.claude.com/docs/en/sandboxing.md) PowerShell command receives none of the variables.

13741374

13751375> [!NOTE]

13761376>

from line 1378

13781378

13791379### Setup

13801380

1381Fires only when you launch Claude Code with `--init-only`, or with `--init` or `--maintenance` in [non-interactive mode](/docs/en/headless.md) with the `-p` flag. It doesn't fire on normal startup. Use it for one-time dependency installation or scheduled cleanup that you trigger explicitly from CI or scripts, separate from normal session startup. For per-session initialization, use [SessionStart](#sessionstart) instead.

1381Fires only when you launch Claude Code with `--init-only`, or with `--init` or `--maintenance` in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag. It doesn't fire on normal startup. Use it for one-time dependency installation or scheduled cleanup that you trigger explicitly from CI or scripts, separate from normal session startup. For per-session initialization, use [SessionStart](#sessionstart) instead.

13821382

13831383The matcher value corresponds to the CLI flag that triggered the hook:

13841384

from line 1393

13931393

13941394On success, `--init-only` prints nothing to the terminal. To confirm the hooks ran, start with `claude --debug-file <path> --init-only`, replacing `<path>` with a log file location, and check the log for the Setup and SessionStart hook entries.

13951395

1396Because Setup doesn't fire on every launch, a plugin that needs a dependency installed can't rely on Setup alone. The practical pattern is to check for the dependency on first use and install on miss, for example a hook or skill that tests for `${CLAUDE_PLUGIN_DATA}/node_modules` and runs `npm install` if absent. See the [persistent data directory](/docs/en/plugins/components.md#path-variables-and-persistent-data) for where to store installed dependencies. If you distribute your plugin through a marketplace, you may not need this pattern: Claude Code [installs eligible Node.js package dependencies automatically](/docs/en/plugins/loading.md#node-js-package-dependencies) when it caches the plugin.

1396Because Setup doesn't fire on every launch, a plugin that needs a dependency installed can't rely on Setup alone. The practical pattern is to check for the dependency on first use and install on miss, for example a hook or skill that tests for `${CLAUDE_PLUGIN_DATA}/node_modules` and runs `npm install` if absent. See the [persistent data directory](https://code.claude.com/docs/en/plugins/components.md#path-variables-and-persistent-data) for where to store installed dependencies. If you distribute your plugin through a marketplace, you may not need this pattern: Claude Code [installs eligible Node.js package dependencies automatically](https://code.claude.com/docs/en/plugins/loading.md#node-js-package-dependencies) when it caches the plugin.

13971397

13981398#### Setup input

13991399

from line 1411

14111411

14121412#### Setup decision control

14131413

1414Setup hooks can't block; execution continues on any exit code. On every exit code, Claude Code discards a Setup hook's [JSON output fields](#json-output), such as `systemMessage`, `continue`, and `hookSpecificOutput.additionalContext`. With `-p`, a Setup hook's stdout, stderr, and exit code appear in the run's output only as [`hook_response` events](/docs/en/headless#read-session-metadata) when you launch with `--output-format stream-json --verbose`.

1414Setup hooks can't block; execution continues on any exit code. On every exit code, Claude Code discards a Setup hook's [JSON output fields](#json-output), such as `systemMessage`, `continue`, and `hookSpecificOutput.additionalContext`. With `-p`, a Setup hook's stdout, stderr, and exit code appear in the run's output only as [`hook_response` events](https://code.claude.com/docs/en/headless#read-session-metadata) when you launch with `--output-format stream-json --verbose`.

14151415

14161416Setup hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, as in [SessionStart hooks](#persist-environment-variables). Only `type: "command"` hooks run on `Setup`. A `type: "mcp_tool"` hook on `Setup` is always skipped, as described under [MCP tool hook fields](#mcp-tool-hook-fields).

14171417

from line 1419

14191419

14201420Fires when a `CLAUDE.md` or `.claude/rules/*.md` file is loaded into context. This event fires at session start for eagerly loaded files and again later when files are lazily loaded, for example when Claude accesses a subdirectory that contains a nested `CLAUDE.md` or when conditional rules with `paths:` frontmatter match. The hook doesn't support blocking or decision control. It runs asynchronously for observability purposes.

14211421

1422This event doesn't fire when Claude [reads `AGENTS.md` directly](/docs/en/memory#agents-md) through the **Project instructions** setting. It does fire when a `CLAUDE.md` imports your `AGENTS.md`, with `load_reason` set to `include` as for any other imported file, and when `CLAUDE.md` is a symlink to it, as a normal `CLAUDE.md` load.

1422This event doesn't fire when Claude [reads `AGENTS.md` directly](https://code.claude.com/docs/en/memory#agents-md) through the **Project instructions** setting. It does fire when a `CLAUDE.md` imports your `AGENTS.md`, with `load_reason` set to `include` as for any other imported file, and when `CLAUDE.md` is a symlink to it, as a normal `CLAUDE.md` load.

14231423

14241424The matcher runs against `load_reason`. For example, use `"matcher": "session_start"` to fire only for files loaded at session start, or `"matcher": "path_glob_match|nested_traversal"` to fire only for lazy loads.

14251425

from line 1460

14601460

14611461`UserPromptSubmit` hooks don't fire only on prompts you type. Claude Code also runs them on:

14621462

1463* A [session-scoped scheduled task](/docs/en/scheduled-tasks.md) firing, including a `/loop` iteration

1464* A [background subagent](/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) reporting back to the session that started it

1465* A [message another session sends](/docs/en/cross-session-messaging.md) to your main conversation

1463* A [session-scoped scheduled task](https://code.claude.com/docs/en/scheduled-tasks.md) firing, including a `/loop` iteration

1464* A [background subagent](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) reporting back to the session that started it

1465* A [message another session sends](https://code.claude.com/docs/en/cross-session-messaging.md) to your main conversation

14661466

14671467`UserPromptSubmit` hooks have a default timeout of 30 seconds for `command`, `http`, and `mcp_tool` types, shorter than the 600-second default for those types on most other events. Because this hook runs before every prompt and blocks model processing until it completes, a stuck hook stalls the session. If your hook needs more time, set the `timeout` field in the hook entry.

14681468

14691469Apart from a command hook you run with [`async: true`](#run-hooks-in-the-background), a `UserPromptSubmit` command, HTTP, or MCP tool hook that reaches its timeout is canceled and its output, including any `additionalContext`, is discarded. The prompt still reaches Claude without that context. To block the prompt instead, set [`onFailure: "block"`](#block-the-action-when-a-hook-fails) on a command or HTTP hook. The transcript shows a notice naming the hook, the timeout that fired, and that the output was discarded.

14701470

1471An [Agent SDK callback hook](/docs/en/agent-sdk/hooks.md) on `UserPromptSubmit` that reaches its timeout blocks the prompt with a message naming the hook and the timeout, because a callback there can be acting as a policy gate that must not fail open. The session continues.

1471An [Agent SDK callback hook](https://code.claude.com/docs/en/agent-sdk/hooks.md) on `UserPromptSubmit` that reaches its timeout blocks the prompt with a message naming the hook and the timeout, because a callback there can be acting as a policy gate that must not fail open. The session continues.

14721472

14731473#### UserPromptSubmit input

14741474

1475In addition to the [common input fields](#common-input-fields), UserPromptSubmit hooks receive the `prompt` field containing the submitted text. Pasted content that collapsed to a `[Pasted text #N]` placeholder arrives expanded in place. In sessions where Claude Code [marks pasted text for Claude](/docs/en/terminal-config.md#how-claude-treats-pasted-text), that expanded content sits between a `<pasted_content id="…">` line and a `</pasted_content id="…">` line, so account for those lines if your hook parses the prompt.

1475In addition to the [common input fields](#common-input-fields), UserPromptSubmit hooks receive the `prompt` field containing the submitted text. Pasted content that collapsed to a `[Pasted text #N]` placeholder arrives expanded in place. In sessions where Claude Code [marks pasted text for Claude](https://code.claude.com/docs/en/terminal-config.md#how-claude-treats-pasted-text), that expanded content sits between a `<pasted_content id="…">` line and a `</pasted_content id="…">` line, so account for those lines if your hook parses the prompt.

14761476

14771477UserPromptSubmit hooks also receive `session_title` when the session has a custom title, with the same meaning as the [SessionStart `session_title` field](#sessionstart-input).

14781478

from line 1487

14871487}

14881488```

14891489

1490When the prompt is a [skill](/docs/en/skills.md) or custom command you typed, such as `/deploy staging`, the hook receives that line as you typed it rather than the expanded skill content. If the hook blocks the prompt, the command doesn't run, so shell commands the skill [injects with `` !`<command>` ``](/docs/en/skills#inject-dynamic-context) don't run either. To match on the command's name or arguments instead, use [UserPromptExpansion](#userpromptexpansion).

1490When the prompt is a [skill](https://code.claude.com/docs/en/skills.md) or custom command you typed, such as `/deploy staging`, the hook receives that line as you typed it rather than the expanded skill content. If the hook blocks the prompt, the command doesn't run, so shell commands the skill [injects with `` !`<command>` ``](https://code.claude.com/docs/en/skills#inject-dynamic-context) don't run either. To match on the command's name or arguments instead, use [UserPromptExpansion](#userpromptexpansion).

14911491

14921492#### UserPromptSubmit decision control

14931493

from line 1529

15291529

15301530A blocked prompt never reaches Claude, but its text isn't removed everywhere. By default the block message shown to the user ends with `Original prompt:` followed by the submitted text, and Claude Code writes that message to the session's transcript file on disk. To leave the text out of the message, print JSON with `"suppressOriginalPrompt": true` inside `hookSpecificOutput`. This works whether the hook blocks with `decision: "block"` or by exiting 2.

15311531

1532`suppressOriginalPrompt` changes only the block message. The submitted text can still appear in local files such as the session transcript and your prompt history, so a blocking hook isn't a way to keep a secret off disk. To limit or remove those files, see [Plaintext storage](/docs/en/claude-directory.md#plaintext-storage) and [Clear local data](/docs/en/claude-directory.md#clear-local-data).

1532`suppressOriginalPrompt` changes only the block message. The submitted text can still appear in local files such as the session transcript and your prompt history, so a blocking hook isn't a way to keep a secret off disk. To limit or remove those files, see [Plaintext storage](https://code.claude.com/docs/en/claude-directory.md#plaintext-storage) and [Clear local data](https://code.claude.com/docs/en/claude-directory.md#clear-local-data).

15331533

15341534### UserPromptExpansion

15351535

from line 1719

17191719

17201720> [!WARNING]

17211721>

1722> PreToolUse runs only when Claude calls a tool. By default, files you [reference with `@` in your prompt](/docs/en/common-workflows#reference-files-and-directories) are added without any tool call. Claude Code inserts their contents while building the prompt, so no PreToolUse hook fires for them, including hooks matching `Read`. PreToolUse also doesn't fire for [`EndConversation`](/docs/en/tools-reference#endconversation-tool-behavior).

1722> PreToolUse runs only when Claude calls a tool. By default, files you [reference with `@` in your prompt](https://code.claude.com/docs/en/common-workflows#reference-files-and-directories) are added without any tool call. Claude Code inserts their contents while building the prompt, so no PreToolUse hook fires for them, including hooks matching `Read`. PreToolUse also doesn't fire for [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior).

17231723>

17241724> You can block specific paths from `@` references, or turn the insertion off:

17251725>

1726> * **Block specific paths**: add a [`Read` deny rule](/docs/en/permissions#read-and-edit) for them

1727> * **Turn the insertion off**: set [`CLAUDE_CODE_DISABLE_FILE_MENTIONS=1`](/docs/en/env-vars#variables) in your shell, user settings, or managed settings. Claude then gets the mentioned paths with a note to read them using its file tools. If it does, your matching PreToolUse hooks run. The variable requires Claude Code v2.1.299 or later, and Claude Code ignores it in project and local settings.

1726> * **Block specific paths**: add a [`Read` deny rule](https://code.claude.com/docs/en/permissions#read-and-edit) for them

1727> * **Turn the insertion off**: set [`CLAUDE_CODE_DISABLE_FILE_MENTIONS=1`](https://code.claude.com/docs/en/env-vars#variables) in your shell, user settings, or managed settings. Claude then gets the mentioned paths with a note to read them using its file tools. If it does, your matching PreToolUse hooks run. The variable requires Claude Code v2.1.299 or later, and Claude Code ignores it in project and local settings.

17281728

17291729Use [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, ask, or defer the tool call.

17301730

1731An [Agent SDK callback hook](/docs/en/agent-sdk/hooks.md) on `PreToolUse` that exceeds its timeout blocks the tool call, and Claude receives an error result naming the timeout.

1731An [Agent SDK callback hook](https://code.claude.com/docs/en/agent-sdk/hooks.md) on `PreToolUse` that exceeds its timeout blocks the tool call, and Claude receives an error result naming the timeout.

17321732

17331733#### PreToolUse input

17341734

17351735In addition to the [common input fields](#common-input-fields), PreToolUse hooks receive `tool_name`, `tool_input`, and `tool_use_id`.

17361736

1737For an [MCP tool](#match-mcp-tools), the input also carries `mcp_server`, an object with the server's `name` and a `source` that says where the server's definition came from. The `source` values include `plugin`, `sdk`, and configuration scopes such as `user` and `project`. [`McpServerProvenance`](/docs/en/agent-sdk/typescript#mcpserverprovenance) in the Agent SDK reference lists them all and says how to treat one you don't recognize. Base trust decisions on `source` rather than on `name` or the `mcp__<server>__` tool-name prefix. The `mcp_server` field requires Claude Code v2.1.274 or later.

1737For an [MCP tool](#match-mcp-tools), the input also carries `mcp_server`, an object with the server's `name` and a `source` that says where the server's definition came from. The `source` values include `plugin`, `sdk`, and configuration scopes such as `user` and `project`. [`McpServerProvenance`](https://code.claude.com/docs/en/agent-sdk/typescript#mcpserverprovenance) in the Agent SDK reference lists them all and says how to treat one you don't recognize. Base trust decisions on `source` rather than on `name` or the `mcp__<server>__` tool-name prefix. The `mcp_server` field requires Claude Code v2.1.274 or later.

17381738

17391739For the file tools `Write`, `Edit`, and `Read`, `tool_input.file_path` is always absolute:

17401740

from line 1767

17671767| :- | :- | :- | :- |

1770| `timeout` | number | `120000` | Optional timeout in milliseconds. Values above the [maximum](https://code.claude.com/docs/en/tools-reference.md#bash-tool-behavior) are reduced to the maximum rather than rejected |

17721772

1773When a Bash command changes files in a Git repository, Claude Code can record what changed. It records the changes in every permission mode when the [`bashEditDiffEnabled`](/docs/en/settings-reference#basheditdiffenabled) setting turns recording on; that setting's entry says which files can set it. Otherwise it records them only in auto mode and `bypassPermissions` mode, and only when Claude Code directs Claude to edit files through Bash. Set `bashEditDiffEnabled` to `false` to turn the recording off. Background commands and read-only commands carry no diff.

1773When a Bash command changes files in a Git repository, Claude Code can record what changed. It records the changes in every permission mode when the [`bashEditDiffEnabled`](https://code.claude.com/docs/en/settings-reference#basheditdiffenabled) setting turns recording on; that setting's entry says which files can set it. Otherwise it records them only in auto mode and `bypassPermissions` mode, and only when Claude Code directs Claude to edit files through Bash. Set `bashEditDiffEnabled` to `false` to turn the recording off. Background commands and read-only commands carry no diff.

17741774

17751775Your [PostToolUse hook](#posttooluse) then receives the changed files in `tool_response.bashEditDiff`. The list covers what changed under the repository while the command ran. Files that Git ignores and files in submodules aren't listed. Requires Claude Code v2.1.269 or later.

17761776

from line 1791

17911791

17921792##### PowerShell

17931793

1794Executes PowerShell commands. See the [PowerShell tool](/docs/en/tools-reference.md#powershell-tool) for availability by platform.

1794Executes PowerShell commands. See the [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) for availability by platform.

17951795

17961796The fields match the Bash tool, with the command string in `command`:

17971797

from line 1882

18821882

18831883##### Agent

18841884

1885Spawns a [subagent](/docs/en/sub-agents.md).

1885Spawns a [subagent](https://code.claude.com/docs/en/sub-agents.md).

18861886

18881888| :- | :- | :- | :- |

from line 1891

18931893

1894When a foreground Agent call completes, your [PostToolUse hook](#posttooluse) receives the subagent's result and run telemetry in `tool_response`. Read these fields to inspect the run; for token and cost rollups across subagents, use the [token and cost counters](/docs/en/monitoring-usage.md#token-counter) filtered to `query_source` `"subagent"`, since `totalTokens` and `usage` cover the final request only:

1894When a foreground Agent call completes, your [PostToolUse hook](#posttooluse) receives the subagent's result and run telemetry in `tool_response`. Read these fields to inspect the run; for token and cost rollups across subagents, use the [token and cost counters](https://code.claude.com/docs/en/monitoring-usage.md#token-counter) filtered to `query_source` `"subagent"`, since `totalTokens` and `usage` cover the final request only:

18951895

18971897| :- | :- | :- | :- |

1898| `status` | string | `"completed"` | `"completed"` for foreground subagents, `"async_launched"` for background subagents. For which subagents run each way, see [Run subagents in foreground or background](/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) |

1898| `status` | string | `"completed"` | `"completed"` for foreground subagents, `"async_launched"` for background subagents. For which subagents run each way, see [Run subagents in foreground or background](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) |

19001900| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | The subagent's final text blocks, or, for a subagent whose report goes through `SubagentHandback`, a short note about that hand-back in their place |

from line 1905

19061906| `usage` | object | `{"input_tokens": 8320, ...}` | Per-type token breakdown of the final API request: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |

19071907

1908On Claude Code v2.1.271 or later, a subagent that runs with the [`SubagentHandback`](/docs/en/tools-reference) tool, which Claude Code provides in [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), delivers its report through that tool rather than returning it as text. The `content` field of its `completed` result then carries a short note about that hand-back rather than the report itself. To read the report, match a `PreToolUse` or `PostToolUse` hook on `SubagentHandback` and read `tool_input.message`.

1908On Claude Code v2.1.271 or later, a subagent that runs with the [`SubagentHandback`](https://code.claude.com/docs/en/tools-reference) tool, which Claude Code provides in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), delivers its report through that tool rather than returning it as text. The `content` field of its `completed` result then carries a short note about that hand-back rather than the report itself. To read the report, match a `PreToolUse` or `PostToolUse` hook on `SubagentHandback` and read `tool_input.message`.

19091909

19101910For background subagents, the tool returns when the task moves to the background, so `tool_response` carries no usage fields: a background launch returns immediately, and a foreground task that Claude Code backgrounds mid-run returns at that transition. It has `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, and `resolvedModel`.

19111911

from line 1922

19221922

19231923##### ExitPlanMode

19241924

1925Presents a plan and asks the user to approve it before Claude leaves [plan mode](/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode). Claude writes the plan to a file on disk before calling the tool, so the literal `tool_input` from the model is typically empty. Claude Code injects the plan content and file path before passing the input to hooks.

1925Presents a plan and asks the user to approve it before Claude leaves [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode). Claude writes the plan to a file on disk before calling the tool, so the literal `tool_input` from the model is typically empty. Claude Code injects the plan content and file path before passing the input to hooks.

19261926

19281928| :- | :- | :- | :- |

from line 1938

19381938

19391939| Field | Description |

19401940| :- | :- |

1941| `permissionDecision` | `"allow"` skips the permission prompt, except for [actions no mode auto-approves](/docs/en/permission-modes.md#actions-no-mode-auto-approves) and [reads from network paths](/docs/en/permissions.md#network-paths). `AskUserQuestion` and `ExitPlanMode` need [`updatedInput` paired with `"allow"`](#allow-with-updatedinput). For plan mode, see [Hook approvals in plan mode](/docs/en/permissions.md#hook-approvals-in-plan-mode). `"deny"` prevents the tool call. `"ask"` prompts the user to confirm. `"defer"` ends the turn so the tool can be resumed later, and requires [non-interactive mode](#defer-a-tool-call-for-later) with the `-p` flag. [Deny and ask rules](/docs/en/permissions.md#manage-permissions) are still evaluated regardless of what the hook returns |

1942| `permissionDecisionReason` | For `"ask"`, shown to the user in the permission prompt. When Claude Code [denies the call](/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs) in a `-p` run where no one can answer that prompt, Claude reads the reason in the tool result instead. For `"deny"`, shown to Claude. For `"allow"` and `"defer"`, written to the [debug log](#debug-hooks) only |

1943| `updatedInput` | Modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. Claude Code evaluates permission rules and a Bash command's [auto-background eligibility](/docs/en/tools-reference.md#foreground-commands-that-move-to-the-background) against the input your hook returns, not the input Claude sent. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user. For `"defer"`, ignored |

1941| `permissionDecision` | `"allow"` skips the permission prompt, except for [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves) and [reads from network paths](https://code.claude.com/docs/en/permissions.md#network-paths). `AskUserQuestion` and `ExitPlanMode` need [`updatedInput` paired with `"allow"`](#allow-with-updatedinput). For plan mode, see [Hook approvals in plan mode](https://code.claude.com/docs/en/permissions.md#hook-approvals-in-plan-mode). `"deny"` prevents the tool call. `"ask"` prompts the user to confirm. `"defer"` ends the turn so the tool can be resumed later, and requires [non-interactive mode](#defer-a-tool-call-for-later) with the `-p` flag. [Deny and ask rules](https://code.claude.com/docs/en/permissions.md#manage-permissions) are still evaluated regardless of what the hook returns |

1942| `permissionDecisionReason` | For `"ask"`, shown to the user in the permission prompt. When Claude Code [denies the call](https://code.claude.com/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs) in a `-p` run where no one can answer that prompt, Claude reads the reason in the tool result instead. For `"deny"`, shown to Claude. For `"allow"` and `"defer"`, written to the [debug log](#debug-hooks) only |

1943| `updatedInput` | Modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. Claude Code evaluates permission rules and a Bash command's [auto-background eligibility](https://code.claude.com/docs/en/tools-reference.md#foreground-commands-that-move-to-the-background) against the input your hook returns, not the input Claude sent. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user. For `"defer"`, ignored |

19441944| `additionalContext` | String added to Claude's context alongside the tool result. Ignored when `permissionDecision` is `"defer"`. See [Add context for Claude](#add-context-for-claude) |

19451945

19461946When multiple PreToolUse hooks return different decisions, precedence is `deny` > `defer` > `ask` > `allow`.

from line 1949

19491949

19501950When a hook returns `"ask"`, the permission prompt displayed to the user includes a label identifying where the hook came from: `[settings]` for a hook from any settings file or from agent frontmatter, `[plugin:<name>]` for a plugin's hook, or `[skill]` for a hook from skill frontmatter. This helps users understand which configuration source is requesting confirmation.

19511951

1952A hook's `"ask"` also forces a permission prompt in [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode): the classifier can still deny the tool call, but it can't approve the call silently.

1952A hook's `"ask"` also forces a permission prompt in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode): the classifier can still deny the tool call, but it can't approve the call silently.

19531953

19541954```json theme={null}

19551955{

from line 1971

19711971

19721972#### Tools that require user interaction

19731973

1974`AskUserQuestion` and `ExitPlanMode` require user interaction. In [non-interactive mode](/docs/en/headless.md) with the `-p` flag, Claude Code offers them only when the run has a [permission host](/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs) to receive the prompt, such as an Agent SDK `canUseTool` callback.

1974`AskUserQuestion` and `ExitPlanMode` require user interaction. In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag, Claude Code offers them only when the run has a [permission host](https://code.claude.com/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs) to receive the prompt, such as an Agent SDK `canUseTool` callback.

19751975

19761976A `PreToolUse` hook satisfies that requirement when it does the following:

19771977

from line 2003

20032003}

20042004```

20052005

2006An MCP tool whose server marks it with [`_meta["anthropic/requiresUserInteraction"]`](/docs/en/mcp#require-approval-for-a-specific-tool) is stricter: a hook can't skip its approval prompt with `"allow"`, with or without `updatedInput`, because Claude Code can't confirm the hook collected the interaction the tool needs.

2006An MCP tool whose server marks it with [`_meta["anthropic/requiresUserInteraction"]`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool) is stricter: a hook can't skip its approval prompt with `"allow"`, with or without `updatedInput`, because Claude Code can't confirm the hook collected the interaction the tool needs.

20072007

20082008#### Defer a tool call for later

20092009

2010`"defer"` is for integrations that run `claude -p` as a subprocess and read its JSON output, such as an Agent SDK app or a custom UI built on top of Claude Code. It lets that calling process pause Claude at a tool call, collect input through its own interface, and resume where it left off. Claude Code honors this value only in [non-interactive mode](/docs/en/headless.md) with the `-p` flag. In interactive sessions it logs a warning and ignores the hook result.

2011

2012The `AskUserQuestion` tool is the typical case: Claude wants to ask the user something, but there is no terminal to answer in. A `-p` run offers `AskUserQuestion` only when it has a [permission host](/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs), such as an MCP tool you pass with `--permission-prompt-tool`, so start the run with one. The round trip works like this:

2010`"defer"` is for integrations that run `claude -p` as a subprocess and read its JSON output, such as an Agent SDK app or a custom UI built on top of Claude Code. It lets that calling process pause Claude at a tool call, collect input through its own interface, and resume where it left off. Claude Code honors this value only in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag. In interactive sessions it logs a warning and ignores the hook result.

2011

2012The `AskUserQuestion` tool is the typical case: Claude wants to ask the user something, but there is no terminal to answer in. A `-p` run offers `AskUserQuestion` only when it has a [permission host](https://code.claude.com/docs/en/headless.md#turn-off-permission-prompts-in-unattended-runs), such as an MCP tool you pass with `--permission-prompt-tool`, so start the run with one. The round trip works like this:

20132013

201420141. Claude calls `AskUserQuestion`. The `PreToolUse` hook fires.

201520152. The hook returns `permissionDecision: "defer"`. The tool doesn't execute. The turn ends with a result carrying `stop_reason: "tool_deferred"`, and the pending tool call stays in the transcript.

from line 2033

20332033}

20342034```

20352035

2036There is no timeout or retry limit. The session remains on disk until you resume it, subject to the [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) retention sweep, which deletes session files after 30 days by default, following the [retention sweep rules](/docs/en/claude-directory.md#cleaned-up-automatically).

2036There is no timeout or retry limit. The session remains on disk until you resume it, subject to the [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) retention sweep, which deletes session files after 30 days by default, following the [retention sweep rules](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically).

20372037

20382038If the deferred tool is no longer available when you resume, the resume's first result has `stop_reason: "tool_deferred_unavailable"` and `is_error: true`, and the hook doesn't fire. This happens when an MCP server that provided the tool is not connected for the resumed session. The `deferred_tool_use` payload is still included so you can identify which tool went missing.

20392039

from line 2046

20462046

20472047> [!NOTE]

20482048>

2049> To resume a deferred session in plan mode, pass [`--permission-prompt-tool`](/docs/en/cli-reference#cli-flags) along with `--resume` so that Claude Code can present the plan for approval. For the other conditions, see [Resume in plan mode with `-p`](/docs/en/sessions#resume-in-plan-mode-with-p). Requires Claude Code v2.1.246 or later.

2049> To resume a deferred session in plan mode, pass [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags) along with `--resume` so that Claude Code can present the plan for approval. For the other conditions, see [Resume in plan mode with `-p`](https://code.claude.com/docs/en/sessions#resume-in-plan-mode-with-p). Requires Claude Code v2.1.246 or later.

20502050>

2051> When you resume with `-p`, Claude Code doesn't restore any other stored permission mode. It starts the run in the permission mode a new `claude -p` run would start in, so pass `--permission-mode` or `--dangerously-skip-permissions` again if the deferred session used one. When you resume with `claude --resume <session-id>` without `-p`, Claude Code restores the stored permission mode, with the exceptions listed in [permission mode on resume](/docs/en/sessions.md#permission-mode-on-resume).

20522052

20532053### PermissionRequest

20542054

2055Runs when Claude Code is about to ask you for permission to use a tool. In sessions that can't show a prompt, such as background subagents in [non-interactive mode](/docs/en/headless.md), Claude Code still runs these hooks, and if no hook returns a decision, it denies the tool call. For a call that reaches a `--permission-prompt-tool` or the Agent SDK's [`canUseTool` callback](/docs/en/agent-sdk/permissions), the hooks run alongside your host, and whichever decides first applies.

2055Runs when Claude Code is about to ask you for permission to use a tool. In sessions that can't show a prompt, such as background subagents in [non-interactive mode](https://code.claude.com/docs/en/headless.md), Claude Code still runs these hooks, and if no hook returns a decision, it denies the tool call. For a call that reaches a `--permission-prompt-tool` or the Agent SDK's [`canUseTool` callback](https://code.claude.com/docs/en/agent-sdk/permissions), the hooks run alongside your host, and whichever decides first applies.

20562056Use [PermissionRequest decision control](#permissionrequest-decision-control) to allow or deny on behalf of the user.

20572057

20582058Use this event when you need a signal the moment Claude asks for permission to use a tool. Claude Code runs a [Notification](#notification) hook with the `permission_prompt` type only after the prompt has waited about six seconds.

20592059

2060Claude Code doesn't run PermissionRequest hooks for a sandboxed command's [network request](/docs/en/sandboxing.md#network-isolation). To get a signal for that prompt, use the `permission_prompt` notification type.

2060Claude Code doesn't run PermissionRequest hooks for a sandboxed command's [network request](https://code.claude.com/docs/en/sandboxing.md#network-isolation). To get a signal for that prompt, use the `permission_prompt` notification type.

20612061

20622062Matches on tool name, same values as PreToolUse.

20632063

from line 2065

20652065

20662066PermissionRequest hooks receive `tool_name` and `tool_input` fields like PreToolUse hooks, but without `tool_use_id`. For an MCP tool, they also receive the [`mcp_server`](#pretooluse-input) object. An optional `permission_suggestions` array contains the [permission updates](#permission-update-entries) Claude Code suggests for this request, such as adding an allow rule or changing the permission mode.

20672067

2068The `permission_suggestions` array isn't an exact list of the options you see, because each permission dialog builds its own options. Some dialogs, such as the one for file edits, don't read the array at all and derive their options from the request itself. A dialog that does read it can still withhold an option whose suggestion stays in the array, for example when [`allowManagedPermissionRulesOnly`](/docs/en/settings-reference#allowmanagedpermissionrulesonly) hides rule-saving options. It can also offer options that have no suggestion entry, such as [**Yes, and switch to auto mode**](/docs/en/permission-modes.md#switch-permission-modes), which changes the permission mode directly rather than through a permission update.

2069

2070PreToolUse hooks run before every tool call, whether or not it needs permission. PermissionRequest hooks run only when Claude Code is about to ask you for permission, or when it would otherwise auto-deny a call that can't prompt. Neither event fires for [`EndConversation`](/docs/en/tools-reference#endconversation-tool-behavior).

2068The `permission_suggestions` array isn't an exact list of the options you see, because each permission dialog builds its own options. Some dialogs, such as the one for file edits, don't read the array at all and derive their options from the request itself. A dialog that does read it can still withhold an option whose suggestion stays in the array, for example when [`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedpermissionrulesonly) hides rule-saving options. It can also offer options that have no suggestion entry, such as [**Yes, and switch to auto mode**](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes), which changes the permission mode directly rather than through a permission update.

2069

2070PreToolUse hooks run before every tool call, whether or not it needs permission. PermissionRequest hooks run only when Claude Code is about to ask you for permission, or when it would otherwise auto-deny a call that can't prompt. Neither event fires for [`EndConversation`](https://code.claude.com/docs/en/tools-reference#endconversation-tool-behavior).

20712071

20722072```json theme={null}

20732073{

from line 2098

20982098

20992099| Field | Description |

21002100| :- | :- |

2101| `behavior` | `"allow"` grants the permission, `"deny"` denies it. [Deny and ask rules](/docs/en/permissions.md#manage-permissions) are still evaluated, so a hook returning `"allow"` doesn't override a matching deny rule |

2101| `behavior` | `"allow"` grants the permission, `"deny"` denies it. [Deny and ask rules](https://code.claude.com/docs/en/permissions.md#manage-permissions) are still evaluated, so a hook returning `"allow"` doesn't override a matching deny rule |

21022102| `updatedInput` | For `"allow"` only: modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. The modified input is re-evaluated against deny and ask rules |

21032103| `updatedPermissions` | For `"allow"` only: array of [permission update entries](#permission-update-entries) to apply, such as adding an allow rule or changing the session permission mode |

21042104| `message` | For `"deny"` only: tells Claude why the permission was denied |

from line 2135

21352135

21362136> [!NOTE]

21372137>

2138> `setMode` with `bypassPermissions` only takes effect if you launched the session with bypass mode already available: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](/docs/en/settings-reference#permissions-defaultmode). Otherwise the update is a no-op. The update is also a no-op when [`permissions.disableBypassPermissionsMode`](/docs/en/permissions#managed-settings) disables the mode, or when the session starts in [restricted mode](/docs/en/cli-reference.md#cli-flags).

2138> `setMode` with `bypassPermissions` only takes effect if you launched the session with bypass mode already available: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](https://code.claude.com/docs/en/settings-reference#permissions-defaultmode). Otherwise the update is a no-op. The update is also a no-op when [`permissions.disableBypassPermissionsMode`](https://code.claude.com/docs/en/permissions#managed-settings) disables the mode, or when the session starts in [restricted mode](https://code.claude.com/docs/en/cli-reference.md#cli-flags).

21392139>

21402140> `bypassPermissions` is never persisted as `defaultMode` regardless of `destination`.

21412141

from line 2199

21992199| `decision` | `"block"` adds the `reason` next to the tool result. Claude still sees the original output; to replace it, use `updatedToolOutput` |

22002200| `reason` | Explanation shown to Claude when `decision` is `"block"` |

22012201| `additionalContext` | String added to Claude's context alongside the tool result. See [Add context for Claude](#add-context-for-claude) |

2202| `classifierContext` | Short note about this call's result for the [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier rather than for Claude. See [Annotate a result for the auto mode classifier](#annotate-a-result-for-the-auto-mode-classifier). Requires Claude Code v2.1.236 or later |

2202| `classifierContext` | Short note about this call's result for the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier rather than for Claude. See [Annotate a result for the auto mode classifier](#annotate-a-result-for-the-auto-mode-classifier). Requires Claude Code v2.1.236 or later |

22032203| `updatedToolOutput` | Replaces the tool's output with the provided value before it is sent to Claude. The value must match the tool's output shape |

22042204| `updatedMCPToolOutput` | Replaces the output for [MCP tools](#match-mcp-tools) only. Prefer `updatedToolOutput`, which works for all tools |

22052205

from line 2228

22282228

22292229#### Annotate a result for the auto mode classifier

22302230

2231Return `classifierContext` to send a short note about the tool call's result to the [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier rather than to Claude. The classifier [never receives tool results themselves](/docs/en/permission-modes.md#how-the-classifier-evaluates-actions), so this field is the supported way to tell it something about what a call returned before it reviews later actions. The field requires Claude Code v2.1.236 or later.

2231Return `classifierContext` to send a short note about the tool call's result to the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier rather than to Claude. The classifier [never receives tool results themselves](https://code.claude.com/docs/en/permission-modes.md#how-the-classifier-evaluates-actions), so this field is the supported way to tell it something about what a call returned before it reviews later actions. The field requires Claude Code v2.1.236 or later.

22322232

22332233The example below tells the classifier where a query's output came from:

22342234

from line 2244

22442244How much weight the classifier gives the note depends on where you configured the hook:

22452245

22462246* **Hooks configured in Claude Code**: for hooks from settings files, plugins, skills, and agent frontmatter, the classifier treats the note as unverified, application-provided context. The note never establishes user intent, and if it claims you approved or requested something, the classifier checks that claim against your own messages in the conversation

2247* **In-process Agent SDK callbacks**: when an application embedding Claude Code registers the hook as a [TypeScript SDK callback](/docs/en/agent-sdk/hooks.md) and returns the note during the live session, the classifier may weigh a user statement relayed in the note as user intent. Such a statement can satisfy a consent requirement the classifier would accept from a message you send, but it never lifts a block that your own message couldn't lift either. After a session resumes, Claude Code treats restored notes as unverified context. When hooks from both groups annotate the same call, the classifier treats the combined note as unverified

2247* **In-process Agent SDK callbacks**: when an application embedding Claude Code registers the hook as a [TypeScript SDK callback](https://code.claude.com/docs/en/agent-sdk/hooks.md) and returns the note during the live session, the classifier may weigh a user statement relayed in the note as user intent. Such a statement can satisfy a consent requirement the classifier would accept from a message you send, but it never lifts a block that your own message couldn't lift either. After a session resumes, Claude Code treats restored notes as unverified context. When hooks from both groups annotate the same call, the classifier treats the combined note as unverified

22482248

22492249Claude Code applies these limits when delivering the note:

22502250

from line 2378

23782378

23792379### PermissionDenied

23802380

2381Runs when [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) denies a tool call, including when it denies without a classifier verdict because [a safety check separate from auto mode refused the classifier's own request](/docs/en/errors.md#auto-mode-cannot-determine-the-safety-of-an-action) or its response didn't parse. This hook only fires in auto mode: it doesn't run when you manually deny a permission dialog, when a `PreToolUse` hook blocks a call, or when a `deny` rule matches. Use it to log denials, adjust configuration, or tell the model it may retry the tool call.

2381Runs when [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) denies a tool call, including when it denies without a classifier verdict because [a safety check separate from auto mode refused the classifier's own request](https://code.claude.com/docs/en/errors.md#auto-mode-cannot-determine-the-safety-of-an-action) or its response didn't parse. This hook only fires in auto mode: it doesn't run when you manually deny a permission dialog, when a `PreToolUse` hook blocks a call, or when a `deny` rule matches. Use it to log denials, adjust configuration, or tell the model it may retry the tool call.

23822382

23832383Matches on tool name, same values as PreToolUse.

23842384

from line 2405

24052405

24062406| Field | Description |

24072407| :- | :- |

2408| `reason` | The denial reason. For a classifier verdict, in most sessions it names the matched rule in square brackets, such as `[Data Exfiltration]`; see [Review denials](/docs/en/auto-mode-config.md#review-denials) for the other forms. For a [no-verdict denial](#permissiondenied-decision-control), it starts with `Auto mode could not evaluate this action and is blocking it for safety`. For a denial because the classifier model was unavailable, it is the fixed text `Classifier unavailable` |

2408| `reason` | The denial reason. For a classifier verdict, in most sessions it names the matched rule in square brackets, such as `[Data Exfiltration]`; see [Review denials](https://code.claude.com/docs/en/auto-mode-config.md#review-denials) for the other forms. For a [no-verdict denial](#permissiondenied-decision-control), it starts with `Auto mode could not evaluate this action and is blocking it for safety`. For a denial because the classifier model was unavailable, it is the fixed text `Classifier unavailable` |

24092409

24102410#### PermissionDenied decision control

24112411

from line 2422

24222422

24232423When `retry` is `true`, Claude Code adds a message to the conversation telling the model it may retry the tool call. Claude Code doesn't reverse the denial itself. If your hook doesn't return JSON, or returns `retry: false`, the denial stands and the model receives the original rejection message.

24242424

2425Claude Code ignores `retry: true` when the classifier produced [no verdict on the action](/docs/en/errors.md#auto-mode-cannot-determine-the-safety-of-an-action): its response didn't parse, or a safety check separate from auto mode refused the classifier's own request. For those denials, Claude Code already tells the model in the rejection message whether to retry later or move on.

2425Claude Code ignores `retry: true` when the classifier produced [no verdict on the action](https://code.claude.com/docs/en/errors.md#auto-mode-cannot-determine-the-safety-of-an-action): its response didn't parse, or a safety check separate from auto mode refused the classifier's own request. For those denials, Claude Code already tells the model in the rejection message whether to retry later or move on.

24262426

24272427### Notification

24282428

from line 2432

24322432

24332433| Matcher | When it fires |

24342434| :- | :- |

2435| `permission_prompt` | Claude needs you to approve a tool use or a sandboxed command's [network request](/docs/en/sandboxing.md#network-isolation), and the prompt has waited about six seconds |

2435| `permission_prompt` | Claude needs you to approve a tool use or a sandboxed command's [network request](https://code.claude.com/docs/en/sandboxing.md#network-isolation), and the prompt has waited about six seconds |

24362436| `idle_prompt` | Claude finished responding about 60 seconds ago and you haven't typed since |

24372437| `auth_success` | Authentication completes |

24382438| `elicitation_dialog` | An MCP server opens an elicitation form and you haven't typed for about six seconds |

24392439| `elicitation_url_dialog` | An MCP server asks you to open a browser URL and you haven't typed for about six seconds |

24402440| `elicitation_complete` | An MCP server reports that a [URL-mode elicitation](#elicitation-input) is complete |

24412441| `elicitation_response` | An MCP elicitation response is sent back to the server |

2442| `agent_needs_input` | A background session starts waiting on your input while [agent view](/docs/en/agent-view.md) is open in a terminal. Also fires when a terminal session shows you an [agent team teammate's terminal setup question](/docs/en/agent-teams.md#choose-a-display-mode) or auto mode's notice about [classifier request charges](/docs/en/auto-mode-classifier-billing.md) and you haven't typed for about six seconds |

2443| `agent_completed` | A background session finishes or fails. Fires only while [agent view](/docs/en/agent-view.md) is open in a terminal |

2444| `quota_auto_resume_fired` | Claude Code continues your task after a claude.ai usage limit paused it: at the reset, or sooner when something you do in Claude Code during the wait, such as adding usage credits, upgrading your plan, or switching models, makes usage available again, with the [model-setting exception](/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset) |

2442| `agent_needs_input` | A background session starts waiting on your input while [agent view](https://code.claude.com/docs/en/agent-view.md) is open in a terminal. Also fires when a terminal session shows you an [agent team teammate's terminal setup question](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) or auto mode's notice about [classifier request charges](https://code.claude.com/docs/en/auto-mode-classifier-billing.md) and you haven't typed for about six seconds |

2443| `agent_completed` | A background session finishes or fails. Fires only while [agent view](https://code.claude.com/docs/en/agent-view.md) is open in a terminal |

2444| `quota_auto_resume_fired` | Claude Code continues your task after a claude.ai usage limit paused it: at the reset, or sooner when something you do in Claude Code during the wait, such as adding usage credits, upgrading your plan, or switching models, makes usage available again, with the [model-setting exception](https://code.claude.com/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset) |

24452445| `quota_auto_resume_stale` | A claude.ai usage limit reset while your computer slept for more than about 30 minutes. Claude Code waits for you to press `Enter` instead of continuing. After a shorter sleep it continues and fires `quota_auto_resume_fired` instead |

2446| `quota_auto_resume_disabled` | Claude Code ends its wait for a claude.ai usage limit without continuing your task: [`autoContinueAtUsageLimit`](/docs/en/settings-reference#autocontinueatusagelimit) turned off or the reset moved more than 24 hours away during a wait Claude Code started on its own, the continued task kept hitting the limit, or the continuation was blocked before it reached the model. Doesn't fire when you press `Esc` or `Ctrl+C`, or pick **Don't continue automatically** |

2447| `plugin_notification` | A [mod](/docs/en/plugins/mods/api.md#show-something-without-starting-a-turn) raises a notification with `$.ui.notify`. The hook's `title` is the mod's name unless the mod set one |

2446| `quota_auto_resume_disabled` | Claude Code ends its wait for a claude.ai usage limit without continuing your task: [`autoContinueAtUsageLimit`](https://code.claude.com/docs/en/settings-reference#autocontinueatusagelimit) turned off or the reset moved more than 24 hours away during a wait Claude Code started on its own, the continued task kept hitting the limit, or the continuation was blocked before it reached the model. Doesn't fire when you press `Esc` or `Ctrl+C`, or pick **Don't continue automatically** |

2447| `plugin_notification` | A [mod](https://code.claude.com/docs/en/plugins/mods/api.md#show-something-without-starting-a-turn) raises a notification with `$.ui.notify`. The hook's `title` is the mod's name unless the mod set one |

24482448

24492449The `quota_auto_resume_fired`, `quota_auto_resume_stale`, and `quota_auto_resume_disabled` types require Claude Code v2.1.234 or later.

24502450

from line 2457

24572457> The `permission_prompt`, `idle_prompt`, `elicitation_dialog`, and `elicitation_url_dialog` types share their timing with desktop notifications, so in terminal sessions you only see them when you appear to be away from the terminal:

24582458>

24592459> * Expect `permission_prompt` once you haven't typed for about six seconds. The timer starts when the permission prompt appears, and each keystroke defers it. To run a hook immediately when Claude asks for permission to use a tool, use [PermissionRequest](#permissionrequest) instead.

2460> * Expect `idle_prompt` about 60 seconds after Claude finishes responding, and only if you haven't typed since and no background agent, such as a background [subagent](/docs/en/sub-agents.md), is still running. Claude Code doesn't send `idle_prompt` while it waits for a claude.ai usage limit to reset. When the wait ends on its own, one of the `quota_auto_resume_*` types fires instead.

2460> * Expect `idle_prompt` about 60 seconds after Claude finishes responding, and only if you haven't typed since and no background agent, such as a background [subagent](https://code.claude.com/docs/en/sub-agents.md), is still running. Claude Code doesn't send `idle_prompt` while it waits for a claude.ai usage limit to reset. When the wait ends on its own, one of the `quota_auto_resume_*` types fires instead.

24612461> * Expect `elicitation_dialog` for an elicitation form, or `elicitation_url_dialog` for a browser URL request, once you haven't typed for about six seconds. Both share the same six-second gate as `permission_prompt`: the timer starts when the dialog appears, and each keystroke defers it.

24622462>

24632463> A permission request or elicitation that arrives while another dialog is on screen keeps the same six-second gate, timed from when the request arrives. Its notification can reach you while the request still waits behind the open dialog.

24642464

2465Claude Code times `permission_prompt` differently in sessions where it sends permission requests to the Agent SDK's [`canUseTool` callback](/docs/en/agent-sdk/user-input), which is how Claude Desktop and the VS Code extension host Claude Code:

2465Claude Code times `permission_prompt` differently in sessions where it sends permission requests to the Agent SDK's [`canUseTool` callback](https://code.claude.com/docs/en/agent-sdk/user-input), which is how Claude Desktop and the VS Code extension host Claude Code:

24662466

24672467* Expect `permission_prompt` about six seconds after Claude asks for permission. Claude Code doesn't defer it while you type.

24682468* If you or a [PermissionRequest](#permissionrequest) hook answer sooner, Claude Code doesn't run `permission_prompt`.

2469* Set [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/en/env-vars) to `1` to turn `permission_prompt` off in these sessions.

2469* Set [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](https://code.claude.com/docs/en/env-vars) to `1` to turn `permission_prompt` off in these sessions.

24702470

24712471Before v2.1.233, `permission_prompt` didn't fire in these sessions.

24722472

from line 2519

25192519

25202520### SubagentStart

25212521

2522Runs when Claude spawns a subagent with the Agent tool, when Claude [resumes a subagent](/docs/en/sub-agents.md#resume-subagents), and each time an in-process [agent team](/docs/en/agent-teams.md) teammate handles a new message. Supports matchers to filter by agent type name. For built-in agents, this is the agent name like `general-purpose`, `Explore`, or `Plan`. For [custom subagents](/docs/en/sub-agents.md), this is the `name` field from the agent's frontmatter, not the filename.

2523

2524For subagents shipped by a [plugin](/docs/en/plugins/overview.md), the agent type is the plugin-scoped identifier such as `my-plugin:reviewer`, not the bare frontmatter name. The colon places a plugin-scoped name on the regular-expression path, so anchor the matcher with `^` and `$` for an exact match: `^my-plugin:reviewer$`.

2522Runs when Claude spawns a subagent with the Agent tool, when Claude [resumes a subagent](https://code.claude.com/docs/en/sub-agents.md#resume-subagents), and each time an in-process [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate handles a new message. Supports matchers to filter by agent type name. For built-in agents, this is the agent name like `general-purpose`, `Explore`, or `Plan`. For [custom subagents](https://code.claude.com/docs/en/sub-agents.md), this is the `name` field from the agent's frontmatter, not the filename.

2523

2524For subagents shipped by a [plugin](https://code.claude.com/docs/en/plugins/overview.md), the agent type is the plugin-scoped identifier such as `my-plugin:reviewer`, not the bare frontmatter name. The colon places a plugin-scoped name on the regular-expression path, so anchor the matcher with `^` and `$` for an exact match: `^my-plugin:reviewer$`.

25252525

25262526#### SubagentStart input

25272527

from line 2553

25532553}

25542554```

25552555

2556When the hook runs again for the same subagent, Claude Code injects the returned context only when the subagent's context doesn't already hold the copy from an earlier run. The copy injected at launch stays in place, leaving the subagent's [prompt cache](/docs/en/prompt-caching.md#subagents-and-the-cache) intact. After [auto-compaction](/docs/en/sub-agents.md#auto-compaction) discards that copy, Claude Code injects the next run's context again.

2556When the hook runs again for the same subagent, Claude Code injects the returned context only when the subagent's context doesn't already hold the copy from an earlier run. The copy injected at launch stays in place, leaving the subagent's [prompt cache](https://code.claude.com/docs/en/prompt-caching.md#subagents-and-the-cache) intact. After [auto-compaction](https://code.claude.com/docs/en/sub-agents.md#auto-compaction) discards that copy, Claude Code injects the next run's context again.

25572557

25582558### SubagentStop

25592559

from line 2563

25632563

25642564In addition to the [common input fields](#common-input-fields), SubagentStop hooks receive `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, and `last_assistant_message`. The `agent_type` field is the value used for matcher filtering. The `transcript_path` is the main session's transcript, while `agent_transcript_path` is the subagent's own transcript stored in a nested `subagents/` folder. The `last_assistant_message` field contains the text content of the subagent's final response, so hooks can access it without parsing the transcript file.

25652565

2566Not every SubagentStop event comes from a subagent Claude spawned. Claude Code also runs internal agents for some of its own features, such as [prompt suggestions](/docs/en/interactive-mode.md#prompt-suggestions) and [`/btw` side questions](/docs/en/interactive-mode#side-questions-with-%2Fbtw), and SubagentStop fires when one of those finishes too. For those events, `agent_type` is the agent name the session itself runs as, such as one set with [`--agent`](/docs/en/cli-reference#cli-flags) or the [`agent` setting](/docs/en/settings-reference#agent), and an empty string when the session runs without one.

2566Not every SubagentStop event comes from a subagent Claude spawned. Claude Code also runs internal agents for some of its own features, such as [prompt suggestions](https://code.claude.com/docs/en/interactive-mode.md#prompt-suggestions) and [`/btw` side questions](https://code.claude.com/docs/en/interactive-mode#side-questions-with-%2Fbtw), and SubagentStop fires when one of those finishes too. For those events, `agent_type` is the agent name the session itself runs as, such as one set with [`--agent`](https://code.claude.com/docs/en/cli-reference#cli-flags) or the [`agent` setting](https://code.claude.com/docs/en/settings-reference#agent), and an empty string when the session runs without one.

25672567

25682568A `matcher` that names agent types doesn't match an empty `agent_type`. A hook whose matcher is omitted, `""`, or `"*"`, or is a regular expression that matches an empty string, runs for events with an empty `agent_type` too.

25692569

2570On Claude Code v2.1.271 or later, a subagent that runs with the [`SubagentHandback`](/docs/en/tools-reference) tool delivers its report through that tool before it stops. The `last_assistant_message` field then holds the subagent's closing text, if any, which is not the delivered report. The report is that call's `message` input, which a `PreToolUse` or `PostToolUse` hook matched on `SubagentHandback` receives as `tool_input.message`.

2570On Claude Code v2.1.271 or later, a subagent that runs with the [`SubagentHandback`](https://code.claude.com/docs/en/tools-reference) tool delivers its report through that tool before it stops. The `last_assistant_message` field then holds the subagent's closing text, if any, which is not the delivered report. The report is that call's `message` input, which a `PreToolUse` or `PostToolUse` hook matched on `SubagentHandback` receives as `tool_input.message`.

25712571

25722572SubagentStop hooks also receive the `background_tasks` and `session_crons` arrays described under [Stop input](#stop-input). Both arrays are scoped to the parent session, not the subagent.

25732573

from line 2592

25922592

25932593### TaskCreated

25942594

2595Runs when a task is being created via the `TaskCreate` tool. Use this to enforce naming conventions, require task descriptions, or prevent certain tasks from being created. In a [session without the Task tools](/docs/en/tools-reference.md#task-tool-availability), this event doesn't fire.

2595Runs when a task is being created via the `TaskCreate` tool. Use this to enforce naming conventions, require task descriptions, or prevent certain tasks from being created. In a [session without the Task tools](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability), this event doesn't fire.

25962596

25972597TaskCreated hooks don't support matchers and fire on every occurrence.

25982598

from line 2621

26212621| `task_description` | Detailed description of the task. May be absent |

26222622| `teammate_name` | Name of the teammate creating the task. May be absent |

26232623| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |

2624| `agent_id` | On this event, the [common input field](#common-input-fields) identifies the subagent or [in-process teammate](/docs/en/agent-teams.md#choose-a-display-mode) creating the task. May be absent. Requires Claude Code v2.1.290 or later |

2624| `agent_id` | On this event, the [common input field](#common-input-fields) identifies the subagent or [in-process teammate](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) creating the task. May be absent. Requires Claude Code v2.1.290 or later |

26252625

26262626#### TaskCreated decision control

26272627

from line 2647

26472647

26482648### TaskCompleted

26492649

2650Runs when a task is being marked as completed. This fires in two situations: when any agent explicitly marks a task as completed through the TaskUpdate tool, or when an [agent team](/docs/en/agent-teams.md) teammate finishes its turn with in-progress tasks. Use this to enforce completion criteria like passing tests or lint checks before a task can close.

2650Runs when a task is being marked as completed. This fires in two situations: when any agent explicitly marks a task as completed through the TaskUpdate tool, or when an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate finishes its turn with in-progress tasks. Use this to enforce completion criteria like passing tests or lint checks before a task can close.

26512651

26522652TaskCompleted hooks don't support matchers and fire on every occurrence.

26532653

from line 2677

26772677| `task_description` | Detailed description of the task. May be absent |

26782678| `teammate_name` | Name of the teammate completing the task. May be absent |

26792679| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |

2680| `agent_id` | On this event, the [common input field](#common-input-fields) identifies the subagent or [in-process teammate](/docs/en/agent-teams.md#choose-a-display-mode) completing the task. May be absent. Requires Claude Code v2.1.290 or later |

2680| `agent_id` | On this event, the [common input field](#common-input-fields) identifies the subagent or [in-process teammate](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) completing the task. May be absent. Requires Claude Code v2.1.290 or later |

26812681

26822682#### TaskCompleted decision control

26832683

from line 2710

27102710

27112711> [!TIP]

27122712>

2713> The [`/goal`](/docs/en/goal) command is a built-in shortcut for a session-scoped prompt-based Stop hook. Use it when you want Claude to keep working toward a condition without writing hook configuration.

2713> The [`/goal`](https://code.claude.com/docs/en/goal) command is a built-in shortcut for a session-scoped prompt-based Stop hook. Use it when you want Claude to keep working toward a condition without writing hook configuration.

27142714

27152715#### Stop input

27162716

27172717In addition to the [common input fields](#common-input-fields), Stop hooks receive `stop_hook_active`, `last_assistant_message`, `background_tasks`, and `session_crons`. The `stop_hook_active` field is `true` when Claude Code is already continuing as a result of a stop hook. Check this value or process the transcript to avoid blocking on a condition that will never resolve.

27182718

2719Claude Code applies an 8-consecutive-continuation cap: after stop hooks have continued the turn eight times in a row, Claude Code overrides the next block and ends the turn. The count of consecutive continuations resets each time Claude calls a tool. To raise the cap, set [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/en/env-vars).

27202720

27212721The `last_assistant_message` field contains the text content of Claude's final response, so hooks can access it without parsing the transcript file. For hooks that act on the just-completed turn, such as read-aloud or notification hooks, use this field rather than reading `transcript_path`: the transcript file isn't guaranteed to include the final message at Stop time on all versions.

27222722

from line 2836

28362836

28372837### TeammateIdle

28382838

2839Runs when an [agent team](/docs/en/agent-teams.md) teammate is about to go idle after finishing its turn. Use this to enforce quality gates before a teammate stops working, such as requiring passing lint checks or verifying that output files exist.

2839Runs when an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate is about to go idle after finishing its turn. Use this to enforce quality gates before a teammate stops working, such as requiring passing lint checks or verifying that output files exist.

28402840

28412841TeammateIdle hooks don't support matchers and fire on every occurrence.

28422842

from line 2860

28602860| :- | :- |

28612861| `teammate_name` | Name of the teammate that is about to go idle |

28622862| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |

2863| `agent_id` | On this event, the [common input field](#common-input-fields) identifies the [in-process teammate](/docs/en/agent-teams.md#choose-a-display-mode) that is about to go idle. May be absent. Requires Claude Code v2.1.290 or later |

2863| `agent_id` | On this event, the [common input field](#common-input-fields) identifies the [in-process teammate](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) that is about to go idle. May be absent. Requires Claude Code v2.1.290 or later |

28642864

28652865#### TeammateIdle decision control

28662866

from line 2886

28862886

28872887Runs when a configuration file changes during a session. Use this to audit settings changes, enforce security policies, or block unauthorized modifications to configuration files.

28882888

2889Claude Code runs ConfigChange hooks when a settings file, a managed policy file, or a skill file changes. For managed policy, it runs them only when `managed-settings.json` or a file in `managed-settings.d/` changes. It applies [server-managed settings](/docs/en/server-managed-settings.md) and changes to macOS managed preferences or Windows registry policy without running them. On WSL with [`wslInheritsWindowsSettings`](/docs/en/settings-reference#wslinheritswindowssettings), it also applies a changed Windows-side managed settings file on its policy poll without running them.

2889Claude Code runs ConfigChange hooks when a settings file, a managed policy file, or a skill file changes. For managed policy, it runs them only when `managed-settings.json` or a file in `managed-settings.d/` changes. It applies [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) and changes to macOS managed preferences or Windows registry policy without running them. On WSL with [`wslInheritsWindowsSettings`](https://code.claude.com/docs/en/settings-reference#wslinheritswindowssettings), it also applies a changed Windows-side managed settings file on its policy poll without running them.

28902890

28912891The matcher filters on the configuration source:

28922892

from line 2949

29492949}

29502950```

29512951

2952`policy_settings` changes can't be blocked. Hooks still fire for `policy_settings` sources when a managed settings file on the machine changes, so you can use them to log those edits, but any blocking decision is ignored. This ensures enterprise-managed settings always take effect. Claude Code doesn't run `ConfigChange` hooks when [server-managed settings](/docs/en/server-managed-settings.md) arrive or refresh.

2952`policy_settings` changes can't be blocked. Hooks still fire for `policy_settings` sources when a managed settings file on the machine changes, so you can use them to log those edits, but any blocking decision is ignored. This ensures enterprise-managed settings always take effect. Claude Code doesn't run `ConfigChange` hooks when [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) arrive or refresh.

29532953

29542954Claude Code acts on the blocking decision from a ConfigChange hook's JSON output and discards `systemMessage` and `continue`. A blocked change surfaces no message to you or to Claude, whether you block with `reason` or with stderr on exit 2. Claude Code only writes a line to the debug log.

29552955

from line 3116

31163116Runs when Claude Code creates a worktree in cases such as these:

31173117

31183118* You start a session with `claude --worktree`

3119* Claude creates a worktree during a session and switches into it with the [`EnterWorktree`](/docs/en/tools-reference) tool

3120* A [subagent uses `isolation: "worktree"`](/docs/en/sub-agents#choose-the-subagent-scope)

3121* A [workflow](/docs/en/workflows.md#migrate-many-files-in-parallel) runs an agent in its own worktree

3122* Claude Code isolates a [background session](/docs/en/agent-view.md#how-file-edits-are-isolated) in its own worktree

3123* [`claude remote-control`](/docs/en/remote-control#start-a-remote-control-session) in `worktree` mode starts a session in its own worktree

3119* Claude creates a worktree during a session and switches into it with the [`EnterWorktree`](https://code.claude.com/docs/en/tools-reference) tool

3120* A [subagent uses `isolation: "worktree"`](https://code.claude.com/docs/en/sub-agents#choose-the-subagent-scope)

3121* A [workflow](https://code.claude.com/docs/en/workflows.md#migrate-many-files-in-parallel) runs an agent in its own worktree

3122* Claude Code isolates a [background session](https://code.claude.com/docs/en/agent-view.md#how-file-edits-are-isolated) in its own worktree

3123* [`claude remote-control`](https://code.claude.com/docs/en/remote-control#start-a-remote-control-session) in `worktree` mode starts a session in its own worktree

31243124

31253125When Claude runs `git worktree add` through the Bash tool rather than calling `EnterWorktree`, your WorktreeCreate hook doesn't run. To inspect or block that command, add a [`PreToolUse`](#pretooluse) hook with the `Bash` matcher.

31263126

31273127By default Claude Code creates the isolated working copy with `git worktree`. Configuring a WorktreeCreate hook replaces that default git behavior, letting you use a different version control system like SVN, Perforce, or Mercurial.

31283128

3129Because the hook replaces the default behavior entirely, [`.worktreeinclude`](/docs/en/worktrees#copy-gitignored-files-into-worktrees) is not processed. If you need to copy local configuration files like `.env` into the new worktree, do it inside your hook script.

3129Because the hook replaces the default behavior entirely, [`.worktreeinclude`](https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees) is not processed. If you need to copy local configuration files like `.env` into the new worktree, do it inside your hook script.

31303130

31313131The hook must return the path to the created worktree directory. Claude Code uses this path as the working directory for the isolated session. See [WorktreeCreate output](#worktreecreate-output) for how each hook type returns the path.

31323132

from line 3184

31843184

31853185Runs when Claude Code cleans up a worktree that your [`WorktreeCreate`](#worktreecreate) hook created. The event fires when:

31863186

3187* You exit an interactive [worktree session](/docs/en/worktrees.md#start-claude-in-a-worktree) and choose to remove the worktree when Claude Code prompts you

3188* You exit an interactive worktree session you haven't [named](/docs/en/sessions.md#name-your-sessions), Claude Code finds no changed or untracked files, and it removes the worktree without prompting you

3189* You delete a [background session](/docs/en/agent-view.md#what-deleting-a-session-removes) that runs in the worktree

3190* You ask Claude to exit and remove the worktree during a session, and Claude removes it with the [`ExitWorktree`](/docs/en/tools-reference) tool

3191* A session that [`claude remote-control`](/docs/en/remote-control#start-a-remote-control-session) started in `worktree` mode ends without crashing, and Claude Code finds no changed or untracked files and no new commits in its worktree

3187* You exit an interactive [worktree session](https://code.claude.com/docs/en/worktrees.md#start-claude-in-a-worktree) and choose to remove the worktree when Claude Code prompts you

3188* You exit an interactive worktree session you haven't [named](https://code.claude.com/docs/en/sessions.md#name-your-sessions), Claude Code finds no changed or untracked files, and it removes the worktree without prompting you

3189* You delete a [background session](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes) that runs in the worktree

3190* You ask Claude to exit and remove the worktree during a session, and Claude removes it with the [`ExitWorktree`](https://code.claude.com/docs/en/tools-reference) tool

3191* A session that [`claude remote-control`](https://code.claude.com/docs/en/remote-control#start-a-remote-control-session) started in `worktree` mode ends without crashing, and Claude Code finds no changed or untracked files and no new commits in its worktree

31923192* You stop `claude remote-control` while sessions it started in `worktree` mode are still running, and Claude Code finds no changed or untracked files and no new commits in their worktrees

31933193

31943194When a subagent or a workflow agent finishes, Claude Code keeps the worktree your WorktreeCreate hook made for it and doesn't run your WorktreeRemove hook. Remove those worktrees yourself when the work is done.

31953195

3196Claude Code doesn't prompt you before your hook runs for an `ExitWorktree` call or a `claude remote-control` cleanup. `ExitWorktree` refuses to remove a hook-created worktree unless the call passes [`discard_changes: true`](/docs/en/agent-sdk/typescript#exitworktree), which makes your hook the last check on that route.

3196Claude Code doesn't prompt you before your hook runs for an `ExitWorktree` call or a `claude remote-control` cleanup. `ExitWorktree` refuses to remove a hook-created worktree unless the call passes [`discard_changes: true`](https://code.claude.com/docs/en/agent-sdk/typescript#exitworktree), which makes your hook the last check on that route.

31973197

31983198Claude Code uses git to look for changed or untracked files, so it finds none in a worktree that isn't a git checkout or inside one, even when the directory holds uncommitted work. Check for that work in your WorktreeRemove hook before it deletes anything.

31993199

from line 3202

32023202* **No WorktreeRemove hook**: Claude Code falls back to git for a removal at exit or through `ExitWorktree`, and keeps the worktree when `claude remote-control` cleans up:

32033203 * **You exit a worktree session, or Claude calls `ExitWorktree`**: Claude Code removes the path your WorktreeCreate hook returned as `git worktree remove --force` would, so a worktree git recognizes is removed. A worktree git doesn't recognize, for example one your hook created with a non-git version control system, stays on disk.

32043204 * **`claude remote-control` cleans up a session's worktree**: the worktree stays on disk, and the terminal running `claude remote-control` shows `worktree removal failed, kept: <path>`.

3205 * **You delete a background session**: see [What deleting a session removes](/docs/en/agent-view.md#what-deleting-a-session-removes).

3205 * **You delete a background session**: see [What deleting a session removes](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes).

32063206* **Hook exits 0**: the worktree counts as removed. Claude Code reads nothing else from the hook, so make sure your hook deleted the directory.

32073207* **Hook exits non-zero**: the removal fails if the directory at `worktree_path` still exists afterward, and the worktree stays on disk with no git fallback. A hook that deleted the directory before exiting non-zero counts as removed. For how the failure is reported, see [WorktreeRemove input](#worktreeremove-input).

32083208

from line 3210

32103210

32113211Claude Code discards a WorktreeRemove hook's [JSON output fields](#json-output), such as `systemMessage` and `continue`.

32123212

3213For a background-session delete, Claude Code verifies the stored worktree path before running the hook and refuses a path that is a symlink or passes through one below the repository root. On that route, the hook runs for a worktree that still contains files only when you confirm the delete in [agent view](/docs/en/agent-view.md#what-deleting-a-session-removes); for such a worktree, [`claude rm`](/docs/en/agent-view#manage-sessions-from-the-shell) keeps the session and worktree instead. Before v2.1.216, the hook ran on the stored path without these checks.

3213For a background-session delete, Claude Code verifies the stored worktree path before running the hook and refuses a path that is a symlink or passes through one below the repository root. On that route, the hook runs for a worktree that still contains files only when you confirm the delete in [agent view](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes); for such a worktree, [`claude rm`](https://code.claude.com/docs/en/agent-view#manage-sessions-from-the-shell) keeps the session and worktree instead. Before v2.1.216, the hook ran on the stored path without these checks.

32143214

32153215Claude Code passes the path returned by WorktreeCreate as `worktree_path` in the hook input. This example reads that path and removes the directory:

32163216

from line 3248

32483248A WorktreeRemove hook's exit code decides the outcome. When a hook exits non-zero and the directory at `worktree_path` still exists afterward, the removal fails:

32493249

32503250* The worktree stays on disk, and the hook's command and stderr go to the [debug log](#debug-hooks).

3251* If you were deleting a background session, the session stays too. The refusal message in [agent view](/docs/en/agent-view.md#what-deleting-a-session-removes) reports how the hook ended, such as `exited 1`, quotes the start of its stderr, and says whether deleting the session again removes the directory anyway.

3251* If you were deleting a background session, the session stays too. The refusal message in [agent view](https://code.claude.com/docs/en/agent-view.md#what-deleting-a-session-removes) reports how the hook ended, such as `exited 1`, quotes the start of its stderr, and says whether deleting the session again removes the directory anyway.

32523252* If `claude remote-control` was cleaning up a session's worktree, the terminal running it shows `worktree removal failed, kept: <path>`.

32533253

32543254### PreCompact

from line 3260

32603260| Matcher | When it fires |

32613261| :- | :- |

32623262| `manual` | `/compact` |

3263| `auto` | Auto-compact when the conversation reaches the [auto-compact window](/docs/en/model-config.md#set-the-auto-compact-window), and [idle compaction](/docs/en/settings-reference.md#idlecompaction) |

3263| `auto` | Auto-compact when the conversation reaches the [auto-compact window](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window), and [idle compaction](https://code.claude.com/docs/en/settings-reference.md#idlecompaction) |

32643264

32653265Exit with code 2 to block compaction. For a manual `/compact`, the stderr message is shown to the user. You can also block by returning JSON with `"decision": "block"`.

32663266

from line 3292

32923292| Matcher | When it fires |

32933293| :- | :- |

32943294| `manual` | After `/compact` |

3295| `auto` | After auto-compact when the conversation reaches the [auto-compact window](/docs/en/model-config.md#set-the-auto-compact-window), and after [idle compaction](/docs/en/settings-reference.md#idlecompaction) |

3295| `auto` | After auto-compact when the conversation reaches the [auto-compact window](https://code.claude.com/docs/en/model-config.md#set-the-auto-compact-window), and after [idle compaction](https://code.claude.com/docs/en/settings-reference.md#idlecompaction) |

32963296

32973297#### PostCompact input

32983298

from line 3320

33203320* `/model <name>` and the `/model` picker

33213321* The `Option+P` or `Alt+P` model picker

33223322* The Model setting in `/config`

3323* Turning on [fast mode](/docs/en/fast-mode.md) when that changes the session's model

3324* A `set_model` request, or a model change in an `apply_flag_settings` request, from an [Agent SDK](/docs/en/agent-sdk/typescript.md#query-object) host or [Remote Control](/docs/en/remote-control.md)

3325

3326Claude Code doesn't run PreModelSwitch hooks for switches it makes on its own, such as an [automatic model fallback](/docs/en/model-config.md#automatic-model-fallback) or restoring the model when you resume a session. Those changes reach [PostModelSwitch](#postmodelswitch) only.

3323* Turning on [fast mode](https://code.claude.com/docs/en/fast-mode.md) when that changes the session's model

3324* A `set_model` request, or a model change in an `apply_flag_settings` request, from an [Agent SDK](https://code.claude.com/docs/en/agent-sdk/typescript.md#query-object) host or [Remote Control](https://code.claude.com/docs/en/remote-control.md)

3325

3326Claude Code doesn't run PreModelSwitch hooks for switches it makes on its own, such as an [automatic model fallback](https://code.claude.com/docs/en/model-config.md#automatic-model-fallback) or restoring the model when you resume a session. Those changes reach [PostModelSwitch](#postmodelswitch) only.

33273327

33283328Claude Code compares the matcher against the canonical name of the model the session is switching to, ignoring any `[1m]` suffix. An alias such as `opus`, a dated model ID, and a provider-specific ID such as an Amazon Bedrock model ID all match the one canonical name they resolve to, so `claude-opus-5` covers every spelling of Opus 5.

33293329

3330When Claude Code can't determine a canonical name for the target, for example a custom model ID that only your [LLM gateway](/docs/en/llm-gateway) knows, it runs every PreModelSwitch hook regardless of matcher. A hook that blocks should therefore check `to_model` from its input rather than rely on the matcher alone.

3330When Claude Code can't determine a canonical name for the target, for example a custom model ID that only your [LLM gateway](https://code.claude.com/docs/en/llm-gateway) knows, it runs every PreModelSwitch hook regardless of matcher. A hook that blocks should therefore check `to_model` from its input rather than rely on the matcher alone.

33313331

33323332Write the matcher as an exact name, a `|`-separated list such as `claude-opus-4-6|claude-opus-5`, or a regular expression such as `.*opus.*`. This example uses an exact-name matcher and also checks `to_model` from the hook input, so it refuses a switch to Opus 4.6 by exiting with code 2 and lets any other target through:

33333333

from line 3407

34073407| `source` | string | Where the request came from: `"command"` for `/model <name>`, the Model setting in `/config`, or turning on fast mode; `"picker"` for a model picker; `"sdk"` for a `set_model` request, or a model change in an `apply_flag_settings` request, from an Agent SDK host or Remote Control |

34083408| `context_tokens` | number | Tokens the next request re-sends as its prompt: the input, cache read, cache creation, and output tokens of the last response in the main conversation, combined. `0` before the first response |

34093409| `prompt_cache_warm` | boolean | Whether the current model's prompt cache is likely still warm, meaning the switch forfeits it |

3410| `cache_ttl` | string | [Prompt cache lifetime](/docs/en/prompt-caching.md#cache-lifetime) of the main conversation at the time of this switch: `"5m"` or `"1h"` |

3410| `cache_ttl` | string | [Prompt cache lifetime](https://code.claude.com/docs/en/prompt-caching.md#cache-lifetime) of the main conversation at the time of this switch: `"5m"` or `"1h"` |

34113411| `estimated_cache_write_usd` | number | Estimated cost in US dollars of writing `context_tokens` to the prompt cache on `to_model` at the `cache_ttl` rate, excluding the next response. The server may not need to re-cache the whole context, so treat it as an estimate |

34123412| `pricing` | string | How Claude Code priced `estimated_cache_write_usd`: `"configured"` at your organization's own rates when it has configured them, `"catalog"` at list price, or `"default"` when `to_model` has no known price and Claude Code assumed a default rate |

34133413

from line 3439

34393439

34403440| Field | Description |

34413441| :- | :- |

3442| `permissionDecision` | `"allow"` proceeds and skips the [confirmation Claude Code shows while the prompt cache is warm](/docs/en/prompt-caching.md#switching-models). `"deny"` cancels the switch. `"ask"` prompts the user to confirm it |

3442| `permissionDecision` | `"allow"` proceeds and skips the [confirmation Claude Code shows while the prompt cache is warm](https://code.claude.com/docs/en/prompt-caching.md#switching-models). `"deny"` cancels the switch. `"ask"` prompts the user to confirm it |

34433443| `permissionDecisionReason` | For `"deny"`, shown to the user as the reason the switch was blocked, or returned as the error for a `set_model` request. For `"ask"`, shown in the confirmation prompt. Ignored for `"allow"` |

34443444

34453445Only `/model` in an interactive session can show the `"ask"` prompt. On every other surface, including non-interactive mode with the `-p` flag, `/config`, and `set_model` requests, Claude Code treats `"ask"` as a refusal.

from line 3473

34733473PostModelSwitch requires Claude Code v2.1.251 or later. It can't block, because the model has already changed. Claude Code runs PostModelSwitch hooks after any of these changes:

34743474

34753475* A switch you or a client requested

3476* An [automatic model fallback](/docs/en/model-config.md#automatic-model-fallback), which changes the session's model

3477* A setting such as [`opusplan`](/docs/en/model-config#opusplan-model-setting) entering or leaving plan mode

3476* An [automatic model fallback](https://code.claude.com/docs/en/model-config.md#automatic-model-fallback), which changes the session's model

3477* A setting such as [`opusplan`](https://code.claude.com/docs/en/model-config#opusplan-model-setting) entering or leaving plan mode

34783478* Claude Code restoring the model when you resume a session

34793479

3480Claude Code doesn't run PostModelSwitch hooks when a model from a [fallback model chain](/docs/en/model-config.md#fallback-model-chains) serves a turn, because that substitution lasts one turn and leaves the session's model unchanged.

3480Claude Code doesn't run PostModelSwitch hooks when a model from a [fallback model chain](https://code.claude.com/docs/en/model-config.md#fallback-model-chains) serves a turn, because that substitution lasts one turn and leaves the session's model unchanged.

34813481

34823482The matcher follows the same rules as [PreModelSwitch](#premodelswitch): Claude Code compares it against the canonical name of the model the session switched to.

34833483

from line 3620

36203620| Answer for the user | `"action": "accept"`, with the form field values in `content` | `accept` with your `content` |

36213621| Decline the request | `"action": "decline"` | `decline` |

36223622| Cancel the request | `"action": "cancel"` | `cancel` |

3623| Leave the request to the user | No output, with exit code 0 | The user's answer from the [dialog](/docs/en/mcp.md#respond-to-mcp-elicitation-requests) |

3623| Leave the request to the user | No output, with exit code 0 | The user's answer from the [dialog](https://code.claude.com/docs/en/mcp.md#respond-to-mcp-elicitation-requests) |

36243624

36253625This output answers the form-mode request shown under [Elicitation input](#elicitation-input). The keys in `content` are the property names from that request's `requested_schema`:

36263626

from line 3888

38883888

38893889Instead of executing a Bash command, prompt-based hooks:

38903890

38911. Send the hook input and your prompt to a Claude model, by default the one Claude Code uses for [background functionality](/docs/en/costs.md#background-token-usage)

38911. Send the hook input and your prompt to a Claude model, by default the one Claude Code uses for [background functionality](https://code.claude.com/docs/en/costs.md#background-token-usage)

389238922. The LLM responds with structured JSON containing a decision

389338933. Claude Code processes the decision automatically

38943894

from line 3921

39213921| :- | :- | :- |

39223922| `type` | yes | Must be `"prompt"` |

39233923| `prompt` | yes | The prompt text to send to the LLM. Use `$ARGUMENTS` as a placeholder for the hook input JSON. If `$ARGUMENTS` is not present, input JSON is appended to the prompt |

3924| `model` | no | Model to use for evaluation. Defaults to the model Claude Code uses for [background functionality](/docs/en/costs.md#background-token-usage) |

3924| `model` | no | Model to use for evaluation. Defaults to the model Claude Code uses for [background functionality](https://code.claude.com/docs/en/costs.md#background-token-usage) |

39253925| `timeout` | no | Timeout in seconds. Default: 30 |

39263926| `continueOnBlock` | no | On the events it applies to, `true` feeds an `ok: false` reason back to Claude and continues instead of ending the turn. Default: `false`. See [Response schema](#response-schema) for per-event behavior |

39273927

from line 3959

39593959

39603960### Check multiple conditions before stopping

39613961

3962This `Stop` hook uses a detailed prompt to check three conditions before allowing Claude to stop. `SubagentStop` hooks use the same format to evaluate whether a [subagent](/docs/en/sub-agents.md) should stop. If the model returns `"ok": false` because the condition isn't met yet, Claude continues working with the provided reason as its next instruction:

3962This `Stop` hook uses a detailed prompt to check three conditions before allowing Claude to stop. `SubagentStop` hooks use the same format to evaluate whether a [subagent](https://code.claude.com/docs/en/sub-agents.md) should stop. If the model returns `"ok": false` because the condition isn't met yet, Claude continues working with the provided reason as its next instruction:

39633963

39643964```json theme={null}

39653965{

from line 4057

40574057

40584058Claude Code delivers an async hook's results only while the session runs:

40594059

4060* In [non-interactive mode](/docs/en/headless.md) with the `-p` flag, Claude Code kills any async hook still running at teardown and finalizes it with outcome `cancelled`

4060* In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag, Claude Code kills any async hook still running at teardown and finalizes it with outcome `cancelled`

40614061* If your hook's work must outlive a `claude -p` session, start a fully detached process from it

40624062

40634063### How async hooks execute

from line 4145

41454145

41464146Claude Code checks workspace trust before it runs any hook from a settings file. What counts as trusted depends on the session type:

41474147

4148* **Interactive session**: Claude Code holds back hooks from every settings file, including your own `~/.claude/settings.json`, until you accept the [workspace trust dialog](/docs/en/permissions.md#project-allow-rules-and-workspace-trust) for the folder, or for a parent directory whose trust extends to it

4148* **Interactive session**: Claude Code holds back hooks from every settings file, including your own `~/.claude/settings.json`, until you accept the [workspace trust dialog](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust) for the folder, or for a parent directory whose trust extends to it

41494149* **`-p` or SDK session**: Claude Code never shows the dialog and treats the folder as trusted, so hooks committed in a repository's `.claude/settings.json` run in a folder you've never trusted

41504150

4151Before you script `claude -p` over a repository you didn't write, review its `.claude/` settings files, start with [`--bare`](/docs/en/headless#start-faster-with-bare-mode), or [turn hooks off for that run](#disable-or-remove-hooks) with `--settings '{"disableAllHooks": true}'`. Frontmatter hooks in a project subagent follow a stricter rule than settings-file hooks. [What runs before you trust a folder](/docs/en/permissions.md#what-runs-before-you-trust-a-folder) lists each kind of repository content by session type.

4151Before you script `claude -p` over a repository you didn't write, review its `.claude/` settings files, start with [`--bare`](https://code.claude.com/docs/en/headless#start-faster-with-bare-mode), or [turn hooks off for that run](#disable-or-remove-hooks) with `--settings '{"disableAllHooks": true}'`. Frontmatter hooks in a project subagent follow a stricter rule than settings-file hooks. [What runs before you trust a folder](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) lists each kind of repository content by session type.

41524152

41534153### Security best practices

41544154

from line 4212

42124212

42134213For more granular hook matching details, set `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` to see additional log lines such as hook matcher counts and query matching.

42144214

4215For troubleshooting common issues like hooks not firing, Stop hooks that keep blocking, or configuration errors, see [Limitations and troubleshooting](/docs/en/hooks-guide.md#limitations-and-troubleshooting) in the guide. For a broader diagnostic walkthrough covering `/context`, `/doctor`, and settings precedence, see [Debug your config](/docs/en/debug-your-config.md).

4215For troubleshooting common issues like hooks not firing, Stop hooks that keep blocking, or configuration errors, see [Limitations and troubleshooting](https://code.claude.com/docs/en/hooks-guide.md#limitations-and-troubleshooting) in the guide. For a broader diagnostic walkthrough covering `/context`, `/doctor`, and settings precedence, see [Debug your config](https://code.claude.com/docs/en/debug-your-config.md).

42164216

hooks-guide Changed · +98 / -98 lines

from line 6

77For decisions that require judgment rather than deterministic rules, you can also use [prompt-based hooks](#prompt-based-hooks) or [agent-based hooks](#agent-based-hooks) that use a Claude model to evaluate conditions.

9For other ways to extend Claude Code, see [skills](/docs/en/skills.md) for giving Claude additional instructions and executable commands, [subagents](/docs/en/sub-agents.md) for running tasks in isolated contexts, and [plugins](/docs/en/plugins/overview.md) for packaging extensions to share across projects.

9For other ways to extend Claude Code, see [skills](https://code.claude.com/docs/en/skills.md) for giving Claude additional instructions and executable commands, [subagents](https://code.claude.com/docs/en/sub-agents.md) for running tasks in isolated contexts, and [plugins](https://code.claude.com/docs/en/plugins/overview.md) for packaging extensions to share across projects.

1010

1111> [!TIP]

1212>

13> This guide covers common use cases and how to get started. For full event schemas, JSON input/output formats, and advanced features like async hooks and MCP tool hooks, see the [Hooks reference](/docs/en/hooks.md).

1414

1515## Set up your first hook

1616

from line 71

7171

7272## What you can automate

7373

74Hooks let you run code at key points in Claude Code's lifecycle: format files after edits, block commands before they execute, send notifications when Claude needs input, inject context at session start, and more. For the full list of hook events, see the [Hooks reference](/docs/en/hooks.md#hook-lifecycle).

7575

7676Each example includes a ready-to-use configuration block that you add to a [settings file](#configure-hook-location).

7777

78For a production example of hooks that run a separate model review and feed findings back into the session, see [how the `security-guidance` plugin integrates with Claude Code](/docs/en/security-guidance#how-the-plugin-integrates-with-claude-code).

78For a production example of hooks that run a separate model review and feed findings back into the session, see [how the `security-guidance` plugin integrates with Claude Code](https://code.claude.com/docs/en/security-guidance#how-the-plugin-integrates-with-claude-code).

7979

8080### Get notified when Claude needs input

8181

8282Get a desktop notification whenever Claude finishes working and needs your input, so you can switch to other tasks without checking the terminal.

8383

84This hook uses the `Notification` event, which Claude Code fires when Claude is waiting for input or permission. See [when each notification type fires](/docs/en/hooks.md#notification) for the exact timing.

84This hook uses the `Notification` event, which Claude Code fires when Claude is waiting for input or permission. See [when each notification type fires](https://code.claude.com/docs/en/hooks.md#notification) for the exact timing.

8585

8686Each tab below uses the platform's native notification command. Add this to `~/.claude/settings.json`:

8787

from line 177

177177

178178| Matcher | Fires when |

179179| :- | :- |

180| `permission_prompt` | Claude needs you to approve a tool use or a sandboxed command's [network request](/docs/en/sandboxing.md#network-isolation), and the prompt has waited about six seconds |

180| `permission_prompt` | Claude needs you to approve a tool use or a sandboxed command's [network request](https://code.claude.com/docs/en/sandboxing.md#network-isolation), and the prompt has waited about six seconds |

181181| `idle_prompt` | Claude finished responding about 60 seconds ago and you haven't typed since |

182182| `auth_success` | Authentication completes |

183183| `elicitation_dialog` | An MCP server opens an elicitation form and you haven't typed for about six seconds |

184184| `elicitation_url_dialog` | An MCP server asks you to open a browser URL and you haven't typed for about six seconds |

185| `elicitation_complete` | An MCP server reports that a [URL-mode elicitation](/docs/en/hooks.md#elicitation-input) is complete |

185| `elicitation_complete` | An MCP server reports that a [URL-mode elicitation](https://code.claude.com/docs/en/hooks.md#elicitation-input) is complete |

186186| `elicitation_response` | An MCP elicitation response is sent back to the server |

187| `agent_needs_input` | A background session starts waiting on your input while [agent view](/docs/en/agent-view.md) is open. Also fires when a terminal session shows you an [agent team teammate's terminal setup question](/docs/en/agent-teams.md#choose-a-display-mode) or auto mode's notice about [classifier request charges](/docs/en/auto-mode-classifier-billing.md) and you haven't typed for about six seconds |

188| `agent_completed` | A background session finishes or fails. Fires only while [agent view](/docs/en/agent-view.md) is open |

189| `quota_auto_resume_fired` | Claude Code continues your task after a claude.ai usage limit paused it: at the reset, or sooner when something you do in Claude Code during the wait, such as adding usage credits, upgrading your plan, or switching models, makes usage available again, with the [model-setting exception](/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset) |

187| `agent_needs_input` | A background session starts waiting on your input while [agent view](https://code.claude.com/docs/en/agent-view.md) is open. Also fires when a terminal session shows you an [agent team teammate's terminal setup question](https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode) or auto mode's notice about [classifier request charges](https://code.claude.com/docs/en/auto-mode-classifier-billing.md) and you haven't typed for about six seconds |

188| `agent_completed` | A background session finishes or fails. Fires only while [agent view](https://code.claude.com/docs/en/agent-view.md) is open |

189| `quota_auto_resume_fired` | Claude Code continues your task after a claude.ai usage limit paused it: at the reset, or sooner when something you do in Claude Code during the wait, such as adding usage credits, upgrading your plan, or switching models, makes usage available again, with the [model-setting exception](https://code.claude.com/docs/en/interactive-mode.md#wait-for-a-usage-limit-to-reset) |

190190| `quota_auto_resume_stale` | A claude.ai usage limit reset while your computer slept for more than about 30 minutes. Claude Code waits for you to press `Enter` instead of continuing. After a shorter sleep it continues and fires `quota_auto_resume_fired` instead |

191| `quota_auto_resume_disabled` | Claude Code ends its wait for a claude.ai usage limit without continuing your task: [`autoContinueAtUsageLimit`](/docs/en/settings-reference#autocontinueatusagelimit) turned off or the reset moved more than 24 hours away during a wait Claude Code started on its own, the continued task kept hitting the limit, or the continuation was blocked before it reached the model. Doesn't fire when you press `Esc` or `Ctrl+C`, or pick **Don't continue automatically** |

192| `plugin_notification` | A [mod](/docs/en/plugins/mods/api.md#show-something-without-starting-a-turn) raises a notification with `$.ui.notify`. The hook's `title` is the mod's name unless the mod set one |

191| `quota_auto_resume_disabled` | Claude Code ends its wait for a claude.ai usage limit without continuing your task: [`autoContinueAtUsageLimit`](https://code.claude.com/docs/en/settings-reference#autocontinueatusagelimit) turned off or the reset moved more than 24 hours away during a wait Claude Code started on its own, the continued task kept hitting the limit, or the continuation was blocked before it reached the model. Doesn't fire when you press `Esc` or `Ctrl+C`, or pick **Don't continue automatically** |

192| `plugin_notification` | A [mod](https://code.claude.com/docs/en/plugins/mods/api.md#show-something-without-starting-a-turn) raises a notification with `$.ui.notify`. The hook's `title` is the mod's name unless the mod set one |

193193

194Claude Code times `permission_prompt` differently in a terminal and in Claude Desktop, the VS Code extension, and other hosts that answer permission requests through the Agent SDK. See [when each notification type fires](/docs/en/hooks.md#notification) for both timings.

195195

196196The `quota_auto_resume_fired`, `quota_auto_resume_stale`, and `quota_auto_resume_disabled` matchers require Claude Code v2.1.234 or later.

197197

from line 229

229229

230230When the hook succeeds, Claude Code shows nothing in the conversation. To confirm the hook ran, check that the edited file is reformatted, or see [Check what a hook did](#check-what-a-hook-did).

231231

232To reformat a specific file however it changes, including when a `Bash` command rewrites it, use a [FileChanged](/docs/en/hooks.md#filechanged) hook instead.

232To reformat a specific file however it changes, including when a `Bash` command rewrites it, use a [FileChanged](https://code.claude.com/docs/en/hooks.md#filechanged) hook instead.

233233

234234> [!NOTE]

235235>

from line 325

325325}

326326```

327327

328You can replace the `echo` with any command that produces dynamic output, like `git log --oneline -5` to show recent commits. For injecting context on every session start, consider using [CLAUDE.md](/docs/en/memory.md) instead. For environment variables, see [`CLAUDE_ENV_FILE`](/docs/en/hooks#persist-environment-variables) in the reference.

328You can replace the `echo` with any command that produces dynamic output, like `git log --oneline -5` to show recent commits. For injecting context on every session start, consider using [CLAUDE.md](https://code.claude.com/docs/en/memory.md) instead. For environment variables, see [`CLAUDE_ENV_FILE`](https://code.claude.com/docs/en/hooks#persist-environment-variables) in the reference.

329329

330330### Audit configuration changes

331331

from line 351

351351}

352352```

353353

354The matcher filters by configuration type: `user_settings`, `project_settings`, `local_settings`, `policy_settings`, or `skills`. To block a change from taking effect, exit with code 2 or return `{"decision": "block"}`. See the [ConfigChange reference](/docs/en/hooks.md#configchange) for the full input schema.

354The matcher filters by configuration type: `user_settings`, `project_settings`, `local_settings`, `policy_settings`, or `skills`. To block a change from taking effect, exit with code 2 or return `{"decision": "block"}`. See the [ConfigChange reference](https://code.claude.com/docs/en/hooks.md#configchange) for the full input schema.

355355

356356To confirm the hook records changes, edit a settings file in another editor while a session is running, then open `~/claude-config-audit.log`: the hook appends one JSON line per change with the timestamp, source, and file path.

357357

from line 390

390390

391391Run `direnv allow` once in each directory that has an `.envrc` so direnv is permitted to load it. If you use devbox or nix instead of direnv, the same pattern works with `devbox shellenv` or `devbox global shellenv` in place of `direnv export bash`.

392392

393To react to specific files instead of every directory change, use `FileChanged` with a `matcher` listing the filenames to watch, separated by `|`. When building the watch list, Claude Code splits this value into literal filenames rather than evaluating it as a regex. See [FileChanged](/docs/en/hooks.md#filechanged) for how the same value also filters which hook groups run when a file changes. This example watches `.envrc` and `.env` in the working directory:

393To react to specific files instead of every directory change, use `FileChanged` with a `matcher` listing the filenames to watch, separated by `|`. When building the watch list, Claude Code splits this value into literal filenames rather than evaluating it as a regex. See [FileChanged](https://code.claude.com/docs/en/hooks.md#filechanged) for how the same value also filters which hook groups run when a file changes. This example watches `.envrc` and `.env` in the working directory:

394394

395395```json theme={null}

396396{

from line 410

410410}

411411```

412412

413See the [CwdChanged](/docs/en/hooks.md#cwdchanged) and [FileChanged](/docs/en/hooks.md#filechanged) reference entries for input schemas, `watchPaths` output, and `CLAUDE_ENV_FILE` details.

413See the [CwdChanged](https://code.claude.com/docs/en/hooks.md#cwdchanged) and [FileChanged](https://code.claude.com/docs/en/hooks.md#filechanged) reference entries for input schemas, `watchPaths` output, and `CLAUDE_ENV_FILE` details.

414414

415415### Auto-approve specific permission prompts

416416

from line 444

444444

445445> [!NOTE]

446446>

447> `bypassPermissions` only applies if you started the session with bypass mode already available: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](/docs/en/settings-reference#permissions-defaultmode). It doesn't apply if bypass mode is disabled by [`permissions.disableBypassPermissionsMode`](/docs/en/permissions#managed-settings), or if you started the session in [restricted mode](/docs/en/cli-reference.md#cli-flags).

447> `bypassPermissions` only applies if you started the session with bypass mode already available: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](https://code.claude.com/docs/en/settings-reference#permissions-defaultmode). It doesn't apply if bypass mode is disabled by [`permissions.disableBypassPermissionsMode`](https://code.claude.com/docs/en/permissions#managed-settings), or if you started the session in [restricted mode](https://code.claude.com/docs/en/cli-reference.md#cli-flags).

448448>

449449> Claude Code never saves it as `defaultMode`.

450450

from line 464

464464}

465465```

466466

467Keep the matcher as narrow as possible. Matching on `.*` or leaving the matcher empty would auto-approve every tool permission prompt, including file writes and shell commands. See the [PermissionRequest reference](/docs/en/hooks.md#permissionrequest-decision-control) for the full set of decision fields.

467Keep the matcher as narrow as possible. Matching on `.*` or leaving the matcher empty would auto-approve every tool permission prompt, including file writes and shell commands. See the [PermissionRequest reference](https://code.claude.com/docs/en/hooks.md#permissionrequest-decision-control) for the full set of decision fields.

468468

469469## How hooks work

470470

471Claude Code fires hook events at specific points in its lifecycle. When an event fires, Claude Code runs the matching hooks in parallel; see [Hook handler fields](/docs/en/hooks.md#hook-handler-fields) for how duplicate handlers are treated. The table below shows each event and when it triggers:

471Claude Code fires hook events at specific points in its lifecycle. When an event fires, Claude Code runs the matching hooks in parallel; see [Hook handler fields](https://code.claude.com/docs/en/hooks.md#hook-handler-fields) for how duplicate handlers are treated. The table below shows each event and when it triggers:

472472

473473| Event | When it fires |

474474| :- | :- |

475475| `SessionStart` | When a session begins or resumes |

476476| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |

477| `UserPromptSubmit` | When a prompt is submitted, before Claude processes it. Also fires on [turns Claude Code starts on its own](/docs/en/hooks.md#userpromptsubmit) |

477| `UserPromptSubmit` | When a prompt is submitted, before Claude processes it. Also fires on [turns Claude Code starts on its own](https://code.claude.com/docs/en/hooks.md#userpromptsubmit) |

478478| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |

479479| `PreToolUse` | Before a tool call executes. Can block it |

480480| `PermissionRequest` | When a tool call needs a permission decision |

from line 490

490490| `TaskCompleted` | When a task is being marked as completed |

491491| `Stop` | When Claude finishes responding |

492492| `StopFailure` | When the turn ends due to an API error |

493| `TeammateIdle` | When an [agent team](/docs/en/agent-teams.md) teammate is about to go idle |

493| `TeammateIdle` | When an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate is about to go idle |

494494| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

495495| `ConfigChange` | When a configuration file changes during a session |

496496| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

from line 509

509509Each hook has a `type` that determines how it runs. Most hooks use `"type": "command"`, which runs a shell command. Four other types are available:

510510

511511* `"type": "http"`: POST event data to a URL. See [HTTP hooks](#http-hooks).

512* `"type": "mcp_tool"`: call a tool on a configured MCP server. See [MCP tool hooks](/docs/en/hooks.md#mcp-tool-hook-fields).

512* `"type": "mcp_tool"`: call a tool on a configured MCP server. See [MCP tool hooks](https://code.claude.com/docs/en/hooks.md#mcp-tool-hook-fields).

513513* `"type": "prompt"`: single-turn LLM evaluation. See [Prompt-based hooks](#prompt-based-hooks).

514514* `"type": "agent"`: multi-turn verification with tool access. Agent hooks are experimental and may change. See [Agent-based hooks](#agent-based-hooks).

515515

from line 571

571571}

572572```

573573

574Your script can parse that JSON and act on any of those fields. `UserPromptSubmit` hooks get the `prompt` text instead, `SessionStart` hooks get a `source` of `startup`, `resume`, `clear`, `compact`, or `fork`, and so on. See [Common input fields](/docs/en/hooks.md#common-input-fields) in the reference for shared fields, and each event's section for event-specific schemas.

574Your script can parse that JSON and act on any of those fields. `UserPromptSubmit` hooks get the `prompt` text instead, `SessionStart` hooks get a `source` of `startup`, `resume`, `clear`, `compact`, or `fork`, and so on. See [Common input fields](https://code.claude.com/docs/en/hooks.md#common-input-fields) in the reference for shared fields, and each event's section for event-specific schemas.

575575

576576#### Hook output

577577

from line 590

590590exit 0 # exit 0 = no decision; the normal permission flow applies

591591```

592592

593With an exit code besides 0 and 2 and no valid JSON output, the action proceeds on most events, unless the hook is one [whose failure blocks the action](/docs/en/hooks.md#block-the-action-when-a-hook-fails). A hook with `onFailure` set to `"block"` is one example. Exit 0 to report no objection, or exit 2 to block the action:

593With an exit code besides 0 and 2 and no valid JSON output, the action proceeds on most events, unless the hook is one [whose failure blocks the action](https://code.claude.com/docs/en/hooks.md#block-the-action-when-a-hook-fails). A hook with `onFailure` set to `"block"` is one example. Exit 0 to report no objection, or exit 2 to block the action:

594594

595* **Exit 0**: if you exit 0 from a `PreToolUse` hook, the tool call still goes through the normal [permission flow](/docs/en/permissions.md), because exit 0 doesn't approve it. For `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart`, and `PostModelSwitch` hooks, Claude Code adds stdout it [treats as plain text](/docs/en/hooks.md#exit-code-0) to Claude's context.

596* **Exit 2**: write a reason to stderr. Depending on the event, Claude receives it as feedback so it can adjust, the user sees it, or no message appears, as with `ConfigChange` and `Elicitation`. Some events can't be blocked: for `SessionStart` and others, exit 2 shows stderr to the user and execution continues. See [exit code 2 behavior per event](/docs/en/hooks.md#exit-code-2-behavior-per-event) for the full list.

597* **Any other exit code**: for the per-event exceptions, such as `WorktreeCreate` failing on any nonzero exit, see [Exit code output](/docs/en/hooks.md#exit-code-output). On other events, unless the hook is one whose failure blocks the action, find your case by what your hook printed to stdout:

595* **Exit 0**: if you exit 0 from a `PreToolUse` hook, the tool call still goes through the normal [permission flow](https://code.claude.com/docs/en/permissions.md), because exit 0 doesn't approve it. For `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart`, and `PostModelSwitch` hooks, Claude Code adds stdout it [treats as plain text](https://code.claude.com/docs/en/hooks.md#exit-code-0) to Claude's context.

596* **Exit 2**: write a reason to stderr. Depending on the event, Claude receives it as feedback so it can adjust, the user sees it, or no message appears, as with `ConfigChange` and `Elicitation`. Some events can't be blocked: for `SessionStart` and others, exit 2 shows stderr to the user and execution continues. See [exit code 2 behavior per event](https://code.claude.com/docs/en/hooks.md#exit-code-2-behavior-per-event) for the full list.

597* **Any other exit code**: for the per-event exceptions, such as `WorktreeCreate` failing on any nonzero exit, see [Exit code output](https://code.claude.com/docs/en/hooks.md#exit-code-output). On other events, unless the hook is one whose failure blocks the action, find your case by what your hook printed to stdout:

598598 * A parsed object that passes schema validation: Claude Code ignores the exit code, the JSON alone decides the outcome, and the hook isn't reported as an error.

599 * A parsed object that fails schema validation, or stdout that Claude Code [tries to parse as JSON](/docs/en/hooks.md#exit-code-0) but that isn't valid JSON: the action proceeds as a non-blocking error. Check the `<hook name> hook error` notice for the validation or parse message.

600 * Stdout that Claude Code [treats as plain text](/docs/en/hooks.md#exit-code-0), or empty stdout: the action proceeds as a non-blocking error. The transcript shows a `<hook name> hook error` notice, then the first line of stderr prefixed with `Failed with non-blocking status code:`. To capture the full stderr, enable [debug logging](/docs/en/hooks.md#debug-hooks) with `claude --debug` or by running `/debug` mid-session.

599 * A parsed object that fails schema validation, or stdout that Claude Code [tries to parse as JSON](https://code.claude.com/docs/en/hooks.md#exit-code-0) but that isn't valid JSON: the action proceeds as a non-blocking error. Check the `<hook name> hook error` notice for the validation or parse message.

600 * Stdout that Claude Code [treats as plain text](https://code.claude.com/docs/en/hooks.md#exit-code-0), or empty stdout: the action proceeds as a non-blocking error. The transcript shows a `<hook name> hook error` notice, then the first line of stderr prefixed with `Failed with non-blocking status code:`. To capture the full stderr, enable [debug logging](https://code.claude.com/docs/en/hooks.md#debug-hooks) with `claude --debug` or by running `/debug` mid-session.

601601

602602#### Structured JSON output

603603

from line 605

605605

606606> [!NOTE]

607607>

608> Use exit 2 to block with a stderr message, or exit 0 with JSON for structured control. Choose one approach per hook. For what happens when you mix them, see [Exit code output](/docs/en/hooks.md#exit-code-output).

608> Use exit 2 to block with a stderr message, or exit 0 with JSON for structured control. Choose one approach per hook. For what happens when you mix them, see [Exit code output](https://code.claude.com/docs/en/hooks.md#exit-code-output).

609609

610610For example, a `PreToolUse` hook can deny a tool call and tell Claude why, or escalate it to the user for approval:

611611

from line 623

623623

624624On `PreToolUse`, you can also return `"ask"` to show the user the normal permission prompt, or `"allow"` to skip the interactive permission prompt. With `"allow"`, deny and ask rules, including enterprise managed deny lists, still apply, as do prompts for:

625625

626* Reads from [network paths](/docs/en/permissions.md#network-paths)

627* MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool)

628* Connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) in sessions where that setting reaches Claude Code

626* Reads from [network paths](https://code.claude.com/docs/en/permissions.md#network-paths)

627* MCP tools marked [`requiresUserInteraction`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool)

628* Connector tools [your organization set to `ask`](https://code.claude.com/docs/en/mcp#organization-controls-on-connector-tools) in sessions where that setting reaches Claude Code

629629

630For what `"allow"` does in plan mode, see [Hook approvals in plan mode](/docs/en/permissions.md#hook-approvals-in-plan-mode).

630For what `"allow"` does in plan mode, see [Hook approvals in plan mode](https://code.claude.com/docs/en/permissions.md#hook-approvals-in-plan-mode).

631631

632A fourth value, `"defer"`, is available in [non-interactive mode](/docs/en/headless.md) with the `-p` flag. Returning it ends the turn with the tool call preserved, so an Agent SDK wrapper can collect input and resume. See [Defer a tool call for later](/docs/en/hooks.md#defer-a-tool-call-for-later) in the reference.

632A fourth value, `"defer"`, is available in [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag. Returning it ends the turn with the tool call preserved, so an Agent SDK wrapper can collect input and resume. See [Defer a tool call for later](https://code.claude.com/docs/en/hooks.md#defer-a-tool-call-for-later) in the reference.

633633

634A `PreModelSwitch` hook returns the same `permissionDecision` field: `"allow"` lets a model switch proceed, and `"deny"` cancels it. `"ask"` has you confirm the switch when you run `/model` in an interactive session; everywhere else, Claude Code treats `"ask"` as a refusal. See [PreModelSwitch decision control](/docs/en/hooks.md#premodelswitch-decision-control).

634A `PreModelSwitch` hook returns the same `permissionDecision` field: `"allow"` lets a model switch proceed, and `"deny"` cancels it. `"ask"` has you confirm the switch when you run `/model` in an interactive session; everywhere else, Claude Code treats `"ask"` as a refusal. See [PreModelSwitch decision control](https://code.claude.com/docs/en/hooks.md#premodelswitch-decision-control).

635635

636Other events use different decision patterns. For example, `PostToolUse` and `Stop` hooks use a top-level `decision: "block"` field, while `PermissionRequest` uses `hookSpecificOutput.decision.behavior`. See the [summary table](/docs/en/hooks.md#decision-control) in the reference for a full breakdown by event.

636Other events use different decision patterns. For example, `PostToolUse` and `Stop` hooks use a top-level `decision: "block"` field, while `PermissionRequest` uses `hookSpecificOutput.decision.behavior`. See the [summary table](https://code.claude.com/docs/en/hooks.md#decision-control) in the reference for a full breakdown by event.

637637

638638For `UserPromptSubmit` hooks, use `hookSpecificOutput.additionalContext` instead to inject text into Claude's context. Nest `additionalContext` inside `hookSpecificOutput`; if you place it at the top level of the JSON, Claude Code silently ignores it. For example, this output adds the current branch state to every prompt:

639639

from line 646

646646}

647647```

648648

649See [UserPromptSubmit decision control](/docs/en/hooks.md#userpromptsubmit-decision-control) for the full output shape, including blocking prompts and setting the session title.

649See [UserPromptSubmit decision control](https://code.claude.com/docs/en/hooks.md#userpromptsubmit-decision-control) for the full output shape, including blocking prompts and setting the session title.

650650

651651Hooks with `type: "prompt"` handle output differently: see [Prompt-based hooks](#prompt-based-hooks).

652652

from line 669

669669}

670670```

671671

672The `"Edit|Write"` matcher fires only when Claude uses the `Edit` or `Write` tool, not when it uses `Bash`, `Read`, or any other tool. A comma separates alternatives the same way, so `"Edit, Write"` is equivalent. See [Matcher patterns](/docs/en/hooks.md#matcher-patterns) for how plain names and regular expressions are evaluated.

672The `"Edit|Write"` matcher fires only when Claude uses the `Edit` or `Write` tool, not when it uses `Bash`, `Read`, or any other tool. A comma separates alternatives the same way, so `"Edit, Write"` is equivalent. See [Matcher patterns](https://code.claude.com/docs/en/hooks.md#matcher-patterns) for how plain names and regular expressions are evaluated.

673673

674674> [!NOTE]

675675>

676> Claude can also create or modify files by running shell commands. If your hook must see every file change, such as for compliance scanning or audit logging, add a [`Stop`](/docs/en/hooks#stop) hook that scans the working tree once per turn. For per-call coverage instead, also match `Bash|PowerShell` and have your script list modified and untracked files with `git status --porcelain`. The [PowerShell hook input section](/docs/en/hooks.md#powershell) explains why matching `Bash` alone is not enough. To run a hook when a specific file changes on disk, whatever wrote it, use a [FileChanged](/docs/en/hooks.md#filechanged) hook.

676> Claude can also create or modify files by running shell commands. If your hook must see every file change, such as for compliance scanning or audit logging, add a [`Stop`](https://code.claude.com/docs/en/hooks#stop) hook that scans the working tree once per turn. For per-call coverage instead, also match `Bash|PowerShell` and have your script list modified and untracked files with `git status --porcelain`. The [PowerShell hook input section](https://code.claude.com/docs/en/hooks.md#powershell) explains why matching `Bash` alone is not enough. To run a hook when a specific file changes on disk, whatever wrote it, use a [FileChanged](https://code.claude.com/docs/en/hooks.md#filechanged) hook.

677677

678678Each event type matches on a specific field:

679679

from line 686

686686| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`, `plugin_notification` |

687687| `SubagentStart` | agent type | `general-purpose`, `Explore`, `Plan`, or custom agent names |

688688| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` |

689| `PreModelSwitch`, `PostModelSwitch` | canonical name of the model the session switches to, as described under [PreModelSwitch](/docs/en/hooks.md#premodelswitch) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |

689| `PreModelSwitch`, `PostModelSwitch` | canonical name of the model the session switches to, as described under [PreModelSwitch](https://code.claude.com/docs/en/hooks.md#premodelswitch) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |

690690| `SubagentStop` | agent type | same values as `SubagentStart` |

691691| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |

692692| `DirectoryAdded` | how the directory was added | `slash_command`, `register_repo_root` |

from line 694

694694| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |

695695| `Elicitation` | MCP server name | your configured MCP server names |

696696| `ElicitationResult` | MCP server name | same values as `Elicitation` |

698698| `UserPromptExpansion` | command name | your skill or command names |

699699| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | no matcher support | always fires on every occurrence |

700700

from line 724

724724

725725**Match MCP tools**

726726

727MCP tools use a different naming convention than built-in tools: `mcp__<server>__<tool>`, where `<server>` is the MCP server name and `<tool>` is the tool it provides. For example, `mcp__github__search_repositories` or `mcp__filesystem__read_file`. Tools from a [plugin-bundled server](/docs/en/mcp.md#plugin-provided-mcp-servers) use a scoped server segment instead, such as `mcp__plugin_my-plugin_db__query`. Use a regex matcher to target all tools from a specific server, or match across servers with a pattern like `mcp__.*__write.*`. See [Match MCP tools](/docs/en/hooks.md#match-mcp-tools) in the reference for the full list of examples.

727MCP tools use a different naming convention than built-in tools: `mcp__<server>__<tool>`, where `<server>` is the MCP server name and `<tool>` is the tool it provides. For example, `mcp__github__search_repositories` or `mcp__filesystem__read_file`. Tools from a [plugin-bundled server](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers) use a scoped server segment instead, such as `mcp__plugin_my-plugin_db__query`. Use a regex matcher to target all tools from a specific server, or match across servers with a pattern like `mcp__.*__write.*`. See [Match MCP tools](https://code.claude.com/docs/en/hooks.md#match-mcp-tools) in the reference for the full list of examples.

728728

729The command below extracts the tool name from the hook's JSON input with `jq` and writes it to stderr. Writing to stderr keeps stdout clean for JSON output and sends the message to the [debug log](/docs/en/hooks.md#debug-hooks):

730730

731731```json theme={null}

732732{

from line 770

770770

771771#### Filter by tool name and arguments with the `if` field

772772

773The `if` field uses [permission rule syntax](/docs/en/permissions.md) to filter hooks by tool name and arguments together, so the hook process only spawns when the tool call matches. This goes beyond `matcher`, which filters at the group level by tool name only.

773The `if` field uses [permission rule syntax](https://code.claude.com/docs/en/permissions.md) to filter hooks by tool name and arguments together, so the hook process only spawns when the tool call matches. This goes beyond `matcher`, which filters at the group level by tool name only.

774774

775775For example, this configuration runs a hook only when Claude uses `git` commands rather than all Bash commands:

776776

from line 803

805805

806When Claude Code can't determine which commands the Bash input runs, it runs your hook regardless of the pattern. The [Bash matching table](/docs/en/hooks.md#bash-if-matching) covers the command shapes Claude Code can and can't narrow by subcommand. Because the filter is best-effort, use the [permission system](/docs/en/permissions.md) rather than a hook to enforce a hard allow or deny.

806When Claude Code can't determine which commands the Bash input runs, it runs your hook regardless of the pattern. The [Bash matching table](https://code.claude.com/docs/en/hooks.md#bash-if-matching) covers the command shapes Claude Code can and can't narrow by subcommand. Because the filter is best-effort, use the [permission system](https://code.claude.com/docs/en/permissions.md) rather than a hook to enforce a hard allow or deny.

807807

808808The `if` field accepts the same patterns as permission rules: `"Bash(git *)"`, `"Edit(*.ts)"`, and so on. To match multiple tool names, use separate handlers each with its own `if` value, or match at the `matcher` level where pipe alternation is supported.

809809

from line 819

819819| `.claude/settings.json` | Single project | Yes, can be committed to the repo |

820820| `.claude/settings.local.json` | Single project | No, gitignored when Claude Code saves a setting to it |

821821| Managed policy settings | Organization-wide | Yes, admin-controlled |

822| [Plugin](/docs/en/plugins/overview.md) `hooks/hooks.json` | When plugin is enabled | Yes, bundled with the plugin |

823| [Skill](/docs/en/skills.md) frontmatter | The rest of the session once the skill is invoked. See [Hooks in skills and agents](/docs/en/hooks.md#hooks-in-skills-and-agents) | Yes, defined in the skill file |

824| [Subagent](/docs/en/sub-agents.md) frontmatter | While that subagent is running | Yes, defined in the subagent file |

822| [Plugin](https://code.claude.com/docs/en/plugins/overview.md) `hooks/hooks.json` | When plugin is enabled | Yes, bundled with the plugin |

823| [Skill](https://code.claude.com/docs/en/skills.md) frontmatter | The rest of the session once the skill is invoked. See [Hooks in skills and agents](https://code.claude.com/docs/en/hooks.md#hooks-in-skills-and-agents) | Yes, defined in the skill file |

824| [Subagent](https://code.claude.com/docs/en/sub-agents.md) frontmatter | While that subagent is running | Yes, defined in the subagent file |

825825

826Run [`/hooks`](/docs/en/hooks#the-%2Fhooks-menu) in Claude Code to browse all configured hooks grouped by event.

826Run [`/hooks`](https://code.claude.com/docs/en/hooks#the-%2Fhooks-menu) in Claude Code to browse all configured hooks grouped by event.

827827

828To disable hooks, set `"disableAllHooks": true` in your settings file. Claude Code reads the value left after [settings precedence](/docs/en/hooks.md#disable-or-remove-hooks) applies, so a project's settings file can override yours. Hooks configured in managed settings still run unless `disableAllHooks` is also set there. For the full reach of each level, see [`disableAllHooks`](/docs/en/settings-reference#disableallhooks).

828To disable hooks, set `"disableAllHooks": true` in your settings file. Claude Code reads the value left after [settings precedence](https://code.claude.com/docs/en/hooks.md#disable-or-remove-hooks) applies, so a project's settings file can override yours. Hooks configured in managed settings still run unless `disableAllHooks` is also set there. For the full reach of each level, see [`disableAllHooks`](https://code.claude.com/docs/en/settings-reference#disableallhooks).

829829

830830If you edit settings files directly while Claude Code is running, the file watcher normally picks up hook changes automatically.

831831

from line 861

861861}

862862```

863863

864For full configuration options, see [Prompt-based hooks](/docs/en/hooks.md#prompt-based-hooks) in the reference.

864For full configuration options, see [Prompt-based hooks](https://code.claude.com/docs/en/hooks.md#prompt-based-hooks) in the reference.

865865

866866## Agent-based hooks

867867

868868> [!WARNING]

869869>

870> Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](/docs/en/hooks.md#command-hook-fields).

870> Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](https://code.claude.com/docs/en/hooks.md#command-hook-fields).

871871

872872When verification requires inspecting files or running commands, use `type: "agent"` hooks. Unlike prompt hooks, which make a single LLM call, agent hooks spawn a subagent that can read files, search code, and use other tools to verify conditions before returning a decision.

873873

874Agent hooks use the `"ok"` / `"reason"` response format with a longer default timeout of 60 seconds and up to 50 tool-use turns. They don't support the prompt-hook `impossible` field. On `ok: false`, Claude Code handles an agent hook the way it handles a prompt hook with `continueOnBlock: true` on the same event, so on `PreToolUse` and `PostToolUse` the turn continues; agent hooks have no `continueOnBlock` field. See [agent hook configuration](/docs/en/hooks.md#agent-hook-configuration) for the fields, including the `$ARGUMENTS` placeholder that Claude Code replaces with the hook's JSON input.

874Agent hooks use the `"ok"` / `"reason"` response format with a longer default timeout of 60 seconds and up to 50 tool-use turns. They don't support the prompt-hook `impossible` field. On `ok: false`, Claude Code handles an agent hook the way it handles a prompt hook with `continueOnBlock: true` on the same event, so on `PreToolUse` and `PostToolUse` the turn continues; agent hooks have no `continueOnBlock` field. See [agent hook configuration](https://code.claude.com/docs/en/hooks.md#agent-hook-configuration) for the fields, including the `$ARGUMENTS` placeholder that Claude Code replaces with the hook's JSON input.

875875

876876This example verifies that tests pass before allowing Claude to stop:

877877

from line 895

895895

896896Use prompt hooks when the hook input data alone is enough to make a decision. Use agent hooks when you need to verify something against the actual state of the codebase.

897897

898For full configuration options, see [Agent-based hooks](/docs/en/hooks.md#agent-based-hooks) in the reference.

898For full configuration options, see [Agent-based hooks](https://code.claude.com/docs/en/hooks.md#agent-based-hooks) in the reference.

899899

900900## HTTP hooks

901901

from line 926

926926}

927927```

928928

929Your endpoint responds with a JSON body in the same [output format](/docs/en/hooks.md#json-output) as command hooks, and Claude Code also checks the response status:

929Your endpoint responds with a JSON body in the same [output format](https://code.claude.com/docs/en/hooks.md#json-output) as command hooks, and Claude Code also checks the response status:

930930

931931* **2xx status**: to block a tool call, return the appropriate `hookSpecificOutput` fields in the body.

932* **Any other status, or the request fails**: Claude Code reports a [non-blocking error](/docs/en/hooks.md#exit-code-output) and lets the action continue. To make a failed endpoint block the action, set [`onFailure: "block"`](/docs/en/hooks#block-the-action-when-a-hook-fails) on the hook.

932* **Any other status, or the request fails**: Claude Code reports a [non-blocking error](https://code.claude.com/docs/en/hooks.md#exit-code-output) and lets the action continue. To make a failed endpoint block the action, set [`onFailure: "block"`](https://code.claude.com/docs/en/hooks#block-the-action-when-a-hook-fails) on the hook.

933933

934934Header values support environment variable interpolation using `$VAR_NAME` or `${VAR_NAME}` syntax. Only variables listed in the `allowedEnvVars` array are resolved; all other `$VAR` references remain empty.

935935

936For full configuration options and response handling, see [HTTP hooks](/docs/en/hooks.md#http-hook-fields) in the reference.

936For full configuration options and response handling, see [HTTP hooks](https://code.claude.com/docs/en/hooks.md#http-hook-fields) in the reference.

937937

938938## Limitations and troubleshooting

939939

from line 941

941941

942942Keep these constraints in mind when designing hooks:

943943

944* Command hooks communicate through stdout, stderr, and exit codes only. They can't trigger `/` commands or tool calls. Text returned via `additionalContext` is injected as a [system reminder](/docs/en/glossary.md#system-reminder) that Claude reads as plain text. HTTP hooks communicate through the response body instead.

944* Command hooks communicate through stdout, stderr, and exit codes only. They can't trigger `/` commands or tool calls. Text returned via `additionalContext` is injected as a [system reminder](https://code.claude.com/docs/en/glossary.md#system-reminder) that Claude reads as plain text. HTTP hooks communicate through the response body instead.

945945* Hook timeouts vary by type. Override per hook with the `timeout` field in seconds.

946946 * `command`, `http`, `mcp_tool`: 10 minutes. Claude Code lowers this default to 30 seconds for `UserPromptSubmit`, `PreModelSwitch`, and `PostModelSwitch` hooks, and to 10 seconds for `MessageDisplay`.

947947 * `prompt`: 30 seconds.

948948 * `agent`: 60 seconds.

949 * [`SessionEnd`](/docs/en/hooks#sessionend) hooks of any type share a 1.5-second budget. If your settings set a longer per-hook `timeout`, Claude Code raises the budget to match, up to 60 seconds.

949 * [`SessionEnd`](https://code.claude.com/docs/en/hooks#sessionend) hooks of any type share a 1.5-second budget. If your settings set a longer per-hook `timeout`, Claude Code raises the budget to match, up to 60 seconds.

950950* `PostToolUse` hooks can't undo actions since the tool has already executed.

951* [`PermissionRequest`](/docs/en/hooks#permissionrequest) hooks fire when Claude Code is about to ask you for permission, or when it would otherwise auto-deny a call that can't prompt. In [non-interactive mode](/docs/en/headless.md) with the `-p` flag, they still run outside [`dontAsk` mode](/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), and a call that no hook decides and nothing else can answer is denied.

952* `Stop` hooks fire whenever Claude finishes responding, not only at task completion. They don't fire on user interrupts. API errors fire [StopFailure](/docs/en/hooks.md#stopfailure) instead.

953* When multiple `PreToolUse` hooks return [`updatedInput`](/docs/en/hooks#pretooluse) to rewrite a tool's arguments, the last one to finish takes effect. Since hooks run in parallel, the order is non-deterministic. Avoid having more than one hook modify the same tool's input.

951* [`PermissionRequest`](https://code.claude.com/docs/en/hooks#permissionrequest) hooks fire when Claude Code is about to ask you for permission, or when it would otherwise auto-deny a call that can't prompt. In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag, they still run outside [`dontAsk` mode](https://code.claude.com/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), and a call that no hook decides and nothing else can answer is denied.

952* `Stop` hooks fire whenever Claude finishes responding, not only at task completion. They don't fire on user interrupts. API errors fire [StopFailure](https://code.claude.com/docs/en/hooks.md#stopfailure) instead.

953* When multiple `PreToolUse` hooks return [`updatedInput`](https://code.claude.com/docs/en/hooks#pretooluse) to rewrite a tool's arguments, the last one to finish takes effect. Since hooks run in parallel, the order is non-deterministic. Avoid having more than one hook modify the same tool's input.

954954

955955### Hooks and permission modes

956956

from line 958

958958

959959* **What still holds over `"allow"`**: a hook returning `"allow"` doesn't bypass deny rules from settings, and it can't suppress the prompt for:

960960

961 * Reads from [network paths](/docs/en/permissions.md#network-paths)

962 * MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool)

963 * Connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) in sessions where that setting reaches Claude Code

961 * Reads from [network paths](https://code.claude.com/docs/en/permissions.md#network-paths)

962 * MCP tools marked [`requiresUserInteraction`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool)

963 * Connector tools [your organization set to `ask`](https://code.claude.com/docs/en/mcp#organization-controls-on-connector-tools) in sessions where that setting reaches Claude Code

964964

965 In [plan mode](/docs/en/permissions.md#hook-approvals-in-plan-mode), if your `PreToolUse` hook returns `"allow"` for a file edit, you get the same prompt, block, or approval the edit would get with no hook. To lift this limit on hook approvals, [approve the plan](/docs/en/permission-modes.md#review-and-approve-a-plan) or switch to another permission mode.

966* **`"deny"` in every permission mode**: a hook that returns `permissionDecision: "deny"` blocks the tool even in `bypassPermissions` mode or with `--dangerously-skip-permissions`. `PreToolUse` hooks fire before any permission-mode check, in every [permission mode](/docs/en/permission-modes.md), including `dontAsk`. This lets you enforce policy that users can't bypass by changing their permission mode.

965 In [plan mode](https://code.claude.com/docs/en/permissions.md#hook-approvals-in-plan-mode), if your `PreToolUse` hook returns `"allow"` for a file edit, you get the same prompt, block, or approval the edit would get with no hook. To lift this limit on hook approvals, [approve the plan](https://code.claude.com/docs/en/permission-modes.md#review-and-approve-a-plan) or switch to another permission mode.

966* **`"deny"` in every permission mode**: a hook that returns `permissionDecision: "deny"` blocks the tool even in `bypassPermissions` mode or with `--dangerously-skip-permissions`. `PreToolUse` hooks fire before any permission-mode check, in every [permission mode](https://code.claude.com/docs/en/permission-modes.md), including `dontAsk`. This lets you enforce policy that users can't bypass by changing their permission mode.

967967

968968> [!NOTE]

969969>

970> If your machine has no [managed settings](/docs/en/settings.md#check-what-your-organization-enforces) and your session doesn't use [`/login` credentials](/docs/en/authentication#authentication-precedence) for a Team or Enterprise plan, a [mod](/docs/en/plugins/mods/overview.md) can approve a call your `PreToolUse` hook blocked. A session that runs on an API key or a long-lived [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/en/authentication#generate-a-long-lived-token) instead isn't using that login, even when that login is stored.

970> If your machine has no [managed settings](https://code.claude.com/docs/en/settings.md#check-what-your-organization-enforces) and your session doesn't use [`/login` credentials](https://code.claude.com/docs/en/authentication#authentication-precedence) for a Team or Enterprise plan, a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) can approve a call your `PreToolUse` hook blocked. A session that runs on an API key or a long-lived [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/en/authentication#generate-a-long-lived-token) instead isn't using that login, even when that login is stored.

971971>

972> In plan mode, a mod can approve such a blocked call only when it's read-only, so not a file edit. For the cases where a mod's approval doesn't get past your rules and hooks, see [Extend permissions with hooks](/docs/en/permissions.md#precedence-among-rules-hooks-and-mods).

972> In plan mode, a mod can approve such a blocked call only when it's read-only, so not a file edit. For the cases where a mod's approval doesn't get past your rules and hooks, see [Extend permissions with hooks](https://code.claude.com/docs/en/permissions.md#precedence-among-rules-hooks-and-mods).

973973

974974### Hook not firing

975975

from line 976

976976The hook is configured but never executes.

977977

978978* Run `/hooks` and confirm the hook appears under the correct event

979* For a hook in a skill's frontmatter, invoke the skill or ask Claude to, then run `/hooks` again. `/hooks` doesn't list hooks from a skill that hasn't been invoked in the session. If `/hooks` still doesn't list the hook, check for other causes, such as [frontmatter that didn't parse](/docs/en/skills.md#skill-not-triggering) or one of the [limits on skill hooks](/docs/en/hooks.md#limits-on-skill-hooks)

979* For a hook in a skill's frontmatter, invoke the skill or ask Claude to, then run `/hooks` again. `/hooks` doesn't list hooks from a skill that hasn't been invoked in the session. If `/hooks` still doesn't list the hook, check for other causes, such as [frontmatter that didn't parse](https://code.claude.com/docs/en/skills.md#skill-not-triggering) or one of the [limits on skill hooks](https://code.claude.com/docs/en/hooks.md#limits-on-skill-hooks)

980980* Check that the matcher pattern matches the tool name exactly. Matchers are case-sensitive

981981* Verify you're triggering the right event type: `PreToolUse` fires before tool execution, `PostToolUse` fires after. A `PermissionRequest` hook fires when Claude Code is about to ask you for permission; see the [limitations](#limitations) for the non-interactive cases

982982

from line 989

989989 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh

990990 echo $? # Check the exit code

991991 ```

992* If you see "command not found", use absolute paths or `${CLAUDE_PROJECT_DIR}` to reference scripts. To avoid shell quoting entirely, add `"args": []` to switch to [exec form](/docs/en/hooks.md#exec-form-and-shell-form), which spawns the script directly without a shell

992* If you see "command not found", use absolute paths or `${CLAUDE_PROJECT_DIR}` to reference scripts. To avoid shell quoting entirely, add `"args": []` to switch to [exec form](https://code.claude.com/docs/en/hooks.md#exec-form-and-shell-form), which spawns the script directly without a shell

993993* If you see "jq: command not found", install `jq` or use Python/Node.js for JSON parsing

994* If the message includes `blocking because Git Bash wasn't found`, you're on Windows, Claude Code didn't find Git Bash, and the failed or timed-out hook blocked the tool call. See [Failed hooks on Windows without Git Bash](/docs/en/hooks.md#failed-hooks-on-windows-without-git-bash) for the fixes

994* If the message includes `blocking because Git Bash wasn't found`, you're on Windows, Claude Code didn't find Git Bash, and the failed or timed-out hook blocked the tool call. See [Failed hooks on Windows without Git Bash](https://code.claude.com/docs/en/hooks.md#failed-hooks-on-windows-without-git-bash) for the fixes

995995* If the notice shows a JSON validation message, your hook's stdout parsed as JSON but failed schema validation. If it shows a JSON parse message, the stdout looked like a JSON object but wasn't valid JSON. Both happen even on exit 0.

996996

997 To fix a parse failure, build the payload with a JSON encoder such as `jq` instead of string concatenation, so quotes and backslashes inside values are escaped. The reference's [Exit code output](/docs/en/hooks.md#exit-code-output) section covers the exit-code and JSON combinations

997 To fix a parse failure, build the payload with a JSON encoder such as `jq` instead of string concatenation, so quotes and backslashes inside values are escaped. The reference's [Exit code output](https://code.claude.com/docs/en/hooks.md#exit-code-output) section covers the exit-code and JSON combinations

998998* If the script isn't running at all, make it executable: `chmod +x ./my-hook.sh`

999999

10001000### `/hooks` shows no hooks configured

from line 1004

10041004* File edits are normally picked up automatically. If they haven't appeared after a few seconds, the file watcher may have missed the change: restart your session to force a reload.

10051005* Verify your JSON is valid: trailing commas and comments aren't allowed

10061006* Confirm the settings file is in the correct location: `.claude/settings.json` for project hooks, `~/.claude/settings.json` for global hooks

1007* If the menu shows `Only hooks from managed settings run here`, your organization has set [`allowManagedHooksOnly`](/docs/en/settings-reference#allowmanagedhooksonly). Hooks in your user, project, and local settings files don't run and aren't listed

1007* If the menu shows `Only hooks from managed settings run here`, your organization has set [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly). Hooks in your user, project, and local settings files don't run and aren't listed

10081008

10091009### Stop hook hits the block cap

10101010

from line 1021

10211021# ... rest of your hook logic

10221022```

10231023

1024If your hook legitimately needs more than eight iterations to converge, raise the cap with [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/en/env-vars).

1024If your hook legitimately needs more than eight iterations to converge, raise the cap with [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](https://code.claude.com/docs/en/env-vars).

10251025

10261026### Hook JSON has no effect

10271027

from line 1028

10281028Your hook prints valid JSON, but the decision doesn't take effect and no error appears in the transcript. Check which cause applies:

10291029

10301030* **Extra output before the JSON**: something else writes to stdout first, usually an unconditional `echo` in your shell profile, so the output no longer starts with `{`. See [Shell profile output before the JSON](#shell-profile-output-before-the-json).

1031* **A field at the wrong level**: compare each field's placement against the [JSON output](/docs/en/hooks.md#json-output) format. For example, `permissionDecision` belongs inside `hookSpecificOutput`, not at the top level. See [Fields at the wrong level](#fields-at-the-wrong-level).

1031* **A field at the wrong level**: compare each field's placement against the [JSON output](https://code.claude.com/docs/en/hooks.md#json-output) format. For example, `permissionDecision` belongs inside `hookSpecificOutput`, not at the top level. See [Fields at the wrong level](#fields-at-the-wrong-level).

10321032

10331033#### Shell profile output before the JSON

10341034

from line 1039

10391039{"decision": "block", "reason": "Not allowed"}

10401040```

10411041

1042Unless the hook is [async](/docs/en/hooks.md#how-async-hooks-execute), Claude Code reads output that doesn't start with `{` as plain text, so your JSON is ignored. Because the hook exited 0, the transcript shows no error either. To check for this cause, start Claude Code with `claude --debug`, trigger the hook, and search the [debug log](/docs/en/hooks.md#debug-hooks) for `Hook output does not start with {`. To fix it, wrap the `echo` statements in your profile so they run only in interactive shells:

1042Unless the hook is [async](https://code.claude.com/docs/en/hooks.md#how-async-hooks-execute), Claude Code reads output that doesn't start with `{` as plain text, so your JSON is ignored. Because the hook exited 0, the transcript shows no error either. To check for this cause, start Claude Code with `claude --debug`, trigger the hook, and search the [debug log](https://code.claude.com/docs/en/hooks.md#debug-hooks) for `Hook output does not start with {`. To fix it, wrap the `echo` statements in your profile so they run only in interactive shells:

10431043

10441044```bash theme={null}

10451045# In ~/.zshrc or ~/.bashrc

from line 1052

10521052

10531053#### Fields at the wrong level

10541054

1055When your hook returns `permissionDecision` or `additionalContext` at the top level instead of inside `hookSpecificOutput`, the JSON still parses, and Claude Code ignores the misplaced fields without reporting an error. To see which fields it ignored, start Claude Code with `claude --debug` and search the [debug log](/docs/en/hooks.md#debug-hooks) for `Hook JSON output had unrecognized keys`.

1055When your hook returns `permissionDecision` or `additionalContext` at the top level instead of inside `hookSpecificOutput`, the JSON still parses, and Claude Code ignores the misplaced fields without reporting an error. To see which fields it ignored, start Claude Code with `claude --debug` and search the [debug log](https://code.claude.com/docs/en/hooks.md#debug-hooks) for `Hook JSON output had unrecognized keys`.

10561056

10571057### Check what a hook did

10581058

from line 1060

10601060

10611061* **Success**: you see nothing, unless the hook's JSON surfaces something, such as `systemMessage` or Stop hook feedback.

10621062 * To confirm the hook ran, check for its effect, like a reformatted file

1063* **Blocking error**: on most events you see the message that came with the block, for example `Blocked: rm commands are not allowed`. On a few events, such as `ConfigChange` and `Elicitation`, you see no message. [Exit code 2](/docs/en/hooks.md#exit-code-2) covers where the message comes from.

1063* **Blocking error**: on most events you see the message that came with the block, for example `Blocked: rm commands are not allowed`. On a few events, such as `ConfigChange` and `Elicitation`, you see no message. [Exit code 2](https://code.claude.com/docs/en/hooks.md#exit-code-2) covers where the message comes from.

10641064* **Non-blocking error**: you see a `<hook name> hook error` notice with a short explanation, such as the first line of stderr after `Failed with non-blocking status code:`, or a JSON validation or parse message. The action went ahead.

10651065

1066To look up the outcome for a specific exit code and stdout, including the per-event exceptions, see [Exit code output](/docs/en/hooks.md#exit-code-output) in the reference.

1066To look up the outcome for a specific exit code and stdout, including the per-event exceptions, see [Exit code output](https://code.claude.com/docs/en/hooks.md#exit-code-output) in the reference.

10671067

1068For full execution details, including hook exit codes, stdout, and stderr, read the [debug log](/docs/en/hooks.md#debug-hooks). Start Claude Code with `claude --debug-file /tmp/claude.log` to write to a known path, then `tail -f /tmp/claude.log` in another terminal. If you started without that flag, run `/debug` mid-session to enable logging and find the log path.

1068For full execution details, including hook exit codes, stdout, and stderr, read the [debug log](https://code.claude.com/docs/en/hooks.md#debug-hooks). Start Claude Code with `claude --debug-file /tmp/claude.log` to write to a known path, then `tail -f /tmp/claude.log` in another terminal. If you started without that flag, run `/debug` mid-session to enable logging and find the log path.

10691069

10701070## Learn more

10711071

1072* [Hooks reference](/docs/en/hooks.md): full event schemas, JSON output format, async hooks, and MCP tool hooks

1073* [Security considerations](/docs/en/hooks.md#security-considerations): review before deploying hooks in shared or production environments

1072* [Hooks reference](https://code.claude.com/docs/en/hooks.md): full event schemas, JSON output format, async hooks, and MCP tool hooks

1073* [Security considerations](https://code.claude.com/docs/en/hooks.md#security-considerations): review before deploying hooks in shared or production environments

10741074* [Bash command validator example](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py): complete reference implementation

10751075

how-claude-code-works Changed · +39 / -39 lines

from line 4

55Claude Code is an agentic assistant that runs in your terminal. While it excels at coding, it can help with anything you can do from the command line: writing docs, running builds, searching files, researching topics, and more.

7This guide covers the core architecture, built-in capabilities, and [tips for working effectively](#work-effectively-with-claude-code). For step-by-step walkthroughs, see [Common workflows](/docs/en/common-workflows.md). For extensibility features like skills, MCP, and hooks, see [Extend Claude Code](/docs/en/features-overview.md).

7This guide covers the core architecture, built-in capabilities, and [tips for working effectively](#work-effectively-with-claude-code). For step-by-step walkthroughs, see [Common workflows](https://code.claude.com/docs/en/common-workflows.md). For extensibility features like skills, MCP, and hooks, see [Extend Claude Code](https://code.claude.com/docs/en/features-overview.md).

99## The agentic loop

1010

from line 22

2222

2323Claude Code uses Claude models to understand your code and reason about tasks. Claude can read code in any language, understand how components connect, and figure out what needs to change to accomplish your goal. For complex tasks, it breaks work into steps, executes them, and adjusts based on what it learns.

2424

25[Multiple models](/docs/en/model-config.md) are available with different tradeoffs. Sonnet handles most coding tasks well. Opus provides stronger reasoning for complex architectural decisions. Switch with `/model` during a session or start with `claude --model <name>`.

25[Multiple models](https://code.claude.com/docs/en/model-config.md) are available with different tradeoffs. Sonnet handles most coding tasks well. Opus provides stronger reasoning for complex architectural decisions. Switch with `/model` during a session or start with `claude --model <name>`.

2626

2727When this guide says "Claude chooses" or "Claude decides," it's the model doing the reasoning.

2828

from line 38

3838| **Search** | Find files by pattern, search content with regex, explore codebases |

3939| **Execution** | Run shell commands, start servers, run tests, use git |

4040| **Web** | Search the web, fetch documentation, look up error messages |

41| **Code intelligence** | See type errors and warnings after edits, jump to definitions, find references (requires [code intelligence plugins](/docs/en/plugins/code-intelligence.md)) |

41| **Code intelligence** | See type errors and warnings after edits, jump to definitions, find references (requires [code intelligence plugins](https://code.claude.com/docs/en/plugins/code-intelligence.md)) |

4242

43These are the primary capabilities. Claude also has tools for spawning subagents, asking you questions, and other orchestration tasks. See [Tools available to Claude](/docs/en/tools-reference.md) for the complete list.

43These are the primary capabilities. Claude also has tools for spawning subagents, asking you questions, and other orchestration tasks. See [Tools available to Claude](https://code.claude.com/docs/en/tools-reference.md) for the complete list.

4444

4545Claude chooses which tools to use based on your prompt and what it learns along the way. When you say "fix the failing tests," Claude might:

4646

from line 53

5353

5454Each tool use gives Claude new information that informs the next step. This is the agentic loop in action.

5555

56**Extending the base capabilities:** The built-in tools are the foundation. You can extend what Claude knows with [skills](/docs/en/skills.md), connect to external services with [MCP](/docs/en/mcp.md), automate workflows with [hooks](/docs/en/hooks.md), and offload tasks to [subagents](/docs/en/sub-agents.md). These extensions form a layer on top of the core agentic loop. See [Extend Claude Code](/docs/en/features-overview.md) for guidance on choosing the right extension for your needs.

56**Extending the base capabilities:** The built-in tools are the foundation. You can extend what Claude knows with [skills](https://code.claude.com/docs/en/skills.md), connect to external services with [MCP](https://code.claude.com/docs/en/mcp.md), automate workflows with [hooks](https://code.claude.com/docs/en/hooks.md), and offload tasks to [subagents](https://code.claude.com/docs/en/sub-agents.md). These extensions form a layer on top of the core agentic loop. See [Extend Claude Code](https://code.claude.com/docs/en/features-overview.md) for guidance on choosing the right extension for your needs.

5757

5858## What Claude can access

5959

from line 62

6262* **Your project.** Files in your directory and subdirectories, plus files elsewhere with your permission.

6363* **Your terminal.** Any command you could run: build tools, git, package managers, system utilities, scripts. If you can do it from the command line, Claude can too.

6464* **Your git state.** Current branch, uncommitted changes, and recent commit history.

65* **Your [CLAUDE.md](/docs/en/memory.md).** A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session. If your repository has an AGENTS.md for other coding agents, Claude [can read that](/docs/en/memory.md#agents-md) in place of a CLAUDE.md.

66* **[Auto memory](/docs/en/memory.md#auto-memory).** Learnings Claude saves automatically as you work, like your preferences. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of each session.

67* **Extensions you configure.** [MCP servers](/docs/en/mcp.md) for external services, [skills](/docs/en/skills.md) for workflows, [subagents](/docs/en/sub-agents.md) for delegated work, and [Claude in Chrome](/docs/en/chrome.md) for browser interaction.

65* **Your [CLAUDE.md](https://code.claude.com/docs/en/memory.md).** A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session. If your repository has an AGENTS.md for other coding agents, Claude [can read that](https://code.claude.com/docs/en/memory.md#agents-md) in place of a CLAUDE.md.

66* **[Auto memory](https://code.claude.com/docs/en/memory.md#auto-memory).** Learnings Claude saves automatically as you work, like your preferences. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of each session.

67* **Extensions you configure.** [MCP servers](https://code.claude.com/docs/en/mcp.md) for external services, [skills](https://code.claude.com/docs/en/skills.md) for workflows, [subagents](https://code.claude.com/docs/en/sub-agents.md) for delegated work, and [Claude in Chrome](https://code.claude.com/docs/en/chrome.md) for browser interaction.

6868

6969Because Claude sees your whole project, it can work across it. When you ask Claude to "fix the authentication bug," it searches for relevant files, reads multiple files to understand context, makes coordinated edits across them, runs tests to verify the fix, and commits the changes if you ask. This is different from inline code assistants that only see the current file.

7070

from line 79

7979| Environment | Where code runs | Use case |

8080| - | - | - |

8181| **Local** | Your machine | Default. Full access to your files, tools, and environment |

82| **Cloud** | Anthropic-managed VMs, or [self-hosted environments](/docs/en/self-hosted-environments) your organization operates | Offload tasks, work on repos you don't have locally |

82| **Cloud** | Anthropic-managed VMs, or [self-hosted environments](https://code.claude.com/docs/en/self-hosted-environments) your organization operates | Offload tasks, work on repos you don't have locally |

8383| **Remote Control** | Your machine, controlled from a browser | Use the web UI while execution and your files stay local |

8484

8585### Interfaces

8686

87You can access Claude Code through the terminal, the [desktop app](/docs/en/desktop.md), [IDE extensions](/docs/en/vs-code.md), [claude.ai/code](https://claude.ai/code), [Remote Control](/docs/en/remote-control.md), [Slack](/docs/en/slack.md), and [CI/CD pipelines](/docs/en/github-actions.md). The interface determines how you see and interact with Claude, but the underlying agentic loop is identical. See [Use Claude Code everywhere](/docs/en/overview.md#use-claude-code-everywhere) for the full list.

87You can access Claude Code through the terminal, the [desktop app](https://code.claude.com/docs/en/desktop.md), [IDE extensions](https://code.claude.com/docs/en/vs-code.md), [claude.ai/code](https://claude.ai/code), [Remote Control](https://code.claude.com/docs/en/remote-control.md), [Slack](https://code.claude.com/docs/en/slack.md), and [CI/CD pipelines](https://code.claude.com/docs/en/github-actions.md). The interface determines how you see and interact with Claude, but the underlying agentic loop is identical. See [Use Claude Code everywhere](https://code.claude.com/docs/en/overview.md#use-claude-code-everywhere) for the full list.

8888

8989## Work with sessions

9090

91Claude Code saves your conversation locally as you work. Each message, tool use, and result is written to a plaintext JSONL file under `~/.claude/projects/`, which enables [rewinding](#undo-changes-with-checkpoints), [resuming, and forking](#resume-or-fork-sessions) sessions. Before Claude makes code changes, it also snapshots the affected files so you can revert if needed. For paths, retention, and how to clear this data, see [application data in `~/.claude`](/docs/en/claude-directory#application-data).

9292

93**Sessions are independent.** Each new session starts with a fresh context window, without the conversation history from previous sessions. Claude can persist learnings across sessions using [auto memory](/docs/en/memory.md#auto-memory), and you can add your own persistent instructions in [CLAUDE.md](/docs/en/memory.md).

93**Sessions are independent.** Each new session starts with a fresh context window, without the conversation history from previous sessions. Claude can persist learnings across sessions using [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory), and you can add your own persistent instructions in [CLAUDE.md](https://code.claude.com/docs/en/memory.md).

9494

9595### Work across branches

9696

97Each Claude Code conversation is a session tied to your current directory. The `/resume` picker shows sessions from the current worktree by default, with keyboard shortcuts to widen the list to other worktrees or projects. See [Manage sessions](/docs/en/sessions.md#use-the-session-picker) for the full list of picker shortcuts and how name resolution works.

97Each Claude Code conversation is a session tied to your current directory. The `/resume` picker shows sessions from the current worktree by default, with keyboard shortcuts to widen the list to other worktrees or projects. See [Manage sessions](https://code.claude.com/docs/en/sessions.md#use-the-session-picker) for the full list of picker shortcuts and how name resolution works.

9898

9999Claude sees your current branch's files. When you switch branches, Claude sees the new branch's files, but your conversation history stays the same. Claude remembers what you discussed even after switching.

100100

101Since sessions are tied to directories, you can run parallel Claude sessions by using [git worktrees](/docs/en/worktrees.md), which create separate directories for individual branches.

101Since sessions are tied to directories, you can run parallel Claude sessions by using [git worktrees](https://code.claude.com/docs/en/worktrees.md), which create separate directories for individual branches.

102102

103103### Resume or fork sessions

104104

from line 106

106106

107107![Diagram of session continuity: resume continues the same session, fork creates a new branch with a new ID.](https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/session-continuity.svg?fit=max\&auto=format\&n=ikqp3_70mqIahteV\&q=85\&s=04ed0984a58e4127e05b3640265241a3)

108108

109For the resume flags, the `/resume` picker, naming, and what happens when the same session is open in two terminals, see [Manage sessions](/docs/en/sessions.md).

109For the resume flags, the `/resume` picker, naming, and what happens when the same session is open in two terminals, see [Manage sessions](https://code.claude.com/docs/en/sessions.md).

110110

111111### The context window

112112

113Claude's context window holds your conversation history, file contents, command outputs, [CLAUDE.md](/docs/en/memory.md), [auto memory](/docs/en/memory.md#auto-memory), loaded skills, and system instructions. As you work, context fills up. Claude compacts automatically, but instructions from early in the conversation can get lost. Put persistent rules in CLAUDE.md, and run `/context` to see what's using space.

113Claude's context window holds your conversation history, file contents, command outputs, [CLAUDE.md](https://code.claude.com/docs/en/memory.md), [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory), loaded skills, and system instructions. As you work, context fills up. Claude compacts automatically, but instructions from early in the conversation can get lost. Put persistent rules in CLAUDE.md, and run `/context` to see what's using space.

114114

115For an interactive walkthrough of what loads and when, see [Explore the context window](/docs/en/context-window.md).

115For an interactive walkthrough of what loads and when, see [Explore the context window](https://code.claude.com/docs/en/context-window.md).

116116

117117#### Context Claude Code adds on its own

118118

119If Claude follows a rule you didn't write, such as adding a `Co-Authored-By` trailer to a commit, the rule may have come from a [system reminder](/docs/en/glossary.md#system-reminder). As you work, Claude Code adds its own context to the conversation alongside your messages:

119If Claude follows a rule you didn't write, such as adding a `Co-Authored-By` trailer to a commit, the rule may have come from a [system reminder](https://code.claude.com/docs/en/glossary.md#system-reminder). As you work, Claude Code adds its own context to the conversation alongside your messages:

120120

121121* Your CLAUDE.md files

122* The instructions of your [output style](/docs/en/output-styles.md)

122* The instructions of your [output style](https://code.claude.com/docs/en/output-styles.md)

123123* A note when a file Claude read earlier changes on disk

124124* The commit and pull request attribution lines

125125

126To change or remove the attribution lines, set [`attribution`](/docs/en/settings-reference#attribution). To remove Claude Code's built-in commit and pull request instructions, set [`includeGitInstructions`](/docs/en/settings-reference#includegitinstructions) to `false`. For the other switches, see [Turn off the context your agent replaces](/docs/en/agent-sdk/modifying-system-prompts.md#turn-off-the-context-your-agent-replaces).

126To change or remove the attribution lines, set [`attribution`](https://code.claude.com/docs/en/settings-reference#attribution). To remove Claude Code's built-in commit and pull request instructions, set [`includeGitInstructions`](https://code.claude.com/docs/en/settings-reference#includegitinstructions) to `false`. For the other switches, see [Turn off the context your agent replaces](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md#turn-off-the-context-your-agent-replaces).

127127

128128#### When context fills up

129129

from line 131

131131

132132To control what's preserved during compaction, add a "Compact Instructions" section to CLAUDE.md or run `/compact` with a focus (like `/compact focus on the API changes`).

133133

134If a single file or tool output is so large that context refills immediately after each summary, Claude Code stops auto-compacting after a few attempts and shows an error instead of looping. See [Auto-compaction stops with a thrashing error](/docs/en/troubleshooting.md#auto-compaction-stops-with-a-thrashing-error) for recovery steps.

134If a single file or tool output is so large that context refills immediately after each summary, Claude Code stops auto-compacting after a few attempts and shows an error instead of looping. See [Auto-compaction stops with a thrashing error](https://code.claude.com/docs/en/troubleshooting.md#auto-compaction-stops-with-a-thrashing-error) for recovery steps.

135135

136Run `/context` to see what's using space. MCP tool definitions are deferred by default and loaded on demand via [tool search](/docs/en/mcp.md#scale-with-mcp-tool-search), so only tool names and server instructions consume context until Claude uses a specific tool.

136Run `/context` to see what's using space. MCP tool definitions are deferred by default and loaded on demand via [tool search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search), so only tool names and server instructions consume context until Claude uses a specific tool.

137137

138138#### Manage context with skills and subagents

139139

140140Beyond compaction, you can use other features to control what loads into context.

141141

142[Skills](/docs/en/skills.md) load on demand. Claude sees skill descriptions at session start, but the full content only loads when a skill is used. For skills you invoke manually, set `disable-model-invocation: true` to keep descriptions out of context until you need them. For skills you didn't write, use [`skillOverrides`](/docs/en/skills#override-skill-visibility-from-settings) to do the same from settings.

142[Skills](https://code.claude.com/docs/en/skills.md) load on demand. Claude sees skill descriptions at session start, but the full content only loads when a skill is used. For skills you invoke manually, set `disable-model-invocation: true` to keep descriptions out of context until you need them. For skills you didn't write, use [`skillOverrides`](https://code.claude.com/docs/en/skills#override-skill-visibility-from-settings) to do the same from settings.

143143

144[Subagents](/docs/en/sub-agents.md) work in their own context window. A subagent starts fresh unless it's a [fork](/docs/en/sub-agents.md#fork-the-current-conversation), which starts with a copy of your conversation so far. Either way, the subagent's tool calls stay out of your context, and Claude gets back a summary when the subagent finishes.

144[Subagents](https://code.claude.com/docs/en/sub-agents.md) work in their own context window. A subagent starts fresh unless it's a [fork](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation), which starts with a copy of your conversation so far. Either way, the subagent's tool calls stay out of your context, and Claude gets back a summary when the subagent finishes.

145145

146See [context costs](/docs/en/features-overview.md#understand-context-costs) for what each feature costs, and [reduce token usage](/docs/en/costs.md#reduce-token-usage) for tips on managing context.

146See [context costs](https://code.claude.com/docs/en/features-overview.md#understand-context-costs) for what each feature costs, and [reduce token usage](https://code.claude.com/docs/en/costs.md#reduce-token-usage) for tips on managing context.

147147

148148## Stay safe with checkpoints and permissions

149149

from line 153

153153

154154**File edits are reversible.** Before Claude edits a file, it snapshots the current contents. If something goes wrong, press `Esc` twice to rewind to a previous state, or ask Claude to undo.

155155

156Checkpoints are separate from git and remain available when you resume a conversation. They only cover file changes, and a restore [skips symlinked and hard-linked files](/docs/en/checkpointing.md#symlinked-and-hard-linked-paths-not-restored). Actions that affect remote systems (databases, APIs, deployments) can't be checkpointed. You control those with your permission mode and permission rules.

156Checkpoints are separate from git and remain available when you resume a conversation. They only cover file changes, and a restore [skips symlinked and hard-linked files](https://code.claude.com/docs/en/checkpointing.md#symlinked-and-hard-linked-paths-not-restored). Actions that affect remote systems (databases, APIs, deployments) can't be checkpointed. You control those with your permission mode and permission rules.

157157

158158### Control what Claude can do

159159

160160Choose a permission mode to set what Claude can do without asking you. Press `Shift+Tab` to cycle through the permission modes:

161161

162* **Auto**: a classifier reviews most actions in the background and blocks the risky ones instead of asking you. With Claude Code v2.1.283 or later, it's the [built-in starting permission mode](/docs/en/permission-modes.md#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions, and on earlier versions only on Pro, Max, and Team plans

162* **Auto**: a classifier reviews most actions in the background and blocks the risky ones instead of asking you. With Claude Code v2.1.283 or later, it's the [built-in starting permission mode](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions, and on earlier versions only on Pro, Max, and Team plans

163163* **Manual**: Claude asks before file edits and shell commands

164164* **Accept edits**: Claude edits files and runs common filesystem commands like `mkdir` and `mv` without asking, still asks for other commands

165165* **Plan**: Claude explores and proposes a plan without editing your source files

166166

167You can also allow specific commands in `.claude/settings.json` so Claude doesn't ask each time. This is useful for trusted commands like `npm test` or `git status`. Settings can be scoped from organization-wide policies down to personal preferences. See [Permissions](/docs/en/permissions.md) for details.

168168

169169***

170170

171171## Work effectively with Claude Code

172172

173These tips help you get better results from Claude Code. For more on specific prompts, verification, and planning, see [Best practices](/docs/en/best-practices.md).

173These tips help you get better results from Claude Code. For more on specific prompts, verification, and planning, see [Best practices](https://code.claude.com/docs/en/best-practices.md).

174174

175175### Ask Claude Code for help

176176

from line 203

203203

204204You can redirect Claude at any point without starting over. Do either of these:

205205

206* **Press `Esc`** to stop Claude immediately. The running tool call is canceled and Claude waits for your next instruction. If you have messages queued, Claude Code [sends them next](/docs/en/interactive-mode.md#queue-messages-while-claude-works).

207* **Type a correction and press `Enter`** without stopping Claude. The message shows as queued in the conversation. If Claude is running tool calls, it reads the message as soon as those calls finish, within the same turn, and adjusts before its next step. [Queue messages while Claude works](/docs/en/interactive-mode.md#queue-messages-while-claude-works) covers when other queued entries are sent.

206* **Press `Esc`** to stop Claude immediately. The running tool call is canceled and Claude waits for your next instruction. If you have messages queued, Claude Code [sends them next](https://code.claude.com/docs/en/interactive-mode.md#queue-messages-while-claude-works).

207* **Type a correction and press `Enter`** without stopping Claude. The message shows as queued in the conversation. If Claude is running tool calls, it reads the message as soon as those calls finish, within the same turn, and adjusts before its next step. [Queue messages while Claude works](https://code.claude.com/docs/en/interactive-mode.md#queue-messages-while-claude-works) covers when other queued entries are sent.

208208

209209### Delegate, don't dictate

210210

from line 219

219219

220220## What's next

221221

222> **[Extend with features](/docs/en/features-overview.md)**

222> **[Extend with features](https://code.claude.com/docs/en/features-overview.md)**

223223>

224224> Add skills and MCP connections

225225

226> **[Common workflows](/docs/en/common-workflows.md)**

226> **[Common workflows](https://code.claude.com/docs/en/common-workflows.md)**

227227>

228228> Step-by-step guides for typical tasks

229229