One read of Claude Code CLIclaude-code-20261020T183702Z
212 pages moved out of 228 read.
Pages moved
212
significant first
Pages read
228
in this capture
Captured
18:37 UTC
Corpus hash
f4a7dc09bf09
corpus-hash
What this read moved
76-100 of 212, page 4 of 9This capture is too large to show at once. Changes 76-100 of 212 are below, significant first; the rest are on the following screens.
desktop-linux Changed · +32 / -36 lines
### Running as root without `--no-sandbox` is not supported
from line 2
22
33> Install and update the Claude desktop app on Ubuntu and Debian
44
5<Note>
6 Linux support for the Claude desktop app is in beta.
7</Note>
5> [!NOTE]
6>
7> Linux support for the Claude desktop app is in beta.
88
99The 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) for the feature reference.
1010
from line 29
2929
3030Install from Anthropic's apt repository so that updates arrive through your system's regular package updates. Open a terminal and run the commands in each step.
3131
32<Steps>
33 <Step title="Add Anthropic's apt repository">
34 This step downloads the signing key with `curl` and verifies it with `gpg`, which fresh Debian and Ubuntu installations may not include. If either command reports `command not found`, install both first:
32**1. Add Anthropic's apt repository**
3533
36 ```bash theme={null}
37 sudo apt install curl gnupg
38 ```
34This step downloads the signing key with `curl` and verifies it with `gpg`, which fresh Debian and Ubuntu installations may not include. If either command reports `command not found`, install both first:
3935
40 Download Anthropic's signing key:
36```bash theme={null}
37sudo apt install curl gnupg
38```
4139
42 ```bash theme={null}
43 sudo curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc https://downloads.claude.ai/claude-desktop/key.asc
44 ```
40Download Anthropic's signing key:
4541
46 The command prints nothing when it succeeds and a `curl:` error when it doesn't. A missing or wrong key makes `apt update` fail later with `NO_PUBKEY BAA929FF1A7ECACE`, so confirm the key downloaded and belongs to Anthropic before continuing:
42```bash theme={null}
43sudo curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc https://downloads.claude.ai/claude-desktop/key.asc
44```
4745
48 ```bash theme={null}
49 gpg --show-keys /usr/share/keyrings/claude-desktop-archive-keyring.asc
50 ```
46The command prints nothing when it succeeds and a `curl:` error when it doesn't. A missing or wrong key makes `apt update` fail later with `NO_PUBKEY BAA929FF1A7ECACE`, so confirm the key downloaded and belongs to Anthropic before continuing:
5147
52 The fingerprint gpg prints should be `31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE`. If gpg reports that the file can't be opened or contains no valid OpenPGP data, the download failed or returned the wrong content: confirm your network can reach `downloads.claude.ai`, then rerun the download command.
48```bash theme={null}
49gpg --show-keys /usr/share/keyrings/claude-desktop-archive-keyring.asc
50```
5351
54 Register the repository:
52The fingerprint gpg prints should be `31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE`. If gpg reports that the file can't be opened or contains no valid OpenPGP data, the download failed or returned the wrong content: confirm your network can reach `downloads.claude.ai`, then rerun the download command.
5553
56 ```bash theme={null}
57 echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/claude-desktop-archive-keyring.asc] https://downloads.claude.ai/claude-desktop/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop.list
58 ```
59 </Step>
54Register the repository:
6055
61 <Step title="Install the package">
62 ```bash theme={null}
63 sudo apt update && sudo apt install claude-desktop
64 ```
65 </Step>
56```bash theme={null}
57echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/claude-desktop-archive-keyring.asc] https://downloads.claude.ai/claude-desktop/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop.list
58```
6659
67 <Step title="Launch and sign in">
68 Launch **Claude** from your application launcher, or run `claude-desktop` from a terminal, and sign in with your Anthropic account.
60**2. Install the package**
6961
70 The Linux app signs in the same way as on macOS and Windows: with a claude.ai subscription, or through your organization's SSO. Desktop doesn't accept a Claude Console API key directly; use the [CLI](/docs/en/quickstart) for API-key authentication. For enterprise deployments that route Desktop to Google Cloud's Agent Platform or an LLM gateway, see [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview) and [network configuration](/docs/en/network-config).
71 </Step>
72</Steps>
62```bash theme={null}
63sudo apt update && sudo apt install claude-desktop
64```
7365
66**3. Launch and sign in**
67
68Launch **Claude** from your application launcher, or run `claude-desktop` from a terminal, and sign in with your Anthropic account.
69
70The Linux app signs in the same way as on macOS and Windows: with a claude.ai subscription, or through your organization's SSO. Desktop doesn't accept a Claude Console API key directly; use the [CLI](/docs/en/quickstart) for API-key authentication. For enterprise deployments that route Desktop to Google Cloud's Agent Platform or an LLM gateway, see [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview) and [network configuration](/docs/en/network-config).
71
7472### Install from a downloaded file
7573
7674If you can't install through the apt repository, download the `.deb` package directly from the repository's package pool. This command looks up the newest package for your architecture in the repository index, then downloads it to the current directory:
from line 133
135133* `libc6 (>= 2.34)`: your distribution is older than the package supports. Ubuntu 20.04 ships `libc6` 2.31. Upgrade to Ubuntu 22.04 or later, or Debian 12 or later.
136134* All missing dependencies show `not installable` with an `:amd64` or `:arm64` suffix: you downloaded the `.deb` for a different architecture than your machine's. Run `dpkg --print-architecture` and download the matching `.deb`, or [install from the apt repository](#install), which selects the package for your architecture.
137135
138<h3 id="running-as-root-without-no-sandbox-is-not-supported">
139 Running as root without `--no-sandbox` is not supported
140</h3>
136### Running as root without `--no-sandbox` is not supported
141137
142138If `claude-desktop` exits with this message, you launched it as root. Log in as a regular user and launch it from there.
143139
desktop-quickstart Changed · +51 / -57 lines
from line 4
44
55The desktop app gives you Claude Code with a graphical interface, so you can ask Claude to work on the code in a folder on your computer and review its changes without using a terminal. This page walks through installing the app and starting your first session in the **Code** tab. Claude Code requires a [Pro, Max, Team, or Enterprise subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing).
66
7<CardGroup cols={3}>
8 <Card title="Download for macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">
9 Universal build for Intel and Apple Silicon
10 </Card>
7> **[Download for macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs)**
8>
9> Universal build for Intel and Apple Silicon
1110
12 <Card title="Download for Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">
13 For x64 processors
14 </Card>
11> **[Download for Windows](https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs)**
12>
13> For x64 processors
1514
16 <Card title="Get Claude for Linux (beta)" icon="linux" href="/docs/en/desktop-linux">
17 apt or .deb for Ubuntu and Debian
18 </Card>
19</CardGroup>
15> **[Get Claude for Linux (beta)](/docs/en/desktop-linux)**
16>
17> apt or .deb for Ubuntu and Debian
2018
2119For 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).
2220
23<Note>
24 These cases are covered on other pages:
21> [!NOTE]
22>
23> These cases are covered on other pages:
24>
25> * **Already set up**: see [Use Claude Code Desktop](/docs/en/desktop) for everything the Code tab can do
26> * **Want `claude` in your terminal**: [install the CLI](/docs/en/quickstart) separately
2527
26 * **Already set up**: see [Use Claude Code Desktop](/docs/en/desktop) for everything the Code tab can do
27 * **Want `claude` in your terminal**: [install the CLI](/docs/en/quickstart) separately
28</Note>
29
3028The desktop app has three tabs:
3129
3230* **Chat**: General conversation with no file access, similar to claude.ai.
from line 35
3735
3836## Install
3937
40<Steps>
41 <Step title="Install and sign in">
42 On 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). 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.
43 </Step>
38**1. Install and sign in**
4439
45 <Step title="Open the Code tab">
46 Click the **Code** tab at the top center. If clicking Code prompts you 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. If it prompts you to sign in online, complete the sign-in and restart the app. If you see a 403 error, see [authentication troubleshooting](/docs/en/desktop#403-or-authentication-errors-in-the-code-tab).
47 </Step>
48</Steps>
40On 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). 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.
4941
42**2. Open the Code tab**
43
44Click the **Code** tab at the top center. If clicking Code prompts you 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. If it prompts you to sign in online, complete the sign-in and restart the app. If you see a 403 error, see [authentication troubleshooting](/docs/en/desktop#403-or-authentication-errors-in-the-code-tab).
45
5046The desktop app includes Claude Code, so you don't need to install Node.js or the CLI to use the Code tab.
5147
5248## Start your first session
from line 49
5349
5450With the Code tab open, choose a project and give Claude something to do.
5551
56<Steps>
57 <Step title="Choose an environment and folder">
58 In the [row under the prompt box](/docs/en/desktop#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.
52**1. Choose an environment and folder**
5953
60 If no environment selector appears under your prompt box, you have the earlier layout. See [Check which layout you have](/docs/en/desktop#check-which-layout-you-have).
54In the [row under the prompt box](/docs/en/desktop#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.
6155
62 <Tip>
63 Start with a small project you know well. It's the fastest way to see what Claude Code can do.
64 </Tip>
56If no environment selector appears under your prompt box, you have the earlier layout. See [Check which layout you have](/docs/en/desktop#check-which-layout-you-have).
6557
66 You can also select:
58> [!TIP]
59>
60> Start with a small project you know well. It's the fastest way to see what Claude Code can do.
6761
68 * **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) for how cloud sessions work.
69 * **SSH**: Connect to a remote machine over SSH, such as your own servers, cloud VMs, or dev containers. [Add a connection](/docs/en/desktop#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#keep-a-task-running-while-desktop-is-disconnected), but with a Claude account it can stop when its sign-in expires.
70 * **WSL** (Windows): Run the session inside a [WSL 2 distribution](/docs/en/desktop-wsl); Claude Code, tools, and git execute on the Linux side with native paths.
71 </Step>
62You can also select:
7263
73 <Step title="Choose a model">
74 Select a model from the model picker toward the right end of the row under the prompt box. See [models](/docs/en/model-config#available-models) for a comparison of the available models. You can change the model later from the model picker.
75 </Step>
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) 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#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#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); Claude Code, tools, and git execute on the Linux side with native paths.
7667
77 <Step title="Tell Claude what to do">
78 Type what you want Claude to do:
68**2. Choose a model**
7969
80 * `Find a TODO comment and fix it`
81 * `Add tests for the main function`
82 * `Create a CLAUDE.md with instructions for this codebase`
70Select a model from the model picker toward the right end of the row under the prompt box. See [models](/docs/en/model-config#available-models) for a comparison of the available models. You can change the model later from the model picker.
8371
84 A [session](/docs/en/desktop#work-in-parallel-with-sessions) is a conversation with Claude about your code. Each session tracks its own context and changes.
85 </Step>
72**3. Tell Claude what to do**
8673
87 <Step title="Review and accept changes">
88 Check your [permission mode](/docs/en/desktop#choose-a-permission-mode) in the row under the prompt box to see whether Claude waits for your approval:
74Type what you want Claude to do:
8975
90 * **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
91 * **Manual**: Claude proposes each change and waits for your approval before applying it
76* `Find a TODO comment and fix it`
77* `Add tests for the main function`
78* `Create a CLAUDE.md with instructions for this codebase`
9279
93 In Manual mode, you'll see:
80A [session](/docs/en/desktop#work-in-parallel-with-sessions) is a conversation with Claude about your code. Each session tracks its own context and changes.
9481
95 1. A [diff view](/docs/en/desktop#review-changes-with-diff-view) showing exactly what will change in each file
96 2. Accept/Reject buttons to approve or decline each change
97 3. Real-time updates as Claude works through your request
98 </Step>
99</Steps>
82**4. Review and accept changes**
83
84Check your [permission mode](/docs/en/desktop#choose-a-permission-mode) in the row under the prompt box to see whether Claude waits for your approval:
85
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
87* **Manual**: Claude proposes each change and waits for your approval before applying it
88
89In Manual mode, you'll see:
90
911. A [diff view](/docs/en/desktop#review-changes-with-diff-view) showing exactly what will change in each file
922. Accept/Reject buttons to approve or decline each change
933. Real-time updates as Claude works through your request
10094
10195## Now what?
10296
desktop-scheduled-tasks Changed · +37 / -39 lines
from line 27
2727| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |
2828| Minimum interval | 1 hour | 1 minute | 1 minute |
2929
30<Tip>
31 Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.
32</Tip>
30> [!TIP]
31>
32> Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.
3333
34<Note>
35 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#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</Note>
34> [!NOTE]
35>
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#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
4040Local scheduled tasks require Claude Desktop 1.1.5368 or later.
4141
42<Steps>
43 <Step title="Open the Scheduled tasks page">
44 In the [**Code** tab](/docs/en/desktop), click **Scheduled** in the sidebar or in the sidebar's **More** menu.
45 </Step>
42**1. Open the Scheduled tasks page**
4643
47 <Step title="Start a new task">
48 Click **New task**. If a menu opens with **Create with Claude** and **Set up manually**, select **Set up manually**. The **New scheduled task** dialog opens. If **Only on this computer** is at the top of the dialog, go to [Dialog with Only on this computer at the top](#dialog-with-only-on-this-computer-at-the-top) before you enter anything.
49 </Step>
44In the [**Code** tab](/docs/en/desktop), click **Scheduled** in the sidebar or in the sidebar's **More** menu.
5045
51 <Step title="Name the task">
52 Enter a name in the **Name** field. Desktop converts it to lowercase kebab-case and uses it as the task's folder name on disk, so the name must be unique across your tasks.
53 </Step>
46**2. Start a new task**
5447
55 <Step title="Write the instructions">
56 In the box below the name, enter what Claude should do when the task runs.
57 </Step>
48Click **New task**. If a menu opens with **Create with Claude** and **Set up manually**, select **Set up manually**. The **New scheduled task** dialog opens. If **Only on this computer** is at the top of the dialog, go to [Dialog with Only on this computer at the top](#dialog-with-only-on-this-computer-at-the-top) before you enter anything.
5849
59 <Step title="Turn on Only on this computer">
60 Skip 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, and the **Trigger** card offers the presets listed in [Schedule options](#schedule-options).
50**3. Name the task**
6151
62 If 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).
63 </Step>
52Enter a name in the **Name** field. Desktop converts it to lowercase kebab-case and uses it as the task's folder name on disk, so the name must be unique across your tasks.
6453
65 <Step title="Pick the local folder">
66 In the **Local folder** row, select a folder. **Create** stays unavailable until you pick one.
67 </Step>
54**4. Write the instructions**
6855
69 <Step title="Set the schedule">
70 Back in the **Trigger** card, select a [schedule preset](#schedule-options).
71 </Step>
56In the box below the name, enter what Claude should do when the task runs.
7257
73 <Step title="Choose the permission mode and model">
74 In the instructions box's toolbar, select a [permission mode](#permissions-for-scheduled-tasks) and model. If you leave them unchanged, runs use your Claude Code settings and the default model.
75 </Step>
58**5. Turn on Only on this computer**
7659
77 <Step title="Create the task">
78 Click **Create**. If you haven't trusted the folder yet, Desktop asks you to trust it at this point. The task's detail page opens.
79 </Step>
80</Steps>
60Skip 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, and the **Trigger** card offers the presets listed in [Schedule options](#schedule-options).
8161
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).
63
64**6. Pick the local folder**
65
66In the **Local folder** row, select a folder. **Create** stays unavailable until you pick one.
67
68**7. Set the schedule**
69
70Back in the **Trigger** card, select a [schedule preset](#schedule-options).
71
72**8. Choose the permission mode and model**
73
74In the instructions box's toolbar, select a [permission mode](#permissions-for-scheduled-tasks) and model. If you leave them unchanged, runs use your Claude Code settings and the default model.
75
76**9. Create the task**
77
78Click **Create**. If you haven't trusted the folder yet, Desktop asks you to trust it at this point. The task's detail page opens.
79
8280On the detail page, click the pencil icon to open the [**Edit** form](#manage-scheduled-tasks). There you can change the **Description** that Desktop filled in from your instructions, select **Worktree**, or switch the schedule to **Manual**.
8381
8482You can also create a task by describing what you want in any session. For example, "set up a daily code review that runs every morning at 9am" creates a recurring task. A request like "remind me at 3pm tomorrow to check the deploy" creates a one-time task that disables itself after it fires.
from line 113
115113
116114Tasks only run while the desktop app is running and your computer is awake. If your computer sleeps through a scheduled time, the run is skipped. To prevent idle-sleep, turn on **Keep computer awake** in **Settings > This computer > System**. Closing the laptop lid still puts it to sleep.
117115
118<Note>
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) instead.
120</Note>
116> [!NOTE]
117>
118> 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) instead.
121119
122120When a local task fires, a new session appears under a **Scheduled** section in the sidebar. Open it to see what Claude did, review changes, or 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.
123121
desktop-wsl Changed · +9 / -13 lines
from line 14
1414
1515## Start a WSL session
1616
17<Steps>
18 <Step title="Pick a distribution">
19 Start a new session in the Code tab and open the [environment selector](/docs/en/desktop#start-a-session) under the prompt box, or above it in the [earlier layout](/docs/en/desktop#check-which-layout-you-have). Your installed WSL 2 distributions appear under **WSL**. Pick one.
20 </Step>
17**1. Pick a distribution**
2118
22 <Step title="Choose a folder">
23 The session starts in the distribution's home directory. Use the folder picker to choose a project folder. Browsing happens inside the distribution, with Linux paths like `/home/you/project`.
24 </Step>
19Start a new session in the Code tab and open the [environment selector](/docs/en/desktop#start-a-session) under the prompt box, or above it in the [earlier layout](/docs/en/desktop#check-which-layout-you-have). Your installed WSL 2 distributions appear under **WSL**. Pick one.
2520
26 <Step title="Trust the folder">
27 The first session in a folder shows the workspace trust dialog. You grant trust per distribution and folder. A folder you trust in one distribution isn't trusted in another distribution or at the same path on Windows.
28 </Step>
29</Steps>
21**2. Choose a folder**
3022
23The session starts in the distribution's home directory. Use the folder picker to choose a project folder. Browsing happens inside the distribution, with Linux paths like `/home/you/project`.
24
25**3. Trust the folder**
26
27The first session in a folder shows the workspace trust dialog. You grant trust per distribution and folder. A folder you trust in one distribution isn't trusted in another distribution or at the same path on Windows.
28
3129The first session in a distribution takes a little longer while Claude sets up inside it. You can also open a `\\wsl.localhost\...` folder from the normal folder picker, and it reopens inside that distribution.
3230
3331## What works in a WSL session
from line 38
4038* **[Plugins](/docs/en/desktop#install-plugins)**: not available in WSL sessions
4139* **File editing**: you can view files in the [file pane](/docs/en/desktop#open-and-edit-files) but can't edit them there, so ask Claude to make the changes
4240* **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#add-files-and-context-to-prompts).
43
44<a id="check-for-the-terminal-and-connectors" />
4541
4642### If the terminal or connectors are unavailable
4743
devcontainer Changed · +53 / -59 lines
from line 6
66
77This page covers [installing Claude Code in a dev container](#add-claude-code-to-your-dev-container), then a set of self-contained configuration topics: persisting authentication across rebuilds, enforcing organization policy, restricting network egress, and running without permission prompts. Read the ones that match your setup.
88
9<Warning>
10 While the dev container provides substantial protections, no system is completely immune to all attacks.
11 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).
12 Only use dev containers when developing with trusted repositories, and monitor Claude's activities.
13 Avoid mounting host secrets such as `~/.ssh` or cloud credential files into the container; prefer repository-scoped or short-lived tokens.
14</Warning>
9> [!WARNING]
10>
11> 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).
13> Only use dev containers when developing with trusted repositories, and monitor Claude's activities.
14> Avoid mounting host secrets such as `~/.ssh` or cloud credential files into the container; prefer repository-scoped or short-lived tokens.
1515
16<Accordion title="How dev containers work with your editor">
17 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="Diagram showing an editor on the host connecting to a Docker dev container. Claude Code, the terminal, and build tools run inside the container. The host repository is bind-mounted into the container as the workspace." width="640" height="300" data-path="images/devcontainer-architecture.svg" />
16> **How dev containers work with your editor**
17>
18> 
19>
20> 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.
21>
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) or run `claude` in the integrated terminal; both run inside the container and share the same `~/.claude` configuration.
1823
19 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=a0a340b1f2afc6a590696102c8acaaca" className="hidden dark:block" alt="Diagram showing an editor on the host connecting to a Docker dev container. Claude Code, the terminal, and build tools run inside the container. The host repository is bind-mounted into the container as the workspace." width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />
20
21 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.
22
23 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) or run `claude` in the integrated terminal; both run inside the container and share the same `~/.claude` configuration.
24</Accordion>
25
2624## Add Claude Code to your dev container
2725
2826Claude Code installs into any dev container through the [Claude Code Dev Container Feature](https://github.com/anthropics/devcontainer-features/tree/main/src/claude-code).
from line 29
3129
3230When you open the container in VS Code or Codespaces, the feature also adds the Claude Code VS Code extension; other editors ignore that part.
3331
34<Tip>
35 New to dev containers? The [VS Code Dev Containers tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial) walks through installing Docker, the extension, and opening your first container. For a fuller hardened example with a firewall and persistent volumes, see [Try the reference container](#try-the-reference-container).
36</Tip>
32> [!TIP]
33>
34> New to dev containers? The [VS Code Dev Containers tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial) walks through installing Docker, the extension, and opening your first container. For a fuller hardened example with a firewall and persistent volumes, see [Try the reference container](#try-the-reference-container).
3735
38<Steps>
39 <Step title="Create or update devcontainer.json">
40 Save the following as `.devcontainer/devcontainer.json` in your repository, or add the `features` block to your existing file.
36**1. Create or update devcontainer.json**
4137
42 The version tag at the end, such as `:1.0`, pins the feature's install script, not the Claude Code release. The feature installs the latest Claude Code, and Claude Code auto-updates itself inside the container by default.
38Save the following as `.devcontainer/devcontainer.json` in your repository, or add the `features` block to your existing file.
4339
44 To pin the CLI version or disable auto-update, see [Enforce organization policy](#enforce-organization-policy).
40The version tag at the end, such as `:1.0`, pins the feature's install script, not the Claude Code release. The feature installs the latest Claude Code, and Claude Code auto-updates itself inside the container by default.
4541
46 ```json .devcontainer/devcontainer.json theme={null}
47 {
48 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
49 "features": {
50 "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
51 }
52 }
53 ```
42To pin the CLI version or disable auto-update, see [Enforce organization policy](#enforce-organization-policy).
5443
55 Replace the `image` line with your project's base image or remove it if your existing file uses a Dockerfile.
44```json .devcontainer/devcontainer.json theme={null}
45{
46 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
47 "features": {
48 "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
49 }
50}
51```
5652
57 The Claude Code feature installs Node.js itself when the base image doesn't provide it. If that install fails and the build stops with `Failed to install Node.js and npm`, add `"ghcr.io/devcontainers/features/node:1": {}` to the `features` block above the Claude Code feature and rebuild.
58 </Step>
53Replace the `image` line with your project's base image or remove it if your existing file uses a Dockerfile.
5954
60 <Step title="Rebuild the container">
61 Open the VS Code Command Palette with `Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows and Linux, and run **Dev Containers: Rebuild Container**.
55The Claude Code feature installs Node.js itself when the base image doesn't provide it. If that install fails and the build stops with `Failed to install Node.js and npm`, add `"ghcr.io/devcontainers/features/node:1": {}` to the `features` block above the Claude Code feature and rebuild.
6256
63 For other tools, follow that tool's rebuild action: see [rebuilding in GitHub Codespaces](https://docs.github.com/en/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace), the [Dev Containers CLI](https://github.com/devcontainers/cli), or your IDE's dev container documentation.
64 </Step>
57**2. Rebuild the container**
6558
66 <Step title="Sign in to Claude Code">
67 Open a terminal in the rebuilt container and run `claude`, then follow the authentication prompt.
68 </Step>
69</Steps>
59Open the VS Code Command Palette with `Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows and Linux, and run **Dev Containers: Rebuild Container**.
7060
61For other tools, follow that tool's rebuild action: see [rebuilding in GitHub Codespaces](https://docs.github.com/en/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace), the [Dev Containers CLI](https://github.com/devcontainers/cli), or your IDE's dev container documentation.
62
63**3. Sign in to Claude Code**
64
65Open a terminal in the rebuilt container and run `claude`, then follow the authentication prompt.
66
7167What you see at the authentication prompt depends on your provider:
7268
7369* **Anthropic**: sign in through a browser with your Claude or Anthropic Console account
from line 73
7773
7874See [Choose your API provider](/docs/en/admin-setup#choose-your-api-provider) to decide which path fits your organization.
7975
80<Note>
81 If the browser sign-in completes but the callback never reaches the container, copy the code shown in the browser and paste it at the `Paste code here if prompted` prompt in the terminal. This can happen when the editor's port forwarding doesn't route the localhost callback.
82</Note>
76> [!NOTE]
77>
78> If the browser sign-in completes but the callback never reaches the container, copy the code shown in the browser and paste it at the `Paste code here if prompted` prompt in the terminal. This can happen when the editor's port forwarding doesn't route the localhost callback.
8379
8480## Persist authentication and settings across rebuilds
8581
from line 148
152148
153149The [`anthropics/claude-code`](https://github.com/anthropics/claude-code/tree/main/.devcontainer) repository includes an example dev container that combines the CLI, the egress firewall, persistent volumes, and a Zsh-based shell. It is provided as a working example rather than a maintained base image; use it to see how the pieces fit together before applying them to your own configuration.
154150
155<Steps>
156 <Step title="Install prerequisites">
157 Install VS Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
158 </Step>
151**1. Install prerequisites**
159152
160 <Step title="Clone the reference">
161 Clone the [Claude Code repository](https://github.com/anthropics/claude-code) and open it in VS Code.
162 </Step>
153Install VS Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
163154
164 <Step title="Reopen in container">
165 When prompted, click **Reopen in Container**, or run **Dev Containers: Reopen in Container** from the Command Palette.
166 </Step>
155**2. Clone the reference**
167156
168 <Step title="Start Claude Code">
169 Once the container finishes building, open a terminal with `` Ctrl+` `` and run `claude` to sign in and start your first session.
170 </Step>
171</Steps>
157Clone the [Claude Code repository](https://github.com/anthropics/claude-code) and open it in VS Code.
158
159**3. Reopen in container**
160
161When prompted, click **Reopen in Container**, or run **Dev Containers: Reopen in Container** from the Command Palette.
162
163**4. Start Claude Code**
164
165Once the container finishes building, open a terminal with `` Ctrl+` `` and run `claude` to sign in and start your first session.
172166
173167To use this configuration with your own project, copy the `.devcontainer/` directory into your repository and adjust the Dockerfile for your toolchain, or return to [Add Claude Code to your dev container](#add-claude-code-to-your-dev-container) to add only the feature to a setup you already have.
174168
errors Changed · +224 / -382 lines
### You've hit your session limit ### You've hit your monthly spend limit ### Spend limit reached ### Routines are disabled by your organization's policy ### Remote Control couldn't refresh your login ### Remote Control could not renew this computer's connection ### Remote Control stopped because the signed-in account changed ### Remote Control stopped because the app running the session signed out or switched accounts ### Could not refresh your login because another Claude Code process is refreshing it ### Couldn't save your login ### Artifacts need a claude.ai login ### Administrator policy requires a Cloud gateway sign-in ### The proxy refused the connection ### The cloud environments service returned an empty or unexpected response ### Failed to fetch session from Sessions API ### Couldn't reconnect to your Remote Control session ### Sessions ended while this machine was offline ### Couldn't share the transcript ### Couldn't send feedback ### MCP tool name over 128 characters ### tool\_use.name over 200 characters ### There's an issue with the selected model ### Couldn't confirm model with the API ### API error when checking the picked model ### Model is restricted by your organization's settings ### Can't switch to the default model ### Couldn't save it as your default ### Effort isn't available with thinking turned off ### Invalid data in redacted\_thinking block ### role 'system' must precede an 'assistant' message ### Invalid encrypted\_content in search\_result block ### Safeguards flagged a request for Claude's reasoning ### Conflict between `--bg` and `--print` ### Couldn't tell whether `--bg` is a flag or text ### Conflict between a system prompt flag and its file form ### Invalid `--agents` configuration ### Cloud sessions cannot be created from a `--restricted` session ### Cloud sessions are disabled by your organization's policy ### Cloud sessions use your claude.ai login ### Couldn't verify your organization's policy for cloud sessions ### Nothing was stashed because a folder replaced a tracked file ### The `--json-schema` value is not a valid JSON Schema ### Temp directory refused or cannot be created ### Directory couldn't be resolved to a real location ### Not carried over to the sessions Remote Control starts ### `--sandbox` or `--no-sandbox` is not supported by claude remote-control ### Cannot add MCP server when managed settings allow only plugin servers ### Can't read .mcp.json ### MCP server was not saved or removed ### MCP server may not have been saved or removed ### Server is Anthropic-hosted and doesn't support local OAuth ### Server rejected the Authorization header minted by the configured headersHelper ### /security-review fails without origin/HEAD ### No shell command in a skill or command was run ### Input must be provided when using `--print` ### Claude Code can't read the keyboard here ### stream-json input carried over 256M characters with no newline ### No GitHub account is connected to your Claude account ### Your connected GitHub account can't see the repository ### The GitHub App preflight failed transiently ### The repository upload can't follow a git setting ### GitHub isn't connected to your Claude account ### A GitHub organization policy is blocking Claude ### Single sign-on authorization needed ### Windows reported an error (EBADF) when Claude Code read this session's transcript file ### Claude Code couldn't restart ### Couldn't open Claude Desktop ### /terminal-setup left your Zed keymap unchanged ### Custom output styles can't be selected over Remote Control ### Output styles are saved to local settings which this session doesn't load ### /recap only runs when you ask for it yourself ### /feedback is disabled by your organization's policy ### plugin eval is currently in early access ### Marketplace name is another spelling of a reserved name ### Claude Code refuses the marketplace name ### Plugin command references user\_config in a shell command ### Plugin is required by your organization ### Plugin was not uninstalled ### No such tool available ### Path cannot contain null bytes ### File is too large to read as an image ### subagent\_type is required ### Failed to write to a teammate's inbox ### Teammate's agent definition was not restored ### Cross-session message was dropped at the recipient session's inbox ### Refusing to read, write, or search a path ### Task output swap refused ### Disk quota or temp filesystem is full ### File is not valid UTF-8 ### The source file is not valid UTF-8 text ### Not published: that file is on a network share ### Not published: Claude sent the same content again after a newer version of the artifact turned it away ### Reading a local file from outside the connected folders in a Cowork session ### WebFetch cannot fetch localhost ### WebFetch domain safety check failed ### This session is running in another terminal ### This session's saved conversation is no longer on disk ### Worktree has commits that are not pushed anywhere ### Session isn't responding ### Session agent no longer available ### This session restarted after its next /loop wakeup was due ### No LLM gateway: a gateway set in your shell isn't passed to a session opened from another folder ### Could not locate the Claude CLI on PATH ### The connection to Claude Code ended before this message completed ### Restored the code, but skipped files ### No files were restored ### Transcript saving is off because CLAUDE\_CODE\_SKIP\_PROMPT\_HISTORY is set ### Transcript saving is off because of an inherited CLAUDE\_CODE\_CHILD\_SESSION marker ### Claude Code exited after an unrecoverable interface error ### Agent descriptions are over the 15.0k-token limit ### Hook needs quotes around a path with a space ### Instruction file not loaded ### A skill, command, or workflow wasn't loaded because its name is reserved ### Skill or command name refused ### Remote managed settings failed to load ### Managed settings were not approved ### Managed settings block the default model ### Managed settings don't allow this API provider ### MCP server is blocked by enterprise managed policy ### MCP server name is reserved ### Managed settings document could not be parsed ### Unable to read managed policy settings ### Managed settings contain invalid entries, including PreToolUse/PermissionRequest hooks that are NOT loaded ### otelHeadersHelper failed ### Malformed Tool(content) rule ### crossSessionInbound must be one of accept, hold, refuse ### ANTHROPIC\_FOUNDRY\_RESOURCE must be a Foundry resource name ### The 200K limit isn't enforced ### Unrecognized model ID on a request ### Sandbox allow entries are ignored under a managed lock
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 6
66
77Except for [Wrapper and IDE errors](#wrapper-and-ide-errors), which the launching program prints rather than Claude Code itself, these errors and recovery commands apply across the CLI, the [Desktop app](/docs/en/desktop), and [cloud sessions](/docs/en/claude-code-on-the-web), since all three wrap the same Claude Code CLI. For other surface-specific issues, see the troubleshooting section on that surface's page.
88
9<Note>
10 Claude Code calls the Claude API for model responses, so most runtime errors map to an underlying API error code. This page covers what each error means inside Claude Code and how to recover. For the raw HTTP status code definitions, see the [Claude Platform error reference](https://platform.claude.com/docs/en/api/errors).
11</Note>
9> [!NOTE]
10>
11> Claude Code calls the Claude API for model responses, so most runtime errors map to an underlying API error code. This page covers what each error means inside Claude Code and how to recover. For the raw HTTP status code definitions, see the [Claude Platform error reference](https://platform.claude.com/docs/en/api/errors).
1212
1313## Find your error
1414
from line 96
9696| `claude.ai rejected the session token` / `session token rejected` | [Authentication](#claude-ai-rejected-the-session-token) |
9797| `MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)` | [Authentication](#mcp-server-needs-you-to-sign-in-again) |
9898| `rejected the credential from its headersHelper` / `rejected the Authorization header in its config` | [Authentication](#mcp-server-needs-you-to-sign-in-again) |
99| `(check the helper, then start a new task or chat)` / `(update it, then start a new task or chat)` | [Authentication](#mcp-credential-rejected-in-cowork) |
99100| `MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate` | [Authentication](#mcp-server-needs-you-to-sign-in-again) |
100101| `MCP server "<name>" requires re-authorization (token expired)` | [Authentication](#mcp-server-needs-you-to-sign-in-again) |
101102| `This server's URL is missing or not a valid URL, so sign-in can't start` | [Authentication](#mcp-server-url-is-missing-or-not-a-valid-url) |
from line 267
266267| `Custom output styles can't be selected over Remote Control or from a relayed message` | [Command-line errors](#custom-output-styles-cant-be-selected-over-remote-control) |
267268| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [Command-line errors](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |
268269| `/recap only runs when you ask for it yourself in this session` | [Command-line errors](#recap-only-runs-when-you-ask-for-it-yourself) |
270| `/feedback is disabled by your organization's policy`, or the same for `/bug` or `/share` | [Command-line errors](#feedback-is-disabled-by-your-organizations-policy) |
269271| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [Plugin errors](#plugin-eval-is-currently-in-early-access) |
270272| `cannot be evaluated where sessions load it` | [Test plugins with evals](/docs/en/plugin-evals#cannot-be-evaluated-where-sessions-load-it) |
271273| `Marketplace "<name>" is registered from an untrusted source` | [Plugin errors](#marketplace-is-registered-from-an-untrusted-source) |
from line 302
300302| `File is covered by a Read deny rule in your permission settings` | [Tool errors](#file-is-covered-by-a-read-deny-rule) |
301303| `cannot contain null bytes (\0)` | [Tool errors](#path-cannot-contain-null-bytes) |
302304| `Path contains null bytes` | [Tool errors](#path-cannot-contain-null-bytes) |
305| `File is too large to read as an image (the limit is 128MB)` | [Tool errors](#file-is-too-large-to-read-as-an-image) |
306| `Cannot read this as an image: <path> is a pipe or a device` | [Tool errors](#file-is-too-large-to-read-as-an-image) |
303307| `subagent_type is required: the general-purpose agent is not available in this session` | [Tool errors](#subagent-type-is-required) |
304308| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [Tool errors](#memory-index-is-over-its-read-limit) |
305309| `pkill: refusing to run` | [Tool errors](#pkill-pattern-matches-the-claude-code-process) |
from line 329
325329| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [Tool errors](#the-source-file-is-not-valid-utf-8-text) |
326330| `the source file has the replacement character U+FFFD` | [Tool errors](#the-source-file-is-not-valid-utf-8-text) |
327331| `Not published: that file is on a network share` | [Tool errors](#not-published-that-file-is-on-a-network-share) |
332| `Not published: Claude sent the same content again after a newer version of the artifact turned it away` / `Not published: Claude sent its changes again over the same file after a newer version of the artifact turned them away` | [Tool errors](#not-published-a-newer-version-of-the-artifact-turned-it-away) |
328333| `Reading a local file from outside this session's connected folders, or through a link, needs the approval card` | [Tool errors](#reading-a-local-file-from-outside-the-connected-folders) |
329334| `cannot read file_path (...) — the file could not be examined, and no one can answer the approval card` | [Tool errors](#reading-a-local-file-from-outside-the-connected-folders) |
330335| `WebFetch cannot fetch localhost or other hostnames without a dot` | [Tool errors](#webfetch-cannot-fetch-localhost) |
from line 355
350355| `Session <id> was stopped while the respawn was in flight` | [Background session errors](#session-was-stopped-while-the-respawn-was-in-flight) |
351356| `This session was running agent '<name>', which is no longer available` | [Background session errors](#session-agent-no-longer-available) |
352357| `This session restarted <time> after its next /loop wakeup was due, so that wakeup will not fire` | [Background session errors](#restarted-after-its-next-loop-wakeup-was-due) |
358| `No LLM gateway: a gateway set in your shell isn't passed to a session opened from another folder` | [Background session errors](#no-llm-gateway-opened-from-another-folder) |
359| `No LLM gateway: opened from another folder · respawn from <folder>` | [Background session errors](#no-llm-gateway-opened-from-another-folder) |
353360| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [Background session errors](#claude_code_process_wrapper-launcher-errors) |
354361| `EUNKNOWN: unknown error, uv_spawn` | [Background session errors](#eunknown-when-starting-a-background-session) |
355362| `EACCES: permission denied, posix_spawn` | [Background session errors](#eacces-when-starting-a-background-session) |
from line 744
737744
738745Most errors in this section mean a quota tied to your account or plan has been reached. Three work differently: [`Server is temporarily limiting requests`](#server-is-temporarily-limiting-requests) is a server-side throttle unrelated to your plan quota, [`Usage credits required for 1M context`](#usage-credits-required-for-1m-context) is an entitlement check rather than an exhausted quota, and [`The prompt to confirm went unanswered`](#the-prompt-to-confirm-went-unanswered) means a usage-credits consent prompt closed unanswered, whether or not a quota was reached.
739746
740<h3 id="youve-hit-your-session-limit">
741 You've hit your session limit
742</h3>
747### You've hit your session limit
743748
744749Subscription plans include a rolling usage allowance. When it runs out you see one of these messages:
745750
from line 850
845850* For Anthropic API keys, see the [rate limits reference](https://platform.claude.com/docs/en/api/rate-limits) for how tiers work and how to set per-workspace caps
846851* Reduce concurrency: lower [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/en/env-vars), avoid running many parallel subagents, or switch to a smaller model with `/model` for high-volume scripted runs
847852
848<h3 id="youve-hit-your-monthly-spend-limit">
849 You've hit your monthly spend limit
850</h3>
853### You've hit your monthly spend limit
851854
852855Your plan's included usage can't cover this request, and the [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) that would otherwise pay for it have reached a spend limit. That happens when one of your plan's usage windows has run out, or when the request is one that only usage credits pay for, such as a request to a model that [bills to usage credits](/docs/en/model-config#fable-and-usage-credits). The message names whose limit blocked you. The text after the `·` says how to get that limit increased, and varies with your plan and whether you manage billing:
853856
from line 876
873876* If the message names a reset time for your plan's window, you can wait for it instead
874877* Run `/usage` to see your plan's windows and when each resets
875878
876<h3 id="spend-limit-reached">
877 Spend limit reached
878</h3>
879### Spend limit reached
879880
880881You connect through a [Claude apps gateway](/docs/en/claude-apps-gateway) and have passed a [spend cap](/docs/en/claude-apps-gateway-spend-limits) your gateway operator set. The gateway blocks your requests until the named period resets or the operator raises the cap. It marks each blocked `429` response `x-should-retry: false`, so Claude Code shows this message without retrying.
881882
from line 1108
11071108* Authenticate with a Console API key instead of your subscription. See [Claude Console authentication](/docs/en/authentication#claude-console-authentication) for setup.
11081109* If you are the admin and do not see an option to enable access, contact [Anthropic support](https://support.claude.com)
11091110
1110<h3 id="routines-are-disabled-by-your-organizations-policy">
1111 Routines are disabled by your organization's policy
1112</h3>
1111### Routines are disabled by your organization's policy
11131112
11141113An Owner in your Team or Enterprise organization has turned off [cloud scheduled tasks](/docs/en/routines), formerly routines, at the organization level. The error appears when you try to create or run one, for example at [claude.ai/code/routines](https://claude.ai/code/routines). On Claude Code v2.1.227 or later, the same setting also [hides `/schedule`](/docs/en/routines#troubleshooting) in the CLI.
11151114
from line 1143
11441143* If the variable isn't set in your shell, check the `env` key in your [settings files](/docs/en/settings#where-settings-live), which applies environment variables to every session
11451144* For this and the other Remote Control startup messages, see [Troubleshoot Remote Control](/docs/en/remote-control#troubleshooting)
11461145
1147<h3 id="remote-control-couldnt-refresh-your-login">
1148 Remote Control couldn't refresh your login
1149</h3>
1146### Remote Control couldn't refresh your login
11501147
11511148Claude Code runs a live [Remote Control](/docs/en/remote-control) connection on short-lived credentials that it obtains and renews using your saved claude.ai login. When claude.ai stops accepting that login, or Claude Code has no saved login left, Claude Code stops Remote Control and needs you to sign in again. Either failure can happen while Claude Code is still connecting or later, when it renews the credentials.
11521149
from line 1178
11811178
11821179Before v2.1.238, Claude Code reported the cases that now say `Signed out of Claude` as `JWT refresh failed: no OAuth token — run /login`, and stopped Remote Control with `Claude.ai login expired — run /login to restore Remote Control` as soon as one login refresh got no answer.
11831180
1184<h3 id="remote-control-could-not-renew-this-computers-connection">
1185 Remote Control could not renew this computer's connection
1186</h3>
1181### Remote Control could not renew this computer's connection
11871182
11881183This warning appears in the terminal running [`claude remote-control`](/docs/en/remote-control#start-a-remote-control-session) when the server can't use your claude.ai login to renew its connection's credential before it expires. The warning's last sentence says how long the current credential still works, or that it has already expired:
11891184
from line 1191
11961191* If the warning tells you to run `claude /login`, open another terminal on the machine running the server, run `claude /login` there, and sign in with your claude.ai account
11971192* If the server still can't sign in once the connection's credential has expired, it prints an error containing `Poll: Authentication failed (401)` and stops. Sign in again as the warning's second sentence says, then run `claude remote-control` again in the terminal where the server stopped.
11981193
1199<h3 id="remote-control-stopped-because-the-signed-in-account-changed">
1200 Remote Control stopped because the signed-in account changed
1201</h3>
1194### Remote Control stopped because the signed-in account changed
12021195
12031196Claude Code shows this line during a [Remote Control](/docs/en/remote-control) session when you sign in to a different claude.ai account or organization on this machine. You made the switch outside the Claude Code session, for example by running `/login` in another terminal.
12041197
from line 1210
12171210
12181211Before v2.1.234, Claude Code didn't notice when you switched to a different account or organization outside the Claude Code session. Claude Code kept the Remote Control session connected until a later request to the Remote Control server failed with `Remote Control server rejected the request (HTTP 404)`. That failure could come hours after the switch.
12191212
1220<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">
1221 Remote Control stopped because the app running the session signed out or switched accounts
1222</h3>
1213### Remote Control stopped because the app running the session signed out or switched accounts
12231214
12241215When the Claude desktop app or an IDE hosts your session, Claude Code gets its login token from that app rather than from `/login`. When claude.ai rejects that token, Claude Code asks the app for a new one. If the app answers that it's signed out, or that it's now signed in to a different Claude account, Claude Code ends the [Remote Control](/docs/en/remote-control) session and sends the app one of these lines:
12251216
from line 1302
13111302* In non-interactive mode, run `claude` in the same environment, complete `/login`, then rerun your command. For automation that can't sign in interactively, authenticate with `ANTHROPIC_API_KEY` or [generate a long-lived token with `claude setup-token`](/docs/en/authentication#generate-a-long-lived-token).
13121303* If signing in keeps failing, see [Login and authentication](/docs/en/troubleshoot-install#login-and-authentication)
13131304
1314<h3 id="could-not-refresh-your-login">
1315 Could not refresh your login because another Claude Code process is refreshing it
1316</h3>
1305### Could not refresh your login because another Claude Code process is refreshing it
13171306
13181307This message doesn't mean your login was rejected. Your saved claude.ai login had expired and needed renewing. Another Claude Code process on the same machine held the shared refresh lock, or exited and left it behind, and the refresh made no progress while this session waited. Claude Code stops the request before sending it:
13191308
from line 1324
13351324* If the message keeps returning, close other Claude Code windows and processes, then retry.
13361325* If it returns with no other Claude Code process running, run `/login`. Signing in again doesn't wait on the refresh lock.
13371326
1338<h3 id="couldnt-save-your-login">
1339 Couldn't save your login
1340</h3>
1327### Couldn't save your login
13411328
13421329You signed in with claude.ai, but Claude Code couldn't save the login to its credential store, so the login didn't complete. On macOS this can happen when the login keychain locks, for example on sleep or idle, after Claude Code has already read or saved credentials in it during the same session.
13431330
from line 1370
13831370
13841371* Run `/login`, complete the sign-in, then start the session again
13851372
1386<h3 id="artifacts-need-a-claude-ai-login">
1387 Artifacts need a claude.ai login
1388</h3>
1373### Artifacts need a claude.ai login
13891374
13901375Claude Code refused an [artifact](/docs/en/artifacts) publish or read because the session has no claude.ai login it can use for artifacts.
13911376
from line 1388
14031388* When the message says the credential is injected by the session's host environment, you can't change it in that session; start a session that is signed in to claude.ai
14041389* See [Availability](/docs/en/artifacts#availability) for the other requirements artifacts have, such as plan, model provider, and organization policy
14051390
1406<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">
1407 Administrator policy requires a Cloud gateway sign-in
1408</h3>
1391### Administrator policy requires a Cloud gateway sign-in
14091392
14101393An administrator's [managed settings](/docs/en/managed-settings) on this machine set [`forceLoginMethod`](/docs/en/settings-reference#forceloginmethod) to `"gateway"` or set [`forceLoginGatewayUrl`](/docs/en/settings-reference#forcelogingatewayurl). Unless you select a cloud provider through a variable such as `CLAUDE_CODE_USE_BEDROCK`, Claude Code then accepts only the [Claude apps gateway](/docs/en/claude-apps-gateway) sign-in. You see one of two messages:
14111394
from line 1516
15331516
15341517Update the header value where the server is configured, then reconnect from `/mcp`.
15351518
1536Before v2.1.273, the expired sign-in, `headersHelper`, and `Authorization` header cases all showed `MCP server "<name>" requires re-authorization (token expired)`.
1519In a [Cowork](https://claude.com/docs/cowork/overview) session on your machine in the Claude Desktop app, these messages mean the MCP server rejected a credential it was given. Fix the one the message names, then start a new task or chat in Cowork:
15371520
1521```text theme={null}
1522MCP server "<name>" rejected the credential from its headersHelper (check the helper, then start a new task or chat)
1523MCP server "<name>" rejected the Authorization header in its config (update it, then start a new task or chat)
1524```
1525
1526* **`headersHelper` credential rejected**: check that the helper returns a credential the server accepts, then start a new task or chat in Cowork
1527* **`Authorization` header rejected**: update the `Authorization` value under `headers` in that server's configuration, then start a new task or chat in Cowork
1528
1529Before v2.1.302, a Cowork session showed the `run /mcp to reconnect` endings instead, although `/mcp` isn't available there. If you see such an ending in Cowork, still check the helper or update the header, then start a new task or chat. Before v2.1.273, the expired sign-in, `headersHelper`, and `Authorization` header cases all showed `MCP server "<name>" requires re-authorization (token expired)`.
1530
15381531A server can also refuse a tool call with HTTP 403 `insufficient_scope` to ask you to authorize a scope, sometimes one your token already lists. The message names that scope:
15391532
15401533```text theme={null}
from line 1978
19851978
19861979See [Network access](/docs/en/cloud-environments#network-access) for access levels and the default allowlist. Local CLI sessions are not affected by this policy.
19871980
1988<h3 id="the-proxy-refused-the-connection">
1989 The proxy refused the connection
1990</h3>
1981### The proxy refused the connection
19911982
19921983You see this message when Claude reads an [artifact](/docs/en/artifacts) through the proxy you set in `HTTPS_PROXY` or a related [proxy variable](/docs/en/network-config#environment-variables). Artifact content comes from `*.frame.claudeusercontent.com`, so Claude Code first sends the proxy a `CONNECT` request asking it to open a tunnel to that host. When the proxy refuses, nothing reaches the host, and the message carries the proxy's HTTP status:
19931984
from line 2002
20112002
20122003Before v2.1.238, Claude Code reported a refused tunnel as a generic network error.
20132004
2014<h3 id="the-cloud-environments-service-returned-an-empty-or-unexpected-response">
2015 The cloud environments service returned an empty or unexpected response
2016</h3>
2005### The cloud environments service returned an empty or unexpected response
20172006
20182007Claude Code requests your [cloud environments](/docs/en/cloud-environments) list at several points, such as when you create a cloud session from the CLI or run [`/remote-env`](/docs/en/cloud-environments#select-an-environment-from-the-cli). When it can't read the server's answer, it shows one of these messages:
20192008
from line 2021
20322021
20332022Before v2.1.236, Claude Code showed a raw JavaScript TypeError instead of these messages.
20342023
2035<h3 id="failed-to-fetch-session-from-sessions-api">
2036 Failed to fetch session from Sessions API
2037</h3>
2024### Failed to fetch session from Sessions API
20382025
20392026This message means Claude Code found the [cloud session you asked to pull into your terminal](/docs/en/claude-code-on-the-web#from-cloud-to-terminal) but couldn't read its conversation history from Anthropic's servers, so it didn't open it:
20402027
from line 2037
20502037
20512038Before v2.1.296, Claude Code didn't retry a failed read, and after one it could open the session with an empty conversation and report success instead of printing this message.
20522039
2053<h3 id="couldnt-reconnect-to-your-remote-control-session">
2054 Couldn't reconnect to your Remote Control session
2055</h3>
2040### Couldn't reconnect to your Remote Control session
20562041
20572042```text theme={null}
20582043Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.
from line 2053
20682053
20692054If the server reports instead that the previous session is gone, you don't see this message. Claude Code starts a new session in its place or shows [`Previous session is unavailable — run /remote-control to start a new one`](/docs/en/remote-control#previous-session-is-unavailable).
20702055
2071<h3 id="sessions-ended-while-this-machine-was-offline">
2072 Sessions ended while this machine was offline
2073</h3>
2056### Sessions ended while this machine was offline
20742057
20752058Claude Code shows this message in the terminal running [`claude remote-control`](/docs/en/remote-control#start-a-remote-control-session) after your machine was offline long enough that the server cleaned up the Remote Control environment your machine was serving. The sessions in that environment ended, and you can't resume them. The count is the number of sessions that ended.
20762059
from line 2066
20832066* When Claude Code lists kept worktrees under this message, pick up any uncommitted work from them
20842067* Run `claude remote-control` to start a fresh environment
20852068
2086<h3 id="couldnt-share-the-transcript">
2087 Couldn't share the transcript
2088</h3>
2069### Couldn't share the transcript
20892070
20902071After you agree to share your session transcript from a survey prompt, such as the [session quality survey](/docs/en/data-usage#session-quality-surveys), Claude Code uploads it to Anthropic, or saves a local archive instead on third-party providers, on [Claude apps gateway](/docs/en/claude-apps-gateway) sessions, and when no Anthropic credentials are available. This message means the share didn't complete.
20912072
from line 2081
21002081* Run `/feedback` to send the transcript with a description of what happened. See [Report an error](#report-an-error) if `/feedback` is unavailable in your environment
21012082* If other requests are failing too, check your network connection and see [Unable to connect to API](#unable-to-connect-to-api)
21022083
2103<h3 id="couldnt-send-feedback">
2104 Couldn't send feedback
2105</h3>
2084### Couldn't send feedback
21062085
21072086You sent a report from the [`/feedback`, `/bug`, or `/share` dialog](/docs/en/commands#all-commands) and the upload to Anthropic failed. The dialog keeps your text so you can retry.
21082087
from line 2324
23452324* Configure your gateway to forward the `anthropic-beta` header. See [feature pass-through](/docs/en/llm-gateway-protocol#feature-pass-through) for what gateways must forward.
23462325* As a fallback, set [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/en/env-vars) before launching. [Disable pre-release capabilities](/docs/en/llm-gateway-protocol#disable-pre-release-capabilities) covers the exact scope.
23472326
2327Before v2.1.302, this error could also name the field `diagnostics` with no gateway involved. It appeared when a session that had already used the Anthropic API moved to Amazon Bedrock or Google Cloud's Agent Platform without a restart. For example, a session you left open moves to Bedrock when you run [`/setup-bedrock`](/docs/en/commands) in another Claude Code window. On those versions, run `/clear` in that session or restart it.
2328
23482329### Tool input schema is invalid
23492330
23502331A tool in the request declared an `input_schema` that fails the API's JSON Schema validation, so the API rejected the whole request. The number after `tools.` is the failing tool's position in the request's tool list, not a name you can look up.
from line 2351
23702351* Remove or [disable](/docs/en/mcp#disable-a-server-without-removing-it) the MCP server that declares the invalid schema. The error names the tool only by position. On v2.1.216 or later, check each server's log for a line naming a tool whose input schema would be rejected. If no log names one, disable servers one at a time.
23712352* If you maintain the server, fix the tool's `input_schema`. The schema must be valid JSON Schema, and top-level property names must be 1 to 64 characters long and use only ASCII letters and digits, `_`, `.`, and `-`. See [Tools with invalid input schemas](/docs/en/mcp#tools-with-invalid-input-schemas).
23722353
2373<h3 id="mcp-tool-name-over-128-characters">
2374 MCP tool name over 128 characters
2375</h3>
2354### MCP tool name over 128 characters
23762355
23772356An MCP server lists a tool whose full name, such as `mcp__<server>__<tool>`, is longer than the 128 characters the API accepts. Claude Code [leaves that tool out of the tools it sends to Claude](/docs/en/mcp#tools-with-names-longer-than-128-characters), and the server's other tools keep working. In a session you start with `claude --debug` from your shell, Claude Code writes this message to the debug log at `~/.claude/debug/<session-id>.txt`:
23782357
from line 2367
23882367
23892368Before v2.1.292, Claude Code sent the tool anyway, and the API rejected every request that included it with `API Error: 400 ... tools.N.custom.name: String should have at most 128 characters`.
23902369
2391<h3 id="tool-use-name-over-200-characters">
2392 tool\_use.name over 200 characters
2393</h3>
2370### tool\_use.name over 200 characters
23942371
23952372A tool call in the conversation history carries a name longer than the 200 characters the API accepts in a request:
23962373
from line 2383
24062383
24072384Before v2.1.281, the overlong name stayed in the history and the API rejected every request that re-sent the conversation, including `/compact` and `--resume`, so this error repeated and the conversation was stuck.
24082385
2409<h3 id="theres-an-issue-with-the-selected-model">
2410 There's an issue with the selected model
2411</h3>
2386### There's an issue with the selected model
24122387
24132388The configured model name was not recognized or your account lacks access to it. As of v2.1.160 the trailing hint, shown here in its interactive form, varies by surface.
24142389
from line 2439
24642439* In the Agent SDK, `setModel()` fails with this message and the session keeps running on its previous model. In the TypeScript SDK, call [`supportedModels()`](/docs/en/agent-sdk/typescript#query-object) to list the models you can switch to.
24652440* Before v2.1.265, `/model` also rejected the `opusplan[1m]` alias spelling with this error. On those versions, update Claude Code, or set the model in [settings](/docs/en/model-config#setting-your-model) or with `--model` instead.
24662441
2467<h3 id="couldnt-confirm-model-with-the-api">
2468 Couldn't confirm model with the API
2469</h3>
2442### Couldn't confirm model with the API
24702443
24712444You switched models through the [Agent SDK](/docs/en/agent-sdk/typescript) `setModel()` method or an app that runs the Claude Code CLI for you, such as the [Desktop app](/docs/en/desktop), and the request that confirms the model ID with your API endpoint got no answer within five seconds. The session keeps its current model.
24722445
from line 2454
24812454* Switch to the model again
24822455* If the switch keeps failing, check that Claude Code can reach your API endpoint; see [Network and connection errors](#network-and-connection-errors)
24832456
2484<h3 id="api-error-model-not-changed">
2485 API error when checking the picked model
2486</h3>
2457### API error when checking the picked model
24872458
24882459You picked a model with `/model <name>`, or an app connected to the session requested the switch. The API refused the minimal request Claude Code sends to verify the model, for a reason that has no entry of its own, such as a rate limit or a server error. The session keeps its current model, and the message ends by saying so:
24892460
from line 2516
25452516* For the per-model wording, you can keep working in the current session by switching to another model: run `/model` in the CLI, call [`setModel()`](/docs/en/agent-sdk/typescript#query-object) on the TypeScript SDK's `Query` object in streaming input mode, or call [`set_model()`](/docs/en/agent-sdk/python#claudesdkclient) on the Python SDK's `ClaudeSDKClient`
25462517* For the organization-policy wording, update before you continue
25472518
2548<h3 id="model-is-restricted-by-your-organizations-settings">
2549 Model is restricted by your organization's settings
2550</h3>
2519### Model is restricted by your organization's settings
25512520
25522521Your organization admin has disabled this model in the claude.ai admin console, or managed settings exclude it through an [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist or a [`deniedModels`](/docs/en/model-config#block-specific-models-or-versions) list. The notice appears at startup when `--model`, `ANTHROPIC_MODEL`, or the `model` setting named the restricted model, and it names the model the session uses instead. If managed settings leave no permitted model for the session to use, see [Managed settings block the default model](#managed-settings-block-the-default-model). The substitution notice can also appear mid-session after an admin disables the model a session is running on in the claude.ai admin console.
25532522
from line 2536
25672536* If the restricted model was set in `--model`, `ANTHROPIC_MODEL`, the `model` field of a settings file, or the `model` frontmatter of a [subagent](/docs/en/sub-agents#choose-a-model), skill, or command, remove or update that value so the notice doesn't recur
25682537* If you need access to the restricted model, ask your organization admin to enable it. See [Organization model restrictions](/docs/en/model-config#organization-model-restrictions).
25692538
2570<h3 id="cant-switch-to-the-default-model">
2571 Can't switch to the default model
2572</h3>
2539### Can't switch to the default model
25732540
25742541You picked the Default model, for example by selecting the Default row in the `/model` picker or typing `/model default`. Claude Code refused the switch, so the session keeps its current model.
25752542
from line 2576
26092576
26102577Before v2.1.260, the managed-plugin refusal read `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`. Claude Code retried the plugin load once and then refused later switches in the session, even when your organization managed no plugins. Restart the session to run the plugin load again on those versions.
26112578
2612<h3 id="couldnt-save-it-as-your-default">
2613 Couldn't save it as your default
2614</h3>
2579### Couldn't save it as your default
26152580
26162581You picked a model to save as your default, for example with `/model <name>` or `Enter` in the `/model` picker, and Claude Code couldn't write the pick to your user settings file, `~/.claude/settings.json`. The switch itself applied, so the current session runs on the model you picked, but your default is unchanged and the next session starts on the old value.
26172582
from line 2629
26642629* If you can't upgrade, run `/model` and select Opus 4.6 or Sonnet 4.6 instead
26652630* If you hit this in the [Agent SDK](/docs/en/agent-sdk/overview), upgrade the SDK package instead. Opus 4.8 needs TypeScript SDK v0.3.154 or later and Python SDK v0.2.88 or later. Sonnet 5 needs TypeScript SDK v0.3.197 or later. Opus 5 needs TypeScript SDK v0.3.219 or later. Opus 5.5 needs TypeScript SDK v0.3.280 or later. Sonnet 5.5 needs TypeScript SDK v0.3.284 or later
26662631
2667<h3 id="effort-isnt-available-with-thinking-turned-off">
2668 Effort isn't available with thinking turned off
2669</h3>
2632### Effort isn't available with thinking turned off
26702633
26712634You turned [extended thinking](/docs/en/model-config#extended-thinking) off and ran at an [effort level](/docs/en/model-config#adjust-effort-level) above `high`. The model doesn't accept that combination, so the API rejected the request.
26722635
from line 2695
27322695* If you are using Opus 4.7 or Opus 4.8, run `claude update` first. Versions before v2.1.156 can trigger this error during normal tool use, and `/rewind` doesn't clear it.
27332696* Run `/rewind`, or press Esc twice, to step back to a checkpoint before the corrupted turn and continue from there. See [Checkpointing](/docs/en/checkpointing) for how checkpoints are created and restored.
27342697
2735<h3 id="invalid-data-in-redacted-thinking-block">
2736 Invalid data in redacted\_thinking block
2737</h3>
2698### Invalid data in redacted\_thinking block
27382699
27392700The API refused the request with a 400 because it couldn't accept a `redacted_thinking` block that an earlier turn in the conversation history carries.
27402701
27412702```text theme={null}
2742API Error: 400 ... Invalid `data` in `redacted_thinking` block
2743```
2744
2745Claude Code leaves the conversation's earlier thinking out of the request and retries once, so the session continues without showing the error. Before v2.1.282, Claude Code kept the refused block, and every later turn failed with the same error.
2746
2747**What to do:**
2748
2749* If you're on v2.1.281 or earlier and every turn fails with this error, run `claude update` and resume the session
2750* If the error persists, run `/clear` to start a conversation that doesn't carry the block
2751
2752### Unsupported tool content removed
2753
2754When Claude Code connects directly to the Anthropic API and loads or previews a saved session, it removes tool content the Anthropic API doesn't accept and leaves this line where removed content sat between two thinking blocks:
2755
2756```text theme={null}
2757[Unsupported tool content removed]
2758```
2759
2760Such content reaches a session file when something other than the Anthropic API answered in the API's format, typically a third-party proxy set through [`ANTHROPIC_BASE_URL`](/docs/en/env-vars) that translates another provider's tool calls. Claude Code removes it only when th
2703API Error: 400 ... Invalid `data` in `redacted_thinkin
fast-mode Changed · +14 / -14 lines
from line 2
22
33> Get faster Opus responses in Claude Code by toggling fast mode.
44
5<Note>
6 Fast mode is in [research preview](#research-preview). The feature, pricing, and availability may change based on feedback.
7</Note>
5> [!NOTE]
6>
7> Fast mode is in [research preview](#research-preview). The feature, pricing, and availability may change based on feedback.
88
99Fast mode is a high-speed configuration for Claude Opus, making the model up to 2.5x faster at a higher cost per token. Toggle it on with `/fast` when you need speed for interactive work like rapid iteration or live debugging, and toggle it off when cost matters more than latency.
1010
from line 120
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
123<Note>
124 Fast mode usage draws directly from usage credits, even if you have remaining usage on your plan.
125</Note>
123> [!NOTE]
124>
125> Fast mode usage draws directly from usage credits, even if you have remaining usage on your plan.
126126
127127* **Paid Console organization**: Claude Console accounts don't use usage credits, and your organization pays for fast mode per token with the rest of its API usage. On the Console's free Evaluation plan, `/fast` shows "Fast mode unavailable during evaluation. Please purchase credits." To clear it, purchase credits in your [Console billing settings](https://platform.claude.com/settings/billing).
128128* **Owner enablement for Team and Enterprise**: fast mode is disabled by default for Team and Enterprise organizations. An Owner must explicitly [enable fast mode](#enable-fast-mode-for-your-organization) before users can access it.
129129
130<Note>
131 Four organization settings can block turning fast mode on with `/fast`:
132
133 * **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."
134 * **Fast mode turned off by managed settings**: if your organization deploys [managed settings](/docs/en/managed-settings) 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 * **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.
136 * **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</Note>
130> [!NOTE]
131>
132> Four organization settings can block turning fast mode on with `/fast`:
133>
134> * **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) 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.
136> * **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.
138138
139139### Enable fast mode for your organization
140140
feature-availability Changed · +93 / -90 lines
from line 79
7979 <td>✓</td>
8080 <td>✗</td>
8181 <td>✓</td>
82 <td>See note <sup><a href="#fn1">1</a></sup></td>
82 <td>See note <sup>[1](#fn1)</sup></td>
8383 <td>✓</td>
8484 </tr>
8585
from line 97
9797 <td>[Auto mode](/docs/en/auto-mode-config)</td>
9898 <td>✓</td>
9999 <td>✓</td>
100 <td>See note <sup><a href="#fn2">2</a></sup></td>
100 <td>See note <sup>[2](#fn2)</sup></td>
101101 <td>✓</td>
102 <td>See note <sup><a href="#fn2">2</a></sup></td>
103 <td>See note <sup><a href="#fn2">2</a></sup></td>
102 <td>See note <sup>[2](#fn2)</sup></td>
103 <td>See note <sup>[2](#fn2)</sup></td>
104104 </tr>
105105
106106 <tr>
from line 115
115115
116116 <tr>
117117 <td>[Cross-session messaging](/docs/en/cross-session-messaging)</td>
118 <td>✓ <sup><a href="#fn5">5</a></sup></td>
119 <td>✓ (same machine) <sup><a href="#fn5">5</a></sup></td>
120 <td>✓ (same machine) <sup><a href="#fn5">5</a></sup></td>
121 <td>✓ (same machine) <sup><a href="#fn5">5</a></sup></td>
122 <td>✓ (same machine) <sup><a href="#fn5">5</a></sup></td>
123 <td>✓ (same machine) <sup><a href="#fn5">5</a></sup></td>
118 <td>✓ <sup>[5](#fn5)</sup></td>
119 <td>✓ (same machine) <sup>[5](#fn5)</sup></td>
120 <td>✓ (same machine) <sup>[5](#fn5)</sup></td>
121 <td>✓ (same machine) <sup>[5](#fn5)</sup></td>
122 <td>✓ (same machine) <sup>[5](#fn5)</sup></td>
123 <td>✓ (same machine) <sup>[5](#fn5)</sup></td>
124124 </tr>
125125
126126 <tr>
from line 176
176176 <tr>
177177 <td>[Analytics dashboard and API](/docs/en/analytics)</td>
178178 <td>✓ (dashboard: Team and Enterprise; API: Enterprise)</td>
179 <td>✓ <sup><a href="#fn4">4</a></sup></td>
179 <td>✓ <sup>[4](#fn4)</sup></td>
180180 <td>✗</td>
181181 <td>✗</td>
182182 <td>✗</td>
from line 197
197197 <td>[Zero Data Retention](/docs/en/zero-data-retention)</td>
198198 <td>✓ (qualified Enterprise accounts)</td>
199199 <td>✓ (qualified accounts)</td>
200 <td>See note <sup><a href="#fn3">3</a></sup></td>
200 <td>See note <sup>[3](#fn3)</sup></td>
201201 <td>✓ (qualified accounts)</td>
202 <td>See note <sup><a href="#fn3">3</a></sup></td>
203 <td>See note <sup><a href="#fn3">3</a></sup></td>
202 <td>See note <sup>[3](#fn3)</sup></td>
203 <td>See note <sup>[3](#fn3)</sup></td>
204204 </tr>
205205 </tbody>
206206</table>
207207
208<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> On Google Cloud's Agent Platform, web search is available for Opus 4, Sonnet 4, Haiku 4.5, and later models.<br />
209<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 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). For the permission mode a session on these providers starts in, see [Which mode a session starts in](/docs/en/permission-modes#which-mode-a-session-starts-in).<br />
210<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> Subject to your agreement with the cloud provider.<br />
211<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> Dashboard and API only. [Contribution metrics](/docs/en/analytics#enable-contribution-metrics) requires a claude.ai Team or Enterprise organization.<br />
212<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 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) and your sessions on other machines only from a session that is connected to [Remote Control](/docs/en/remote-control). To connect, you need a claude.ai sign-in and the other [Remote Control requirements](/docs/en/remote-control#requirements). See [Message sessions on other machines](/docs/en/cross-session-messaging#message-sessions-on-other-machines).
208<sup>1</sup> On Google Cloud's Agent Platform, web search is available for Opus 4, Sonnet 4, Haiku 4.5, and later models.\
213209
214<Note>
215 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#requirements) and [server-managed settings](/docs/en/server-managed-settings#platform-availability), whatever the gateway forwards. Some Anthropic-only features such as the [Advisor](/docs/en/advisor) work only if the gateway forwards requests intact to the Anthropic API.
210<sup>2</sup> 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). For the permission mode a session on these providers starts in, see [Which mode a session starts in](/docs/en/permission-modes#which-mode-a-session-starts-in).\
216211
217 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#how-the-connection-method-changes-client-behavior).
218</Note>
212<sup>3</sup> Subject to your agreement with the cloud provider.\
219213
214<sup>4</sup> Dashboard and API only. [Contribution metrics](/docs/en/analytics#enable-contribution-metrics) requires a claude.ai Team or Enterprise organization.\
215
216<sup>5</sup> 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) and your sessions on other machines only from a session that is connected to [Remote Control](/docs/en/remote-control). To connect, you need a claude.ai sign-in and the other [Remote Control requirements](/docs/en/remote-control#requirements). See [Message sessions on other machines](/docs/en/cross-session-messaging#message-sessions-on-other-machines).
217
218> [!NOTE]
219>
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#requirements) and [server-managed settings](/docs/en/server-managed-settings#platform-availability), whatever the gateway forwards. Some Anthropic-only features such as the [Advisor](/docs/en/advisor) work only if the gateway forwards requests intact to the Anthropic API.
221>
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#how-the-connection-method-changes-client-behavior).
223
220224### Summary by provider
221225
222226Each 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#default-behaviors-by-api-provider) for what traffic still reaches Anthropic and how to opt out.
223227
224<Tabs>
225 <Tab title="Amazon Bedrock">
226 **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [web search](/docs/en/tools-reference#websearch-tool-behavior), [fast mode](/docs/en/fast-mode), [Advisor](/docs/en/advisor), [Channels](/docs/en/channels), the [analytics dashboard](/docs/en/analytics), [server-managed settings](/docs/en/server-managed-settings), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).
228**Amazon Bedrock**
227229
228 **Partial support:**
230**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [web search](/docs/en/tools-reference#websearch-tool-behavior), [fast mode](/docs/en/fast-mode), [Advisor](/docs/en/advisor), [Channels](/docs/en/channels), the [analytics dashboard](/docs/en/analytics), [server-managed settings](/docs/en/server-managed-settings), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).
229231
230 * [Desktop](/docs/en/desktop): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)
231 * [Auto mode](/docs/en/auto-mode-config): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only
232 * [Cross-session messaging](/docs/en/cross-session-messaging): between your sessions on this machine only <sup><a href="#fn5">5</a></sup>
233 * [Zero Data Retention](/docs/en/zero-data-retention): subject to your AWS agreement
232**Partial support:**
234233
235 **Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](/docs/en/github-actions) or [GitLab CI/CD](/docs/en/gitlab-ci-cd). For web lookups, use the [WebFetch tool](/docs/en/tools-reference#webfetch-tool-behavior) with a specific URL.
236 </Tab>
234* [Desktop](/docs/en/desktop): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)
235* [Auto mode](/docs/en/auto-mode-config): 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): between your sessions on this machine only <sup>[5](#fn5)</sup>
237* [Zero Data Retention](/docs/en/zero-data-retention): subject to your AWS agreement
237238
238 <Tab title="Claude Platform on AWS">
239 **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](/docs/en/fast-mode), [Advisor](/docs/en/advisor), [Channels](/docs/en/channels), [GitHub Actions](/docs/en/github-actions), the [analytics dashboard](/docs/en/analytics), [server-managed settings](/docs/en/server-managed-settings), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).
239**Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](/docs/en/github-actions) or [GitLab CI/CD](/docs/en/gitlab-ci-cd). For web lookups, use the [WebFetch tool](/docs/en/tools-reference#webfetch-tool-behavior) with a specific URL.
240240
241 **Available where Amazon Bedrock is not:** [web search](/docs/en/tools-reference#websearch-tool-behavior).
241**Claude Platform on AWS**
242242
243 **Partial support:**
243**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](/docs/en/fast-mode), [Advisor](/docs/en/advisor), [Channels](/docs/en/channels), [GitHub Actions](/docs/en/github-actions), the [analytics dashboard](/docs/en/analytics), [server-managed settings](/docs/en/server-managed-settings), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).
244244
245 * [Cross-session messaging](/docs/en/cross-session-messaging): between your sessions on this machine only <sup><a href="#fn5">5</a></sup>
245**Available where Amazon Bedrock is not:** [web search](/docs/en/tools-reference#websearch-tool-behavior).
246246
247 **Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitLab CI/CD](/docs/en/gitlab-ci-cd).
248 </Tab>
247**Partial support:**
249248
250 <Tab title="Google Cloud's Agent Platform">
251 **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](/docs/en/fast-mode), [Advisor](/docs/en/advisor), [Channels](/docs/en/channels), the [analytics dashboard](/docs/en/analytics), [server-managed settings](/docs/en/server-managed-settings), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).
249* [Cross-session messaging](/docs/en/cross-session-messaging): between your sessions on this machine only <sup>[5](#fn5)</sup>
252250
253 **Partial support:**
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).
254252
255 * [Desktop](/docs/en/desktop): 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)
256 * [Web search](/docs/en/tools-reference#websearch-tool-behavior): Opus 4, Sonnet 4, Haiku 4.5, and later models
257 * [Auto mode](/docs/en/auto-mode-config): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only
258 * [Cross-session messaging](/docs/en/cross-session-messaging): between your sessions on this machine only <sup><a href="#fn5">5</a></sup>
259 * [Zero Data Retention](/docs/en/zero-data-retention): subject to your Google Cloud agreement
253**Google Cloud's Agent Platform**
260254
261 **Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](/docs/en/github-actions) or [GitLab CI/CD](/docs/en/gitlab-ci-cd).
262 </Tab>
255**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](/docs/en/fast-mode), [Advisor](/docs/en/advisor), [Channels](/docs/en/channels), the [analytics dashboard](/docs/en/analytics), [server-managed settings](/docs/en/server-managed-settings), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).
263256
264 <Tab title="Microsoft Foundry">
265 **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](/docs/en/fast-mode), [Advisor](/docs/en/advisor), [Channels](/docs/en/channels), [GitLab CI/CD](/docs/en/gitlab-ci-cd), the [analytics dashboard](/docs/en/analytics), [server-managed settings](/docs/en/server-managed-settings), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).
257**Partial support:**
266258
267 **Partial support:**
259* [Desktop](/docs/en/desktop): 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#websearch-tool-behavior): Opus 4, Sonnet 4, Haiku 4.5, and later models
261* [Auto mode](/docs/en/auto-mode-config): 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): between your sessions on this machine only <sup>[5](#fn5)</sup>
263* [Zero Data Retention](/docs/en/zero-data-retention): subject to your Google Cloud agreement
268264
269 * [Desktop](/docs/en/desktop): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)
270 * [Auto mode](/docs/en/auto-mode-config): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only
271 * [Cross-session messaging](/docs/en/cross-session-messaging): between your sessions on this machine only <sup><a href="#fn5">5</a></sup>
272 * [Zero Data Retention](/docs/en/zero-data-retention): subject to your Azure agreement
265**Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](/docs/en/github-actions) or [GitLab CI/CD](/docs/en/gitlab-ci-cd).
273266
274 **Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](/docs/en/github-actions).
275 </Tab>
267**Microsoft Foundry**
276268
277 <Tab title="Anthropic Console">
278 **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription).
269**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](/docs/en/fast-mode), [Advisor](/docs/en/advisor), [Channels](/docs/en/channels), [GitLab CI/CD](/docs/en/gitlab-ci-cd), the [analytics dashboard](/docs/en/analytics), [server-managed settings](/docs/en/server-managed-settings), and the [`/design-sync` and `/import` commands](/docs/en/commands#all-commands).
279270
280 Everything in [CLI capabilities that vary by provider](#cli-capabilities-that-vary-by-provider) is available, except that [fast mode](/docs/en/fast-mode) requires [provisioned access](/docs/en/fast-mode#enable-fast-mode-for-your-organization). [Server-managed settings](/docs/en/server-managed-settings) 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#platform-availability) for how to cover those sessions.
281 </Tab>
282</Tabs>
271**Partial support:**
283272
273* [Desktop](/docs/en/desktop): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)
274* [Auto mode](/docs/en/auto-mode-config): 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): between your sessions on this machine only <sup>[5](#fn5)</sup>
276* [Zero Data Retention](/docs/en/zero-data-retention): subject to your Azure agreement
277
278**Alternatives:** for scheduling, use [`/loop`](/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](/docs/en/github-actions).
279
280**Anthropic Console**
281
282**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription).
283
284Everything in [CLI capabilities that vary by provider](#cli-capabilities-that-vary-by-provider) is available, except that [fast mode](/docs/en/fast-mode) requires [provisioned access](/docs/en/fast-mode#enable-fast-mode-for-your-organization). [Server-managed settings](/docs/en/server-managed-settings) 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#platform-availability) for how to cover those sessions.
285
284286## Availability by subscription plan
285287
286288If 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.
from line 291
289291
290292| Feature | Pro | Max | Team | Enterprise |
291293| :- | :- | :- | :- | :- |
292| [Cloud sessions](/docs/en/claude-code-on-the-web) | ✓ | ✓ | ✓ | ✓ <sup><a href="#fn6">6</a></sup> |
294| [Cloud sessions](/docs/en/claude-code-on-the-web) | ✓ | ✓ | ✓ | ✓ <sup>[6](#fn6)</sup> |
293295| [Cloud scheduled tasks](/docs/en/routines) | ✓ | ✓ | ✓ | ✓ |
294296| [Remote Control](/docs/en/remote-control) | ✓ | ✓ | Admin-enabled | Admin-enabled |
295297| [Channels](/docs/en/channels) | ✓ | ✓ | Admin-enabled | Admin-enabled |
from line 305
303305| [SSO](https://support.claude.com/en/articles/9266767-what-is-the-team-plan) | ✗ | ✗ | ✓ | ✓ |
304306| SCIM | ✗ | ✗ | ✗ | ✓ |
305307| [Compliance API](https://platform.claude.com/docs/en/api/compliance) | ✗ | ✗ | ✗ | ✓ |
306| [Zero Data Retention](/docs/en/zero-data-retention) | ✗ | ✗ | ✗ | ✓ <sup><a href="#fn7">7</a></sup> |
308| [Zero Data Retention](/docs/en/zero-data-retention) | ✗ | ✗ | ✗ | ✓ <sup>[7](#fn7)</sup> |
307309
308<span id="fn6" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>6</sup> 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).<br />
309<span id="fn7" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>7</sup> Not included in the standard Enterprise plan. Requires separate enablement by Anthropic for qualified accounts. See [Zero Data Retention](/docs/en/zero-data-retention).
310<sup>6</sup> 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).\
311
312<sup>7</sup> Not included in the standard Enterprise plan. Requires separate enablement by Anthropic for qualified accounts. See [Zero Data Retention](/docs/en/zero-data-retention).
310313
311314For 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).
312315
features-overview Changed · +241 / -237 lines
from line 4
44
55Claude Code combines a model that reasons about your code with [built-in tools](/docs/en/how-claude-code-works#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.
66
7<Note>
8 For how the core agentic loop works, see [How Claude Code works](/docs/en/how-claude-code-works).
9</Note>
7> [!NOTE]
8>
9> For how the core agentic loop works, see [How Claude Code works](/docs/en/how-claude-code-works).
1010
1111**New to Claude Code?** Start with [CLAUDE.md](/docs/en/memory) for project conventions, then add other extensions [as specific triggers come up](#build-your-setup-over-time).
1212
from line 68
6868
6969Some features can seem similar. For a deeper walkthrough of choosing between them, see [Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents](https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more) on the blog. Here's how to tell them apart.
7070
71<Tabs>
72 <Tab title="Skill vs Subagent">
73 Skills and subagents solve different problems:
71**Skill vs Subagent**
7472
75 * **Skills** are reusable content you can load into any context
76 * **Subagents** are isolated workers that run separately from your main conversation
73Skills and subagents solve different problems:
7774
78 | Aspect | Skill | Subagent |
79 | - | - | - |
80 | **What it is** | Reusable instructions, knowledge, or workflows | Isolated worker with its own context |
81 | **Key benefit** | Share content across contexts | Context isolation. Work happens separately, only summary returns |
82 | **[Context window](/docs/en/context-window) impact** | Adds to your main window | Uses a separate window with its own input and output tokens |
83 | **Best for** | Reference material, invocable workflows | Tasks that read many files, parallel work, specialized workers |
75* **Skills** are reusable content you can load into any context
76* **Subagents** are isolated workers that run separately from your main conversation
8477
85 **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).
78| Aspect | Skill | Subagent |
79| - | - | - |
80| **What it is** | Reusable instructions, knowledge, or workflows | Isolated worker with its own context |
81| **Key benefit** | Share content across contexts | Context isolation. Work happens separately, only summary returns |
82| **[Context window](/docs/en/context-window) impact** | Adds to your main window | Uses a separate window with its own input and output tokens |
83| **Best for** | Reference material, invocable workflows | Tasks that read many files, parallel work, specialized workers |
8684
87 **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.
85**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).
8886
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) for details.
90 </Tab>
87**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.
9188
92 <Tab title="CLAUDE.md vs Skill">
93 Both store instructions, but they load differently and serve different purposes.
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) for details.
9490
95 | Aspect | CLAUDE.md | Skill |
96 | - | - | - |
97 | **Loads** | Every session, automatically | On demand |
98 | **Can include files** | Yes, with `@path` imports | Yes, with `@path` imports |
99 | **Can trigger workflows** | No | Yes, with `/<name>` |
100 | **Best for** | "Always do X" rules | Reference material, invocable workflows |
91**CLAUDE.md vs Skill**
10192
102 **Put it in CLAUDE.md** if Claude should always know it: coding conventions, build commands, project structure, "never do X" rules.
93Both store instructions, but they load differently and serve different purposes.
10394
104 **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).
95| Aspect | CLAUDE.md | Skill |
96| - | - | - |
97| **Loads** | Every session, automatically | On demand |
98| **Can include files** | Yes, with `@path` imports | Yes, with `@path` imports |
99| **Can trigger workflows** | No | Yes, with `/<name>` |
100| **Best for** | "Always do X" rules | Reference material, invocable workflows |
105101
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.
107 </Tab>
102**Put it in CLAUDE.md** if Claude should always know it: coding conventions, build commands, project structure, "never do X" rules.
108103
109 <Tab title="CLAUDE.md vs Output style">
110 Both give Claude standing instructions. CLAUDE.md carries what Claude should know, and an output style sets how Claude responds.
104**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).
111105
112 | Aspect | CLAUDE.md | Output style |
113 | - | - | - |
114 | **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#change-your-output-style) whenever you want |
116 | **Best for** | Build commands, conventions, "never do X" rules | Shorter responses, explanations alongside code, a non-engineering role |
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.
117107
118 **Put it in CLAUDE.md** if it's true of the project whatever style you're in: coding conventions, build commands, project structure.
108**CLAUDE.md vs Output style**
119109
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#built-in-output-styles), and you can write your own.
110Both give Claude standing instructions. CLAUDE.md carries what Claude should know, and an output style sets how Claude responds.
121111
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).
123 </Tab>
112| Aspect | CLAUDE.md | Output style |
113| - | - | - |
114| **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#change-your-output-style) whenever you want |
116| **Best for** | Build commands, conventions, "never do X" rules | Shorter responses, explanations alongside code, a non-engineering role |
124117
125 <Tab title="CLAUDE.md vs Rules vs Skills">
126 All three store instructions, but they load differently:
118**Put it in CLAUDE.md** if it's true of the project whatever style you're in: coding conventions, build commands, project structure.
127119
128 | Aspect | CLAUDE.md | `.claude/rules/` | Skill |
129 | - | - | - | - |
130 | **Loads** | Every session | Every session, or when matching files are opened | On demand, when invoked or relevant |
131 | **Scope** | Whole project | Can be scoped to file paths | Task-specific |
132 | **Best for** | Core conventions and build commands | Language-specific or directory-specific guidelines | Reference material, repeatable workflows |
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#built-in-output-styles), and you can write your own.
133121
134 **Use CLAUDE.md** for instructions every session needs: build commands, test conventions, project architecture.
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).
135123
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.
124**CLAUDE.md vs Rules vs Skills**
137125
138 **Use skills** for content Claude only needs sometimes, like API documentation or a deployment checklist you trigger with `/<name>`.
139 </Tab>
126All three store instructions, but they load differently:
140127
141 <Tab title="Subagent vs Dynamic workflow">
142 Both do work outside your main conversation. With subagents, Claude decides turn by turn what runs next. In a workflow, the script decides:
128| Aspect | CLAUDE.md | `.claude/rules/` | Skill |
129| - | - | - | - |
130| **Loads** | Every session | Every session, or when matching files are opened | On demand, when invoked or relevant |
131| **Scope** | Whole project | Can be scoped to file paths | Task-specific |
132| **Best for** | Core conventions and build commands | Language-specific or directory-specific guidelines | Reference material, repeatable workflows |
143133
144 * **Subagents** are workers Claude spawns, each returning a summary to the conversation that spawned it
145 * **[Dynamic workflows](/docs/en/workflows)** are scripts Claude writes that run many subagents in the background and return one result
134**Use CLAUDE.md** for instructions every session needs: build commands, test conventions, project architecture.
146135
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 when it spawned them can also [message each other](/docs/en/sub-agents#what-loads-at-startup).
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.
148137
149 **Use a dynamic workflow** when a job [outgrows a handful of subagents](/docs/en/workflows#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#ask-for-a-workflow-in-your-prompt).
138**Use skills** for content Claude only needs sometimes, like API documentation or a deployment checklist you trigger with `/<name>`.
150139
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). [Run agents in parallel](/docs/en/agents) compares the other ways to run more than one Claude at once, including sessions you hand off and check back on later.
152 </Tab>
140**Subagent vs Dynamic workflow**
153141
154 <Tab title="MCP vs Skill">
155 MCP connects Claude to external services. Skills extend what Claude knows, including how to use those services effectively.
142Both do work outside your main conversation. With subagents, Claude decides turn by turn what runs next. In a workflow, the script decides:
156143
157 | Aspect | MCP | Skill |
158 | - | - | - |
159 | **What it is** | Protocol for connecting to external services | Knowledge, workflows, and reference material |
160 | **Provides** | Tools and data access | Knowledge, workflows, reference material |
161 | **Examples** | Slack integration, database queries, browser control | Code review checklist, deploy workflow, API style guide |
144* **Subagents** are workers Claude spawns, each returning a summary to the conversation that spawned it
145* **[Dynamic workflows](/docs/en/workflows)** are scripts Claude writes that run many subagents in the background and return one result
162146
163 These solve different problems and work well together:
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 when it spawned them can also [message each other](/docs/en/sub-agents#what-loads-at-startup).
164148
165 **MCP** gives Claude purpose-built tools for an external system, with the connection and authentication handled by the server.
149**Use a dynamic workflow** when a job [outgrows a handful of subagents](/docs/en/workflows#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#ask-for-a-workflow-in-your-prompt).
166150
167 **Skills** give Claude knowledge about how to use those tools effectively, plus workflows you can trigger with `/<name>`. A skill might include your team's database schema and query patterns, or a `/post-to-slack` workflow with your team's message formatting rules.
168 </Tab>
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). [Run agents in parallel](/docs/en/agents) compares the other ways to run more than one Claude at once, including sessions you hand off and check back on later.
169152
170 <Tab title="Hook vs Skill">
171 Claude Code runs a hook at a lifecycle event; it loads a skill into context for Claude to apply.
153**MCP vs Skill**
172154
173 | Aspect | Hook | Skill |
174 | - | - | - |
175 | **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#hook-events) such as `PostToolUse` or `SessionStart` | You typing `/<name>`, or Claude matching the description to your task |
177 | **Determinism** | Fires on its event without Claude deciding | Claude interprets the instructions; outcome can vary |
178 | **Context cost** | Zero unless the hook returns output | Description loads each session; full content loads when used |
179 | **Best for** | Linting after edits, blocking unsafe commands, logging, notifications | Workflows that need reasoning, reference material, multi-step tasks |
155MCP connects Claude to external services. Skills extend what Claude knows, including how to use those services effectively.
180156
181 **Use a hook** when the action must happen the same way every time and doesn't need Claude to think. For example: format on save, reject `rm -rf /`, post a Slack message when a session ends.
157| Aspect | MCP | Skill |
158| - | - | - |
159| **What it is** | Protocol for connecting to external services | Knowledge, workflows, and reference material |
160| **Provides** | Tools and data access | Knowledge, workflows, reference material |
161| **Examples** | Slack integration, database queries, browser control | Code review checklist, deploy workflow, API style guide |
182162
183 **Use a skill** when Claude should decide how to apply the steps, or when the content is knowledge rather than a script. For example: a `/release` checklist, your API style guide, a debugging playbook.
163These solve different problems and work well together:
184164
185 **Put guardrails in hooks.** An instruction like "never edit `.env`" in CLAUDE.md or a skill is a request, not a guarantee. A `PreToolUse` hook that blocks the edit is enforcement. If a rule must hold every time, make it a hook rather than a prompt instruction.
165**MCP** gives Claude purpose-built tools for an external system, with the connection and authentication handled by the server.
186166
187 **Hook output lands in context.** A `PostToolUse` hook that runs your linter feeds results back as text Claude reads; a `/fix-lint` skill tells Claude how to resolve them.
188 </Tab>
189</Tabs>
167**Skills** give Claude knowledge about how to use those tools effectively, plus workflows you can trigger with `/<name>`. A skill might include your team's database schema and query patterns, or a `/post-to-slack` workflow with your team's message formatting rules.
190168
169**Hook vs Skill**
170
171Claude Code runs a hook at a lifecycle event; it loads a skill into context for Claude to apply.
172
173| Aspect | Hook | Skill |
174| - | - | - |
175| **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#hook-events) such as `PostToolUse` or `SessionStart` | You typing `/<name>`, or Claude matching the description to your task |
177| **Determinism** | Fires on its event without Claude deciding | Claude interprets the instructions; outcome can vary |
178| **Context cost** | Zero unless the hook returns output | Description loads each session; full content loads when used |
179| **Best for** | Linting after edits, blocking unsafe commands, logging, notifications | Workflows that need reasoning, reference material, multi-step tasks |
180
181**Use a hook** when the action must happen the same way every time and doesn't need Claude to think. For example: format on save, reject `rm -rf /`, post a Slack message when a session ends.
182
183**Use a skill** when Claude should decide how to apply the steps, or when the content is knowledge rather than a script. For example: a `/release` checklist, your API style guide, a debugging playbook.
184
185**Put guardrails in hooks.** An instruction like "never edit `.env`" in CLAUDE.md or a skill is a request, not a guarantee. A `PreToolUse` hook that blocks the edit is enforcement. If a rule must hold every time, make it a hook rather than a prompt instruction.
186
187**Hook output lands in context.** A `PostToolUse` hook that runs your linter feeds results back as text Claude reads; a `/fix-lint` skill tells Claude how to resolve them.
188
191189### Understand how features layer
192190
193191Features 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:
from line 232
234232
235233Each feature loads at different points in your session. The tabs below explain when each one loads and what goes into context.
236234
237<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/context-loading.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=aab139e750494a237ae2e0c8f9139b0a" className="dark:hidden" alt="Context loading: CLAUDE.md loads at session start and stays in every request. MCP tool names load at start with full schemas deferred until use. Skills load descriptions at start, full content on invocation. Subagents get isolated context. Hooks run externally." width="720" height="382" data-path="images/context-loading.svg" />
235
238236
239<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/context-loading-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=b274089ef9612d9c760bca9838557626" className="hidden dark:block" alt="Context loading: CLAUDE.md loads at session start and stays in every request. MCP tool names load at start with full schemas deferred until use. Skills load descriptions at start, full content on invocation. Subagents get isolated context. Hooks run externally." width="720" height="382" data-path="images/context-loading-dark.svg" />
237**CLAUDE.md**
240238
241<Tabs>
242 <Tab title="CLAUDE.md">
243 **When:** Session start
239**When:** Session start
244240
245 **What loads:** Full content of all CLAUDE.md files (managed, user, and project levels).
241**What loads:** Full content of all CLAUDE.md files (managed, user, and project levels).
246242
247 **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#how-claude-md-files-load) for details.
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#how-claude-md-files-load) for details.
248244
249 <Tip>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#my-claude-md-is-too-large), run `/doctor`.</Tip>
250 </Tab>
245> [!TIP]
246>
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#my-claude-md-is-too-large), run `/doctor`.
251248
252 <Tab title="Skills">
253 Skills 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) like `/code-review`, `/batch`, and `/debug` that work without setup. You can also create your own.
249**Skills**
254250
255 **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.
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) like `/code-review`, `/batch`, and `/debug` that work without setup. You can also create your own.
256252
257 **What loads:** For model-invocable skills, Claude sees names and descriptions in every request. When you invoke a skill with `/<name>` or Claude loads it automatically, the full content loads into your conversation.
253**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.
258254
259 **How Claude chooses skills:** Claude matches your task against skill descriptions to decide which are relevant. If descriptions are vague or overlap, Claude may load the wrong skill or miss one that would help. To tell Claude to use a specific skill, invoke it with `/<name>`.
255**What loads:** For model-invocable skills, Claude sees names and descriptions in every request. When you invoke a skill with `/<name>` or Claude loads it automatically, the full content loads into your conversation.
260256
261 **Context cost:** Low until used. User-only skills have zero cost until invoked.
257**How Claude chooses skills:** Claude matches your task against skill descriptions to decide which are relevant. If descriptions are vague or overlap, Claude may load the wrong skill or miss one that would help. To tell Claude to use a specific skill, invoke it with `/<name>`.
262258
263 **In subagents:** Skills work differently in subagents. Instead of on-demand loading, skills listed in the subagent's `skills` field are fully preloaded into its context at launch. Subagents can still discover and invoke unlisted project, user, and plugin skills through the Skill tool.
259**Context cost:** Low until used. User-only skills have zero cost until invoked.
264260
265 <Tip>Use `disable-model-invocation: true` for skills with side effects. This saves context and ensures they run only when you name them.</Tip>
266 </Tab>
261**In subagents:** Skills work differently in subagents. Instead of on-demand loading, skills listed in the subagent's `skills` field are fully preloaded into its context at launch. Subagents can still discover and invoke unlisted project, user, and plugin skills through the Skill tool.
267262
268 <Tab title="MCP servers">
269 **When:** Session start.
263> [!TIP]
264>
265> Use `disable-model-invocation: true` for skills with side effects. This saves context and ensures they run only when you name them.
270266
271 **What loads:** Tool names and server instructions from connected servers. Full JSON schemas stay deferred until Claude needs a specific tool.
267**MCP servers**
272268
273 **Context cost:** [Tool search](/docs/en/mcp#scale-with-mcp-tool-search) is on by default, so idle MCP tools consume minimal context.
269**When:** Session start.
274270
275 <Tip>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#automatic-reconnection) if they drop, and you can disconnect servers you're not actively using.</Tip>
276 </Tab>
271**What loads:** Tool names and server instructions from connected servers. Full JSON schemas stay deferred until Claude needs a specific tool.
277272
278 <Tab title="Code intelligence">
279 **When:** After file edits, and on demand when Claude navigates code.
273**Context cost:** [Tool search](/docs/en/mcp#scale-with-mcp-tool-search) is on by default, so idle MCP tools consume minimal context.
280274
281 **What loads:** Type errors and warnings after each file edit. Definition, reference, and type information when Claude looks up a symbol.
275> [!TIP]
276>
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#automatic-reconnection) if they drop, and you can disconnect servers you're not actively using.
282278
283 **Context cost:** Low. Symbol lookups often replace broad file reads, so net context use can go down.
279**Code intelligence**
284280
285 <Tip>The LSP tool is inactive until you install a [code intelligence plugin](/docs/en/plugins/code-intelligence) for your language.</Tip>
286 </Tab>
281**When:** After file edits, and on demand when Claude navigates code.
287282
288 <Tab title="Subagents">
289 **When:** On demand, when you or Claude spawns one for a task.
283**What loads:** Type errors and warnings after each file edit. Definition, reference, and type information when Claude looks up a symbol.
290284
291 **What loads:** Fresh, isolated context containing:
285**Context cost:** Low. Symbol lookups often replace broad file reads, so net context use can go down.
292286
293 * The agent's own system prompt, not the Claude Code system prompt
294 * Full content of skills listed in the agent's `skills:` field
295 * CLAUDE.md and git status. The built-in Explore and Plan agents [start with neither](/docs/en/sub-agents#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.
296 * Whatever context the lead agent passes in the prompt
287> [!TIP]
288>
289> The LSP tool is inactive until you install a [code intelligence plugin](/docs/en/plugins/code-intelligence) for your language.
297290
298 For a [fork](/docs/en/sub-agents#fork-the-current-conversation), Claude Code loads the parent's conversation so far, system prompt, and tools instead.
291**Subagents**
299292
300 **Context cost:** Isolated from main session.
293**When:** On demand, when you or Claude spawns one for a task.
301294
302 <Tip>Use subagents for work that doesn't need your full conversation context. Their isolation prevents bloating your main session.</Tip>
303 </Tab>
295**What loads:** Fresh, isolated context containing:
304296
305 <Tab title="Hooks">
306 **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) for the full list.
297* The agent's own system prompt, not the Claude Code system prompt
298* 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#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.
300* Whatever context the lead agent passes in the prompt
307301
308 **What loads:** Nothing by default. Hooks execute outside the main conversation.
302For a [fork](/docs/en/sub-agents#fork-the-current-conversation), Claude Code loads the parent's conversation so far, system prompt, and tools instead.
309303
310 **Context cost:** Zero, unless the hook returns output that gets added as messages to your conversation.
304**Context cost:** Isolated from main session.
311305
312 <Tip>Hooks are ideal for side effects (linting, logging) that don't need to affect Claude's context.</Tip>
313 </Tab>
314</Tabs>
306> [!TIP]
307>
308> Use subagents for work that doesn't need your full conversation context. Their isolation prevents bloating your main session.
315309
310**Hooks**
311
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) for the full list.
313
314**What loads:** Nothing by default. Hooks execute outside the main conversation.
315
316**Context cost:** Zero, unless the hook returns output that gets added as messages to your conversation.
317
318> [!TIP]
319>
320> Hooks are ideal for side effects (linting, logging) that don't need to affect Claude's context.
321
316322## Learn more
317323
318324Each feature has its own guide with setup instructions, examples, and configuration options.
319325
320<CardGroup cols={2}>
321 <Card title="CLAUDE.md" icon="file-lines" href="/docs/en/memory">
322 Store project context, conventions, and instructions
323 </Card>
326> **[CLAUDE.md](/docs/en/memory)**
327>
328> Store project context, conventions, and instructions
324329
325 <Card title="Skills" icon="brain" href="/docs/en/skills">
326 Give Claude domain expertise and reusable workflows
327 </Card>
330> **[Skills](/docs/en/skills)**
331>
332> Give Claude domain expertise and reusable workflows
328333
329 <Card title="Subagents" icon="users" href="/docs/en/sub-agents">
330 Offload work to isolated context
331 </Card>
334> **[Subagents](/docs/en/sub-agents)**
335>
336> Offload work to isolated context
332337
333 <Card title="Dynamic workflows" icon="network" href="/docs/en/workflows">
334 Run many subagents from one script
335 </Card>
338> **[Dynamic workflows](/docs/en/workflows)**
339>
340> Run many subagents from one script
336341
337 <Card title="Cross-session messaging" icon="terminal" href="/docs/en/cross-session-messaging">
338 Let Claude message your other sessions
339 </Card>
342> **[Cross-session messaging](/docs/en/cross-session-messaging)**
343>
344> Let Claude message your other sessions
340345
341 <Card title="MCP" icon="plug" href="/docs/en/mcp">
342 Connect Claude to external services
343 </Card>
346> **[MCP](/docs/en/mcp)**
347>
348> Connect Claude to external services
344349
345 <Card title="Hooks" icon="bolt" href="/docs/en/hooks-guide">
346 Automate actions with hooks
347 </Card>
350> **[Hooks](/docs/en/hooks-guide)**
351>
352> Automate actions with hooks
348353
349 <Card title="Plugins" icon="puzzle-piece" href="/docs/en/plugins/overview">
350 Bundle and share feature sets
351 </Card>
354> **[Plugins](/docs/en/plugins/overview)**
355>
356> Bundle and share feature sets
352357
353 <Card title="Marketplaces" icon="store" href="/docs/en/plugins/create-marketplace">
354 Host and distribute plugin collections
355 </Card>
356</CardGroup>
358> **[Marketplaces](/docs/en/plugins/create-marketplace)**
359>
360> Host and distribute plugin collections
357361
fullscreen Changed · +7 / -9 lines
### `Claude Code's fullscreen renderer didn't finish starting last time` appears at startup
from line 2
22
33> Enable a smoother, flicker-free rendering mode with mouse support and stable memory usage in long conversations.
44
5<Note>
6 Fullscreen rendering is a [research preview](#research-preview). Whether you [start in fullscreen or in the classic renderer](#fullscreen-by-default) depends on your setup. Run `/tui fullscreen` or `/tui default` to switch in your current conversation. Behavior may change based on feedback.
7</Note>
5> [!NOTE]
6>
7> Fullscreen rendering is a [research preview](#research-preview). Whether you [start in fullscreen or in the classic renderer](#fullscreen-by-default) depends on your setup. Run `/tui fullscreen` or `/tui default` to switch in your current conversation. Behavior may change based on feedback.
88
99Fullscreen rendering is an alternative rendering path for the Claude Code CLI that eliminates flicker, keeps memory usage flat in long conversations, and adds mouse support. It draws the interface on the terminal's alternate screen buffer, like `vim` or `htop`, and only renders messages that are currently visible. This reduces the amount of data sent to your terminal on each update.
1010
1111The difference is most noticeable in terminal emulators where rendering throughput is the bottleneck, such as the VS Code integrated terminal, tmux, and iTerm2. If your terminal scroll position jumps to the top while Claude is working, or the screen flashes as tool output streams in, this mode addresses those.
1212
13<Note>
14 The term fullscreen describes how Claude Code takes over the terminal's drawing surface, the way `vim` does. It has nothing to do with maximizing your terminal window, and works at any window size.
15</Note>
13> [!NOTE]
14>
15> The term fullscreen describes how Claude Code takes over the terminal's drawing surface, the way `vim` does. It has nothing to do with maximizing your terminal window, and works at any window size.
1616
1717## Enable fullscreen rendering
1818
from line 294
294294
295295On Windows, Claude Code already enables full repaint automatically for background sessions and [agent view](/docs/en/agent-view), so you only need to set the variable for an interactive fullscreen session you launched directly.
296296
297<h3 id="fullscreen-renderer-didnt-finish-starting">
298 `Claude Code's fullscreen renderer didn't finish starting last time` appears at startup
299</h3>
297### `Claude Code's fullscreen renderer didn't finish starting last time` appears at startup
300298
301299If a fullscreen session on this machine crashes before it has started successfully, Claude Code starts your next session in the classic renderer and prints one of two lines. A session has started successfully once it has drawn its first frame and then either stayed up for 10 seconds or you ended it with `/exit`, Ctrl+C, or Ctrl+D. The line you see tells you what Claude Code does after this session:
302300
github-actions Changed · +33 / -35 lines
from line 46
4646
4747After installing the GitHub App, Claude Code asks whether to continue with GitHub Actions setup. Choose **Skip for now** to stop with only the GitHub App installed. Run `/install-github-app` again later to finish the workflow and secret steps.
4848
49<Note>
50 * When you install the GitHub App, you grant it several permissions. See [GitHub App permissions](#github-app-permissions) for the full set
51 * 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)
52</Note>
49> [!NOTE]
50>
51> * 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)
5353
5454### Manual setup
5555
5656To configure the Claude Code GitHub Action without running `/install-github-app`, install the app, add a secret, and copy a workflow file yourself:
5757
58<Steps>
59 <Step title="Install the Claude GitHub App">
60 Install the [Claude GitHub App](https://github.com/apps/claude) to your repository. The Claude Code GitHub Action relies on three of the app's permissions:
58**1. Install the Claude GitHub App**
6159
62 * **Contents**: read and write, so Claude can modify repository files
63 * **Issues**: read and write, so Claude can respond to issues
64 * **Pull requests**: read and write, so Claude can create PRs and push changes
60Install the [Claude GitHub App](https://github.com/apps/claude) to your repository. The Claude Code GitHub Action relies on three of the app's permissions:
6561
66 During installation, you also grant permissions that other Claude features use. See [GitHub App permissions](#github-app-permissions) for the full set.
67 </Step>
62* **Contents**: read and write, so Claude can modify repository files
63* **Issues**: read and write, so Claude can respond to issues
64* **Pull requests**: read and write, so Claude can create PRs and push changes
6865
69 <Step title="Add an authentication secret">
70 Add 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).
66During installation, you also grant permissions that other Claude features use. See [GitHub App permissions](#github-app-permissions) for the full set.
7167
72 * `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#generate-a-long-lived-token)
68**2. Add an authentication secret**
7469
75 In 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.
76 </Step>
70Add 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).
7771
78 <Step title="Copy the workflow file">
79 Copy [examples/claude.yml](https://github.com/anthropics/claude-code-action/blob/main/examples/claude.yml) into your repository's `.github/workflows/` directory. The file is a working workflow, not just an example. As committed, Claude responds whenever someone mentions `@claude` in an issue or pull request, authenticating with the `ANTHROPIC_API_KEY` secret. If you added `CLAUDE_CODE_OAUTH_TOKEN` instead, change the workflow's `anthropic_api_key` line to `claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}`.
80 </Step>
81</Steps>
72* `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#generate-a-long-lived-token)
8274
83<Tip>
84 After setup, test the Claude Code GitHub Action by tagging `@claude` in an issue or PR comment.
85</Tip>
75In 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.
8676
77**3. Copy the workflow file**
78
79Copy [examples/claude.yml](https://github.com/anthropics/claude-code-action/blob/main/examples/claude.yml) into your repository's `.github/workflows/` directory. The file is a working workflow, not just an example. As committed, Claude responds whenever someone mentions `@claude` in an issue or pull request, authenticating with the `ANTHROPIC_API_KEY` secret. If you added `CLAUDE_CODE_OAUTH_TOKEN` instead, change the workflow's `anthropic_api_key` line to `claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}`.
80
81> [!TIP]
82>
83> After setup, test the Claude Code GitHub Action by tagging `@claude` in an issue or PR comment.
84
8785### Set up for an organization
8886
8987With quick setup or manual setup, you configure one repository at a time. To roll the Claude Code GitHub Action out across an organization:
from line 286
288286
289287### Protect your credentials
290288
291<Warning>
292 Never commit API keys or OAuth tokens directly to your repository. Always store them as GitHub Secrets and reference them in workflows, for example `anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}`.
293</Warning>
289> [!WARNING]
290>
291> Never commit API keys or OAuth tokens directly to your repository. Always store them as GitHub Secrets and reference them in workflows, for example `anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}`.
294292
295293Grant the workflow only the permissions it needs, and review Claude's changes before merging.
296294
github-actions-cloud-providers Changed · +258 / -264 lines
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
44
55[Claude Code GitHub Actions](/docs/en/github-actions) 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.
66
7<Info>
8 This page builds on the [GitHub Actions setup](/docs/en/github-actions#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</Info>
7> [!NOTE]
8>
9> This page builds on the [GitHub Actions setup](/docs/en/github-actions#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 33
3333
3434Beyond the prerequisites, you create a GitHub identity for the Claude Code GitHub Action, the cloud-side trust configuration, the repository secrets, and the workflow file. The steps below walk through each.
3535
36<Steps>
37 <Step title="Choose a GitHub identity">
38 The Claude Code GitHub Action pushes commits and posts comments through a GitHub identity. The [quick setup](/docs/en/github-actions#quick-setup) installs the official Claude GitHub App for this. With a cloud provider, you choose the identity yourself:
39
40 * **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#github-app-permissions)
42 * **GitHub's automatic `GITHUB_TOKEN`**: no app to create or install, but GitHub doesn't trigger your CI workflows on commits made with it
43
44 The workflow examples in the fourth step authenticate with a custom app. That step also says what to change for the other two options.
45
46 To create a custom app, [register a new GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) with webhooks disabled, since this integration doesn't use them. Grant it three repository permissions:
47
48 * **Contents**: read and write
49 * **Issues**: read and write
50 * **Pull requests**: read and write
51
52 After registering the app, generate a private key and keep the downloaded `.pem` file, note the App ID from the app's settings page, and [install the app](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app) on the repository where the Claude Code GitHub Action runs. You add the key and the ID as secrets in the third step.
53 </Step>
54
55 <Step title="Configure cloud authentication">
56 Configure your cloud to trust the OIDC token that GitHub issues to the workflow, so each workflow run gets short-lived cloud credentials. The bullets in each tab summarize what to create, and each tab links the cloud vendor's own guide for the console-level steps.
57
58 <Tabs>
59 <Tab title="Amazon Bedrock">
60 Create 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):
61
62 * 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#iam-configuration), which grants `bedrock:InvokeModel`, `bedrock:InvokeModelWithResponseStream`, `bedrock:ListInferenceProfiles`, and `bedrock:GetInferenceProfile`, along with two `aws-marketplace` subscription actions
64 * 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
65
66 Note the role's ARN. You add it as a secret in the next step.
67 </Tab>
68
69 <Tab title="Google Cloud's Agent Platform">
70 Create the federation resources in your Google Cloud project, following the [Workload Identity Federation documentation](https://cloud.google.com/iam/docs/workload-identity-federation):
71
72 * Enable three APIs: IAM Credentials, Security Token Service (STS), and the Agent Platform API, whose service name is `aiplatform.googleapis.com`
73 * Create a Workload Identity Pool with a GitHub OIDC provider whose issuer is `https://token.actions.githubusercontent.com`, and add an attribute condition that limits the pool to your repository
74 * Create a dedicated service account with only the `Vertex AI User` role, which is `roles/aiplatform.user`, and allow the pool to impersonate it
75
76 Note the provider's full resource name and the service account's email address. You add them as secrets in the next step.
77 </Tab>
78
79 <Tab title="Microsoft Foundry">
80 Create 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):
81
82 * 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#azure-rbac-configuration) for a narrower custom role
84
85 Note the application's client ID, your tenant ID, and your subscription ID. You add them as secrets in the next step.
86 </Tab>
87 </Tabs>
88 </Step>
89
90 <Step title="Add repository secrets">
91 In the repository where the Claude Code GitHub Action runs, add the secrets for your provider, plus the two app secrets if you created a custom GitHub App in the first step. See GitHub's guide to [using secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
92
93 | Secret | Needed for | Value |
94 | - | - | - |
95 | `AWS_ROLE_TO_ASSUME` | Amazon Bedrock | The ARN of the IAM role |
96 | `GCP_WORKLOAD_IDENTITY_PROVIDER` | Google Cloud's Agent Platform | The provider's full resource name |
97 | `GCP_SERVICE_ACCOUNT` | Google Cloud's Agent Platform | The service account's email address |
98 | `AZURE_CLIENT_ID` | Microsoft Foundry | The Entra application's client ID |
99 | `AZURE_TENANT_ID` | Microsoft Foundry | Your Microsoft Entra tenant ID |
100 | `AZURE_SUBSCRIPTION_ID` | Microsoft Foundry | Your Azure subscription ID |
101 | `APP_ID` | Custom GitHub App | The GitHub App's ID |
102 | `APP_PRIVATE_KEY` | Custom GitHub App | The contents of the `.pem` private key file |
103 </Step>
104
105 <Step title="Create the workflow file">
106 Create a workflow file for your provider, such as `.github/workflows/claude.yml`. Each example responds to `@claude` mentions, authenticates to GitHub with a custom app, and includes the `id-token: write` permission, which GitHub requires to issue the OIDC token that your cloud provider exchanges for credentials.
107
108 If you chose a different GitHub identity in the first step, adjust the example:
109
110 * **Official Claude GitHub App**: delete the Generate GitHub App token step and the `github_token` line
111 * **GitHub's automatic token**: delete the token-generation step and change the `github_token` line to `github_token: ${{ secrets.GITHUB_TOKEN }}`
112
113 <Warning>
114 On public repositories, a comment containing the trigger phrase from any user starts this workflow. The credential steps run before the Claude Code GitHub Action checks the commenter's write access, so the action rejects unauthorized users only after the workflow has generated an App token and signed in to your cloud provider, which leaves audit-log entries and consumes Actions minutes. To avoid those runs, add a step that verifies the commenter's write access before the credential steps.
115 </Warning>
116
117 <Tabs>
118 <Tab title="Amazon Bedrock">
119 Replace the `aws-region` value with your own. The credentials step exports it as `AWS_REGION` for the rest of the job.
120
121 ```yaml theme={null}
122 name: Claude PR Action
123
124 permissions:
125 contents: write
126 pull-requests: write
127 issues: write
128 id-token: write
129
130 on:
131 issue_comment:
132 types: [created]
133 pull_request_review_comment:
134 types: [created]
135 issues:
136 types: [opened]
137
138 jobs:
139 claude-pr:
140 if: |
141 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
142 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
143 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
144 runs-on: ubuntu-latest
145 steps:
146 - name: Checkout repository
147 uses: actions/checkout@v6
148
149 - name: Generate GitHub App token
150 id: app-token
151 uses: actions/create-github-app-token@v2
152 with:
153 app-id: ${{ secrets.APP_ID }}
154 private-key: ${{ secrets.APP_PRIVATE_KEY }}
155
156 - name: Configure AWS Credentials (OIDC)
157 uses: aws-actions/configure-aws-credentials@v4
158 with:
159 role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
160 aws-region: us-west-2
161
162 - uses: anthropics/claude-code-action@v1
163 with:
164 github_token: ${{ steps.app-token.outputs.token }}
165 use_bedrock: "true"
166 claude_args: '--model us.anthropic.claude-sonnet-4-6'
167 ```
168
169 <Tip>
170 Bedrock model IDs include a cross-region inference profile prefix such as `us.`. Use the prefix for the region group where you granted model access.
171 </Tip>
172 </Tab>
173
174 <Tab title="Google Cloud's Agent Platform">
175 Replace the `CLOUD_ML_REGION` value with your own. You don't need to hardcode the project ID, because the workflow reads it from the `auth` step's output.
176
177 ```yaml theme={null}
178 name: Claude PR Action
179
180 permissions:
181 contents: write
182 pull-requests: write
183 issues: write
184 id-token: write
185
186 on:
187 issue_comment:
188 types: [created]
189 pull_request_review_comment:
190 types: [created]
191 issues:
192 types: [opened]
193
194 jobs:
195 claude-pr:
196 if: |
197 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
198 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
199 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
200 runs-on: ubuntu-latest
201 steps:
202 - name: Checkout repository
203 uses: actions/checkout@v6
204
205 - name: Generate GitHub App token
206 id: app-token
207 uses: actions/create-github-app-token@v2
208 with:
209 app-id: ${{ secrets.APP_ID }}
210 private-key: ${{ secrets.APP_PRIVATE_KEY }}
211
212 - name: Authenticate to Google Cloud
213 id: auth
214 uses: google-github-actions/auth@v2
215 with:
216 workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
217 service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
218
219 - uses: anthropics/claude-code-action@v1
220 with:
221 github_token: ${{ steps.app-token.outputs.token }}
222 use_vertex: "true"
223 claude_args: '--model claude-sonnet-5'
224 env:
225 ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
226 CLOUD_ML_REGION: us-east5
227 ```
228 </Tab>
229
230 <Tab title="Microsoft Foundry">
231 Replace `your-resource-name` with your Foundry resource name. Claude Code builds the endpoint URL from it. The `azure/login` step signs in with the workflow's OIDC token, and Claude Code picks up the credentials through the Azure [default credential chain](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview).
232
233 ```yaml theme={null}
234 name: Claude PR Action
235
236 permissions:
237 contents: write
238 pull-requests: write
239 issues: write
240 id-token: write
241
242 on:
243 issue_comment:
244 types: [created]
245 pull_request_review_comment:
246 types: [created]
247 issues:
248 types: [opened]
249
250 jobs:
251 claude-pr:
252 if: |
253 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
254 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
255 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
256 runs-on: ubuntu-latest
257 steps:
258 - name: Checkout repository
259 uses: actions/checkout@v6
260
261 - name: Generate GitHub App token
262 id: app-token
263 uses: actions/create-github-app-token@v2
264 with:
265 app-id: ${{ secrets.APP_ID }}
266 private-key: ${{ secrets.APP_PRIVATE_KEY }}
267
268 - name: Authenticate to Azure
269 uses: azure/login@v2
270 with:
271 client-id: ${{ secrets.AZURE_CLIENT_ID }}
272 tenant-id: ${{ secrets.AZURE_TENANT_ID }}
273 subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
274
275 - uses: anthropics/claude-code-action@v1
276 with:
277 github_token: ${{ steps.app-token.outputs.token }}
278 use_foundry: "true"
279 claude_args: '--model claude-sonnet-5'
280 env:
281 ANTHROPIC_FOUNDRY_RESOURCE: your-resource-name
282 ```
283
284 <Tip>
285 Use a model ID that matches a Claude deployment in your Foundry resource. See [Claude Code on Microsoft Foundry](/docs/en/microsoft-foundry) for model configuration and version pinning.
286 </Tip>
287 </Tab>
288 </Tabs>
289
290 With any provider, you can bound run length and cost by adding `--max-turns` to `claude_args`. See [Manage costs](/docs/en/github-actions#manage-costs).
291 </Step>
292
293 <Step title="Test the setup">
294 Mention `@claude` in an issue or PR comment, then watch the run in the repository's Actions tab. Claude replies in a comment on the same issue or PR.
295 </Step>
296</Steps>
36**1. Choose a GitHub identity**
37
38The Claude Code GitHub Action pushes commits and posts comments through a GitHub identity. The [quick setup](/docs/en/github-actions#quick-setup) installs the official Claude GitHub App for this. With a cloud provider, you choose the identity yourself:
39
40* **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#github-app-permissions)
42* **GitHub's automatic `GITHUB_TOKEN`**: no app to create or install, but GitHub doesn't trigger your CI workflows on commits made with it
43
44The workflow examples in the fourth step authenticate with a custom app. That step also says what to change for the other two options.
45
46To create a custom app, [register a new GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) with webhooks disabled, since this integration doesn't use them. Grant it three repository permissions:
47
48* **Contents**: read and write
49* **Issues**: read and write
50* **Pull requests**: read and write
51
52After registering the app, generate a private key and keep the downloaded `.pem` file, note the App ID from the app's settings page, and [install the app](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app) on the repository where the Claude Code GitHub Action runs. You add the key and the ID as secrets in the third step.
53
54**2. Configure cloud authentication**
55
56Configure your cloud to trust the OIDC token that GitHub issues to the workflow, so each workflow run gets short-lived cloud credentials. The bullets in each tab summarize what to create, and each tab links the cloud vendor's own guide for the console-level steps.
57
58**Amazon Bedrock**
59
60Create 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):
61
62* 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#iam-configuration), which grants `bedrock:InvokeModel`, `bedrock:InvokeModelWithResponseStream`, `bedrock:ListInferenceProfiles`, and `bedrock:GetInferenceProfile`, along with two `aws-marketplace` subscription actions
64* 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
65
66Note the role's ARN. You add it as a secret in the next step.
67
68**Google Cloud's Agent Platform**
69
70Create the federation resources in your Google Cloud project, following the [Workload Identity Federation documentation](https://cloud.google.com/iam/docs/workload-identity-federation):
71
72* Enable three APIs: IAM Credentials, Security Token Service (STS), and the Agent Platform API, whose service name is `aiplatform.googleapis.com`
73* Create a Workload Identity Pool with a GitHub OIDC provider whose issuer is `https://token.actions.githubusercontent.com`, and add an attribute condition that limits the pool to your repository
74* Create a dedicated service account with only the `Vertex AI User` role, which is `roles/aiplatform.user`, and allow the pool to impersonate it
75
76Note the provider's full resource name and the service account's email address. You add them as secrets in the next step.
77
78**Microsoft Foundry**
79
80Create 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):
81
82* 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#azure-rbac-configuration) for a narrower custom role
84
85Note the application's client ID, your tenant ID, and your subscription ID. You add them as secrets in the next step.
86
87**3. Add repository secrets**
88
89In the repository where the Claude Code GitHub Action runs, add the secrets for your provider, plus the two app secrets if you created a custom GitHub App in the first step. See GitHub's guide to [using secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
90
91| Secret | Needed for | Value |
92| - | - | - |
93| `AWS_ROLE_TO_ASSUME` | Amazon Bedrock | The ARN of the IAM role |
94| `GCP_WORKLOAD_IDENTITY_PROVIDER` | Google Cloud's Agent Platform | The provider's full resource name |
95| `GCP_SERVICE_ACCOUNT` | Google Cloud's Agent Platform | The service account's email address |
96| `AZURE_CLIENT_ID` | Microsoft Foundry | The Entra application's client ID |
97| `AZURE_TENANT_ID` | Microsoft Foundry | Your Microsoft Entra tenant ID |
98| `AZURE_SUBSCRIPTION_ID` | Microsoft Foundry | Your Azure subscription ID |
99| `APP_ID` | Custom GitHub App | The GitHub App's ID |
100| `APP_PRIVATE_KEY` | Custom GitHub App | The contents of the `.pem` private key file |
101
102**4. Create the workflow file**
103
104Create a workflow file for your provider, such as `.github/workflows/claude.yml`. Each example responds to `@claude` mentions, authenticates to GitHub with a custom app, and includes the `id-token: write` permission, which GitHub requires to issue the OIDC token that your cloud provider exchanges for credentials.
105
106If you chose a different GitHub identity in the first step, adjust the example:
107
108* **Official Claude GitHub App**: delete the Generate GitHub App token step and the `github_token` line
109* **GitHub's automatic token**: delete the token-generation step and change the `github_token` line to `github_token: ${{ secrets.GITHUB_TOKEN }}`
110
111> [!WARNING]
112>
113> On public repositories, a comment containing the trigger phrase from any user starts this workflow. The credential steps run before the Claude Code GitHub Action checks the commenter's write access, so the action rejects unauthorized users only after the workflow has generated an App token and signed in to your cloud provider, which leaves audit-log entries and consumes Actions minutes. To avoid those runs, add a step that verifies the commenter's write access before the credential steps.
114
115**Amazon Bedrock**
116
117Replace the `aws-region` value with your own. The credentials step exports it as `AWS_REGION` for the rest of the job.
118
119```yaml theme={null}
120name: Claude PR Action
121
122permissions:
123 contents: write
124 pull-requests: write
125 issues: write
126 id-token: write
127
128on:
129 issue_comment:
130 types: [created]
131 pull_request_review_comment:
132 types: [created]
133 issues:
134 types: [opened]
135
136jobs:
137 claude-pr:
138 if: |
139 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
140 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
141 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
142 runs-on: ubuntu-latest
143 steps:
144 - name: Checkout repository
145 uses: actions/checkout@v6
146
147 - name: Generate GitHub App token
148 id: app-token
149 uses: actions/create-github-app-token@v2
150 with:
151 app-id: ${{ secrets.APP_ID }}
152 private-key: ${{ secrets.APP_PRIVATE_KEY }}
153
154 - name: Configure AWS Credentials (OIDC)
155 uses: aws-actions/configure-aws-credentials@v4
156 with:
157 role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
158 aws-region: us-west-2
159
160 - uses: anthropics/claude-code-action@v1
161 with:
162 github_token: ${{ steps.app-token.outputs.token }}
163 use_bedrock: "true"
164 claude_args: '--model us.anthropic.claude-sonnet-4-6'
165```
166
167> [!TIP]
168>
169> Bedrock model IDs include a cross-region inference profile prefix such as `us.`. Use the prefix for the region group where you granted model access.
170
171**Google Cloud's Agent Platform**
172
173Replace the `CLOUD_ML_REGION` value with your own. You don't need to hardcode the project ID, because the workflow reads it from the `auth` step's output.
174
175```yaml theme={null}
176name: Claude PR Action
177
178permissions:
179 contents: write
180 pull-requests: write
181 issues: write
182 id-token: write
183
184on:
185 issue_comment:
186 types: [created]
187 pull_request_review_comment:
188 types: [created]
189 issues:
190 types: [opened]
191
192jobs:
193 claude-pr:
194 if: |
195 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
196 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
197 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
198 runs-on: ubuntu-latest
199 steps:
200 - name: Checkout repository
201 uses: actions/checkout@v6
202
203 - name: Generate GitHub App token
204 id: app-token
205 uses: actions/create-github-app-token@v2
206 with:
207 app-id: ${{ secrets.APP_ID }}
208 private-key: ${{ secrets.APP_PRIVATE_KEY }}
209
210 - name: Authenticate to Google Cloud
211 id: auth
212 uses: google-github-actions/auth@v2
213 with:
214 workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
215 service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
216
217 - uses: anthropics/claude-code-action@v1
218 with:
219 github_token: ${{ steps.app-token.outputs.token }}
220 use_vertex: "true"
221 claude_args: '--model claude-sonnet-5'
222 env:
223 ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
224 CLOUD_ML_REGION: us-east5
225```
226
227**Microsoft Foundry**
228
229Replace `your-resource-name` with your Foundry resource name. Claude Code builds the endpoint URL from it. The `azure/login` step signs in with the workflow's OIDC token, and Claude Code picks up the credentials through the Azure [default credential chain](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview).
230
231```yaml theme={null}
232name: Claude PR Action
233
234permissions:
235 contents: write
236 pull-requests: write
237 issues: write
238 id-token: write
239
240on:
241 issue_comment:
242 types: [created]
243 pull_request_review_comment:
244 types: [created]
245 issues:
246 types: [opened]
247
248jobs:
249 claude-pr:
250 if: |
251 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
252 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
253 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
254 runs-on: ubuntu-latest
255 steps:
256 - name: Checkout repository
257 uses: actions/checkout@v6
258
259 - name: Generate GitHub App token
260 id: app-token
261 uses: actions/create-github-app-token@v2
262 with:
263 app-id: ${{ secrets.APP_ID }}
264 private-key: ${{ secrets.APP_PRIVATE_KEY }}
265
266 - name: Authenticate to Azure
267 uses: azure/login@v2
268 with:
269 client-id: ${{ secrets.AZURE_CLIENT_ID }}
270 tenant-id: ${{ secrets.AZURE_TENANT_ID }}
271 subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
272
273 - uses: anthropics/claude-code-action@v1
274 with:
275 github_token: ${{ steps.app-token.outputs.token }}
276 use_foundry: "true"
277 claude_args: '--model claude-sonnet-5'
278 env:
279 ANTHROPIC_FOUNDRY_RESOURCE: your-resource-name
280```
281
282> [!TIP]
283>
284> Use a model ID that matches a Claude deployment in your Foundry resource. See [Claude Code on Microsoft Foundry](/docs/en/microsoft-foundry) for model configuration and version pinning.
285
286With any provider, you can bound run length and cost by adding `--max-turns` to `claude_args`. See [Manage costs](/docs/en/github-actions#manage-costs).
287
288**5. Test the setup**
289
290Mention `@claude` in an issue or PR comment, then watch the run in the repository's Actions tab. Claude replies in a comment on the same issue or PR.
297291
298292## Troubleshooting
299293
300294
github-enterprise-server Changed · +25 / -27 lines
from line 2
22
33> Connect Claude Code to your self-hosted GitHub Enterprise Server instance for cloud sessions, code review, and plugin marketplaces.
44
5<Note>
6 GitHub Enterprise Server support is available for Team and Enterprise plans.
7</Note>
5> [!NOTE]
6>
7> GitHub Enterprise Server support is available for Team and Enterprise plans.
88
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
from line 31
3131
3232The guided setup generates a GitHub App manifest and redirects you to your GHES instance to create the app in one click. If your environment blocks the redirect flow, an [alternative manual setup](#manual-setup) is available.
3333
34<Steps>
35 <Step title="Open Git providers settings">
36 Go to [**Organization settings > Git providers**](https://claude.ai/admin-settings/source-control#github-enterprise) and find the GitHub Enterprise section.
37 </Step>
34**1. Open Git providers settings**
3835
39 <Step title="Start the guided setup">
40 Click **Connect**, or **Add instance** if an instance is already connected, then select **Set up automatically**. Enter a display name of up to 20 characters for the connection and your GHES hostname, for example `github.example.com`. If your GHES instance uses a self-signed or private certificate authority, paste the CA certificate in the optional field.
41 </Step>
36Go to [**Organization settings > Git providers**](https://claude.ai/admin-settings/source-control#github-enterprise) and find the GitHub Enterprise section.
4237
43 <Step title="Create the GitHub App">
44 Click **Continue to GitHub Enterprise**. Your browser redirects to your GHES instance with a pre-filled app manifest. Review the configuration and click **Create GitHub App**. GHES redirects you back to Claude with the app credentials stored automatically.
45 </Step>
38**2. Start the guided setup**
4639
47 <Step title="Install the app on your repositories">
48 From the GitHub App page on your GHES instance, install the app on the repositories or organizations you want Claude to access. You can start with a subset and add more later.
49 </Step>
40Click **Connect**, or **Add instance** if an instance is already connected, then select **Set up automatically**. Enter a display name of up to 20 characters for the connection and your GHES hostname, for example `github.example.com`. If your GHES instance uses a self-signed or private certificate authority, paste the CA certificate in the optional field.
5041
51 <Step title="Enable Code Review">
52 Go to [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) and enable [Code Review](/docs/en/code-review-setup) for your GHES repositories using the same configuration as github.com.
53 </Step>
54</Steps>
42**3. Create the GitHub App**
5543
44Click **Continue to GitHub Enterprise**. Your browser redirects to your GHES instance with a pre-filled app manifest. Review the configuration and click **Create GitHub App**. GHES redirects you back to Claude with the app credentials stored automatically.
45
46**4. Install the app on your repositories**
47
48From the GitHub App page on your GHES instance, install the app on the repositories or organizations you want Claude to access. You can start with a subset and add more later.
49
50**5. Enable Code Review**
51
52Go to [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) and enable [Code Review](/docs/en/code-review-setup) for your GHES repositories using the same configuration as github.com.
53
5654### GitHub App permissions
5755
5856The manifest configures the GitHub App with the permissions and webhook events below, which together cover cloud sessions, Code Review, Claude Security, and plugin marketplaces:
from line 118
120118| claude.ai user settings | Anthropic's backend fetches the repository using the submitting user's GitHub Enterprise connection | Their own GitHub Enterprise account connected to Claude |
121119| Cloud sessions | Cloud sessions clone marketplaces inside the session sandbox. The sandbox can reach your GHES instance only when the session's repository is on that same instance, and its git credentials are scoped to the session's repositories | Not reliable for GHES-hosted marketplaces: a different host than the session's repository is not reachable, and even same-instance installs can fail. Use the CLI, managed settings, or claude.ai instead |
122120
123<Warning>
124 GitHub Enterprise connections on claude.ai are per user when a marketplace is added from user settings. The [admin setup](#admin-setup) connects your GHES instance to your organization, but it does not connect individual user accounts: each user who adds a GHES marketplace from their own settings must first connect their own GitHub Enterprise account, and one user's connection, including the Owner's, does not cover anyone else. Marketplaces added by an Owner in the organization plugin settings do not put this requirement on users, because ongoing fetches use the organization's GitHub App. The Owner adding the marketplace still needs their own GitHub Enterprise account connected at add time.
125</Warning>
121> [!WARNING]
122>
123> GitHub Enterprise connections on claude.ai are per user when a marketplace is added from user settings. The [admin setup](#admin-setup) connects your GHES instance to your organization, but it does not connect individual user accounts: each user who adds a GHES marketplace from their own settings must first connect their own GitHub Enterprise account, and one user's connection, including the Owner's, does not cover anyone else. Marketplaces added by an Owner in the organization plugin settings do not put this requirement on users, because ongoing fetches use the organization's GitHub App. The Owner adding the marketplace still needs their own GitHub Enterprise account connected at add time.
126124
127125### Add a GHES marketplace
128126
gitlab-ci-cd Changed · +74 / -76 lines
### Prerequisites ### Setup instructions ### Prerequisites ### Setup instructions
from line 2
22
33> Learn about integrating Claude Code into your development workflow with GitLab CI/CD
44
5<Info>
6 Claude Code for GitLab CI/CD is currently in beta. Features and functionality may evolve as we refine the experience.
5> [!NOTE]
6>
7> Claude Code for GitLab CI/CD is currently in beta. Features and functionality may evolve as we refine the experience.
8>
9> This integration is maintained by GitLab. For support, see the following [GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/573776).
710
8 This integration is maintained by GitLab. For support, see the following [GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/573776).
9</Info>
11> [!NOTE]
12>
13> This integration is built on top of the [Claude Code CLI and Agent SDK](/docs/en/agent-sdk/overview), enabling programmatic use of Claude in your CI/CD jobs and custom automation workflows.
1014
11<Note>
12 This integration is built on top of the [Claude Code CLI and Agent SDK](/docs/en/agent-sdk/overview), enabling programmatic use of Claude in your CI/CD jobs and custom automation workflows.
13</Note>
14
1515## Why use Claude Code with GitLab?
1616
1717* **Instant MR creation**: Describe what you need, and Claude proposes a complete MR with changes and explanation
from line 95
9595
9696After adding the job and your `ANTHROPIC_API_KEY` variable, test by running the job manually from **CI/CD** → **Pipelines**, or trigger it from an MR to let Claude propose updates in a branch and open an MR if needed.
9797
98<Note>
99 To run on Amazon Bedrock or Google Cloud's Agent Platform instead of the Claude API, see the [Using with Amazon Bedrock and Google Cloud](#using-with-amazon-bedrock-and-google-cloud) section below for authentication and environment setup.
100</Note>
98> [!NOTE]
99>
100> To run on Amazon Bedrock or Google Cloud's Agent Platform instead of the Claude API, see the [Using with Amazon Bedrock and Google Cloud](#using-with-amazon-bedrock-and-google-cloud) section below for authentication and environment setup.
101101
102102### Manual setup (recommended for production)
103103
from line 154
154154
155155For enterprise environments, you can run Claude Code entirely on your cloud infrastructure with the same developer experience.
156156
157<Tabs>
158 <Tab title="Amazon Bedrock">
159 ### Prerequisites
157**Amazon Bedrock**
160158
161 Before setting up Claude Code with Amazon Bedrock, you need:
159### Prerequisites
162160
163 1. An AWS account with Amazon Bedrock access to the desired Claude models
164 2. GitLab configured as an OIDC identity provider in AWS IAM
165 3. An IAM role with Amazon Bedrock permissions and a trust policy restricted to your GitLab project/refs
166 4. GitLab CI/CD variables for role assumption:
167 * `AWS_ROLE_TO_ASSUME` (role ARN)
168 * `AWS_REGION` (Amazon Bedrock region)
161Before setting up Claude Code with Amazon Bedrock, you need:
169162
170 ### Setup instructions
1631. An AWS account with Amazon Bedrock access to the desired Claude models
1642. GitLab configured as an OIDC identity provider in AWS IAM
1653. An IAM role with Amazon Bedrock permissions and a trust policy restricted to your GitLab project/refs
1664. GitLab CI/CD variables for role assumption:
167 * `AWS_ROLE_TO_ASSUME` (role ARN)
168 * `AWS_REGION` (Amazon Bedrock region)
171169
172 Configure AWS to allow GitLab CI jobs to assume an IAM role via OIDC (no static keys).
170### Setup instructions
173171
174 **Required setup:**
172Configure AWS to allow GitLab CI jobs to assume an IAM role via OIDC (no static keys).
175173
176 1. Enable Amazon Bedrock and request access to your target Claude models
177 2. Create an IAM OIDC provider for GitLab if not already present
178 3. Create an IAM role trusted by the GitLab OIDC provider, restricted to your project and protected refs
179 4. Attach least-privilege permissions for Amazon Bedrock invoke APIs
174**Required setup:**
180175
181 Use the [Amazon Bedrock job example](#configuration-examples) to exchange the job's OIDC token for temporary AWS credentials at runtime.
182 </Tab>
1761. Enable Amazon Bedrock and request access to your target Claude models
1772. Create an IAM OIDC provider for GitLab if not already present
1783. Create an IAM role trusted by the GitLab OIDC provider, restricted to your project and protected refs
1794. Attach least-privilege permissions for Amazon Bedrock invoke APIs
183180
184 <Tab title="Google Cloud's Agent Platform">
185 ### Prerequisites
181Use the [Amazon Bedrock job example](#configuration-examples) to exchange the job's OIDC token for temporary AWS credentials at runtime.
186182
187 Before setting up Claude Code with Google Cloud's Agent Platform, you need:
183**Google Cloud's Agent Platform**
188184
189 1. A Google Cloud project with:
190 * Google Cloud's Agent Platform API enabled
191 * Workload Identity Federation configured to trust GitLab OIDC
192 2. A dedicated service account with only the required Google Cloud's Agent Platform roles
193 3. GitLab CI/CD variables:
194 * `GCP_WORKLOAD_IDENTITY_PROVIDER` (provider resource name without the `//iam.googleapis.com/` prefix, such as `projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider`)
195 * `GCP_SERVICE_ACCOUNT` (service account email)
196 * `GCP_PROJECT_ID` (Google Cloud project ID)
185### Prerequisites
197186
198 ### Setup instructions
187Before setting up Claude Code with Google Cloud's Agent Platform, you need:
199188
200 Configure Google Cloud to allow GitLab CI jobs to impersonate a service account via Workload Identity Federation.
1891. A Google Cloud project with:
190 * Google Cloud's Agent Platform API enabled
191 * Workload Identity Federation configured to trust GitLab OIDC
1922. A dedicated service account with only the required Google Cloud's Agent Platform roles
1933. GitLab CI/CD variables:
194 * `GCP_WORKLOAD_IDENTITY_PROVIDER` (provider resource name without the `//iam.googleapis.com/` prefix, such as `projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider`)
195 * `GCP_SERVICE_ACCOUNT` (service account email)
196 * `GCP_PROJECT_ID` (Google Cloud project ID)
201197
202 **Required setup:**
198### Setup instructions
203199
204 1. Enable IAM Credentials API, STS API, and Google Cloud's Agent Platform API
205 2. Create a Workload Identity Pool and provider for GitLab OIDC
206 3. Create a dedicated service account with Google Cloud's Agent Platform roles
207 4. Grant the WIF principal permission to impersonate the service account
200Configure Google Cloud to allow GitLab CI jobs to impersonate a service account via Workload Identity Federation.
208201
209 Use the [Agent Platform job example](#configuration-examples) to authenticate without storing keys.
210 </Tab>
211</Tabs>
202**Required setup:**
212203
2041. Enable IAM Credentials API, STS API, and Google Cloud's Agent Platform API
2052. Create a Workload Identity Pool and provider for GitLab OIDC
2063. Create a dedicated service account with Google Cloud's Agent Platform roles
2074. Grant the WIF principal permission to impersonate the service account
208
209Use the [Agent Platform job example](#configuration-examples) to authenticate without storing keys.
210
213211## Configuration examples
214212
215213Below are ready-to-use snippets you can adapt to your pipeline.
from line 269
271269 CLAUDE_CODE_USE_BEDROCK: "1"
272270```
273271
274<Note>
275 Model IDs for Amazon Bedrock include region-specific prefixes (for example, `us.anthropic.claude-sonnet-4-6`). Pass the desired model via your job configuration or prompt if your workflow supports it.
276</Note>
272> [!NOTE]
273>
274> Model IDs for Amazon Bedrock include region-specific prefixes (for example, `us.anthropic.claude-sonnet-4-6`). Pass the desired model via your job configuration or prompt if your workflow supports it.
277275
278276### Agent Platform job example (Workload Identity Federation)
279277
from line 343
345343 ANTHROPIC_VERTEX_PROJECT_ID: "$GCP_PROJECT_ID"
346344```
347345
348<Note>
349 With Workload Identity Federation, you do not need to store service account keys. Use repository-specific trust conditions and least-privilege service accounts.
350</Note>
346> [!NOTE]
347>
348> With Workload Identity Federation, you do not need to store service account keys. Use repository-specific trust conditions and least-privilege service accounts.
351349
352350## Best practices
353351
from line 417
419417* `ANTHROPIC_API_KEY`: required for the Claude API (not used for Amazon Bedrock or Google Cloud's Agent Platform)
420418* Provider-specific environment: `AWS_REGION`, project/region vars for Google Cloud's Agent Platform
421419
422<Note>
423 Exact flags and parameters may vary by version of `@anthropic-ai/claude-code`. Run `claude --help` in your job to see supported options.
424</Note>
420> [!NOTE]
421>
422> Exact flags and parameters may vary by version of `@anthropic-ai/claude-code`. Run `claude --help` in your job to see supported options.
425423
426424### Customizing Claude's behavior
427425
goal Changed · +9 / -9 lines
from line 25
2525
2626[Auto mode](/docs/en/auto-mode-config) 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
28<Tip>
29 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#compare-scheduling-options) for cloud and Desktop scheduled tasks.
30</Tip>
28> [!TIP]
29>
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#compare-scheduling-options) for cloud and Desktop scheduled tasks.
3131
3232## Use `/goal`
3333
from line 162
162162
163163To evaluate on a different model, set [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/docs/en/model-config#environment-variables).
164164
165<Warning>
166 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#background-token-usage), such as conversation summarization, on it.
167</Warning>
165> [!WARNING]
166>
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#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
171<Note>
172 Evaluation tokens are billed on the small fast model configured for your provider and are typically negligible compared to main-turn spend.
173</Note>
171> [!NOTE]
172>
173> Evaluation tokens are billed on the small fast model configured for your provider and are typically negligible compared to main-turn spend.
174174
175175## Requirements
176176
google-vertex-ai Changed · +30 / -99 lines
from line 2
22
33> Learn about configuring Claude Code through Google Cloud's Agent Platform, formerly Vertex AI, including setup, IAM configuration, and troubleshooting.
44
5export const ContactSalesCard = ({surface}) => {
6 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;
7 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
8 <line x1="5" y1="12" x2="19" y2="12" />
9 <polyline points="12 5 19 12 12 19" />
10 </svg>;
11 const STYLES = `
12.cc-cs {
13 --cs-slate: #141413;
14 --cs-clay: #d97757;
15 --cs-clay-deep: #c6613f;
16 --cs-gray-000: #ffffff;
17 --cs-gray-700: #3d3d3a;
18 --cs-border-default: rgba(31, 30, 29, 0.15);
19 font-family: inherit;
20}
21.dark .cc-cs {
22 --cs-slate: #f0eee6;
23 --cs-gray-000: #262624;
24 --cs-gray-700: #bfbdb4;
25 --cs-border-default: rgba(240, 238, 230, 0.14);
26}
27.cc-cs-card {
28 display: flex; align-items: center; justify-content: space-between;
29 gap: 16px; padding: 14px 16px; margin: 0;
30 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);
31 border-radius: 8px; flex-wrap: wrap;
32}
33.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }
34.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }
35.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }
36.cc-cs-btn-clay {
37 display: inline-flex; align-items: center; gap: 8px;
38 background: var(--cs-clay-deep); color: #fff; border: none;
39 border-radius: 8px; padding: 8px 14px;
40 font-size: 13px; font-weight: 500;
41 transition: background-color 0.15s; white-space: nowrap;
42}
43.cc-cs-btn-clay:hover { background: var(--cs-clay); }
44.cc-cs-btn-ghost {
45 display: inline-flex; align-items: center; gap: 8px;
46 background: transparent; color: var(--cs-gray-700);
47 border: 0.5px solid var(--cs-border-default);
48 border-radius: 8px; padding: 8px 14px;
49 font-size: 13px; font-weight: 500;
50}
51.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }
52.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }
53@media (max-width: 720px) {
54 .cc-cs-actions { width: 100%; }
55}
56`;
57 return <div className="cc-cs not-prose">
58 <style>{STYLES}</style>
59 <div className="cc-cs-card">
60 <div className="cc-cs-text">
61 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.
62 </div>
63 <div className="cc-cs-actions">
64 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">
65 View plans
66 </a>
67 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">
68 Contact sales {iconArrowRight()}
69 </a>
70 </div>
71 </div>
72 </div>;
73};
5**Deploying Claude Code across your organization?** Talk to sales about enterprise plans, SSO, and centralized billing.
746
75<ContactSalesCard surface="vertex" />
7View plans
8Contact sales
769
7710## Prerequisites
7811
from line 23
9023
9124If you have Google Cloud credentials and want to start using Claude Code through Google Cloud's Agent Platform, the login wizard walks you through it. You complete the GCP-side prerequisites once per project; the wizard handles the Claude Code side.
9225
93<Steps>
94 <Step title="Enable Claude models in your GCP project">
95 [Enable Google Cloud's Agent Platform API](#1-enable-agent-platform-api) for your project, then request access to the Claude models you want in the [Google Cloud's Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden). See [IAM configuration](#iam-configuration) for the permissions your account needs.
96 </Step>
26**1. Enable Claude models in your GCP project**
9727
98 <Step title="Start Claude Code and choose Google Cloud's Agent Platform">
99 Run `claude`. At the login prompt, select **3rd-party platform**, then **Google Vertex AI**, the label the login prompt still uses for Google Cloud's Agent Platform. If you're already signed in, run `/login` to open the same menu.
100 </Step>
28[Enable Google Cloud's Agent Platform API](#1-enable-agent-platform-api) for your project, then request access to the Claude models you want in the [Google Cloud's Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden). See [IAM configuration](#iam-configuration) for the permissions your account needs.
10129
102 <Step title="Follow the wizard prompts">
103 Choose 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), so you don't need to export environment variables yourself.
104 </Step>
105</Steps>
30**2. Start Claude Code and choose Google Cloud's Agent Platform**
10631
32Run `claude`. At the login prompt, select **3rd-party platform**, then **Google Vertex AI**, the label the login prompt still uses for Google Cloud's Agent Platform. If you're already signed in, run `/login` to open the same menu.
33
34**3. Follow the wizard prompts**
35
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), so you don't need to export environment variables yourself.
37
10738After 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.
10839
10940## Region configuration
from line 41
11041
11142Claude Code supports Google Cloud's Agent Platform [global](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai), multi-region, and regional endpoints. Set `CLOUD_ML_REGION` to `global`, a multi-region location such as `eu` or `us`, or a specific region such as `us-east5`. Claude Code selects the correct Google Cloud's Agent Platform hostname for each form, including the `aiplatform.eu.rep.googleapis.com` and `aiplatform.us.rep.googleapis.com` hosts for multi-region locations.
11243
113<Note>
114 Google Cloud's Agent Platform may not support the Claude Code default models on every endpoint type. Model availability varies across [specific regions](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models), multi-region locations, and [global endpoints](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models). You may need to switch to a supported location or specify a supported model.
115</Note>
44> [!NOTE]
45>
46> Google Cloud's Agent Platform may not support the Claude Code default models on every endpoint type. Model availability varies across [specific regions](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models), multi-region locations, and [global endpoints](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models). You may need to switch to a supported location or specify a supported model.
11647
11748## Set up manually
11849
from line 78
14778
14879Claude Code supports [X.509 certificate-based Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates) through the same Application Default Credentials chain. Set `GOOGLE_APPLICATION_CREDENTIALS` to the path of your credential configuration file.
14980
150<Note>
151 Claude Code addresses Google Cloud's Agent Platform requests to the project in `ANTHROPIC_VERTEX_PROJECT_ID`, even when `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT`, or the credential file referenced by `GOOGLE_APPLICATION_CREDENTIALS` carries a different project.
152</Note>
81> [!NOTE]
82>
83> Claude Code addresses Google Cloud's Agent Platform requests to the project in `ANTHROPIC_VERTEX_PROJECT_ID`, even when `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT`, or the credential file referenced by `GOOGLE_APPLICATION_CREDENTIALS` carries a different project.
15384
15485#### Advanced credential configuration
15586
from line 139
208139
209140### 5. Pin model versions
210141
211<Warning>
212 Pin specific model versions when deploying to multiple users. Without pinning, model aliases such as `sonnet` and `opus` resolve to Claude Code's built-in default for Google Cloud's Agent Platform, which can lag the newest release and may not yet be enabled in your project. Claude Code [falls back](#startup-model-checks) to an earlier or lower-tier model at startup when the default is unavailable, but pinning lets you control when your users move to a new model.
213</Warning>
142> [!WARNING]
143>
144> Pin specific model versions when deploying to multiple users. Without pinning, model aliases such as `sonnet` and `opus` resolve to Claude Code's built-in default for Google Cloud's Agent Platform, which can lag the newest release and may not yet be enabled in your project. Claude Code [falls back](#startup-model-checks) to an earlier or lower-tier model at startup when the default is unavailable, but pinning lets you control when your users move to a new model.
214145
215146Set these environment variables to specific Google Cloud's Agent Platform model IDs.
216147
from line 167
236167* 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.
237168* To use Haiku for background tasks, set `ANTHROPIC_DEFAULT_HAIKU_MODEL` to a model ID that is available in your project.
238169
239<Warning>
240 Opus models have a higher per-token price than Sonnet models, so if you don't pin a primary model, you're billed at the Opus rate. To use Sonnet 4.5 as the primary model, set `ANTHROPIC_MODEL` to its full model ID. A deployment that steers the default with `ANTHROPIC_DEFAULT_SONNET_MODEL` and doesn't set `ANTHROPIC_DEFAULT_OPUS_MODEL` keeps its steered Sonnet model as the default.
241</Warning>
170> [!WARNING]
171>
172> Opus models have a higher per-token price than Sonnet models, so if you don't pin a primary model, you're billed at the Opus rate. To use Sonnet 4.5 as the primary model, set `ANTHROPIC_MODEL` to its full model ID. A deployment that steers the default with `ANTHROPIC_DEFAULT_SONNET_MODEL` and doesn't set `ANTHROPIC_DEFAULT_OPUS_MODEL` keeps its steered Sonnet model as the default.
242173
243174Before v2.1.280, the primary model on Google Cloud's Agent Platform defaulted to Opus 5 and the `opus` alias resolved to Opus 5 from v2.1.219. On v2.1.207 through v2.1.218, the primary model on Google Cloud's Agent Platform defaulted to Opus 4.8 and the `opus` alias resolved to Opus 4.8.
244175
from line 231
300231
301232For details, see [Google Cloud's Agent Platform IAM documentation](https://cloud.google.com/vertex-ai/docs/general/access-control).
302233
303<Note>
304 Create a dedicated GCP project for Claude Code to simplify cost tracking and access control.
305</Note>
234> [!NOTE]
235>
236> Create a dedicated GCP project for Claude Code to simplify cost tracking and access control.
306237
307238## 1M token context window
308239
headless Changed · +34 / -32 lines
from line 62
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
65<Note>
66 `--bare` is the recommended mode for scripted and SDK calls, and will become the default for `-p` in a future release.
67</Note>
65> [!NOTE]
66>
67> `--bare` is the recommended mode for scripted and SDK calls, and will become the default for `-p` in a future release.
6868
6969### Background tasks at exit
7070
from line 116
116116
117117With `--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). 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#accumulate-costs-across-multiple-calls). Both figures are [client-side estimates](/docs/en/agent-sdk/cost-tracking) and can differ from your actual bill.
118118
119<Note>
120 Piped stdin is capped at 10MB. If you exceed the cap, Claude Code exits with a clear error and a non-zero status. To work with larger inputs, write the content to a file and reference the file path in your prompt instead of piping it.
121</Note>
119> [!NOTE]
120>
121> Piped stdin is capped at 10MB. If you exceed the cap, Claude Code exits with a clear error and a non-zero status. To work with larger inputs, write the content to a file and reference the file path in your prompt instead of piping it.
122122
123123If Claude Code can't read stdin, for example because the process that started it disconnected its end, Claude Code prints a warning to stderr and continues with the prompt from the command line.
124124
from line 164
164164
165165If the value isn't a valid JSON Schema, `claude` exits with `Error: --json-schema is not a valid JSON Schema` followed by the validator's diagnostic. Claude Code accepts schemas that use the `format` keyword, such as `"format": "email"`, but treats `format` as an annotation and doesn't enforce it.
166166
167<Tip>
168 Use a tool like [jq](https://jqlang.org/) to parse the response and extract specific fields:
167If a run ends without valid structured output, for example because Claude declined the request, the response has no `structured_output` field. Before your script uses `structured_output`, check that the field is present.
169168
170 ```bash theme={null}
171 # Extract the text result
172 claude -p "Summarize this project" --output-format json | jq -r '.result'
169> [!TIP]
170>
171> Use a tool like [jq](https://jqlang.org/) to parse the response and extract specific fields:
172>
173> ```bash theme={null}
174> # Extract the text result
175> claude -p "Summarize this project" --output-format json | jq -r '.result'
176>
177> # Extract structured output
178> claude -p "Extract function names from auth.py" \
179> --output-format json \
180> --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
181> | jq '.structured_output'
182> ```
173183
174 # Extract structured output
175 claude -p "Extract function names from auth.py" \
176 --output-format json \
177 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
178 | jq '.structured_output'
179 ```
180</Tip>
181
182184### Stream responses
183185
184186Use `--output-format stream-json` with `--verbose` and `--include-partial-messages` to receive tokens as they're generated. Each line is a JSON object representing an event:
from line 333
331333
332334With `--output-format stream-json`, denials appear as `permission_denied` system messages, and the final result message lists them in `permission_denials`.
333335
334<Note>
335 The `--permission-prompts` flag requires Claude Code v2.1.259 or later. Earlier versions reject it with an unknown-option error.
336</Note>
336> [!NOTE]
337>
338> The `--permission-prompts` flag requires Claude Code v2.1.259 or later. Earlier versions reject it with an unknown-option error.
337339
338340### Create a commit
339341
from line 348
346348
347349The `--allowedTools` flag uses [permission rule syntax](/docs/en/settings-reference#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`.
348350
349<Note>
350 Command support differs in `-p` mode:
351
352 * User-invoked [skills](/docs/en/skills) and custom commands work. Include `/skill-name` in the prompt string and Claude Code expands it before running.
353 * Built-in commands that only run in the terminal interface, such as `/login`, aren't available.
354 * `/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#all-commands).
355 * To change a setting, pass `key=value` to `/config`, for example `/config thinking=false`.
356 * `/output-style <style>` switches [output styles](/docs/en/output-styles) and `/output-style` alone lists them. Requires Claude Code v2.1.269 or later.
357</Note>
351> [!NOTE]
352>
353> Command support differs in `-p` mode:
354>
355> * User-invoked [skills](/docs/en/skills) and custom commands work. Include `/skill-name` in the prompt string and Claude Code expands it before running.
356> * Built-in commands that only run in the terminal interface, such as `/login`, aren't available.
357> * `/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#all-commands).
358> * To change a setting, pass `key=value` to `/config`, for example `/config thinking=false`.
359> * `/output-style <style>` switches [output styles](/docs/en/output-styles) and `/output-style` alone lists them. Requires Claude Code v2.1.269 or later.
358360
359361### Customize the system prompt
360362
hipaa-setup Changed · +33 / -35 lines
from line 4
44
55The HIPAA configuration is an organization setting on Claude Enterprise plans, for organizations that handle protected health information (PHI) and have a [Business Associate Agreement (BAA)](https://support.claude.com/en/articles/8114513-business-associate-agreements-baa-for-commercial-customers) with Anthropic. It applies to Claude Code (local mode) and Cowork (local mode), and it restricts features in both products.
66
7<Note>
8 "(local mode)" means a local session, not a [cloud session](/docs/en/claude-code-on-the-web). Local sessions run in one of these places:
7> [!NOTE]
8>
9> "(local mode)" means a local session, not a [cloud session](/docs/en/claude-code-on-the-web). Local sessions run in one of these places:
10>
11> * Claude Code in the terminal
12> * Claude Code in the Code tab of Claude Desktop
13> * Cowork in Claude Desktop
14>
15> The Claude Code extensions for VS Code and JetBrains aren't part of (local mode). They keep working with the HIPAA configuration applied, but your BAA doesn't cover them. 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.
916
10 * Claude Code in the terminal
11 * Claude Code in the Code tab of Claude Desktop
12 * Cowork in Claude Desktop
13
14 The Claude Code extensions for VS Code and JetBrains aren't part of (local mode). They keep working with the HIPAA configuration applied, but your BAA doesn't cover them. 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.
15</Note>
16
1717This page is for the IT or security administrator who prepares developers' computers. The Primary Owner of your Claude organization applies the configuration itself. [Use Claude Code (local mode) and Cowork (local mode) on a HIPAA-ready Enterprise plan](https://support.claude.com/en/articles/17318731) explains what your BAA includes, how the configuration is applied, and how to schedule the date it's applied.
1818
1919If members of your organization also use Cowork, follow [Set up Cowork (local mode) for a HIPAA-ready organization](https://claude.com/docs/cowork/hipaa-setup) as well. It covers the Claude Desktop policy and Cowork's local data.
from line 134
134134| [`allowedProviders`](/docs/en/settings-reference#allowedproviders) | `["anthropic"]` | Claude Code refuses to start on a cloud provider or a gateway |
135135| [`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 |
136136
137<Warning>
138 Check the `forceLoginOrgUUID` value before you deploy it. If it doesn't match your organization ID, Claude Code exits at startup for every developer who signs in with a claude.ai account.
139</Warning>
137> [!WARNING]
138>
139> Check the `forceLoginOrgUUID` value before you deploy it. If it doesn't match your organization ID, Claude Code exits at startup for every developer who signs in with a claude.ai account.
140140
141141The HIPAA configuration doesn't limit `cleanupPeriodDays`, so a developer can raise it in their own settings. When you set it in managed settings, Claude Code ignores the developer's value.
142142
from line 160
160160
161161Run this check on one managed computer after the configuration is applied to your organization.
162162
163<Steps>
164 <Step title="Restart Claude Code">
165 Quit any running session, open a terminal, and run `claude`. A running session that's in use picks up the configuration within about an hour without a restart. When you restart, Claude Code fetches it right away.
166 </Step>
163**1. Restart Claude Code**
167164
168 <Step title="Check the startup notice">
169 Confirm that Claude Code prints `Per your organization's policy, some features are limited · /status for details` when it starts.
170 </Step>
165Quit any running session, open a terminal, and run `claude`. A running session that's in use picks up the configuration within about an hour without a restart. When you restart, Claude Code fetches it right away.
171166
172 <Step title="Check the footer">
173 Confirm that a `HIPAA configured` tag appears at the right of the footer, below the prompt. Before v2.1.286, the tag read `HIPAA`.
174 </Step>
167**2. Check the startup notice**
175168
176 <Step title="Run /status">
177 Enter `/status` at the prompt. Confirm that the **Status** tab lists `HIPAA` on the `Organization configuration` line.
178 </Step>
169Confirm that Claude Code prints `Per your organization's policy, some features are limited · /status for details` when it starts.
179170
180 <Step title="Check Claude Desktop">
181 Applying the HIPAA configuration turns the Code tab off for your organization. If your organization uses it, ask an Owner to go to [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code) and turn on the **Desktop** toggle. For Cowork, see [Confirm the HIPAA configuration in Claude Desktop](https://claude.com/docs/cowork/hipaa-setup#confirm-the-hipaa-configuration-in-claude-desktop).
171**3. Check the footer**
182172
183 Reload Claude Desktop or sign in again. Confirm that the title bar shows a **HIPAA configured** label. On a Mac, open the sidebar to see it.
184 </Step>
185</Steps>
173Confirm that a `HIPAA configured` tag appears at the right of the footer, below the prompt. Before v2.1.286, the tag read `HIPAA`.
174
175**4. Run /status**
176
177Enter `/status` at the prompt. Confirm that the **Status** tab lists `HIPAA` on the `Organization configuration` line.
178
179**5. Check Claude Desktop**
180
181Applying the HIPAA configuration turns the Code tab off for your organization. If your organization uses it, ask an Owner to go to [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code) and turn on the **Desktop** toggle. For Cowork, see [Confirm the HIPAA configuration in Claude Desktop](https://claude.com/docs/cowork/hipaa-setup#confirm-the-hipaa-configuration-in-claude-desktop).
182
183Reload Claude Desktop or sign in again. Confirm that the title bar shows a **HIPAA configured** label. On a Mac, open the sidebar to see it.
186184
187185If `HIPAA` is missing from `/status`, check these causes in order:
188186
hooks Changed · +511 / -549 lines
#### How `if` patterns match Bash commands #### Tools that require user interaction
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 2
22
33> Reference for Claude Code hook events, configuration schema, JSON input/output formats, exit codes, async hooks, HTTP hooks, prompt hooks, and MCP tool hooks.
44
5<Tip>
6 For a quickstart guide with examples, see [Automate actions with hooks](/docs/en/hooks-guide).
7</Tip>
5> [!TIP]
6>
7> For a quickstart guide with examples, see [Automate actions with hooks](/docs/en/hooks-guide).
88
99Hooks 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), and [cloud sessions](/docs/en/claude-code-on-the-web). 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.
1010
from line 20
2020* per turn: `UserPromptSubmit`, `Stop`, and `StopFailure`
2121* on every tool call inside the agentic loop: `PreToolUse` and `PostToolUse`, except [`EndConversation`](/docs/en/tools-reference#endconversation-tool-behavior) calls, which skip both
2222
23<div style={{maxWidth: "500px", margin: "0 auto"}}>
24 <Frame>
25 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=81b9256c1bbe8832553485f5d9e9c746" className="dark:hidden" alt="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" width="520" height="1336" data-path="images/hooks-lifecycle.svg" />
26
27 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle-dark.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=c9b3d88487335f58cce0b52e2f9e7531" className="hidden dark:block" alt="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" width="520" height="1336" data-path="images/hooks-lifecycle-dark.svg" />
28 </Frame>
29</div>
23
3024
3125The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.
3226
from line 64
7064
7165To see how the event, the matcher, and the handler fit together, consider this `PreToolUse` hook that blocks destructive shell commands.
7266
73<Tabs>
74 <Tab title="macOS/Linux">
75 The `matcher` narrows to Bash tool calls and the `if` condition narrows further to Bash subcommands matching `rm *`, so `block-rm.sh` only spawns when both filters match:
76
77 ```json theme={null}
78 {
79 "hooks": {
80 "PreToolUse": [
67**macOS/Linux**
68
69The `matcher` narrows to Bash tool calls and the `if` condition narrows further to Bash subcommands matching `rm *`, so `block-rm.sh` only spawns when both filters match:
70
71```json theme={null}
72{
73 "hooks": {
74 "PreToolUse": [
75 {
76 "matcher": "Bash",
77 "hooks": [
8178 {
82 "matcher": "Bash",
83 "hooks": [
84 {
85 "type": "command",
86 "if": "Bash(rm *)",
87 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
88 "args": []
89 }
79 "type": "command",
80 "if": "Bash(rm *)",
81 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
82 "args": []
83 }
84 ]
85 }
86 ]
87 }
88}
89```
90
91The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf`. Save it to `.claude/hooks/block-rm.sh` in your project and make it executable with `chmod +x .claude/hooks/block-rm.sh` so Claude Code can run it:
92
93```bash theme={null}
94#!/bin/bash
95# .claude/hooks/block-rm.sh
96COMMAND=$(jq -r '.tool_input.command')
97
98if echo "$COMMAND" | grep -q 'rm -rf'; then
99 jq -n '{
100 hookSpecificOutput: {
101 hookEventName: "PreToolUse",
102 permissionDecision: "deny",
103 permissionDecisionReason: "Destructive command blocked by hook"
104 }
105 }'
106else
107 exit 0 # no decision; normal permission flow applies
108fi
109```
110
111This script, like the other Bash examples on this page that parse JSON input, uses `jq`, so install `jq` and make sure it is on your `PATH` before trying them.
112
113**Windows (PowerShell)**
114
115The matcher `Bash|PowerShell` covers the [PowerShell tool](#powershell) as well as Bash. A single `if` rule matches only one tool's calls, so each tool gets its own handler: the first narrows to Bash subcommands matching `rm *`, the second to PowerShell commands matching `Remove-Item *`. Both run the same script through `powershell.exe`:
116
117```json theme={null}
118{
119 "hooks": {
120 "PreToolUse": [
121 {
122 "matcher": "Bash|PowerShell",
123 "hooks": [
124 {
125 "type": "command",
126 "if": "Bash(rm *)",
127 "command": "powershell.exe",
128 "args": [
129 "-NoProfile",
130 "-ExecutionPolicy",
131 "Bypass",
132 "-File",
133 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
134 ]
135 },
136 {
137 "type": "command",
138 "if": "PowerShell(Remove-Item *)",
139 "command": "powershell.exe",
140 "args": [
141 "-NoProfile",
142 "-ExecutionPolicy",
143 "Bypass",
144 "-File",
145 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
90146 ]
91147 }
92148 ]
93149 }
150 ]
151 }
152}
153```
154
155The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file.
156
157The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf` or `Remove-Item` followed by `-Recurse`. Save it to `.claude/hooks/block-rm.ps1` in your project:
158
159```powershell theme={null}
160# .claude/hooks/block-rm.ps1
161$callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
162$command = $callInput.tool_input.command
163
164if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
165 @{
166 hookSpecificOutput = @{
167 hookEventName = "PreToolUse"
168 permissionDecision = "deny"
169 permissionDecisionReason = "Destructive command blocked by hook"
94170 }
95 ```
96
97 The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf`. Save it to `.claude/hooks/block-rm.sh` in your project and make it executable with `chmod +x .claude/hooks/block-rm.sh` so Claude Code can run it:
98
99 ```bash theme={null}
100 #!/bin/bash
101 # .claude/hooks/block-rm.sh
102 COMMAND=$(jq -r '.tool_input.command')
103
104 if echo "$COMMAND" | grep -q 'rm -rf'; then
105 jq -n '{
106 hookSpecificOutput: {
107 hookEventName: "PreToolUse",
108 permissionDecision: "deny",
109 permissionDecisionReason: "Destructive command blocked by hook"
110 }
111 }'
112 else
113 exit 0 # no decision; normal permission flow applies
114 fi
115 ```
116
117 This script, like the other Bash examples on this page that parse JSON input, uses `jq`, so install `jq` and make sure it is on your `PATH` before trying them.
118 </Tab>
119
120 <Tab title="Windows (PowerShell)">
121 The matcher `Bash|PowerShell` covers the [PowerShell tool](#powershell) as well as Bash. A single `if` rule matches only one tool's calls, so each tool gets its own handler: the first narrows to Bash subcommands matching `rm *`, the second to PowerShell commands matching `Remove-Item *`. Both run the same script through `powershell.exe`:
122
123 ```json theme={null}
124 {
125 "hooks": {
126 "PreToolUse": [
127 {
128 "matcher": "Bash|PowerShell",
129 "hooks": [
130 {
131 "type": "command",
132 "if": "Bash(rm *)",
133 "command": "powershell.exe",
134 "args": [
135 "-NoProfile",
136 "-ExecutionPolicy",
137 "Bypass",
138 "-File",
139 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
140 ]
141 },
142 {
143 "type": "command",
144 "if": "PowerShell(Remove-Item *)",
145 "command": "powershell.exe",
146 "args": [
147 "-NoProfile",
148 "-ExecutionPolicy",
149 "Bypass",
150 "-File",
151 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
152 ]
153 }
154 ]
155 }
156 ]
157 }
158 }
159 ```
160
161 The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file.
162
163 The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf` or `Remove-Item` followed by `-Recurse`. Save it to `.claude/hooks/block-rm.ps1` in your project:
164
165 ```powershell theme={null}
166 # .claude/hooks/block-rm.ps1
167 $callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
168 $command = $callInput.tool_input.command
169
170 if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
171 @{
172 hookSpecificOutput = @{
173 hookEventName = "PreToolUse"
174 permissionDecision = "deny"
175 permissionDecisionReason = "Destructive command blocked by hook"
176 }
177 } | ConvertTo-Json
178 } else {
179 exit 0 # no decision; normal permission flow applies
180 }
181 ```
182 </Tab>
183</Tabs>
171 } | ConvertTo-Json
172} else {
173 exit 0 # no decision; normal permission flow applies
174}
175```
184176
185177Now suppose Claude Code decides to run `Bash "rm -rf /tmp/build"` against the macOS/Linux config. Here's what happens:
186178
187<Frame>
188 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" className="dark:hidden" alt="Diagram of hook resolution: PreToolUse fires, the matcher checks for a Bash match, then the if condition checks for a Bash(rm *) match. If both match, the hook command runs and returns permissionDecision deny, so the tool call is blocked and Claude Code continues. If either check fails to match, the hook is skipped and the tool call is allowed to proceed." width="930" height="270" data-path="images/hook-resolution.svg" />
189
190 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/hook-resolution-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=e80af91f8507cee6bd51ac3c2dd92f63" className="hidden dark:block" alt="Diagram of hook resolution: PreToolUse fires, the matcher checks for a Bash match, then the if condition checks for a Bash(rm *) match. If both match, the hook command runs and returns permissionDecision deny, so the tool call is blocked and Claude Code continues. If either check fails to match, the hook is skipped and the tool call is allowed to proceed." width="930" height="270" data-path="images/hook-resolution-dark.svg" />
191</Frame>
192
193<Steps>
194 <Step title="Event fires">
195 The `PreToolUse` event fires. Claude Code sends the tool input as JSON on stdin to the hook:
196
197 ```json theme={null}
198 { "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }
199 ```
200 </Step>
201
202 <Step title="Matcher checks">
203 The matcher `"Bash"` matches the tool name, so this hook group activates. If you omit the matcher or use `"*"`, the group activates on every occurrence of the event.
204 </Step>
205
206 <Step title="If condition checks">
207 The `if` condition `"Bash(rm *)"` matches because `rm -rf /tmp/build` is a subcommand matching `rm *`, so this handler spawns. If the command had been `npm test`, the `if` check would fail and `block-rm.sh` would never run, avoiding the process spawn overhead. The `if` field is optional; without it, every handler in the matched group runs.
208 </Step>
209
210 <Step title="Hook handler runs">
211 The script inspects the full command and finds `rm -rf`, so it prints a decision to stdout:
212
213 ```json theme={null}
214 {
215 "hookSpecificOutput": {
216 "hookEventName": "PreToolUse",
217 "permissionDecision": "deny",
218 "permissionDecisionReason": "Destructive command blocked by hook"
219 }
220 }
221 ```
222
223 If 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). The hook can deny the call, but staying silent doesn't approve it.
224 </Step>
225
226 <Step title="Claude Code acts on the result">
227 Claude Code reads the JSON decision, blocks the tool call, and shows Claude the reason.
228 </Step>
229</Steps>
179
180
181**1. Event fires**
182
183The `PreToolUse` event fires. Claude Code sends the tool input as JSON on stdin to the hook:
184
185```json theme={null}
186{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }
187```
188
189**2. Matcher checks**
190
191The matcher `"Bash"` matches the tool name, so this hook group activates. If you omit the matcher or use `"*"`, the group activates on every occurrence of the event.
192
193**3. If condition checks**
194
195The `if` condition `"Bash(rm *)"` matches because `rm -rf /tmp/build` is a subcommand matching `rm *`, so this handler spawns. If the command had been `npm test`, the `if` check would fail and `block-rm.sh` would never run, avoiding the process spawn overhead. The `if` field is optional; without it, every handler in the matched group runs.
196
197**4. Hook handler runs**
198
199The script inspects the full command and finds `rm -rf`, so it prints a decision to stdout:
200
201```json theme={null}
202{
203 "hookSpecificOutput": {
204 "hookEventName": "PreToolUse",
205 "permissionDecision": "deny",
206 "permissionDecisionReason": "Destructive command blocked by hook"
207 }
208}
209```
210
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). The hook can deny the call, but staying silent doesn't approve it.
212
213**5. Claude Code acts on the result**
214
215Claude Code reads the JSON decision, blocks the tool call, and shows Claude the reason.
230216
231217The [Configuration](#configuration) section below documents the full schema, and each [hook event](#hook-events) section documents what input your command receives and what output it can return.
232218
from line 226
240226
241227See [How a hook resolves](#how-a-hook-resolves) above for a complete walkthrough with an annotated example.
242228
243<Note>
244 This page uses specific terms for each level: **hook event** for the lifecycle point, **matcher group** for the filter, and **hook handler** for the shell command, HTTP endpoint, MCP tool, prompt, or agent that runs. "Hook" on its own refers to the general feature.
245</Note>
229> [!NOTE]
230>
231> This page uses specific terms for each level: **hook event** for the lifecycle point, **matcher group** for the filter, and **hook handler** for the shell command, HTTP endpoint, MCP tool, prompt, or agent that runs. "Hook" on its own refers to the general feature.
246232
247233### Hook locations
248234
from line 415
429415
430416In an `if` condition for a file tool, a single-segment directory pattern like `"Edit(src/**)"` matches only the `src` directory in the working directory and the files under it. To match a directory named `src` at any depth, write `"Edit(**/src/**)"`.
431417
432<h4 id="bash-if-matching">
433 How `if` patterns match Bash commands
434</h4>
418#### How `if` patterns match Bash commands
435419
436420For Bash patterns in the [`if` field](#common-fields), whether your hook command runs depends on the shape of the pattern and the Bash command Claude is invoking. Leading `VAR=value` assignments are stripped before matching.
437421
from line 442
458442| `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 |
459443| `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 |
460444
461<a id="exec-form-and-shell-form" />
462
463445##### Exec form and shell form
464446
465447A command hook runs as exec form when `args` is set, and shell form when `args` is omitted. Set `args` whenever the hook references a [path placeholder](#reference-scripts-by-path), since each element is passed as one argument with no quoting. Omit `args` when you need shell features like pipes or `&&`, or when neither concern applies.
from line 450
468450
469451**Shell form** runs when `args` is absent. The `command` string is passed to a shell: `sh -c` on macOS and Linux, Git Bash on Windows, or PowerShell when Git Bash isn't installed. Set the `shell` field to choose explicitly. The shell tokenizes the string, expands variables, and interprets pipes, `&&`, redirects, and globs.
470452
471<Note>
472 On Windows, exec form requires `command` to resolve to a real executable such as a `.exe`. The `.cmd` and `.bat` shims that npm, npx, eslint, and other tools install in `node_modules/.bin` are not executables and can't be spawned without a shell. To run them in exec form, invoke the underlying script with `node` directly, for example `"command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]`. The `node` plus script-path pattern works on every platform because `node.exe` is a real binary. To run a `.cmd` or `.bat` shim by name, use shell form.
473</Note>
453> [!NOTE]
454>
455> On Windows, exec form requires `command` to resolve to a real executable such as a `.exe`. The `.cmd` and `.bat` shims that npm, npx, eslint, and other tools install in `node_modules/.bin` are not executables and can't be spawned without a shell. To run them in exec form, invoke the underlying script with `node` directly, for example `"command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]`. The `node` plus script-path pattern works on every platform because `node.exe` is a real binary. To run a `.cmd` or `.bat` shim by name, use shell form.
474456
475457This example runs a Node script bundled with a plugin. Exec form passes the resolved script path as one argument with no quoting:
476458
from line 479
497479
498480A shell-form plugin hook whose `command` references `${user_config.*}` fails with an [error](/docs/en/errors#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.*}`.
499481
500<Note>
501 In exec form, `command` is the executable name or path only. If `command` is a bare name with no path separator and contains whitespace alongside `args`, Claude Code logs a warning because the spawn will fail: there is no executable named `node script.js`. Move the extra tokens into `args`. Absolute paths with spaces, such as `C:\Program Files\nodejs\node.exe`, are a single valid executable and don't trigger the warning.
502</Note>
482> [!NOTE]
483>
484> In exec form, `command` is the executable name or path only. If `command` is a bare name with no path separator and contains whitespace alongside `args`, Claude Code logs a warning because the spawn will fail: there is no executable named `node script.js`. Move the extra tokens into `args`. Absolute paths with spaces, such as `C:\Program Files\nodejs\node.exe`, are a single valid executable and don't trigger the warning.
503485
504486#### HTTP hook fields
505487
from line 586
604586* `${CLAUDE_PLUGIN_ROOT}`: the plugin's installation directory, for scripts bundled with a [plugin](/docs/en/plugins/overview). See [plugin environment variables](/docs/en/plugins/manifest-reference#environment-variables) for how the path behaves across updates.
605587* `${CLAUDE_PLUGIN_DATA}`: the plugin's [persistent data directory](/docs/en/plugins/components#path-variables-and-persistent-data), for dependencies and state that should survive plugin updates.
606588
607<Note>
608 **Worktrees are different.** If Claude enters a [worktree](/docs/en/worktrees) during the session, Claude Code keeps `${CLAUDE_PROJECT_DIR}` where it was and passes the worktree path to your hooks a different way:
609
610 * **`${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.
611 * **`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.
612
613 For a worktree session that you start from the desktop app, see [What worktrees share with the main checkout](/docs/en/worktrees#what-worktrees-share-with-the-main-checkout) for where `${CLAUDE_PROJECT_DIR}` points.
614</Note>
589> [!NOTE]
590>
591> **Worktrees are different.** If Claude enters a [worktree](/docs/en/worktrees) during the session, Claude Code keeps `${CLAUDE_PROJECT_DIR}` where it was and passes the worktree path to your hooks a different way:
592>
593> * **`${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.
594> * **`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.
595>
596> For a worktree session that you start from the desktop app, see [What worktrees share with the main checkout](/docs/en/worktrees#what-worktrees-share-with-the-main-checkout) for where `${CLAUDE_PROJECT_DIR}` points.
615597
616598Prefer [exec form](#exec-form-and-shell-form) for any hook that references a path placeholder. In shell form, wrap each placeholder in double quotes.
617599
618<Tabs>
619 <Tab title="Project scripts">
620 This example uses `${CLAUDE_PROJECT_DIR}` to run a style checker from the project's `.claude/hooks/` directory after any `Write` or `Edit` tool call:
621
622 ```json theme={null}
623 {
624 "hooks": {
625 "PostToolUse": [
600**Project scripts**
601
602This example uses `${CLAUDE_PROJECT_DIR}` to run a style checker from the project's `.claude/hooks/` directory after any `Write` or `Edit` tool call:
603
604```json theme={null}
605{
606 "hooks": {
607 "PostToolUse": [
608 {
609 "matcher": "Write|Edit",
610 "hooks": [
626611 {
627 "matcher": "Write|Edit",
628 "hooks": [
629 {
630 "type": "command",
631 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",
632 "args": []
633 }
634 ]
612 "type": "command",
613 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",
614 "args": []
635615 }
636616 ]
637617 }
638 }
639 ```
640 </Tab>
641
642 <Tab title="Plugin scripts">
643 Define plugin hooks in `hooks/hooks.json` with an optional top-level `description` field. When a plugin is enabled, its hooks merge with your user and project hooks.
644
645 This example runs a formatting script bundled with the plugin:
646
647 ```json theme={null}
648 {
649 "description": "Automatic code formatting",
650 "hooks": {
651 "PostToolUse": [
618 ]
619 }
620}
621```
622
623**Plugin scripts**
624
625Define plugin hooks in `hooks/hooks.json` with an optional top-level `description` field. When a plugin is enabled, its hooks merge with your user and project hooks.
626
627This example runs a formatting script bundled with the plugin:
628
629```json theme={null}
630{
631 "description": "Automatic code formatting",
632 "hooks": {
633 "PostToolUse": [
634 {
635 "matcher": "Write|Edit",
636 "hooks": [
652637 {
653 "matcher": "Write|Edit",
654 "hooks": [
655 {
656 "type": "command",
657 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
658 "args": [],
659 "timeout": 30
660 }
661 ]
638 "type": "command",
639 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
640 "args": [],
641 "timeout": 30
662642 }
663643 ]
664644 }
665 }
666 ```
667
668 See the [plugin components reference](/docs/en/plugins/components#hooks) for details on creating plugin hooks.
669 </Tab>
670</Tabs>
645 ]
646 }
647}
648```
649
650See the [plugin components reference](/docs/en/plugins/components#hooks) for details on creating plugin hooks.
671651
672652### Hooks in skills and agents
673653
from line 848
868848
869849When you set up a policy hook, watch for this notice on its first run, because a mistyped path in `settings.json` means the hook never runs. To block the action when the hook can't start, set [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
870850
871<Warning>
872 Exit code 1 without valid JSON output is a non-blocking error unless the hook is one [whose failure blocks the action](#block-the-action-when-a-hook-fails), even though 1 is the conventional Unix failure code. If your hook is meant to enforce a policy, use `exit 2`.
873</Warning>
851> [!WARNING]
852>
853> Exit code 1 without valid JSON output is a non-blocking error unless the hook is one [whose failure blocks the action](#block-the-action-when-a-hook-fails), even though 1 is the conventional Unix failure code. If your hook is meant to enforce a policy, use `exit 2`.
874854
875855#### Timeouts
876856
from line 883
903883
904884On most events, when a hook fails or times out, Claude Code still carries out the action. A policy hook with a wrong path or a crashing script then lets everything through. To block the action instead, set `"onFailure": "block"` on a `command` or `http` hook. Requires Claude Code v2.1.295 or later.
905885
906<Note>
907 On Windows without Git Bash, a shell-form `PreToolUse` or `PermissionRequest` command hook that fails with `onFailure` unset can instead [block the tool call](#failed-hooks-on-windows-without-git-bash).
908</Note>
886> [!NOTE]
887>
888> On Windows without Git Bash, a shell-form `PreToolUse` or `PermissionRequest` command hook that fails with `onFailure` unset can instead [block the tool call](#failed-hooks-on-windows-without-git-bash).
909889
910890This `PreToolUse` hook in `.claude/settings.json` runs a project script before each Bash command, and blocks the command if the script fails:
911891
from line 1009
10291009
10301010Exit codes only let you block or stay silent, but JSON output gives you finer-grained control. Instead of exiting with code 2 to block, exit 0 and print a JSON object to stdout. Claude Code reads specific fields from that JSON to control behavior, including [decision control](#decision-control) for blocking, allowing, or escalating to the user.
10311011
1032<Note>
1033 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).
1034</Note>
1012> [!NOTE]
1013>
1014> 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).
10351015
10361016Print 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#hook-json-has-no-effect) shows how to find and silence that text.
10371017
from line 1148
11681148
11691149Here are examples of each pattern in action:
11701150
1171<Tabs>
1172 <Tab title="Top-level decision">
1173 The only value for `decision` is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:
1174
1175 ```json theme={null}
1176 {
1177 "decision": "block",
1178 "reason": "Test suite must pass before proceeding"
1179 }
1180 ```
1181 </Tab>
1182
1183 <Tab title="PreToolUse">
1184 Uses `hookSpecificOutput` for richer control: allow, deny, or escalate to the user. You can also modify tool input before it runs or inject additional context for Claude. See [PreToolUse decision control](#pretooluse-decision-control) for the full set of options.
1185
1186 ```json theme={null}
1187 {
1188 "hookSpecificOutput": {
1189 "hookEventName": "PreToolUse",
1190 "permissionDecision": "deny",
1191 "permissionDecisionReason": "Database writes are not allowed"
1151**Top-level decision**
1152
1153The only value for `decision` is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:
1154
1155```json theme={null}
1156{
1157 "decision": "block",
1158 "reason": "Test suite must pass before proceeding"
1159}
1160```
1161
1162**PreToolUse**
1163
1164Uses `hookSpecificOutput` for richer control: allow, deny, or escalate to the user. You can also modify tool input before it runs or inject additional context for Claude. See [PreToolUse decision control](#pretooluse-decision-control) for the full set of options.
1165
1166```json theme={null}
1167{
1168 "hookSpecificOutput": {
1169 "hookEventName": "PreToolUse",
1170 "permissionDecision": "deny",
1171 "permissionDecisionReason": "Database writes are not allowed"
1172 }
1173}
1174```
1175
1176**PermissionRequest**
1177
1178Uses `hookSpecificOutput` to allow or deny a permission request on behalf of the user. When allowing, you can also modify the tool's input or apply permission rules so the user isn't prompted again. See [PermissionRequest decision control](#permissionrequest-decision-control) for the full set of options.
1179
1180```json theme={null}
1181{
1182 "hookSpecificOutput": {
1183 "hookEventName": "PermissionRequest",
1184 "decision": {
1185 "behavior": "allow",
1186 "updatedInput": {
1187 "command": "npm run lint"
11921188 }
11931189 }
1194 ```
1195 </Tab>
1196
1197 <Tab title="PermissionRequest">
1198 Uses `hookSpecificOutput` to allow or deny a permission request on behalf of the user. When allowing, you can also modify the tool's input or apply permission rules so the user isn't prompted again. See [PermissionRequest decision control](#permissionrequest-decision-control) for the full set of options.
1199
1200 ```json theme={null}
1201 {
1202 "hookSpecificOutput": {
1203 "hookEventName": "PermissionRequest",
1204 "decision": {
1205 "behavior": "allow",
1206 "updatedInput": {
1207 "command": "npm run lint"
1208 }
1209 }
1210 }
1211 }
1212 ```
1213 </Tab>
1214</Tabs>
1190 }
1191}
1192```
12151193
12161194For extended examples including Bash command validation, prompt filtering, and auto-approval scripts, see [What you can automate](/docs/en/hooks-guide#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).
12171195
from line 1344
13661344
13671345Each Bash command runs the file's contents as shell code before the command itself, so a line there can use anything Bash evaluates, such as the `$PATH` reference in `export PATH="$PATH:./node_modules/.bin"`.
13681346
1369<a id="persisted-variables-in-powershell-commands" />
1370
13711347##### Persisted variables in PowerShell commands
13721348
13731349[PowerShell](/docs/en/tools-reference#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:
from line 1353
13771353
13781354If 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) PowerShell command receives none of the variables.
13791355
1380<Note>
1381 `CLAUDE_ENV_FILE` is available for SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged), and [FileChanged](#filechanged) hooks. Other hook events don't have access to this variable, and neither does a hook that runs in PowerShell, whether through [`"shell": "powershell"`](#command-hook-fields) or by default on Windows without Git Bash.
1382</Note>
1356> [!NOTE]
1357>
1358> `CLAUDE_ENV_FILE` is available for SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged), and [FileChanged](#filechanged) hooks. Other hook events don't have access to this variable, and neither does a hook that runs in PowerShell, whether through [`"shell": "powershell"`](#command-hook-fields) or by default on Windows without Git Bash.
13831359
13841360### Setup
13851361
from line 1618
16421618
16431619This example strips markdown formatting from Claude's responses for a plain-text display. The script reads each batch from stdin, removes bold markers and inline code backticks from `delta`, and returns the result as `displayContent`.
16441620
1645<Tabs>
1646 <Tab title="macOS/Linux">
1647 Register a command hook for the event in your settings file:
1648
1649 ```json theme={null}
1650 {
1651 "hooks": {
1652 "MessageDisplay": [
1621**macOS/Linux**
1622
1623Register a command hook for the event in your settings file:
1624
1625```json theme={null}
1626{
1627 "hooks": {
1628 "MessageDisplay": [
1629 {
1630 "hooks": [
16531631 {
1654 "hooks": [
1655 {
1656 "type": "command",
1657 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",
1658 "args": []
1659 }
1632 "type": "command",
1633 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",
1634 "args": []
1635 }
1636 ]
1637 }
1638 ]
1639 }
1640}
1641```
1642
1643Save this script to `.claude/hooks/plain-display.sh` in your project and make it executable with `chmod +x`:
1644
1645```bash theme={null}
1646#!/bin/bash
1647jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'
1648```
1649
1650**Windows (PowerShell)**
1651
1652Register a command hook that runs the script through PowerShell:
1653
1654```json theme={null}
1655{
1656 "hooks": {
1657 "MessageDisplay": [
1658 {
1659 "hooks": [
1660 {
1661 "type": "command",
1662 "command": "powershell.exe",
1663 "args": [
1664 "-NoProfile",
1665 "-ExecutionPolicy",
1666 "Bypass",
1667 "-File",
1668 "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"
16601669 ]
16611670 }
16621671 ]
16631672 }
1664 }
1665 ```
1666
1667 Save this script to `.claude/hooks/plain-display.sh` in your project and make it executable with `chmod +x`:
1668
1669 ```bash theme={null}
1670 #!/bin/bash
1671 jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'
1672 ```
1673 </Tab>
1674
1675 <Tab title="Windows (PowerShell)">
1676 Register a command hook that runs the script through PowerShell:
1677
1678 ```json theme={null}
1679 {
1680 "hooks": {
1681 "MessageDisplay": [
1682 {
1683 "hooks": [
1684 {
1685 "type": "command",
1686 "command": "powershell.exe",
1687 "args": [
1688 "-NoProfile",
1689 "-ExecutionPolicy",
1690 "Bypass",
1691 "-File",
1692 "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"
1693 ]
1694 }
1695 ]
1696 }
1697 ]
1698 }
1699 }
1700 ```
1701
1702 The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file.
1703
1704 Save this script to `.claude/hooks/plain-display.ps1` in your project:
1705
1706 ```powershell theme={null}
1707 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
1708 $text = $batch.delta -replace '\*\*', '' -replace '`', ''
1709 @{
1710 hookSpecificOutput = @{
1711 hookEventName = "MessageDisplay"
1712 displayContent = $text
1713 }
1714 } | ConvertTo-Json
1715 ```
1716 </Tab>
1717</Tabs>
1673 ]
1674 }
1675}
1676```
1677
1678The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file.
1679
1680Save this script to `.claude/hooks/plain-display.ps1` in your project:
1681
1682```powershell theme={null}
1683$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
1684$text = $batch.delta -replace '\*\*', '' -replace '`', ''
1685@{
1686 hookSpecificOutput = @{
1687 hookEventName = "MessageDisplay"
1688 displayContent = $text
1689 }
1690} | ConvertTo-Json
1691```
17181692
17191693Batches with no markdown pass through unchanged. If the script fails, for example because `jq` is missing, Claude Code displays the original text and notes the failure only in [debug output](#debug-hooks), not in the session.
17201694
from line 1698
17241698
17251699To run a hook when a specific file changes on disk, whatever wrote it, use [FileChanged](#filechanged) instead of matching file-editing tools by name. Unlike PreToolUse, Claude Code runs FileChanged hooks after the change, and they have no decision control, so they can't block the write.
17261700
1727<Warning>
1728 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).
1729
1730 You can block specific paths from `@` references, or turn the insertion off:
1731
1732 * **Block specific paths**: add a [`Read` deny rule](/docs/en/permissions#read-and-edit) for them
1733 * **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.
1734</Warning>
1701> [!WARNING]
1702>
1703> 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).
1704>
1705> You can block specific paths from `@` references, or turn the insertion off:
1706>
1707> * **Block specific paths**: add a [`Read` deny rule](/docs/en/permissions#read-and-edit) for them
1708> * **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.
17351709
17361710Use [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, ask, or defer the tool call.
17371711
from line 1740
17661740
17671741The `tool_input` fields depend on the tool:
17681742
1769<a id="bash" />
1770
17711743##### Bash
17721744
17731745Executes shell commands.
from line 1755
17831755
17841756Your [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.
17851757
1786<Note>
1787 The list is best effort and in public beta. Claude Code can miss a change, include a file that another process changed at the same time, or stop at its size limits. The field shape may change. Use the list to find what to review, not to enforce a policy.
1788</Note>
1758> [!NOTE]
1759>
1760> The list is best effort and in public beta. Claude Code can miss a change, include a file that another process changed at the same time, or stop at its size limits. The field shape may change. Use the list to find what to review, not to enforce a policy.
17891761
17901762`changedFiles` and `files` list what the command changed; the remaining fields say how complete and how reliable that list is.
17911763
from line 1769
17971769| `unavailable` | boolean | `true` | Set when the diff is incomplete or couldn't be taken |
17981770| `skipped` | boolean | `true` | Set for a Git command that moves the working tree, such as `git checkout` or `git stash`, so Claude Code takes no diff |
17991771| `shared` | boolean | `true` | Set when another Bash tool call, such as a subagent's, ran in the same repository at the same time, so some listed changes may be that command's |
1800
1801<a id="powershell" />
18021772
18031773##### PowerShell
18041774
from line 1892
19221892
19231893On a `completed` response, `resolvedModel` names the model the subagent started on, which can differ from the `model` value in `tool_input`, such as when `availableModels` or another override applies. On an `async_launched` response, `resolvedModel` names the model in use when the agent moved to the background, so a swap that happened before backgrounding is reflected there.
19241894
1925<a id="askuserquestion" />
1926
19271895##### AskUserQuestion
19281896
19291897Asks the user one to four multiple-choice questions.
from line 1946
19781946}
19791947```
19801948
1981<Note>
1982 PreToolUse previously used top-level `decision` and `reason` fields, but these are deprecated for this event. Use `hookSpecificOutput.permissionDecision` and `hookSpecificOutput.permissionDecisionReason` instead. The deprecated values `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively. Other events like PostToolUse and Stop continue to use top-level `decision` and `reason` as their current format.
1983</Note>
1984
1985<h4 id="allow-with-updatedinput">
1986 Tools that require user interaction
1987</h4>
1949> [!NOTE]
1950>
1951> PreToolUse previously used top-level `decision` and `reason` fields, but these are deprecated for this event. Use `hookSpecificOutput.permissionDecision` and `hookSpecificOutput.permissionDecisionReason` instead. The deprecated values `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively. Other events like PostToolUse and Stop continue to use top-level `decision` and `reason` as their current format.
1952
1953#### Tools that require user interaction
19881954
19891955`AskUserQuestion` and `ExitPlanMode` require user interaction. In [non-interactive mode](/docs/en/headless) with the `-p` flag, Claude Code offers them only when the run has a [permission host](/docs/en/headless#turn-off-permission-prompts-in-unattended-runs) to receive the prompt, such as an Agent SDK `canUseTool` callback.
19901956
from line 2020
20542020
20552021If the deferred tool is no longer available when you resume, the process exits with `stop_reason: "tool_deferred_unavailable"` and `is_error: true` before the hook fires. 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.
20562022
2057<Note>
2058 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.
2059
2060 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#permission-mode-on-resume).
2061</Note>
2023> [!NOTE]
2024>
2025> 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.
2026>
2027> 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#permission-mode-on-resume).
20622028
20632029### PermissionRequest
20642030
from line 2109
21432109| `addDirectories` | `directories`, `destination` | Adds working directories. `directories` is an array of path strings |
21442110| `removeDirectories` | `directories`, `destination` | Removes working directories |
21452111
2146<Note>
2147 `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#cli-flags).
2148
2149 `bypassPermissions` is never persisted as `defaultMode` regardless of `destination`.
2150</Note>
2112> [!NOTE]
2113>
2114> `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#cli-flags).
2115>
2116> `bypassPermissions` is never persisted as `defaultMode` regardless of `destination`.
21512117
21522118The `destination` field on every entry determines whether the change stays in memory or persists to a settings file.
21532119
from line 2196
22302196}
22312197```
22322198
2233<Warning>
2234 `updatedToolOutput` only changes what Claude sees. The tool has already run by the time the hook fires, so any files written, commands executed, or network requests sent have already taken effect. Telemetry such as OpenTelemetry tool spans and analytics events also captures the original output before the hook runs. To prevent or modify a tool call before it runs, use a [PreToolUse](#pretooluse) hook instead.
2235
2236 The replacement value must match the tool's output shape. Built-in tools return structured objects rather than plain strings. For example, `Bash` returns an object with `stdout`, `stderr`, `interrupted`, and `isImage` fields. For built-in tools, a value that doesn't match the tool's output schema is ignored and the original output is used. MCP tool output is passed through without schema validation. Stripping error details that Claude needs can cause it to proceed on a false assumption.
2237</Warning>
2199> [!WARNING]
2200>
2201> `updatedToolOutput` only changes what Claude sees. The tool has already run by the time the hook fires, so any files written, commands executed, or network requests sent have already taken effect. Telemetry such as OpenTelemetry tool spans and analytics events also captures the original output before the hook runs. To prevent or modify a tool call before it runs, use a [PreToolUse](#pretooluse) hook instead.
2202>
2203> The replacement value must match the tool's output shape. Built-in tools return structured objects rather than plain strings. For example, `Bash` returns an object with `stdout`, `stderr`, `interrupted`, and `isImage` fields. For built-in tools, a value that doesn't match the tool's output schema is ignored and the original output is used. MCP tool output is passed through without schema validation. Stripping error details that Claude needs can cause it to proceed on a false assumption.
22382204
22392205#### Annotate a result for the auto mode classifier
22402206
from line 2229
22632229* **Calls that the classifier doesn't record**: the classifier's transcript omits read-only lookups such as file reads and searches. Claude Code discards a note attached to one of those calls
22642230* **Interaction with rewrites**: when the note describes output you're replacing with `updatedToolOutput`, return both fields in the same hook response. Claude Code drops the note if that rewrite is rejected or another hook's rewrite replaces it. Claude Code delivers a note you return without a rewrite even when another hook rewrites the output
22652231
2266<Warning>
2267 The classifier reads content you place in `classifierContext` as information from the application hosting the session, so don't copy untrusted tool output or third-party text into it. Keep the note to a short assertion about this one call, such as a fact about its origin or a user statement about it; don't use the field to deliver unrelated messages or a stream of events.
2268</Warning>
2232> [!WARNING]
2233>
2234> The classifier reads content you place in `classifierContext` as information from the application hosting the session, so don't copy untrusted tool output or third-party text into it. Keep the note to a short assertion about this one call, such as a fact about its origin or a user statement about it; don't use the field to deliver unrelated messages or a stream of events.
22692235
22702236### PostToolUseFailure
22712237
from line 2239
22732239
22742240Matches on tool name, same values as PreToolUse.
22752241
2276<Note>
2277 This event doesn't fire for tool calls rejected before execution: an unknown tool name, input that fails schema or tool-specific validation, or a permission denial. Validation rejections are returned as `tool_use_error` results and happen before hooks run, so they fire neither `PreToolUse` nor `PostToolUseFailure`. Permission denials fire `PreToolUse` but not this event; see [PermissionDenied](#permissiondenied).
2278</Note>
2242> [!NOTE]
2243>
2244> This event doesn't fire for tool calls rejected before execution: an unknown tool name, input that fails schema or tool-specific validation, or a permission denial. Validation rejections are returned as `tool_use_error` results and happen before hooks run, so they fire neither `PreToolUse` nor `PostToolUseFailure`. Permission denials fire `PreToolUse` but not this event; see [PermissionDenied](#permissiondenied).
22792245
22802246#### PostToolUseFailure input
22812247
from line 2329
23632329
23642330`tool_response` contains the same content the model receives in the corresponding `tool_result` block. The value is a serialized string or content-block array, exactly as the tool emitted it. For `Read`, that means line-number-prefixed text rather than raw file contents. Responses can be large, so parse only the fields you need.
23652331
2366<Note>
2367 The `tool_response` shape differs from `PostToolUse`'s. `PostToolUse` passes the tool's structured `Output` object, such as `{filePath: "...", type: "create"}` for `Write`; `PostToolBatch` passes the serialized `tool_result` content the model sees.
2368</Note>
2332> [!NOTE]
2333>
2334> The `tool_response` shape differs from `PostToolUse`'s. `PostToolUse` passes the tool's structured `Output` object, such as `{filePath: "...", type: "create"}` for `Write`; `PostToolBatch` passes the serialized `tool_result` content the model sees.
23692335
23702336#### PostToolBatch decision control
23712337
from line 2427
24612427
24622428`agent_needs_input` for a teammate's terminal setup question requires Claude Code v2.1.248 or later.
24632429
2464<Note>
2465 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:
2466
2467 * 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.
2468 * 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), 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.
2469 * 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.
2470
2471 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.
2472</Note>
2430> [!NOTE]
2431>
2432> 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:
2433>
2434> * 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.
2435> * 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), 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.
2436> * 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.
2437>
2438> 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.
24732439
24742440Claude 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:
24752441
from line 2683
27172683the stoppage occurred due to a user interrupt. API errors fire
27182684[StopFailure](#stopfailure) instead.
27192685
2720<Tip>
2721 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.
2722</Tip>
2686> [!TIP]
2687>
2688> 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.
27232689
27242690#### Stop input
27252691
from line 3306
33403306
33413307Write 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:
33423308
3343<Tabs>
3344 <Tab title="macOS/Linux">
3345 The command checks `to_model` with `jq`:
3346
3347 ```json theme={null}
3348 {
3349 "hooks": {
3350 "PreModelSwitch": [
3309**macOS/Linux**
3310
3311The command checks `to_model` with `jq`:
3312
3313```json theme={null}
3314{
3315 "hooks": {
3316 "PreModelSwitch": [
3317 {
3318 "matcher": "claude-opus-4-6",
3319 "hooks": [
33513320 {
3352 "matcher": "claude-opus-4-6",
3353 "hooks": [
3354 {
3355 "type": "command",
3356 "command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
3357 }
3321 "type": "command",
3322 "command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
3323 }
3324 ]
3325 }
3326 ]
3327 }
3328}
3329```
3330
3331**Windows (PowerShell)**
3332
3333Register a command hook that runs a script through PowerShell:
3334
3335```json theme={null}
3336{
3337 "hooks": {
3338 "PreModelSwitch": [
3339 {
3340 "matcher": "claude-opus-4-6",
3341 "hooks": [
3342 {
3343 "type": "command",
3344 "command": "powershell.exe",
3345 "args": [
3346 "-NoProfile",
3347 "-ExecutionPolicy",
3348 "Bypass",
3349 "-File",
3350 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
33583351 ]
33593352 }
33603353 ]
33613354 }
3362 }
3363 ```
3364 </Tab>
3365
3366 <Tab title="Windows (PowerShell)">
3367 Register a command hook that runs a script through PowerShell:
3368
3369 ```json theme={null}
3370 {
3371 "hooks": {
3372 "PreModelSwitch": [
3373 {
3374 "matcher": "claude-opus-4-6",
3375 "hooks": [
3376 {
3377 "type": "command",
3378 "command": "powershell.exe",
3379 "args": [
3380 "-NoProfile",
3381 "-ExecutionPolicy",
3382 "Bypass",
3383 "-File",
3384 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
3385 ]
3386 }
3387 ]
3388 }
3389 ]
3390 }
3391 }
3392 ```
3393
3394 Save this script to `.claude/hooks/block-opus-46.ps1` in your project:
3395
3396 ```powershell theme={null}
3397 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
3398 if ($hookInput.to_model -match 'opus-4-6') {
3399 [Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
3400 exit 2
3401 }
3402 exit 0
3403 ```
3404 </Tab>
3405</Tabs>
3355 ]
3356 }
3357}
3358```
3359
3360Save this script to `.claude/hooks/block-opus-46.ps1` in your project:
3361
3362```powershell theme={null}
3363$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
3364if ($hookInput.to_model -match 'opus-4-6') {
3365 [Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
3366 exit 2
3367}
3368exit 0
3369```
34063370
34073371To confirm the hook works, run `/model claude-opus-4-6` from a session running a different model. Claude Code keeps the current model and reports that a PreModelSwitch hook blocked the switch, with your message as the reason.
34083372
from line 3654
36903654
36913655This example answers one recurring question for the user. An MCP server named `issue-tracker` asks for a project key in a form, and the hook fills in `DOCS`. The script accepts when `project_key` is the form's single field. For any other request it prints nothing, so the dialog appears.
36923656
3693<Tabs>
3694 <Tab title="macOS/Linux">
3695 Register a command hook for the event in your settings file, with the server name as the matcher:
3696
3697 ```json theme={null}
3698 {
3699 "hooks": {
3700 "Elicitation": [
3657**macOS/Linux**
3658
3659Register a command hook for the event in your settings file, with the server name as the matcher:
3660
3661```json theme={null}
3662{
3663 "hooks": {
3664 "Elicitation": [
3665 {
3666 "matcher": "issue-tracker",
3667 "hooks": [
37013668 {
3702 "matcher": "issue-tracker",
3703 "hooks": [
3704 {
3705 "type": "command",
3706 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh",
3707 "args": []
3708 }
3669 "type": "command",
3670 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh",
3671 "args": []
3672 }
3673 ]
3674 }
3675 ]
3676 }
3677}
3678```
3679
3680Save this script to `.claude/hooks/answer-project-key.sh` in your project and make it executable with `chmod +x`:
3681
3682```bash theme={null}
3683#!/bin/bash
3684input=$(cat)
3685fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input")
3686
3687if [ "$fields" = '["project_key"]' ]; then
3688 jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}'
3689fi
3690```
3691
3692**Windows (PowerShell)**
3693
3694Register a command hook that runs the script through PowerShell, with the server name as the matcher:
3695
3696```json theme={null}
3697{
3698 "hooks": {
3699 "Elicitation": [
3700 {
3701 "matcher": "issue-tracker",
3702 "hooks": [
3703 {
3704 "type": "command",
3705 "command": "powershell.exe",
3706 "args": [
3707 "-NoProfile",
3708 "-ExecutionPolicy",
3709 "Bypass",
3710 "-File",
3711 "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1"
37093712 ]
37103713 }
37113714 ]
37123715 }
3716 ]
3717 }
3718}
3719```
3720
3721Save this script to `.claude/hooks/answer-project-key.ps1` in your project:
3722
3723```powershell theme={null}
3724$request = [Console]::In.ReadToEnd() | ConvertFrom-Json
3725$fields = @($request.requested_schema.properties.PSObject.Properties.Name)
3726
3727if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') {
3728 @{
3729 hookSpecificOutput = @{
3730 hookEventName = "Elicitation"
3731 action = "accept"
3732 content = @{ project_key = "DOCS" }
37133733 }
3714 ```
3715
3716 Save this script to `.claude/hooks/answer-project-key.sh` in your project and make it executable with `chmod +x`:
3717
3718 ```bash theme={null}
3719 #!/bin/bash
3720 input=$(cat)
3721 fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input")
3722
3723 if [ "$fields" = '["project_key"]' ]; then
3724 jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}'
3725 fi
3726 ```
3727 </Tab>
3728
3729 <Tab title="Windows (PowerShell)">
3730 Register a command hook that runs the script through PowerShell, with the server name as the matcher:
3731
3732 ```json theme={null}
3733 {
3734 "hooks": {
3735 "Elicitation": [
3736 {
3737 "matcher": "issue-tracker",
3738 "hooks": [
3739 {
3740 "type": "command",
3741 "command": "powershell.exe",
3742 "args": [
3743 "-NoProfile",
3744 "-ExecutionPolicy",
3745 "Bypass",
3746 "-File",
3747 "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1"
3748 ]
3749 }
3750 ]
3751 }
3752 ]
3753 }
3754 }
3755 ```
3756
3757 Save this script to `.claude/hooks/answer-project-key.ps1` in your project:
3758
3759 ```powershell theme={null}
3760 $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
3761 $fields = @($request.requested_schema.properties.PSObject.Properties.Name)
3762
3763 if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') {
3764 @{
3765 hookSpecificOutput = @{
3766 hookEventName = "Elicitation"
3767 action = "accept"
3768 content = @{ project_key = "DOCS" }
3769 }
3770 } | ConvertTo-Json -Depth 3
3771 }
3772 ```
3773 </Tab>
3774</Tabs>
3734 } | ConvertTo-Json -Depth 3
3735}
3736```
37753737
37763738To confirm the hook works, start Claude Code with `claude --debug` and give Claude a task that makes the server ask for the project key. No dialog appears, and the [debug log](#debug-hooks) has a line that ends with `Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}}`.
37773739
from line 3956
39943956
39953957## Agent-based hooks
39963958
3997<Warning>
3998 Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](#command-hook-fields).
3999</Warning>
3959> [!WARNING]
3960>
3961> Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](#command-hook-fields).
40003962
40013963Agent-based hooks (`type: "agent"`) are like prompt-based hooks but with multi-turn tool access. Instead of a single LLM call, an agent hook spawns a subagent that can read files, search code, and inspect the codebase to verify conditions. Agent hooks support the same events as [prompt-based hooks](#prompt-based-hooks), except `PermissionRequest`.
40023964
from line 4112
41504112
41514113### Disclaimer
41524114
4153<Warning>
4154 Command hooks execute shell commands with your full user permissions. They can modify, delete, or access any files your user account can access. Review and test all hook commands before adding them to your configuration.
4155</Warning>
4115> [!WARNING]
4116>
4117> Command hooks execute shell commands with your full user permissions. They can modify, delete, or access any files your user account can access. Review and test all hook commands before adding them to your configuration.
41564118
41574119### Workspace trust
41584120
41594121
hooks-guide Changed · +290 / -298 lines
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 8
88
99For other ways to extend Claude Code, see [skills](/docs/en/skills) for giving Claude additional instructions and executable commands, [subagents](/docs/en/sub-agents) for running tasks in isolated contexts, and [plugins](/docs/en/plugins/overview) for packaging extensions to share across projects.
1010
11<Tip>
12 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).
13</Tip>
11> [!TIP]
12>
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).
1414
1515## Set up your first hook
1616
1717To create a hook, add a `hooks` block to a [settings file](#configure-hook-location). This walkthrough creates a desktop notification hook, so you get alerted whenever Claude is waiting for your input instead of watching the terminal.
1818
19<Steps>
20 <Step title="Add the hook to your settings">
21 Open `~/.claude/settings.json` and add a `Notification` hook. If the file doesn't exist, create it. The example below uses `osascript` for macOS; see [Get notified when Claude needs input](#get-notified-when-claude-needs-input) for Linux and Windows commands.
22
23 ```json theme={null}
24 {
25 "hooks": {
26 "Notification": [
27 {
28 "matcher": "",
29 "hooks": [
30 {
31 "type": "command",
32 "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
33 }
34 ]
35 }
36 ]
37 }
38 }
39 ```
40
41 If your settings file already has a `hooks` key, add `Notification` as a sibling of the existing event keys rather than replacing the whole object. Each event name is a key inside the single `hooks` object:
42
43 ```json theme={null}
44 {
45 "hooks": {
46 "PostToolUse": [
47 {
48 "matcher": "Edit|Write",
49 "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
50 }
51 ],
52 "Notification": [
53 {
54 "matcher": "",
55 "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
56 }
57 ]
58 }
59 }
60 ```
61
62 You can also ask Claude to write the hook for you by describing what you want in the CLI.
63 </Step>
64
65 <Step title="Verify the configuration">
66 Type `/hooks` at the Claude Code prompt to open the hooks browser. Your new hook appears in the list under `Notification`.
67 </Step>
68
69 <Step title="Test the hook">
70 Press `Esc` to return to the CLI. Press `Shift+Tab` until the status bar shows `⏸ manual mode on`, ask Claude to do something that requires permission, then switch away from the terminal. You should receive a desktop notification.
71 </Step>
72</Steps>
19**1. Add the hook to your settings**
20
21Open `~/.claude/settings.json` and add a `Notification` hook. If the file doesn't exist, create it. The example below uses `osascript` for macOS; see [Get notified when Claude needs input](#get-notified-when-claude-needs-input) for Linux and Windows commands.
22
23```json theme={null}
24{
25 "hooks": {
26 "Notification": [
27 {
28 "matcher": "",
29 "hooks": [
30 {
31 "type": "command",
32 "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
33 }
34 ]
35 }
36 ]
37 }
38}
39```
40
41If your settings file already has a `hooks` key, add `Notification` as a sibling of the existing event keys rather than replacing the whole object. Each event name is a key inside the single `hooks` object:
42
43```json theme={null}
44{
45 "hooks": {
46 "PostToolUse": [
47 {
48 "matcher": "Edit|Write",
49 "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
50 }
51 ],
52 "Notification": [
53 {
54 "matcher": "",
55 "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
56 }
57 ]
58 }
59}
60```
61
62You can also ask Claude to write the hook for you by describing what you want in the CLI.
63
64**2. Verify the configuration**
65
66Type `/hooks` at the Claude Code prompt to open the hooks browser. Your new hook appears in the list under `Notification`.
67
68**3. Test the hook**
69
70Press `Esc` to return to the CLI. Press `Shift+Tab` until the status bar shows `⏸ manual mode on`, ask Claude to do something that requires permission, then switch away from the terminal. You should receive a desktop notification.
7371
7472## What you can automate
7573
from line 85
8785
8886Each tab below uses the platform's native notification command. Add this to `~/.claude/settings.json`:
8987
90<Tabs>
91 <Tab title="macOS">
92 ```json theme={null}
93 {
94 "hooks": {
95 "Notification": [
96 {
97 "matcher": "",
98 "hooks": [
99 {
100 "type": "command",
101 "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
102 }
103 ]
104 }
105 ]
106 }
107 }
108 ```
109
110 <Accordion title="If no notification appears">
111 `osascript` routes notifications through the built-in Script Editor app. If Script Editor doesn't have notification permission, the command fails silently, and macOS won't prompt you to grant it.
112
113 Run this in Terminal once to make Script Editor appear in your notification settings:
114
115 ```bash theme={null}
116 osascript -e 'display notification "test"'
117 ```
118
119 Nothing will appear yet. Open **System Settings > Notifications**, find **Script Editor** in the list, and turn on **Allow Notifications**. Run the command again to confirm the test notification appears.
120 </Accordion>
121 </Tab>
122
123 <Tab title="Linux">
124 ```json theme={null}
125 {
126 "hooks": {
127 "Notification": [
128 {
129 "matcher": "",
130 "hooks": [
131 {
132 "type": "command",
133 "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
134 }
135 ]
136 }
137 ]
138 }
139 }
140 ```
141
142 <Accordion title="If no notification appears">
143 `notify-send` needs a desktop notification daemon, which headless servers, SSH sessions, and most containers don't have. Test the command directly first:
144
145 ```bash theme={null}
146 notify-send 'Claude Code' 'test'
147 ```
148
149 If the command isn't found, install the `libnotify-bin` package on Debian and Ubuntu, or your distribution's equivalent.
150 </Accordion>
151 </Tab>
152
153 <Tab title="Windows (PowerShell)">
154 ```json theme={null}
155 {
156 "hooks": {
157 "Notification": [
158 {
159 "matcher": "",
160 "hooks": [
161 {
162 "type": "command",
163 "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
164 }
165 ]
166 }
167 ]
168 }
169 }
170 ```
171
172 <Accordion title="If no dialog appears">
173 This command opens a dialog box rather than a notification in the corner of your screen, so the dialog can open behind your terminal window. Test the command directly in PowerShell first.
174
175 If you run Claude Code inside WSL, `powershell.exe` must be available on your `PATH` through Windows interop.
176 </Accordion>
177 </Tab>
178</Tabs>
88**macOS**
89
90```json theme={null}
91{
92 "hooks": {
93 "Notification": [
94 {
95 "matcher": "",
96 "hooks": [
97 {
98 "type": "command",
99 "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
100 }
101 ]
102 }
103 ]
104 }
105}
106```
107
108> **If no notification appears**
109>
110> `osascript` routes notifications through the built-in Script Editor app. If Script Editor doesn't have notification permission, the command fails silently, and macOS won't prompt you to grant it.
111>
112> Run this in Terminal once to make Script Editor appear in your notification settings:
113>
114> ```bash theme={null}
115> osascript -e 'display notification "test"'
116> ```
117>
118> Nothing will appear yet. Open **System Settings > Notifications**, find **Script Editor** in the list, and turn on **Allow Notifications**. Run the command again to confirm the test notification appears.
119
120**Linux**
121
122```json theme={null}
123{
124 "hooks": {
125 "Notification": [
126 {
127 "matcher": "",
128 "hooks": [
129 {
130 "type": "command",
131 "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
132 }
133 ]
134 }
135 ]
136 }
137}
138```
139
140> **If no notification appears**
141>
142> `notify-send` needs a desktop notification daemon, which headless servers, SSH sessions, and most containers don't have. Test the command directly first:
143>
144> ```bash theme={null}
145> notify-send 'Claude Code' 'test'
146> ```
147>
148> If the command isn't found, install the `libnotify-bin` package on Debian and Ubuntu, or your distribution's equivalent.
149
150**Windows (PowerShell)**
151
152```json theme={null}
153{
154 "hooks": {
155 "Notification": [
156 {
157 "matcher": "",
158 "hooks": [
159 {
160 "type": "command",
161 "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
162 }
163 ]
164 }
165 ]
166 }
167}
168```
169
170> **If no dialog appears**
171>
172> This command opens a dialog box rather than a notification in the corner of your screen, so the dialog can open behind your terminal window. Test the command directly in PowerShell first.
173>
174> If you run Claude Code inside WSL, `powershell.exe` must be available on your `PATH` through Windows interop.
179175
180176The empty `matcher` fires on all notification types. To fire only on specific events, set it to one of these values:
181177
from line 230
234230
235231To reformat a specific file however it changes, including when a `Bash` command rewrites it, use a [FileChanged](/docs/en/hooks#filechanged) hook instead.
236232
237<Note>
238 The Bash examples on this page use `jq` for JSON parsing. Install it with `brew install jq` on macOS, `apt-get install jq` on Debian and Ubuntu, or see [`jq` downloads](https://jqlang.org/download/).
239</Note>
233> [!NOTE]
234>
235> The Bash examples on this page use `jq` for JSON parsing. Install it with `brew install jq` on macOS, `apt-get install jq` on Debian and Ubuntu, or see [`jq` downloads](https://jqlang.org/download/).
240236
241237### Block edits to protected files
242238
from line 240
244240
245241This example uses a separate script file that the hook calls. The script checks the target file path against a list of protected patterns and exits with code 2 to block the edit.
246242
247<Steps>
248 <Step title="Create the hook script">
249 Save this to `.claude/hooks/protect-files.sh`:
250
251 ```bash theme={null}
252 #!/bin/bash
253 # protect-files.sh
254
255 INPUT=$(cat)
256 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
257
258 # Normalize Windows backslash separators so the patterns below match
259 FILE_PATH="${FILE_PATH//\\//}"
260
261 PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
262
263 for pattern in "${PROTECTED_PATTERNS[@]}"; do
264 if [[ "$FILE_PATH" == *"$pattern"* ]]; then
265 echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
266 exit 2
267 fi
268 done
269
270 exit 0
271 ```
272 </Step>
273
274 <Step title="Make the script executable on macOS and Linux">
275 Hook scripts must be executable for Claude Code to run them:
276
277 ```bash theme={null}
278 chmod +x .claude/hooks/protect-files.sh
279 ```
280 </Step>
281
282 <Step title="Register the hook">
283 Add a `PreToolUse` hook to `.claude/settings.json` that runs the script before any `Edit` or `Write` tool call:
284
285 ```json theme={null}
286 {
287 "hooks": {
288 "PreToolUse": [
289 {
290 "matcher": "Edit|Write",
291 "hooks": [
292 {
293 "type": "command",
294 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
295 }
296 ]
297 }
298 ]
299 }
300 }
301 ```
302 </Step>
303
304 <Step title="Test the hook">
305 Ask Claude to add a comment to your `.env` file. Claude Code blocks the edit before it runs and passes the script's `Blocked:` message to Claude as feedback.
306 </Step>
307</Steps>
243**1. Create the hook script**
244
245Save this to `.claude/hooks/protect-files.sh`:
246
247```bash theme={null}
248#!/bin/bash
249# protect-files.sh
250
251INPUT=$(cat)
252FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
253
254# Normalize Windows backslash separators so the patterns below match
255FILE_PATH="${FILE_PATH//\\//}"
256
257PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
258
259for pattern in "${PROTECTED_PATTERNS[@]}"; do
260 if [[ "$FILE_PATH" == *"$pattern"* ]]; then
261 echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
262 exit 2
263 fi
264done
265
266exit 0
267```
268
269**2. Make the script executable on macOS and Linux**
270
271Hook scripts must be executable for Claude Code to run them:
272
273```bash theme={null}
274chmod +x .claude/hooks/protect-files.sh
275```
276
277**3. Register the hook**
278
279Add a `PreToolUse` hook to `.claude/settings.json` that runs the script before any `Edit` or `Write` tool call:
280
281```json theme={null}
282{
283 "hooks": {
284 "PreToolUse": [
285 {
286 "matcher": "Edit|Write",
287 "hooks": [
288 {
289 "type": "command",
290 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
291 }
292 ]
293 }
294 ]
295 }
296}
297```
298
299**4. Test the hook**
300
301Ask Claude to add a comment to your `.env` file. Claude Code blocks the edit before it runs and passes the script's `Blocked:` message to Claude as feedback.
308302
309303### Re-inject context after compaction
310304
from line 441
447441
448442To set a specific permission mode instead, your hook's output can include an `updatedPermissions` array with a `setMode` entry. The `mode` value is any permission mode like `default`, `acceptEdits`, or `bypassPermissions`, and `destination: "session"` applies it for the current session only.
449443
450<Note>
451 `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#cli-flags).
452
453 Claude Code never saves it as `defaultMode`.
454</Note>
444> [!NOTE]
445>
446> `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#cli-flags).
447>
448> Claude Code never saves it as `defaultMode`.
455449
456450To switch the session to `acceptEdits`, your hook writes this JSON to stdout:
457451
from line 602
608602
609603Exit codes only let you block or stay silent. For more control, exit 0 and print a JSON object to stdout instead.
610604
611<Note>
612 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#exit-code-output).
613</Note>
605> [!NOTE]
606>
607> 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#exit-code-output).
614608
615609For example, a `PreToolUse` hook can deny a tool call and tell Claude why, or escalate it to the user for approval:
616610
from line 670
676670
677671The `"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#matcher-patterns) for how plain names and regular expressions are evaluated.
678672
679<Note>
680 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#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#filechanged) hook.
681</Note>
673> [!NOTE]
674>
675> 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#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#filechanged) hook.
682676
683677Each event type matches on a specific field:
684678
from line 699
705699
706700The tabs below show a few more matchers on different event types.
707701
708<Tabs>
709 <Tab title="Log every Bash command">
710 Match only `Bash` tool calls and log each command to a file. The `PostToolUse` event fires after the command completes, so `tool_input.command` contains what ran. The hook receives the event data as JSON on stdin, and `jq -r '.tool_input.command'` extracts only the command string, which `>>` appends to the log file:
711
712 ```json theme={null}
713 {
714 "hooks": {
715 "PostToolUse": [
716 {
717 "matcher": "Bash",
718 "hooks": [
719 {
720 "type": "command",
721 "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
722 }
723 ]
724 }
725 ]
726 }
727 }
728 ```
729 </Tab>
730
731 <Tab title="Match MCP tools">
732 MCP 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#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#match-mcp-tools) in the reference for the full list of examples.
733
734 The 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#debug-hooks):
735
736 ```json theme={null}
737 {
738 "hooks": {
739 "PreToolUse": [
740 {
741 "matcher": "mcp__github__.*",
742 "hooks": [
743 {
744 "type": "command",
745 "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
746 }
747 ]
748 }
749 ]
750 }
751 }
752 ```
753 </Tab>
754
755 <Tab title="Clean up on session end">
756 The `SessionEnd` event supports matchers on the reason the session ended. This hook only fires on the `clear` reason, set when you run `/clear`, not on normal exits:
757
758 ```json theme={null}
759 {
760 "hooks": {
761 "SessionEnd": [
762 {
763 "matcher": "clear",
764 "hooks": [
765 {
766 "type": "command",
767 "command": "rm -f /tmp/claude-scratch-*.txt"
768 }
769 ]
770 }
771 ]
772 }
773 }
774 ```
775 </Tab>
776</Tabs>
702**Log every Bash command**
703
704Match only `Bash` tool calls and log each command to a file. The `PostToolUse` event fires after the command completes, so `tool_input.command` contains what ran. The hook receives the event data as JSON on stdin, and `jq -r '.tool_input.command'` extracts only the command string, which `>>` appends to the log file:
705
706```json theme={null}
707{
708 "hooks": {
709 "PostToolUse": [
710 {
711 "matcher": "Bash",
712 "hooks": [
713 {
714 "type": "command",
715 "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
716 }
717 ]
718 }
719 ]
720 }
721}
722```
723
724**Match MCP tools**
725
726MCP 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#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#match-mcp-tools) in the reference for the full list of examples.
727
728The 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#debug-hooks):
729
730```json theme={null}
731{
732 "hooks": {
733 "PreToolUse": [
734 {
735 "matcher": "mcp__github__.*",
736 "hooks": [
737 {
738 "type": "command",
739 "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
740 }
741 ]
742 }
743 ]
744 }
745}
746```
747
748**Clean up on session end**
749
750The `SessionEnd` event supports matchers on the reason the session ended. This hook only fires on the `clear` reason, set when you run `/clear`, not on normal exits:
751
752```json theme={null}
753{
754 "hooks": {
755 "SessionEnd": [
756 {
757 "matcher": "clear",
758 "hooks": [
759 {
760 "type": "command",
761 "command": "rm -f /tmp/claude-scratch-*.txt"
762 }
763 ]
764 }
765 ]
766 }
767}
768```
777769
778770#### Filter by tool name and arguments with the `if` field
779771
from line 864
872864
873865## Agent-based hooks
874866
875<Warning>
876 Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](/docs/en/hooks#command-hook-fields).
877</Warning>
867> [!WARNING]
868>
869> Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer [command hooks](/docs/en/hooks#command-hook-fields).
878870
879871When 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.
880872
from line 964
972964 In [plan mode](/docs/en/permissions#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#review-and-approve-a-plan) or switch to another permission mode.
973965* **`"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), including `dontAsk`. This lets you enforce policy that users can't bypass by changing their permission mode.
974966
975<Note>
976 If your machine has no [managed settings](/docs/en/settings#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) 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.
977
978 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#precedence-among-rules-hooks-and-mods).
979</Note>
967> [!NOTE]
968>
969> If your machine has no [managed settings](/docs/en/settings#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) 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>
971> 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#precedence-among-rules-hooks-and-mods).
980972
981973### Hook not firing
982974
983975
how-claude-code-works Changed · +9 / -15 lines
from line 10
1010
1111When you give Claude a task, it works through three phases: **gather context**, **take action**, and **verify results**. These phases blend together. Claude uses tools throughout, whether searching files to understand your code, editing to make changes, or running tests to check its work.
1212
13<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agentic-loop.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=4a30fb7ce2815012a9f27c955e2c6bb0" className="dark:hidden" alt="Diagram of the agentic loop: Your prompt leads to Claude gathering context, taking action, verifying results, and repeating until task complete. You can interrupt at any point." width="720" height="280" data-path="images/agentic-loop.svg" />
13
1414
15<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agentic-loop-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=75e1d55ed76857a952f9a2dffbab02df" className="hidden dark:block" alt="Diagram of the agentic loop: Your prompt leads to Claude gathering context, taking action, verifying results, and repeating until task complete. You can interrupt at any point." width="720" height="280" data-path="images/agentic-loop-dark.svg" />
16
1715The loop adapts to what you ask. A question about your codebase might only need context gathering. A bug fix cycles through all three phases repeatedly. A refactor might involve extensive verification. Claude decides what each step requires based on what it learned from the previous step, chaining dozens of actions together and course-correcting along the way.
1816
1917You're part of this loop too. You can interrupt at any point to steer Claude in a different direction, provide additional context, or ask it to try a different approach. Claude works autonomously but stays responsive to your input.
from line 104
106104
107105Resuming a session with `claude --continue` or `claude --resume` reopens it under the same session ID and appends new messages to the existing conversation. Forking with `--fork-session` or `/branch` copies the history into a new session ID, leaving the original unchanged.
108106
109<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/session-continuity.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=04ed0984a58e4127e05b3640265241a3" className="dark:hidden" alt="Diagram of session continuity: resume continues the same session, fork creates a new branch with a new ID." width="560" height="280" data-path="images/session-continuity.svg" />
107
110108
111<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/session-continuity-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=886a384bce8298594e43f124617ea665" className="hidden dark:block" alt="Diagram of session continuity: resume continues the same session, fork creates a new branch with a new ID." width="560" height="280" data-path="images/session-continuity-dark.svg" />
112
113109For 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).
114110
115111### The context window
from line 219
223219
224220## What's next
225221
226<CardGroup cols={2}>
227 <Card title="Extend with features" icon="puzzle-piece" href="/docs/en/features-overview">
228 Add skills and MCP connections
229 </Card>
222> **[Extend with features](/docs/en/features-overview)**
223>
224> Add skills and MCP connections
230225
231 <Card title="Common workflows" icon="graduation-cap" href="/docs/en/common-workflows">
232 Step-by-step guides for typical tasks
233 </Card>
234</CardGroup>
226> **[Common workflows](/docs/en/common-workflows)**
227>
228> Step-by-step guides for typical tasks
235229
interactive-mode Changed · +51 / -55 lines
### Word boundaries in editing shortcuts
from line 4
44
55## Keyboard shortcuts
66
7<Note>
8 Keyboard shortcuts may vary by platform and terminal. In [fullscreen rendering](/docs/en/fullscreen), press `?` in the transcript viewer to see available shortcuts there.
7> [!NOTE]
8>
9> Keyboard shortcuts may vary by platform and terminal. In [fullscreen rendering](/docs/en/fullscreen), press `?` in the transcript viewer to see available shortcuts there.
10>
11> **macOS users**: Option/Alt key shortcuts (`Alt+B`, `Alt+F`, `Alt+D`, `Alt+Y`, `Alt+P`) require configuring Option as Meta in your terminal. See [Enable Option key shortcuts on macOS](/docs/en/terminal-config#enable-option-key-shortcuts-on-macos) for the setting in each terminal.
912
10 **macOS users**: Option/Alt key shortcuts (`Alt+B`, `Alt+F`, `Alt+D`, `Alt+Y`, `Alt+P`) require configuring Option as Meta in your terminal. See [Enable Option key shortcuts on macOS](/docs/en/terminal-config#enable-option-key-shortcuts-on-macos) for the setting in each terminal.
11</Note>
12
1313### General controls
1414
1515| Shortcut | Description | Context |
from line 53
5353| `Alt+D` | Delete to end of word | Deletes to the end of the current word, or to the end of the next word when the cursor is between words. Stores deleted text for pasting. Requires [Option as Meta](#keyboard-shortcuts) on macOS |
5454| `Ctrl+_` or `Ctrl+Shift+-` | Undo last input edit | Restores the previous input text and cursor position |
5555
56<h3 id="make-ctrl-w-delete-back-to-whitespace">
57 Word boundaries in editing shortcuts
58</h3>
56### Word boundaries in editing shortcuts
5957
6058The word shortcuts `Alt+B`, `Alt+F`, `Alt+D`, `Option+Delete`, and `Ctrl+Backspace` treat a word as a run of letters and digits, so punctuation such as `_`, `.`, and `/` separates words. With `src/utils/foo.ts` in the prompt, repeated presses of `Alt+B` stop at the start of `ts`, `foo`, `utils`, and `src`.
6159
from line 191
193191| `%` | Jump to the matching `()`, `[]`, or `{}` bracket, starting from the next bracket on the current line when the cursor isn't on a bracket. Requires Claude Code v2.1.301 or later |
194192| `/` | Open reverse history search, same as `Ctrl+R`. The empty search prompt shows a hint: press `Esc` then `i` then `/` to open the command menu instead |
195193
196<Note>
197 In vim NORMAL mode, if the cursor is at the beginning or end of input and can't move further, `j`/`k` and `↑`/`↓` navigate command history instead. `←` on an empty prompt opens [agent view](/docs/en/agent-view) from NORMAL mode as well as INSERT; before v2.1.219, `←` on an empty prompt did nothing in NORMAL mode.
198</Note>
194> [!NOTE]
195>
196> In vim NORMAL mode, if the cursor is at the beginning or end of input and can't move further, `j`/`k` and `↑`/`↓` navigate command history instead. `←` on an empty prompt opens [agent view](/docs/en/agent-view) from NORMAL mode as well as INSERT; before v2.1.219, `←` on an empty prompt did nothing in NORMAL mode.
199197
200198### Editing (NORMAL mode)
201199
from line 511
513511
514512Claude Code reads the [`spellcheck`](/docs/en/settings-reference#spellcheck) setting from three places, and ignores it in a project's `.claude/settings.json` and `.claude/settings.local.json`. Turn it on from whichever one you use:
515513
516<Tabs>
517 <Tab title="User settings">
518 Add `spellcheck` to `~/.claude/settings.json`. It applies in every project you open, like the rest of your [user settings](/docs/en/settings#where-settings-live):
514**User settings**
519515
520 ```json theme={null}
521 {
522 "spellcheck": { "enabled": true }
523 }
524 ```
525 </Tab>
516Add `spellcheck` to `~/.claude/settings.json`. It applies in every project you open, like the rest of your [user settings](/docs/en/settings#where-settings-live):
526517
527 <Tab title="Command line">
528 Save `spellcheck` in a JSON file, such as `spellcheck.json`:
518```json theme={null}
519{
520 "spellcheck": { "enabled": true }
521}
522```
529523
530 ```json theme={null}
531 {
532 "spellcheck": { "enabled": true }
533 }
534 ```
524**Command line**
535525
536 Then pass the file to `--settings`. It applies to that session only:
526Save `spellcheck` in a JSON file, such as `spellcheck.json`:
537527
538 ```bash theme={null}
539 claude --settings spellcheck.json
540 ```
541 </Tab>
528```json theme={null}
529{
530 "spellcheck": { "enabled": true }
531}
532```
542533
543 <Tab title="Managed settings">
544 Add `spellcheck` to one of your organization's [managed settings sources](/docs/en/permissions#managed-settings). It applies to every user who receives those settings, and they can't turn it off:
534Then pass the file to `--settings`. It applies to that session only:
545535
546 ```json theme={null}
547 {
548 "spellcheck": { "enabled": true }
549 }
550 ```
551 </Tab>
552</Tabs>
536```bash theme={null}
537claude --settings spellcheck.json
538```
553539
540**Managed settings**
541
542Add `spellcheck` to one of your organization's [managed settings sources](/docs/en/permissions#managed-settings). It applies to every user who receives those settings, and they can't turn it off:
543
544```json theme={null}
545{
546 "spellcheck": { "enabled": true }
547}
548```
549
554550To check that spell checking is on, type a misspelled word and a space. Claude Code underlines the word. If it doesn't, see [When Claude Code underlines nothing](#when-claude-code-underlines-nothing). To turn spell checking off again, set `enabled` to `false` in the same place, or remove `spellcheck`.
555551
556552To choose which of the three programs Claude Code runs, which dictionary it uses, or the underline color, add any of these fields next to `enabled`, in the same place:
from line 776
780776
781777When you set [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/en/env-vars), Claude Code doesn't check pull request or merge request status.
782778
783<Note>
784 PR status for GitHub repositories needs a GitHub token. Claude Code finds one based on the remote's host:
785
786 * **github.com**: `GH_TOKEN` or `GITHUB_TOKEN`, or the token saved by `gh auth login`. Without one, the footer shows `install gh for PR status` when the `gh` CLI isn't installed, or `gh auth login for PR status` when it is
787 * **A GitHub Enterprise host set as `GH_HOST`**: `GH_ENTERPRISE_TOKEN` or `GITHUB_ENTERPRISE_TOKEN`, or the token saved by `gh auth login --hostname <host>`. Without one, the footer shows the same hints
788 * **Any other GitHub host**: the token saved by `gh auth login --hostname <host>`. Without one, Claude Code shows no badge and no hint
789</Note>
779> [!NOTE]
780>
781> PR status for GitHub repositories needs a GitHub token. Claude Code finds one based on the remote's host:
782>
783> * **github.com**: `GH_TOKEN` or `GITHUB_TOKEN`, or the token saved by `gh auth login`. Without one, the footer shows `install gh for PR status` when the `gh` CLI isn't installed, or `gh auth login for PR status` when it is
784> * **A GitHub Enterprise host set as `GH_HOST`**: `GH_ENTERPRISE_TOKEN` or `GITHUB_ENTERPRISE_TOKEN`, or the token saved by `gh auth login --hostname <host>`. Without one, the footer shows the same hints
785> * **Any other GitHub host**: the token saved by `gh auth login --hostname <host>`. Without one, Claude Code shows no badge and no hint
790786
791787### GitLab merge requests
792788
jetbrains Changed · +37 / -45 lines
from line 27
2727
2828The plugin runs the `claude` command in your IDE's integrated terminal and connects to it. It does not bundle its own copy of the CLI, so install both pieces:
2929
30<Steps>
31 <Step title="Install the Claude Code CLI">
32 Follow the [quickstart](/docs/en/quickstart) to install the CLI if you haven't already. The plugin shows a "Cannot launch Claude Code" notification when `claude` isn't on your PATH.
33 </Step>
30**1. Install the Claude Code CLI**
3431
35 <Step title="Install the JetBrains plugin">
36 Install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains Marketplace and restart your IDE.
37 </Step>
38</Steps>
32Follow the [quickstart](/docs/en/quickstart) to install the CLI if you haven't already. The plugin shows a "Cannot launch Claude Code" notification when `claude` isn't on your PATH.
3933
34**2. Install the JetBrains plugin**
35
36Install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains Marketplace and restart your IDE.
37
4038If `claude` is installed somewhere your IDE can't find, set the full path in the plugin's [Claude command setting](#general-settings).
4139
4240Claude Code works with any paid Claude subscription (Pro, Max, Team, or Enterprise) or a Claude Console account, and no API key is required. You'll be prompted to [log in](/docs/en/authentication#log-in-to-claude-code) the first time you run `claude`.
from line 41
4341
4442## Usage
4543
46<span id="from-your-ide" />
47
4844### Run Claude Code from your IDE
4945
5046Run `claude` from your IDE's integrated terminal, and all integration features will be active.
5147
52<span id="from-external-terminals" />
53
5448### Connect from an external terminal
5549
5650Use the `/ide` command in any external terminal to connect Claude Code to your JetBrains IDE and activate all features:
from line 84
9084* **Enable using Option+Enter for multi-line prompts**: on macOS only. When enabled, Option+Enter inserts new lines in Claude Code prompts. Disable if the Option key is being captured unexpectedly. Requires a terminal restart.
9185* **Enable automatic updates**: automatically check for and install plugin updates, applied on restart
9286
93<Tip>
94 For WSL users: Set `wsl -d Ubuntu -- bash -lic "claude"` as your Claude command (replace `Ubuntu` with your WSL distribution name)
95</Tip>
87> [!TIP]
88>
89> For WSL users: Set `wsl -d Ubuntu -- bash -lic "claude"` as your Claude command (replace `Ubuntu` with your WSL distribution name)
9690
9791#### ESC key configuration
9892
from line 104
110104
111105### Remote development
112106
113<Warning>
114 When using JetBrains Remote Development, you must install the plugin on the remote host via **Settings → Plugin (Host)**, not on your local client machine.
115</Warning>
107> [!WARNING]
108>
109> When using JetBrains Remote Development, you must install the plugin on the remote host via **Settings → Plugin (Host)**, not on your local client machine.
116110
117111### WSL configuration
118112
from line 116
122116
123117This is the recommended fix because it keeps your existing WSL2 networking mode.
124118
125<Steps>
126 <Step title="Find your WSL2 IP address">
127 From inside your WSL shell, run:
119**1. Find your WSL2 IP address**
128120
129 ```bash theme={null}
130 hostname -I
131 ```
121From inside your WSL shell, run:
132122
133 Note your subnet: take the first two segments of the address and follow them with `.0.0/16`. For example, if the address is `172.21.123.45`, your subnet is `172.21.0.0/16`.
134 </Step>
123```bash theme={null}
124hostname -I
125```
135126
136 <Step title="Create a firewall rule">
137 Open PowerShell as Administrator and run the following, adjusting the IP range to match your subnet:
127Note your subnet: take the first two segments of the address and follow them with `.0.0/16`. For example, if the address is `172.21.123.45`, your subnet is `172.21.0.0/16`.
138128
139 ```powershell theme={null}
140 New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
141 ```
142 </Step>
129**2. Create a firewall rule**
143130
144 <Step title="Restart your IDE and Claude Code">
145 Close and reopen both so the new rule takes effect.
146 </Step>
147</Steps>
131Open PowerShell as Administrator and run the following, adjusting the IP range to match your subnet:
148132
133```powershell theme={null}
134New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
135```
136
137**3. Restart your IDE and Claude Code**
138
139Close and reopen both so the new rule takes effect.
140
149141#### Switch WSL2 to mirrored networking
150142
151143Mirrored networking requires Windows 11 22H2 or later. If you're on Windows 10, use the firewall rule above instead.
from line 215
223215
224216**Listening interface.** Which network interface the server binds to is controlled by **Accept connections from all network interfaces** under **Settings → Tools → Claude Code \[Beta] → Networking (Advanced)**. With the setting disabled, the server listens on `127.0.0.1` only and is not reachable from other hosts. With it enabled, the port is reachable from your local network. The setting exists for cases where the CLI cannot reach the IDE over loopback, such as WSL2 with default NAT networking or a remote-IDE setup; see [WSL configuration](#wsl-configuration) for that scenario.
225217
226<Warning>
227 Enabling **Accept connections from all network interfaces** makes the IDE MCP port reachable from your local network. Connections still require the auth token from the lock file, but because the transport is unencrypted `ws://`, both the session traffic and that token cross the network in cleartext when the setting is on. Only turn it on when loopback can't work. For WSL2, prefer [mirrored networking](#switch-wsl2-to-mirrored-networking) so the Windows loopback interface is shared with the Linux VM and the socket can stay on loopback.
228</Warning>
218> [!WARNING]
219>
220> Enabling **Accept connections from all network interfaces** makes the IDE MCP port reachable from your local network. Connections still require the auth token from the lock file, but because the transport is unencrypted `ws://`, both the session traffic and that token cross the network in cleartext when the setting is on. Only turn it on when loopback can't work. For WSL2, prefer [mirrored networking](#switch-wsl2-to-mirrored-networking) so the Windows loopback interface is shared with the Linux VM and the socket can stay on loopback.
229221
large-codebases Changed · +6 / -6 lines
from line 25
2525| Give Claude procedures specific to one area that load only when relevant | Per-directory [skills](#add-per-directory-skills) |
2626| Replace many per-directory CLAUDE.md files with one set of conventions everyone installs | A [plugin](#centralize-conventions-when-layering-stops-scaling) in an internal marketplace |
2727
28<Tip>
29 For workflow techniques that keep context small in any repository, such as [running exploration in a subagent](/docs/en/best-practices#use-subagents-for-investigation) so file reads stay out of the main conversation, see [Best practices for Claude Code](/docs/en/best-practices). To roll out a baseline configuration to every developer in your organization, see [Set up Claude Code for your organization](/docs/en/admin-setup).
30</Tip>
28> [!TIP]
29>
30> For workflow techniques that keep context small in any repository, such as [running exploration in a subagent](/docs/en/best-practices#use-subagents-for-investigation) so file reads stay out of the main conversation, see [Best practices for Claude Code](/docs/en/best-practices). To roll out a baseline configuration to every developer in your organization, see [Set up Claude Code for your organization](/docs/en/admin-setup).
3131
3232### The example monorepo
3333
from line 250
250250
251251This creates a symlink from each worktree's `node_modules/` back to the main repository's copy rather than duplicating it on disk.
252252
253<Note>
254 The `sparsePaths` and `symlinkDirectories` settings are read from your starting directory before the worktree is created. After creation, the session's working directory is the worktree root, not the subdirectory you launched from. Project settings inside the worktree therefore load from the worktree root's `.claude/settings.json`, the checked-out copy of the repository root's file. Put any other settings you need inside worktrees, such as permission rules or hooks, in the repository root's `.claude/settings.json`.
255</Note>
253> [!NOTE]
254>
255> The `sparsePaths` and `symlinkDirectories` settings are read from your starting directory before the worktree is created. After creation, the session's working directory is the worktree root, not the subdirectory you launched from. Project settings inside the worktree therefore load from the worktree root's `.claude/settings.json`, the checked-out copy of the repository root's file. Put any other settings you need inside worktrees, such as permission rules or hooks, in the repository root's `.claude/settings.json`.
256256
257257For the full worktree settings reference, see [Worktree settings](/docs/en/settings-reference#worktree).
258258
llm-gateway Changed · +5 / -5 lines
from line 4
44
55This section covers using a gateway product your organization already runs, rather than [Claude apps gateway](/docs/en/claude-apps-gateway). For what a gateway is, how it sits between Claude Code and your provider, and how to choose between Claude apps gateway and another product, see the [gateway overview](/docs/en/gateways).
66
7<Note>
8 * If you're a developer connecting to an existing gateway: [connect Claude Code to your gateway](/docs/en/llm-gateway-connect)
9 * If you're an admin rolling out a gateway for your organization: [deploy and distribute a gateway](/docs/en/llm-gateway-rollout)
10 * If you're configuring a gateway product: the [gateway compatibility guide](/docs/en/llm-gateway-protocol)
11</Note>
7> [!NOTE]
8>
9> * If you're a developer connecting to an existing gateway: [connect Claude Code to your gateway](/docs/en/llm-gateway-connect)
10> * If you're an admin rolling out a gateway for your organization: [deploy and distribute a gateway](/docs/en/llm-gateway-rollout)
11> * If you're configuring a gateway product: the [gateway compatibility guide](/docs/en/llm-gateway-protocol)
1212
1313Any gateway that exposes a [supported API format](/docs/en/llm-gateway-protocol#api-formats) works. Anthropic doesn't endorse, maintain, or audit third-party gateway products, and doesn't support routing Claude Code to non-Claude models through any gateway. Deploy the gateway following its own documentation, then complete the Claude Code side with the [rollout steps below](#roll-out-a-gateway).
1414