One read of Claude Code CLIclaude-code-20261030T180701Z
88 pages moved out of 228 read.
Pages moved
88
significant first
Pages read
228
in this capture
Captured
18:07 UTC
Corpus hash
49664f3a50da
corpus-hash
What this read moved
51-75 of 88, page 3 of 4This capture is too large to show at once. Changes 51-75 of 88 are below, significant first; the rest are on the following screens.
remote-control Changed · +102 / -102 lines
from line 21
2121
2222Before using Remote Control, confirm that your environment meets these conditions:
2323
24* **Subscription**: available on Pro, Max, Team, and Enterprise plans. API keys are not supported. On Team and Enterprise, an Owner must first enable the Remote Control toggle in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).
24* **Subscription**: available on Pro, Max, Ultra, Team, and Enterprise plans. API keys are not supported. On Team and Enterprise, an Owner must first enable the Remote Control toggle in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).
2525* **Custom roles**: if your Enterprise organization manages your access with [custom roles](https://support.claude.com/en/articles/13930452), your roles must give you both the cloud sessions permission and the **Claude Code remote control** permission. If either is missing, starting Remote Control shows [`Remote Control is disabled by your organization's policy`](#remote-control-is-disabled-by-your-organizations-policy). Ask an Owner to check your roles and add what's missing at [**Organization settings > Roles**](https://claude.ai/admin-settings/roles).
2626* **Authentication**: run `claude` and use `/login` to sign in through claude.ai if you haven't already. Without an eligible login, `claude remote-control` exits with an error, while `claude --remote-control` still starts an interactive session and shows a Remote Control failure notification shortly after launch.
2727* **API endpoint**: not available in any of these configurations:
from line 37
3737
3838You can start a Remote Control session from the CLI, the [Claude Desktop app](https://code.claude.com/docs/en/desktop.md), or the VS Code extension. The CLI offers three invocation modes; the Desktop app and VS Code use the `/remote-control` command.
3939
40**Server mode**
40> [tab] Server mode
41>
42> In your project directory, run:
43>
44> ```bash theme={null}
45> claude remote-control
46> ```
47>
48> Until you accept Remote Control's one-time confirmation, `claude remote-control` explains what it does and asks `Enable Remote Control? (y/n)` before starting the server. Answer `y` to accept and start the server. If you decline, Claude Code exits without starting the server and asks again the next time you run the command.
49>
50> The process stays running in your terminal in server mode, waiting for remote connections. It displays a session URL you can use to [connect from another device](#connect-from-another-device), and you can press spacebar to show a QR code for quick access from your phone. While a remote session is active, the terminal shows connection status and tool activity.
51>
52> Pass any of these flags after `remote-control`:
53>
54> | Flag | Description |
55> | - | - |
56> | `--name "My Project"` | Set a custom session title visible in the session list at claude.ai/code. |
57> | `--remote-control-session-name-prefix <prefix>` | Prefix for auto-generated session names when no explicit name is set. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. Set `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` for the same effect. |
58> | `-c`, `--continue` | Bring back the session that the last server in this directory started with, instead of creating a new one. See [Resume sessions after stopping the server](#resume-sessions-after-stopping-the-server). Can't be combined with `--session-id`, `--spawn`, `--capacity`, or `--create-session-in-dir`. Requires Claude Code v2.1.200 or later. |
59> | `--session-id <id>` | Bring back one session by its ID. See [Resume sessions after stopping the server](#resume-sessions-after-stopping-the-server). Can't be combined with `--continue`, `--spawn`, `--capacity`, or `--create-session-in-dir`. Requires Claude Code v2.1.200 or later. |
60> | `--spawn <mode>` | How the server creates sessions. • `same-dir` (default when no mode is saved): all sessions share the current working directory, so they can conflict if editing the same files. • `worktree`: each on-demand session gets its own [git worktree](https://code.claude.com/docs/en/worktrees.md). Requires a git repository or a [`WorktreeCreate` hook](https://code.claude.com/docs/en/hooks#worktreecreate). • `session`: single-session mode. Serves exactly one session and rejects additional connections. Set at startup only. Press `w` at runtime to toggle between `same-dir` and `worktree`. The mode you switch to becomes the [default for this project](#set-the-default-spawn-mode-for-a-project). |
61> | `--capacity <N>` | Maximum number of concurrent sessions. Default is 32. Cannot be used with `--spawn=session`. |
62> | `--[no-]create-session-in-dir` | Pre-create one session in the current directory when the server starts, so you have somewhere to type immediately. In `worktree` mode this session stays in the current directory while on-demand sessions get isolated worktrees. On by default. If you pass `--no-create-session-in-dir` to start with none, Claude Code archives the server's sessions when you stop it, so there's nothing to [resume](#resume-sessions-after-stopping-the-server). |
63> | `--permission-mode <mode>` | Set the starting [permission mode](https://code.claude.com/docs/en/permission-modes.md) for the server's sessions, such as `acceptEdits`. Accepts `manual` as an alias for `default`; an unrecognized mode stops the server at startup and lists the valid modes. |
64> | `--chrome` / `--no-chrome` | Turn [Chrome integration](https://code.claude.com/docs/en/chrome.md) on or off in the sessions the server creates, so Claude can use Chrome on your machine while you work from another device. Without either flag, the session the server pre-creates and any session you start yourself from claude.ai/code or the Claude app begin with Chrome off, even if you [enabled Chrome by default](https://code.claude.com/docs/en/chrome.md#enable-chrome-by-default). A session the server starts for one of your [project](https://code.claude.com/docs/en/claude-projects.md) threads follows that setting instead, except in `bypassPermissions` mode. Requires Claude Code v2.1.273 or later. |
65> | `-d`, `--debug[=<filter>]` | Turn on debug logging for the server, optionally filtered by category. Pass a filter only in the `=` form, such as `--debug=api,hooks`. Requires Claude Code v2.1.282 or later. |
66> | `--debug-file <path>` | Write debug logs to the given file. |
67> | `--verbose` | Show detailed connection and session logs. |
68> | `--sandbox`, `--no-sandbox` | Removed in v2.1.300. If you pass either flag, the server [exits with an error](https://code.claude.com/docs/en/errors.md#sandbox-is-not-supported-by-claude-remote-control) instead of starting. |
69>
70> If you pass a global `claude` flag before `remote-control`, or a wrapper script adds one, Claude Code doesn't carry the flag over to the sessions the server creates. Claude Code lets the flag through only when dropping it is known not to change what those sessions can do, such as `--verbose` or `--model`. For any other flag, such as `--settings`, Claude Code [refuses to start](https://code.claude.com/docs/en/errors.md#not-carried-over-to-the-sessions-remote-control-starts) and names the flag to remove.
71>
72> To sandbox the sessions the server starts, turn on [sandboxing](https://code.claude.com/docs/en/sandboxing.md) in a settings file.
73>
74> To print the `remote-control` flags in your terminal, run `claude remote-control --help`. Before v2.1.302, without an eligible sign-in the command returned one of the errors under [Troubleshooting](#troubleshooting) instead.
4175
42In your project directory, run:
76> [tab] Interactive session
77>
78> To start a normal interactive Claude Code session with Remote Control enabled, use the `--remote-control` flag (or `--rc`):
79>
80> ```bash theme={null}
81> claude --remote-control
82> ```
83>
84> Optionally pass a name for the session:
85>
86> ```bash theme={null}
87> claude --remote-control "My Project"
88> ```
89>
90> This gives you a full interactive session in your terminal that you can also control from claude.ai or the Claude app. Unlike `claude remote-control` (server mode), you can type messages locally while the session is also available remotely.
4391
44```bash theme={null}
45claude remote-control
46```
92> [tab] From an existing session
93>
94> If you're already in a Claude Code session and want to continue it remotely, use the `/remote-control` (or `/rc`) command:
95>
96> ```text theme={null}
97> /remote-control
98> ```
99>
100> Pass a name as an argument to set a custom session title:
101>
102> ```text theme={null}
103> /remote-control My Project
104> ```
105>
106> This starts a Remote Control session that carries over your current conversation history.
107>
108> Until you accept Remote Control's one-time confirmation, a dialog appears before `/remote-control` connects. Select **Enable Remote Control** to accept and connect. If you select **Never mind** or press Esc, Claude Code doesn't connect and asks again the next time you run `/remote-control`.
109>
110> The `--verbose` flag is not available with this command.
47111
48Until you accept Remote Control's one-time confirmation, `claude remote-control` explains what it does and asks `Enable Remote Control? (y/n)` before starting the server. Answer `y` to accept and start the server. If you decline, Claude Code exits without starting the server and asks again the next time you run the command.
112> [tab] VS Code
113>
114> In the [Claude Code VS Code extension](https://code.claude.com/docs/en/vs-code.md), type `/remote-control` or `/rc` in the prompt box.
115>
116> ```text theme={null}
117> /remote-control
118> ```
119>
120> While Remote Control is on, Claude Code shows a **Remote Control** indicator in the prompt box footer. Once the session connects, click the indicator to go directly to the session, or find it in the session list at [claude.ai/code](https://claude.ai/code). Claude Code also posts the session URL in the conversation. To disconnect, run `/remote-control` again.
121>
122> Unlike the CLI, the VS Code command does not accept a name argument or display a QR code. The session title is derived from your conversation history or first prompt.
49123
50The process stays running in your terminal in server mode, waiting for remote connections. It displays a session URL you can use to [connect from another device](#connect-from-another-device), and you can press spacebar to show a QR code for quick access from your phone. While a remote session is active, the terminal shows connection status and tool activity.
124> [tab] Desktop app
125>
126> In a local session in the [Claude Desktop app's](https://code.claude.com/docs/en/desktop.md) Code tab, type `/remote-control` or `/rc` in the prompt box.
127>
128> ```text theme={null}
129> /remote-control
130> ```
131>
132> Once the session connects, find it in the session list at [claude.ai/code](https://claude.ai/code). To disconnect, run `/remote-control` again.
133>
134> To turn Remote Control on for every session by default instead, see [Enable Remote Control for all sessions](#enable-remote-control-for-all-sessions).
51135
52Pass any of these flags after `remote-control`:
53
54| Flag | Description |
55| - | - |
56| `--name "My Project"` | Set a custom session title visible in the session list at claude.ai/code. |
57| `--remote-control-session-name-prefix <prefix>` | Prefix for auto-generated session names when no explicit name is set. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. Set `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` for the same effect. |
58| `-c`, `--continue` | Bring back the session that the last server in this directory started with, instead of creating a new one. See [Resume sessions after stopping the server](#resume-sessions-after-stopping-the-server). Can't be combined with `--session-id`, `--spawn`, `--capacity`, or `--create-session-in-dir`. Requires Claude Code v2.1.200 or later. |
59| `--session-id <id>` | Bring back one session by its ID. See [Resume sessions after stopping the server](#resume-sessions-after-stopping-the-server). Can't be combined with `--continue`, `--spawn`, `--capacity`, or `--create-session-in-dir`. Requires Claude Code v2.1.200 or later. |
60| `--spawn <mode>` | How the server creates sessions. • `same-dir` (default when no mode is saved): all sessions share the current working directory, so they can conflict if editing the same files. • `worktree`: each on-demand session gets its own [git worktree](https://code.claude.com/docs/en/worktrees.md). Requires a git repository or a [`WorktreeCreate` hook](https://code.claude.com/docs/en/hooks#worktreecreate). • `session`: single-session mode. Serves exactly one session and rejects additional connections. Set at startup only. Press `w` at runtime to toggle between `same-dir` and `worktree`. The mode you switch to becomes the [default for this project](#set-the-default-spawn-mode-for-a-project). |
61| `--capacity <N>` | Maximum number of concurrent sessions. Default is 32. Cannot be used with `--spawn=session`. |
62| `--[no-]create-session-in-dir` | Pre-create one session in the current directory when the server starts, so you have somewhere to type immediately. In `worktree` mode this session stays in the current directory while on-demand sessions get isolated worktrees. On by default. If you pass `--no-create-session-in-dir` to start with none, Claude Code archives the server's sessions when you stop it, so there's nothing to [resume](#resume-sessions-after-stopping-the-server). |
63| `--permission-mode <mode>` | Set the starting [permission mode](https://code.claude.com/docs/en/permission-modes.md) for the server's sessions, such as `acceptEdits`. Accepts `manual` as an alias for `default`; an unrecognized mode stops the server at startup and lists the valid modes. |
64| `--chrome` / `--no-chrome` | Turn [Chrome integration](https://code.claude.com/docs/en/chrome.md) on or off in the sessions the server creates, so Claude can use Chrome on your machine while you work from another device. Without either flag, the session the server pre-creates and any session you start yourself from claude.ai/code or the Claude app begin with Chrome off, even if you [enabled Chrome by default](https://code.claude.com/docs/en/chrome.md#enable-chrome-by-default). A session the server starts for one of your [project](https://code.claude.com/docs/en/claude-projects.md) threads follows that setting instead, except in `bypassPermissions` mode. Requires Claude Code v2.1.273 or later. |
65| `-d`, `--debug[=<filter>]` | Turn on debug logging for the server, optionally filtered by category. Pass a filter only in the `=` form, such as `--debug=api,hooks`. Requires Claude Code v2.1.282 or later. |
66| `--debug-file <path>` | Write debug logs to the given file. |
67| `--verbose` | Show detailed connection and session logs. |
68| `--sandbox`, `--no-sandbox` | Removed in v2.1.300. If you pass either flag, the server [exits with an error](https://code.claude.com/docs/en/errors.md#sandbox-is-not-supported-by-claude-remote-control) instead of starting. |
69
70If you pass a global `claude` flag before `remote-control`, or a wrapper script adds one, Claude Code doesn't carry the flag over to the sessions the server creates. Claude Code lets the flag through only when dropping it is known not to change what those sessions can do, such as `--verbose` or `--model`. For any other flag, such as `--settings`, Claude Code [refuses to start](https://code.claude.com/docs/en/errors.md#not-carried-over-to-the-sessions-remote-control-starts) and names the flag to remove.
71
72To sandbox the sessions the server starts, turn on [sandboxing](https://code.claude.com/docs/en/sandboxing.md) in a settings file.
73
74To print the `remote-control` flags in your terminal, run `claude remote-control --help`. Before v2.1.302, without an eligible sign-in the command returned one of the errors under [Troubleshooting](#troubleshooting) instead.
75
76**Interactive session**
77
78To start a normal interactive Claude Code session with Remote Control enabled, use the `--remote-control` flag (or `--rc`):
79
80```bash theme={null}
81claude --remote-control
82```
83
84Optionally pass a name for the session:
85
86```bash theme={null}
87claude --remote-control "My Project"
88```
89
90This gives you a full interactive session in your terminal that you can also control from claude.ai or the Claude app. Unlike `claude remote-control` (server mode), you can type messages locally while the session is also available remotely.
91
92**From an existing session**
93
94If you're already in a Claude Code session and want to continue it remotely, use the `/remote-control` (or `/rc`) command:
95
96```text theme={null}
97/remote-control
98```
99
100Pass a name as an argument to set a custom session title:
101
102```text theme={null}
103/remote-control My Project
104```
105
106This starts a Remote Control session that carries over your current conversation history.
107
108Until you accept Remote Control's one-time confirmation, a dialog appears before `/remote-control` connects. Select **Enable Remote Control** to accept and connect. If you select **Never mind** or press Esc, Claude Code doesn't connect and asks again the next time you run `/remote-control`.
109
110The `--verbose` flag is not available with this command.
111
112**VS Code**
113
114In the [Claude Code VS Code extension](https://code.claude.com/docs/en/vs-code.md), type `/remote-control` or `/rc` in the prompt box.
115
116```text theme={null}
117/remote-control
118```
119
120While Remote Control is on, Claude Code shows a **Remote Control** indicator in the prompt box footer. Once the session connects, click the indicator to go directly to the session, or find it in the session list at [claude.ai/code](https://claude.ai/code). Claude Code also posts the session URL in the conversation. To disconnect, run `/remote-control` again.
121
122Unlike the CLI, the VS Code command does not accept a name argument or display a QR code. The session title is derived from your conversation history or first prompt.
123
124**Desktop app**
125
126In a local session in the [Claude Desktop app's](https://code.claude.com/docs/en/desktop.md) Code tab, type `/remote-control` or `/rc` in the prompt box.
127
128```text theme={null}
129/remote-control
130```
131
132Once the session connects, find it in the session list at [claude.ai/code](https://claude.ai/code). To disconnect, run `/remote-control` again.
133
134To turn Remote Control on for every session by default instead, see [Enable Remote Control for all sessions](#enable-remote-control-for-all-sessions).
135
136136### Check connection status
137137
138138In an interactive session, while Remote Control is connected, the terminal shows an `/rc active` indicator that links to the session on claude.ai. The indicator is hidden when the terminal is too narrow to fit it. To see the session URL and a QR code for [connecting from another device](#connect-from-another-device), run `/remote-control` again to open the status panel. The panel also lets you disconnect Remote Control while your local session keeps running.
from line 246
246246>
247247> Trusted Devices is currently in beta. Features and functionality may evolve as the experience is refined.
248248>
249> Trusted Devices is available on Pro, Max, Team, and Enterprise plans and is off by default. On Team and Enterprise plans, an Owner turns it on for the organization. On Pro and Max plans, you turn on **Require trusted devices** yourself in your settings, on the Cowork or Account page.
249> Trusted Devices is available on Pro, Max, Ultra, Team, and Enterprise plans and is off by default. On Team and Enterprise plans, an Owner turns it on for the organization. On Pro, Max, and Ultra plans, you turn on **Require trusted devices** yourself in your settings, on the Cowork or Account page.
250250
251Trusted Devices requires each member of your organization, or you alone on a Pro or Max plan, to verify their device before they can view or steer Remote Control sessions from claude.ai, the Claude mobile apps, or Claude Desktop. It ties Remote Control access to a known device and a recent authentication, not just a signed-in account.
251Trusted Devices requires a verified device before you can view or steer Remote Control sessions from claude.ai, the Claude mobile apps, or Claude Desktop. The requirement applies to each member of your organization, or you alone on a Pro, Max, or Ultra plan. It ties Remote Control access to a known device and a recent authentication, not just a signed-in account.
252252
253253When the setting is on, interacting with a Remote Control session requires both of the following:
254254
from line 306
306306| [Dispatch](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch) | Message a task from the Claude mobile app | Your machine (Desktop) | [Pair the mobile app with Desktop](https://support.claude.com/en/articles/13947068) | Delegating work while you're away, minimal setup |
307307| [Remote Control](https://code.claude.com/docs/en/remote-control.md) | Drive a running session from [claude.ai/code](https://claude.ai/code) or the Claude mobile app | Your machine (CLI, Desktop, or VS Code) | Run [`claude remote-control` or `/remote-control`](https://code.claude.com/docs/en/remote-control#start-a-remote-control-session) | Steering in-progress work from another device |
308308| [Channels](https://code.claude.com/docs/en/channels.md) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](https://code.claude.com/docs/en/channels.md#quickstart) or [build your own](https://code.claude.com/docs/en/channels-reference.md) | Reacting to external events like CI failures or chat messages |
309| [Slack](https://code.claude.com/docs/en/slack.md) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](https://code.claude.com/docs/en/slack.md#setting-up-claude-code-in-slack) with [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web.md) enabled, on Pro and Max plans | PRs and reviews from team chat |
309| [Slack](https://code.claude.com/docs/en/slack.md) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](https://code.claude.com/docs/en/slack.md#setting-up-claude-code-in-slack) with [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web.md) enabled, on Pro, Max, and Ultra plans | PRs and reviews from team chat |
310310| [Self-hosted environments](https://code.claude.com/docs/en/self-hosted-environments) | Start a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md) and pick your organization's environment | Your organization's infrastructure | [Deploy runners](https://code.claude.com/docs/en/self-hosted-environments-quickstart.md), on Team and Enterprise plans | Cloud sessions that must run inside your network |
311311| [Scheduled tasks](https://code.claude.com/docs/en/scheduled-tasks.md) | Set a schedule | [CLI](https://code.claude.com/docs/en/scheduled-tasks.md), [Desktop](https://code.claude.com/docs/en/desktop-scheduled-tasks.md), or [cloud](https://code.claude.com/docs/en/routines.md) | Pick a frequency | Recurring automation like daily reviews |
312312
from line 440
440440An [environment variable](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching) that turns off feature-flag evaluation is set, and the full message names the variable Claude Code found. On versions before 2.1.154, the same configuration produces "Remote Control is not yet enabled for your account" instead. What to do depends on the variable the message names:
441441
442442* **`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or `DISABLE_GROWTHBOOK`**: unset the variable wherever it's set, in your shell environment or in the `env` block of a [`settings.json` file](https://code.claude.com/docs/en/settings-reference#all-settings).
443* **`DISABLE_TELEMETRY` or `DO_NOT_TRACK`**: on a Pro, Max, Team, or Enterprise plan with `DISABLE_GROWTHBOOK` unset, these variables leave Remote Control available unless your organization requires [Trusted Devices](#trusted-devices). If it does, unset the variable wherever it's set to use Remote Control. On v2.1.154 through v2.1.282, you see this message with either variable set, so update Claude Code to a version that meets the [requirement for these variables](#requirements).
443* **`DISABLE_TELEMETRY` or `DO_NOT_TRACK`**: on a Pro, Max, Ultra, Team, or Enterprise plan with `DISABLE_GROWTHBOOK` unset, Remote Control stays available with these variables set, unless your organization requires [Trusted Devices](#trusted-devices). If it does, unset the variable wherever it's set to use Remote Control. On v2.1.154 through v2.1.282, you see this message with either variable set, so update Claude Code to a version that meets the [requirement for these variables](#requirements).
444444
445445### "Remote Control is only available when using Claude via api.anthropic.com"
446446
from line 453
453453A policy blocks Remote Control. Check these causes in order:
454454
455455* **The error mentions `disableRemoteControl`**: your IT administrator has disabled Remote Control on this device through [managed settings](https://code.claude.com/docs/en/managed-settings.md), independent of the organization-wide toggle and of how you're signed in.
456* **Your claude.ai plan is Pro or Max**: Claude Code is still signed in under a Team or Enterprise organization from an earlier login, so it checks that organization's Remote Control policy. Run `/status` to see which plan and organization your sign-in uses. Run `claude auth logout` then `claude auth login` to sign in again under your current plan.
456* **Your claude.ai plan is Pro, Max, or Ultra**: Claude Code is still signed in under a Team or Enterprise organization from an earlier login, so it checks that organization's Remote Control policy. Run `/status` to see which plan and organization your sign-in uses. Run `claude auth logout` then `claude auth login` to sign in again under your current plan.
457457* **The message doesn't say to contact your organization admin**: your organization has the [HIPAA configuration](https://code.claude.com/docs/en/hipaa-setup.md) applied, which turns Remote Control off. To confirm, run `/status` and look for `HIPAA` on the `Organization configuration` line. An Owner sees the **Remote Control** toggle grayed out in [admin settings](https://claude.ai/admin-settings/claude-code) and can't turn it on. If you have questions about the configuration, ask an Owner, who can contact your organization's Anthropic account team. Before v2.1.267, this case showed "Remote Control isn't available for your organization due to its compliance policy" instead.
458458* **Remote Control works for others in your organization but not for you**: if your Enterprise organization manages your access with [custom roles](https://support.claude.com/en/articles/13930452), your roles can be the cause. Remote Control needs both the cloud sessions permission and the **Claude Code remote control** permission. Ask an Owner to check whether your roles include both and add what's missing at [**Organization settings > Roles**](https://claude.ai/admin-settings/roles).
459459* **Otherwise, an Owner hasn't enabled it for your organization**: Remote Control is off by default on Team and Enterprise plans. An Owner can enable it at [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) by turning on the **Remote Control** toggle. This toggle is a server-side organization setting.
routines Changed · +13 / -13 lines
from line 21
2121* A task with only an API trigger runs when you call its endpoint.
2222* A task with only a GitHub trigger runs when a matching repository event occurs.
2323
24Scheduled tasks are available on Pro, Max, Team, and Enterprise plans. Create and manage them at [claude.ai/code/routines](https://claude.ai/code/routines), or from the CLI with `/schedule`. The earlier name, routines, [still appears](#where-the-name-routines-still-appears).
24Scheduled tasks are available on Pro, Max, Ultra, Team, and Enterprise plans. Create and manage them at [claude.ai/code/routines](https://claude.ai/code/routines), or from the CLI with `/schedule`. The earlier name, routines, [still appears](#where-the-name-routines-still-appears).
2525
2626> [!NOTE]
2727>
from line 81
8181
8282In the **Trigger** row, choose how the task starts. To combine several triggers, click **+** at the end of the row.
8383
84**Schedule**
84> [tab] Schedule
85>
86> Pick a preset frequency for a recurring run. See [Add a schedule trigger](#add-a-schedule-trigger) for timezone handling, late starts, custom cron intervals, and one-off runs.
8587
86Pick a preset frequency for a recurring run. See [Add a schedule trigger](#add-a-schedule-trigger) for timezone handling, late starts, custom cron intervals, and one-off runs.
88> [tab] GitHub event
89>
90> Select the repository, the event to react to, and optional filters. See [Add a GitHub trigger](#add-a-github-trigger) for the full list of supported events and filter fields.
8791
88**GitHub event**
92> [tab] API
93>
94> Select **API** here. When you click **Create**, the **API token** dialog shows the token once, so copy it before you close the dialog. See [Add an API trigger](#add-an-api-trigger) to copy the URL or generate a new token.
8995
90Select the repository, the event to react to, and optional filters. See [Add a GitHub trigger](#add-a-github-trigger) for the full list of supported events and filter fields.
91
92**API**
93
94Select **API** here. When you click **Create**, the **API token** dialog shows the token once, so copy it before you close the dialog. See [Add an API trigger](#add-an-api-trigger) to copy the URL or generate a new token.
95
9696**4. Select repositories**
9797
9898Expand **Advanced settings**. Under **Repository** on the **General** tab, select one or more GitHub repositories for Claude to work in.
from line 498
498498* An Owner [turned off scheduled tasks](#routines-are-disabled-by-your-organizations-policy) for your Team or Enterprise organization. Before v2.1.227, the command still appeared in this case, and claude.ai rejected the task when Claude tried to create or run it
499499* Your Enterprise organization manages your access with [custom roles](https://support.claude.com/en/articles/13930452), and none of your roles includes the scheduled tasks permission under **Remote sessions**. Ask an Owner to add it to one of your roles
500500
501If the cause is your CLI sign-in or being inside a cloud session, you can still create and manage scheduled tasks at [claude.ai/code/routines](https://claude.ai/code/routines). You need a Pro, Max, Team, or Enterprise account there. If scheduled tasks or cloud sessions are off for your organization or missing from your roles, you can't create them on the web either.
501If the cause is your CLI sign-in or being inside a cloud session, you can still create and manage scheduled tasks at [claude.ai/code/routines](https://claude.ai/code/routines). You need a Pro, Max, Ultra, Team, or Enterprise account there. If scheduled tasks or cloud sessions are off for your organization or missing from your roles, you can't create them on the web either.
502502
503503### "Routines are disabled by your organization's policy"
504504
sandboxing Changed · +13 / -13 lines
from line 115
115115
116116Install them with your distribution's package manager:
117117
118**Ubuntu/Debian**
118> [tab] Ubuntu/Debian
119>
120> ```bash theme={null}
121> sudo apt-get install bubblewrap socat
122> ```
119123
120```bash theme={null}
121sudo apt-get install bubblewrap socat
122```
124> [tab] Fedora
125>
126> ```bash theme={null}
127> sudo dnf install bubblewrap socat
128> ```
123129
124**Fedora**
125
126```bash theme={null}
127sudo dnf install bubblewrap socat
128```
129
130130When a dependency is missing, the Dependencies tab in `/sandbox` lists which of `ripgrep`, `bubblewrap`, `socat`, and the seccomp filter your platform lacks. If you don't see the tab after installing and restarting Claude Code, all dependencies are present.
131131
132132Ripgrep is bundled with the native Claude Code binary. The seccomp filter is optional and adds Unix domain socket blocking. Install it with `npm install -g @anthropic-ai/sandbox-runtime` if it is missing.
from line 133
133133
134134When a required dependency is missing, the Dependencies tab is the only tab shown until you install it. When only the optional seccomp filter is missing, the Dependencies tab appears alongside the other tabs. The dependency check runs at startup, so restart Claude Code after installing packages for `/sandbox` to detect them.
135135
136> **Ubuntu 24.04 and later: allow bubblewrap to create user namespaces**
136> [accordion] Ubuntu 24.04 and later: allow bubblewrap to create user namespaces
137137>
138138> On Ubuntu 24.04 and later, the default AppArmor policy prevents bubblewrap from creating the user namespaces it needs for isolation.
139139>
from line 157
157157> sudo systemctl reload apparmor
158158> ```
159159
160> **WSL2 notes**
160> [accordion] WSL2 notes
161161>
162162> Check your WSL version with `wsl -l -v` from PowerShell. If you see `Sandboxing requires WSL2`, your distribution is running WSL1. Upgrade it to WSL2 or run Claude Code without sandboxing.
163163>
self-hosted-environments Changed · +5 / -1 lines
from line 10
1010
1111In a self-hosted environment, those same sessions execute inside your network. The developer experience is otherwise the same apart from the differences in [Availability and limitations](#availability-and-limitations) and the deploy page's [known issues](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#known-issues-and-limitations).
1212
13If your team doesn't use cloud sessions, there's nothing here to configure: sessions in a terminal or IDE always run on the developer's own machine. If you want to run Claude Code on your own always-on machine and drive it from other devices, use [Remote Control](https://code.claude.com/docs/en/remote-control.md), which is also available on Pro and Max plans. When you're ready to set up, go straight to the [quickstart](https://code.claude.com/docs/en/self-hosted-environments-quickstart.md); to review the security posture first, start with [Deploy to production](https://code.claude.com/docs/en/self-hosted-environments-deploy.md). The rest of this page explains how self-hosting works and when to choose it.
13* If your team doesn't use cloud sessions, there's nothing here to configure: sessions in a terminal or IDE always run on the developer's own machine
14* To run Claude Code on your own always-on machine and drive it from other devices, use [Remote Control](https://code.claude.com/docs/en/remote-control.md), which is also available on Pro, Max, and Ultra plans
15* When you're ready to set up, go straight to the [quickstart](https://code.claude.com/docs/en/self-hosted-environments-quickstart.md); to review the security posture first, start with [Deploy to production](https://code.claude.com/docs/en/self-hosted-environments-deploy.md)
16
17To learn how self-hosting works and when to choose it, read [How self-hosted environments work](#how-self-hosted-environments-work) and [Why self-host](#why-self-host).
1418
1519## How self-hosted environments work
1620
self-hosted-environments-configuration Changed · +22 / -22 lines
from line 527
527527
528528Start these runners with [`--confine-repo-settings enforce`](https://code.claude.com/docs/en/self-hosted-environments-deploy#harden-your-deployment). It refuses sessions on repositories whose committed settings it flags, so run in the default `warn` mode first and clear what it logs.
529529
530**Amazon Bedrock**
530> [tab] Amazon Bedrock
531>
532> Replace the region with your own:
533>
534> ```bash theme={null}
535> export CLAUDE_CODE_USE_BEDROCK=1
536> export AWS_REGION=us-east-1
537> ```
538>
539> For how Claude Code resolves the region, see [Configure Claude Code](https://code.claude.com/docs/en/amazon-bedrock.md#3-configure-claude-code). For which inference profile prefix Claude Code uses for your region, see [Cross-region inference profile prefixes](https://code.claude.com/docs/en/amazon-bedrock.md#cross-region-inference-profile-prefixes).
531540
532Replace the region with your own:
533
534```bash theme={null}
535export CLAUDE_CODE_USE_BEDROCK=1
536export AWS_REGION=us-east-1
537```
538
539For how Claude Code resolves the region, see [Configure Claude Code](https://code.claude.com/docs/en/amazon-bedrock.md#3-configure-claude-code). For which inference profile prefix Claude Code uses for your region, see [Cross-region inference profile prefixes](https://code.claude.com/docs/en/amazon-bedrock.md#cross-region-inference-profile-prefixes).
540
541**Google Cloud's Agent Platform**
542
543Replace the region and project ID with your own:
544
545```bash theme={null}
546export CLAUDE_CODE_USE_VERTEX=1
547export CLOUD_ML_REGION=global
548export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
549```
550
551To choose a region, see [Region configuration](https://code.claude.com/docs/en/google-vertex-ai.md#region-configuration).
541> [tab] Google Cloud's Agent Platform
542>
543> Replace the region and project ID with your own:
544>
545> ```bash theme={null}
546> export CLAUDE_CODE_USE_VERTEX=1
547> export CLOUD_ML_REGION=global
548> export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
549> ```
550>
551> To choose a region, see [Region configuration](https://code.claude.com/docs/en/google-vertex-ai.md#region-configuration).
552552
553553**4. Check that the variables reached a session**
554554
self-hosted-environments-identity Changed · +78 / -78 lines
from line 86
8686
8787The checks map directly onto standard JWT libraries. The examples below implement the full sequence in Node.js with [`jose`](https://www.npmjs.com/package/jose), which handles JWKS fetching, caching, and `kid` selection, and in Python with [`PyJWT`](https://pyjwt.readthedocs.io/) and its built-in JWKS client.
8888
89**Node.js (jose)**
89> [tab] Node.js (jose)
90>
91> ```typescript theme={null}
92> import { createRemoteJWKSet, jwtVerify } from "jose";
93>
94> const JWKS = createRemoteJWKSet(
95> new URL("https://api.anthropic.com/v1/code/.well-known/jwks.json")
96> );
97>
98> const PREFIX = "sk-ant-cc-";
99> const EXPECTED_POOL_ID = "ccpool_...";
100>
101> export async function verifySessionToken(raw: string) {
102> if (!raw.startsWith(PREFIX)) {
103> throw new Error("not a self-hosted runner session token");
104> }
105> const jwt = raw.slice(PREFIX.length);
106>
107> const { payload } = await jwtVerify(jwt, JWKS, {
108> issuer: "ccr",
109> audience: EXPECTED_POOL_ID,
110> algorithms: ["ES256"],
111> });
112>
113> if (payload["ccr:role"] !== "session_worker") {
114> throw new Error("token is not a session_worker token");
115> }
116>
117> const act = payload.act as { email?: string; sub?: string };
118> return {
119> sessionId: payload["ccr:session_id"] as string,
120> poolId: payload["ccr:pool_id"] as string,
121> orgId: payload["ccr:org_id"] as string,
122> creatorEmail: act?.email,
123> creatorSub: act?.sub,
124> };
125> }
126> ```
90127
91```typescript theme={null}
92import { createRemoteJWKSet, jwtVerify } from "jose";
93
94const JWKS = createRemoteJWKSet(
95 new URL("https://api.anthropic.com/v1/code/.well-known/jwks.json")
96);
97
98const PREFIX = "sk-ant-cc-";
99const EXPECTED_POOL_ID = "ccpool_...";
100
101export async function verifySessionToken(raw: string) {
102 if (!raw.startsWith(PREFIX)) {
103 throw new Error("not a self-hosted runner session token");
104 }
105 const jwt = raw.slice(PREFIX.length);
106
107 const { payload } = await jwtVerify(jwt, JWKS, {
108 issuer: "ccr",
109 audience: EXPECTED_POOL_ID,
110 algorithms: ["ES256"],
111 });
112
113 if (payload["ccr:role"] !== "session_worker") {
114 throw new Error("token is not a session_worker token");
115 }
116
117 const act = payload.act as { email?: string; sub?: string };
118 return {
119 sessionId: payload["ccr:session_id"] as string,
120 poolId: payload["ccr:pool_id"] as string,
121 orgId: payload["ccr:org_id"] as string,
122 creatorEmail: act?.email,
123 creatorSub: act?.sub,
124 };
125}
126```
127
128**Python (PyJWT)**
129
130```python theme={null}
131import jwt
132from jwt import PyJWKClient
133
134JWKS_URL = "https://api.anthropic.com/v1/code/.well-known/jwks.json"
135PREFIX = "sk-ant-cc-"
136EXPECTED_POOL_ID = "ccpool_..."
137
138jwks = PyJWKClient(JWKS_URL)
139
140
141def verify_session_token(raw: str) -> dict:
142 if not raw.startswith(PREFIX):
143 raise ValueError("not a self-hosted runner session token")
144 token = raw.removeprefix(PREFIX)
145
146 signing_key = jwks.get_signing_key_from_jwt(token)
147 payload = jwt.decode(
148 token,
149 signing_key.key,
150 algorithms=["ES256"],
151 issuer="ccr",
152 audience=EXPECTED_POOL_ID,
153 )
154
155 if payload.get("ccr:role") != "session_worker":
156 raise ValueError("token is not a session_worker token")
157
158 act = payload.get("act") or {}
159 return {
160 "session_id": payload["ccr:session_id"],
161 "pool_id": payload["ccr:pool_id"],
162 "org_id": payload["ccr:org_id"],
163 "creator_email": act.get("email"),
164 "creator_sub": act.get("sub"),
165 }
166```
128> [tab] Python (PyJWT)
129>
130> ```python theme={null}
131> import jwt
132> from jwt import PyJWKClient
133>
134> JWKS_URL = "https://api.anthropic.com/v1/code/.well-known/jwks.json"
135> PREFIX = "sk-ant-cc-"
136> EXPECTED_POOL_ID = "ccpool_..."
137>
138> jwks = PyJWKClient(JWKS_URL)
139>
140>
141> def verify_session_token(raw: str) -> dict:
142> if not raw.startswith(PREFIX):
143> raise ValueError("not a self-hosted runner session token")
144> token = raw.removeprefix(PREFIX)
145>
146> signing_key = jwks.get_signing_key_from_jwt(token)
147> payload = jwt.decode(
148> token,
149> signing_key.key,
150> algorithms=["ES256"],
151> issuer="ccr",
152> audience=EXPECTED_POOL_ID,
153> )
154>
155> if payload.get("ccr:role") != "session_worker":
156> raise ValueError("token is not a session_worker token")
157>
158> act = payload.get("act") or {}
159> return {
160> "session_id": payload["ccr:session_id"],
161> "pool_id": payload["ccr:pool_id"],
162> "org_id": payload["ccr:org_id"],
163> "creator_email": act.get("email"),
164> "creator_sub": act.get("sub"),
165> }
166> ```
167167
168168### Verify the token inside the session
169169
settings-example Changed · +325 / -325 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 16
1616
1717One developer's personal settings. It picks a model and effort, adjusts the terminal, and pre-approves a read-only command and one file read. Everything not listed keeps its default. A file like this goes in `~/.claude/settings.json`, where it applies to every project you open.
1818
19**Copyable settings file**
20
21Save this as `~/.claude/settings.json`. It's valid JSON with no comments, so you can paste it as is and delete the keys you don't want.
22
23```json ~/.claude/settings.json theme={null}
24{
25 "model": "claude-sonnet-5",
26 "modelSettings": {
27 "claude-sonnet-5": { "effortLevel": "xhigh" }
28 },
29 "editorMode": "vim",
30 "theme": "light-daltonized",
31 "statusLine": {
32 "type": "command",
33 "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
34 "padding": 2
35 },
36 "spinnerTipsEnabled": false,
37 "preferredNotifChannel": "terminal_bell",
38 "permissions": {
39 "allow": [
40 "Bash(git diff *)",
41 "Read(~/.zshrc)"
42 ]
43 },
44 "autoUpdatesChannel": "stable",
45 "cleanupPeriodDays": 20
46}
47```
48
49**What each key does**
50
51The same file with a comment above each key. Read it here; copy from the other tab, because Claude Code doesn't accept comments in a settings file.
52
53```jsonc ~/.claude/settings.json theme={null}
54{
55 // Start every session on Sonnet 5
56 "model": "claude-sonnet-5",
57 // Run Sonnet 5 above its default high level; /effort saves a level per model, and --effort sets one for a single session
58 "modelSettings": {
59 "claude-sonnet-5": { "effortLevel": "xhigh" }
60 },
61 // Vim keybindings in the prompt
62 "editorMode": "vim",
63 // The colorblind-friendly light theme
64 "theme": "light-daltonized",
65 // A status line below the prompt: model name and context used
66 "statusLine": {
67 "type": "command",
68 "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
69 "padding": 2
70 },
71 // Hide the tips that rotate under the spinner
72 "spinnerTipsEnabled": false,
73 // Ring the terminal bell for notifications, such as a finished task or a waiting permission prompt
74 "preferredNotifChannel": "terminal_bell",
75 // Let Claude Code run git diff and read your .zshrc without asking
76 "permissions": {
77 "allow": [
78 "Bash(git diff *)",
79 "Read(~/.zshrc)"
80 ]
81 },
82 // Take updates from the stable channel
83 "autoUpdatesChannel": "stable",
84 // Delete session transcripts and other local session data older than 20 days
85 "cleanupPeriodDays": 20
86}
87```
19> [tab] Copyable settings file
20>
21> Save this as `~/.claude/settings.json`. It's valid JSON with no comments, so you can paste it as is and delete the keys you don't want.
22>
23> ```json ~/.claude/settings.json theme={null}
24> {
25> "model": "claude-sonnet-5",
26> "modelSettings": {
27> "claude-sonnet-5": { "effortLevel": "xhigh" }
28> },
29> "editorMode": "vim",
30> "theme": "light-daltonized",
31> "statusLine": {
32> "type": "command",
33> "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
34> "padding": 2
35> },
36> "spinnerTipsEnabled": false,
37> "preferredNotifChannel": "terminal_bell",
38> "permissions": {
39> "allow": [
40> "Bash(git diff *)",
41> "Read(~/.zshrc)"
42> ]
43> },
44> "autoUpdatesChannel": "stable",
45> "cleanupPeriodDays": 20
46> }
47> ```
48
49> [tab] What each key does
50>
51> The same file with a comment above each key. Read it here; copy from the other tab, because Claude Code doesn't accept comments in a settings file.
52>
53> ```jsonc ~/.claude/settings.json theme={null}
54> {
55> // Start every session on Sonnet 5
56> "model": "claude-sonnet-5",
57> // Run Sonnet 5 above its default high level; /effort saves a level per model, and --effort sets one for a single session
58> "modelSettings": {
59> "claude-sonnet-5": { "effortLevel": "xhigh" }
60> },
61> // Vim keybindings in the prompt
62> "editorMode": "vim",
63> // The colorblind-friendly light theme
64> "theme": "light-daltonized",
65> // A status line below the prompt: model name and context used
66> "statusLine": {
67> "type": "command",
68> "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
69> "padding": 2
70> },
71> // Hide the tips that rotate under the spinner
72> "spinnerTipsEnabled": false,
73> // Ring the terminal bell for notifications, such as a finished task or a waiting permission prompt
74> "preferredNotifChannel": "terminal_bell",
75> // Let Claude Code run git diff and read your .zshrc without asking
76> "permissions": {
77> "allow": [
78> "Bash(git diff *)",
79> "Read(~/.zshrc)"
80> ]
81> },
82> // Take updates from the stable channel
83> "autoUpdatesChannel": "stable",
84> // Delete session transcripts and other local session data older than 20 days
85> "cleanupPeriodDays": 20
86> }
87> ```
8888
8989## A team's shared settings
9090
from line 96
9696* **The hook is a script in the repo.** This file's hook runs `.claude/hooks/block-rm.sh`; [How a hook resolves](https://code.claude.com/docs/en/hooks.md#how-a-hook-resolves) walks through writing it.
9797* **Rules match the command and path as written.** `Bash(git push *)` doesn't match [`git -C . push`](https://code.claude.com/docs/en/permissions#bash-rule-limits). `Read(./.env)` on its own stops the file tools and commands that name the file, such as `cat .env`, but not [`grep -r` run over the directory](https://code.claude.com/docs/en/permissions#read-and-edit); the `sandbox` block in this file closes that gap, because the sandbox [adds your `Read` deny paths](https://code.claude.com/docs/en/settings-reference#sandbox-filesystem-denyread) to what every sandboxed command can't read.
9898
99**Copyable settings file**
100
101Save this as `.claude/settings.json` at the top of the repository and commit it. It's valid JSON with no comments, so you can paste it as is and delete the keys you don't want.
102
103```json .claude/settings.json theme={null}
104{
105 "permissions": {
106 "allow": [
107 "Bash(npm run *)"
108 ],
109 "ask": [
110 "Bash(git push *)"
111 ],
112 "deny": [
113 "Read(./.env)",
114 "Read(./.env.*)",
115 "Read(./secrets/**)"
116 ]
117 },
118 "hooks": {
119 "PreToolUse": [
120 {
121 "matcher": "Bash",
122 "hooks": [
123 {
124 "type": "command",
125 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
126 }
127 ]
128 }
129 ]
130 },
131 "extraKnownMarketplaces": {
132 "acme-tools": {
133 "source": {
134 "source": "github",
135 "repo": "acme-corp/claude-plugins"
136 }
137 }
138 },
139 "enabledPlugins": {
140 "code-formatter@acme-tools": true
141 },
142 "sandbox": {
143 "enabled": true,
144 "filesystem": {
145 "allowWrite": [
146 "/tmp/build"
147 ]
148 },
149 "network": {
150 "allowedDomains": [
151 "registry.npmjs.org",
152 "*.example.com"
153 ]
154 }
155 },
156 "plansDirectory": "./plans"
157}
158```
159
160**What each key does**
161
162The same file with a comment above each key. Read it here; copy from the other tab, because Claude Code doesn't accept comments in a settings file.
163
164```jsonc .claude/settings.json theme={null}
165{
166 "permissions": {
167 // Run npm scripts without asking
168 "allow": [
169 "Bash(npm run *)"
170 ],
171 // Confirm before git push commands
172 "ask": [
173 "Bash(git push *)"
174 ],
175 // Deny reads of env files and the secrets folder by the file tools and file-reading commands
176 "deny": [
177 "Read(./.env)",
178 "Read(./.env.*)",
179 "Read(./secrets/**)"
180 ]
181 },
182 // Before every Bash command, run a script in the repo that can block it
183 "hooks": {
184 "PreToolUse": [
185 {
186 "matcher": "Bash",
187 "hooks": [
188 {
189 "type": "command",
190 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
191 }
192 ]
193 }
194 ]
195 },
196 // Register the team's plugin marketplace on every clone
197 "extraKnownMarketplaces": {
198 "acme-tools": {
199 "source": {
200 "source": "github",
201 "repo": "acme-corp/claude-plugins"
202 }
203 }
204 },
205 // Enable one plugin from that marketplace; a plugin from an external source such as a GitHub repository still needs each person to install it once
206 "enabledPlugins": {
207 "code-formatter@acme-tools": true
208 },
209 // Sandbox commands: writable build dir; npm and example.com pre-allowed
210 "sandbox": {
211 "enabled": true,
212 "filesystem": {
213 "allowWrite": [
214 "/tmp/build"
215 ]
216 },
217 "network": {
218 "allowedDomains": [
219 "registry.npmjs.org",
220 "*.example.com"
221 ]
222 }
223 },
224 // Keep plan files inside the repo
225 "plansDirectory": "./plans"
226}
227```
99> [tab] Copyable settings file
100>
101> Save this as `.claude/settings.json` at the top of the repository and commit it. It's valid JSON with no comments, so you can paste it as is and delete the keys you don't want.
102>
103> ```json .claude/settings.json theme={null}
104> {
105> "permissions": {
106> "allow": [
107> "Bash(npm run *)"
108> ],
109> "ask": [
110> "Bash(git push *)"
111> ],
112> "deny": [
113> "Read(./.env)",
114> "Read(./.env.*)",
115> "Read(./secrets/**)"
116> ]
117> },
118> "hooks": {
119> "PreToolUse": [
120> {
121> "matcher": "Bash",
122> "hooks": [
123> {
124> "type": "command",
125> "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
126> }
127> ]
128> }
129> ]
130> },
131> "extraKnownMarketplaces": {
132> "acme-tools": {
133> "source": {
134> "source": "github",
135> "repo": "acme-corp/claude-plugins"
136> }
137> }
138> },
139> "enabledPlugins": {
140> "code-formatter@acme-tools": true
141> },
142> "sandbox": {
143> "enabled": true,
144> "filesystem": {
145> "allowWrite": [
146> "/tmp/build"
147> ]
148> },
149> "network": {
150> "allowedDomains": [
151> "registry.npmjs.org",
152> "*.example.com"
153> ]
154> }
155> },
156> "plansDirectory": "./plans"
157> }
158> ```
159
160> [tab] What each key does
161>
162> The same file with a comment above each key. Read it here; copy from the other tab, because Claude Code doesn't accept comments in a settings file.
163>
164> ```jsonc .claude/settings.json theme={null}
165> {
166> "permissions": {
167> // Run npm scripts without asking
168> "allow": [
169> "Bash(npm run *)"
170> ],
171> // Confirm before git push commands
172> "ask": [
173> "Bash(git push *)"
174> ],
175> // Deny reads of env files and the secrets folder by the file tools and file-reading commands
176> "deny": [
177> "Read(./.env)",
178> "Read(./.env.*)",
179> "Read(./secrets/**)"
180> ]
181> },
182> // Before every Bash command, run a script in the repo that can block it
183> "hooks": {
184> "PreToolUse": [
185> {
186> "matcher": "Bash",
187> "hooks": [
188> {
189> "type": "command",
190> "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
191> }
192> ]
193> }
194> ]
195> },
196> // Register the team's plugin marketplace on every clone
197> "extraKnownMarketplaces": {
198> "acme-tools": {
199> "source": {
200> "source": "github",
201> "repo": "acme-corp/claude-plugins"
202> }
203> }
204> },
205> // Enable one plugin from that marketplace; a plugin from an external source such as a GitHub repository still needs each person to install it once
206> "enabledPlugins": {
207> "code-formatter@acme-tools": true
208> },
209> // Sandbox commands: writable build dir; npm and example.com pre-allowed
210> "sandbox": {
211> "enabled": true,
212> "filesystem": {
213> "allowWrite": [
214> "/tmp/build"
215> ]
216> },
217> "network": {
218> "allowedDomains": [
219> "registry.npmjs.org",
220> "*.example.com"
221> ]
222> }
223> },
224> // Keep plan files inside the repo
225> "plansDirectory": "./plans"
226> }
227> ```
228228
229229## An organization's managed settings
230230
from line 243
243243
244244Administrators deploy a file like this as `managed-settings.json`, or the same JSON through MDM or [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md). One deployed file applies to every machine or account it reaches. To give a group different values, deploy a different file or profile to that group, since [server-managed settings don't support per-group policy yet](https://code.claude.com/docs/en/server-managed-settings.md#current-limitations).
245245
246**Copyable settings file**
247
248Deploy this as `managed-settings.json`, or the same JSON through MDM or the claude.ai console. It's valid JSON with no comments; replace the example organization UUID, server URL, and marketplace with your own and delete the keys you don't want.
249
250```json managed-settings.json theme={null}
251{
252 "forceLoginMethod": "claudeai",
253 "forceLoginOrgUUID": [
254 "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
255 ],
256 "availableModels": [
257 "opus",
258 "sonnet"
259 ],
260 "enforceAvailableModels": true,
261 "permissions": {
262 "deny": [
263 "Bash(curl *)",
264 "Read(./.env)",
265 "Read(./secrets/**)"
266 ],
267 "disableBypassPermissionsMode": "disable"
268 },
269 "allowManagedPermissionRulesOnly": true,
270 "allowedMcpServers": [
271 {
272 "serverUrl": "https://api.githubcopilot.com/*"
273 }
274 ],
275 "allowManagedMcpServersOnly": true,
276 "strictKnownMarketplaces": [
277 {
278 "source": "github",
279 "repo": "acme-corp/approved-plugins"
280 }
281 ],
282 "sandbox": {
283 "enabled": true,
284 "failIfUnavailable": true,
285 "allowUnsandboxedCommands": false,
286 "network": {
287 "allowedDomains": [
288 "registry.npmjs.org",
289 "github.com"
290 ],
291 "allowManagedDomainsOnly": true
292 }
293 },
294 "requiredMinimumVersion": "2.1.150",
295 "cleanupPeriodDays": 7,
296 "companyAnnouncements": [
297 "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
298 ]
299}
300```
301
302**What each key does**
303
304The same file with a comment above each key. Read it here; copy from the other tab, because Claude Code doesn't accept comments in a settings file.
305
306```jsonc managed-settings.json theme={null}
307{
308 // Only claude.ai logins, and only in this organization
309 "forceLoginMethod": "claudeai",
310 "forceLoginOrgUUID": [
311 "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
312 ],
313 // Only Opus and Sonnet models; with enforceAvailableModels, the Default option obeys the list too
314 "availableModels": [
315 "opus",
316 "sonnet"
317 ],
318 "enforceAvailableModels": true,
319 "permissions": {
320 // Deny curl commands and reads of the project's .env file and secrets folder on every machine
321 "deny": [
322 "Bash(curl *)",
323 "Read(./.env)",
324 "Read(./secrets/**)"
325 ],
326 // Remove the bypass-permissions mode from every session
327 "disableBypassPermissionsMode": "disable"
328 },
329 // Ignore permission rules from user, project, and local settings
330 "allowManagedPermissionRulesOnly": true,
331 // Only the GitHub MCP server, matched by URL rather than by name, since a user can
332 // name any server "github". User-added servers that don't match don't load, including
333 // every stdio server when the list has only URL entries. The allowManagedMcpServersOnly
334 // key below makes this managed list the only allowlist that applies
335 "allowedMcpServers": [
336 {
337 "serverUrl": "https://api.githubcopilot.com/*"
338 }
339 ],
340 "allowManagedMcpServersOnly": true,
341 // Plugins can come only from this marketplace
342 "strictKnownMarketplaces": [
343 {
344 "source": "github",
345 "repo": "acme-corp/approved-plugins"
346 }
347 ],
348 // Sandbox every command Claude runs, refuse to start if the sandbox can't be
349 // set up, and never let a blocked command retry outside the sandbox; network
350 // limited to npm and GitHub, and users can't add domains
351 "sandbox": {
352 "enabled": true,
353 "failIfUnavailable": true,
354 "allowUnsandboxedCommands": false,
355 "network": {
356 "allowedDomains": [
357 "registry.npmjs.org",
358 "github.com"
359 ],
360 "allowManagedDomainsOnly": true
361 }
362 },
363 // Refuse to start on versions older than 2.1.150
364 "requiredMinimumVersion": "2.1.150",
365 // Delete session transcripts and other local session data after 7 days
366 "cleanupPeriodDays": 7,
367 // A message every user sees at startup
368 "companyAnnouncements": [
369 "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
370 ]
371}
372```
246> [tab] Copyable settings file
247>
248> Deploy this as `managed-settings.json`, or the same JSON through MDM or the claude.ai console. It's valid JSON with no comments; replace the example organization UUID, server URL, and marketplace with your own and delete the keys you don't want.
249>
250> ```json managed-settings.json theme={null}
251> {
252> "forceLoginMethod": "claudeai",
253> "forceLoginOrgUUID": [
254> "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
255> ],
256> "availableModels": [
257> "opus",
258> "sonnet"
259> ],
260> "enforceAvailableModels": true,
261> "permissions": {
262> "deny": [
263> "Bash(curl *)",
264> "Read(./.env)",
265> "Read(./secrets/**)"
266> ],
267> "disableBypassPermissionsMode": "disable"
268> },
269> "allowManagedPermissionRulesOnly": true,
270> "allowedMcpServers": [
271> {
272> "serverUrl": "https://api.githubcopilot.com/*"
273> }
274> ],
275> "allowManagedMcpServersOnly": true,
276> "strictKnownMarketplaces": [
277> {
278> "source": "github",
279> "repo": "acme-corp/approved-plugins"
280> }
281> ],
282> "sandbox": {
283> "enabled": true,
284> "failIfUnavailable": true,
285> "allowUnsandboxedCommands": false,
286> "network": {
287> "allowedDomains": [
288> "registry.npmjs.org",
289> "github.com"
290> ],
291> "allowManagedDomainsOnly": true
292> }
293> },
294> "requiredMinimumVersion": "2.1.150",
295> "cleanupPeriodDays": 7,
296> "companyAnnouncements": [
297> "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
298> ]
299> }
300> ```
301
302> [tab] What each key does
303>
304> The same file with a comment above each key. Read it here; copy from the other tab, because Claude Code doesn't accept comments in a settings file.
305>
306> ```jsonc managed-settings.json theme={null}
307> {
308> // Only claude.ai logins, and only in this organization
309> "forceLoginMethod": "claudeai",
310> "forceLoginOrgUUID": [
311> "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
312> ],
313> // Only Opus and Sonnet models; with enforceAvailableModels, the Default option obeys the list too
314> "availableModels": [
315> "opus",
316> "sonnet"
317> ],
318> "enforceAvailableModels": true,
319> "permissions": {
320> // Deny curl commands and reads of the project's .env file and secrets folder on every machine
321> "deny": [
322> "Bash(curl *)",
323> "Read(./.env)",
324> "Read(./secrets/**)"
325> ],
326> // Remove the bypass-permissions mode from every session
327> "disableBypassPermissionsMode": "disable"
328> },
329> // Ignore permission rules from user, project, and local settings
330> "allowManagedPermissionRulesOnly": true,
331> // Only the GitHub MCP server, matched by URL rather than by name, since a user can
332> // name any server "github". User-added servers that don't match don't load, including
333> // every stdio server when the list has only URL entries. The allowManagedMcpServersOnly
334> // key below makes this managed list the only allowlist that applies
335> "allowedMcpServers": [
336> {
337> "serverUrl": "https://api.githubcopilot.com/*"
338> }
339> ],
340> "allowManagedMcpServersOnly": true,
341> // Plugins can come only from this marketplace
342> "strictKnownMarketplaces": [
343> {
344> "source": "github",
345> "repo": "acme-corp/approved-plugins"
346> }
347> ],
348> // Sandbox every command Claude runs, refuse to start if the sandbox can't be
349> // set up, and never let a blocked command retry outside the sandbox; network
350> // limited to npm and GitHub, and users can't add domains
351> "sandbox": {
352> "enabled": true,
353> "failIfUnavailable": true,
354> "allowUnsandboxedCommands": false,
355> "network": {
356> "allowedDomains": [
357> "registry.npmjs.org",
358> "github.com"
359> ],
360> "allowManagedDomainsOnly": true
361> }
362> },
363> // Refuse to start on versions older than 2.1.150
364> "requiredMinimumVersion": "2.1.150",
365> // Delete session transcripts and other local session data after 7 days
366> "cleanupPeriodDays": 7,
367> // A message every user sees at startup
368> "companyAnnouncements": [
369> "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
370> ]
371> }
372> ```
373373
setup Changed · +270 / -270 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 31
3131
3232To install Claude Code, open a terminal and run the command for your system. If you haven't used a terminal before, the [terminal guide](https://code.claude.com/docs/en/terminal-guide) shows how to open one and paste the command.
3333
34**Native Install (Recommended)**
35
36**macOS, Linux, WSL:**
37
38```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
39curl -fsSL https://claude.ai/install.sh | bash
40```
41
42On Windows, your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.
43
44**Windows PowerShell:**
45
46```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
47irm https://claude.ai/install.ps1 | iex
48```
49
50**Windows CMD:**
51
52```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
53curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
54```
55
56The install command shows no progress while it downloads Claude Code. When the installer finishes, open a new terminal window and run `claude --version`. A working installation prints a version number. If your shell says `claude` isn't found or isn't recognized, the install directory isn't on your PATH yet: see [Fix your PATH](https://code.claude.com/docs/en/troubleshoot-install.md#command-not-found-claude-after-installation).
57
58If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell.
59
60If the install command fails with `syntax error near unexpected token '<'`, a `403`, or any other error, see [Troubleshoot installation](https://code.claude.com/docs/en/troubleshoot-install.md#find-your-error) to match the error to a fix and for alternative install methods.
61
62[Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.
63
64> [!NOTE]
65>
66> Native installations automatically update in the background to keep you on the latest version.
67
68**Homebrew**
69
70```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
71brew install --cask claude-code
72```
73
74Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.
75
76> [!NOTE]
77>
78> Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.
79
80**WinGet**
81
82```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
83winget install Anthropic.ClaudeCode
84```
85
86> [!NOTE]
87>
88> WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.
34> [tab] Native Install (Recommended)
35>
36> **macOS, Linux, WSL:**
37>
38> ```bash theme={null}
39> curl -fsSL https://claude.ai/install.sh | bash
40> ```
41>
42> On Windows, your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.
43>
44> **Windows PowerShell:**
45>
46> ```powershell theme={null}
47> irm https://claude.ai/install.ps1 | iex
48> ```
49>
50> **Windows CMD:**
51>
52> ```batch theme={null}
53> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
54> ```
55>
56> The install command shows no progress while it downloads Claude Code. When the installer finishes, open a new terminal window and run `claude --version`. A working installation prints a version number. If your shell says `claude` isn't found or isn't recognized, the install directory isn't on your PATH yet: see [Fix your PATH](https://code.claude.com/docs/en/troubleshoot-install.md#command-not-found-claude-after-installation).
57>
58> If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell.
59>
60> If the install command fails with `syntax error near unexpected token '<'`, a `403`, or any other error, see [Troubleshoot installation](https://code.claude.com/docs/en/troubleshoot-install.md#find-your-error) to match the error to a fix and for alternative install methods.
61>
62> [Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.
63>
64> > [!NOTE]
65> >
66> > Native installations automatically update in the background to keep you on the latest version.
67
68> [tab] Homebrew
69>
70> ```bash theme={null}
71> brew install --cask claude-code
72> ```
73>
74> Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.
75>
76> > [!NOTE]
77> >
78> > Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.
79
80> [tab] WinGet
81>
82> ```powershell theme={null}
83> winget install Anthropic.ClaudeCode
84> ```
85>
86> > [!NOTE]
87> >
88> > WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.
8989
9090You can also install with [apt, dnf, or apk](https://code.claude.com/docs/en/setup.md#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.
9191
from line 184
184184
185185## Authenticate
186186
187Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free claude.ai plan does not include Claude Code access. You can also use Claude Code with a third-party API provider like [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md).
187Claude Code requires a Pro, Max, Ultra, Team, Enterprise, or Console account. The free claude.ai plan does not include Claude Code access. You can also use Claude Code with a third-party API provider like [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md).
188188
189189After installing, log in by running `claude` and following the browser prompts. If you've set the `ANTHROPIC_API_KEY` environment variable and you approve the key when Claude Code asks whether to use it, Claude Code skips the login prompt. See [Authentication](https://code.claude.com/docs/en/authentication.md) for all account types and team setup options.
190190
from line 296
296296
297297To install the latest version (default):
298298
299**macOS, Linux, WSL**
300
301```bash theme={null}
302curl -fsSL https://claude.ai/install.sh | bash
303```
304
305**Windows PowerShell**
306
307```powershell theme={null}
308irm https://claude.ai/install.ps1 | iex
309```
310
311**Windows CMD**
312
313```batch theme={null}
314curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
315```
299> [tab] macOS, Linux, WSL
300>
301> ```bash theme={null}
302> curl -fsSL https://claude.ai/install.sh | bash
303> ```
304
305> [tab] Windows PowerShell
306>
307> ```powershell theme={null}
308> irm https://claude.ai/install.ps1 | iex
309> ```
310
311> [tab] Windows CMD
312>
313> ```batch theme={null}
314> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
315> ```
316316
317317To install the stable version:
318318
319**macOS, Linux, WSL**
320
321```bash theme={null}
322curl -fsSL https://claude.ai/install.sh | bash -s stable
323```
324
325**Windows PowerShell**
326
327```powershell theme={null}
328& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable
329```
330
331**Windows CMD**
332
333```batch theme={null}
334curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd
335```
319> [tab] macOS, Linux, WSL
320>
321> ```bash theme={null}
322> curl -fsSL https://claude.ai/install.sh | bash -s stable
323> ```
324
325> [tab] Windows PowerShell
326>
327> ```powershell theme={null}
328> & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable
329> ```
330
331> [tab] Windows CMD
332>
333> ```batch theme={null}
334> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd
335> ```
336336
337337To install a specific version number:
338338
339**macOS, Linux, WSL**
340
341```bash theme={null}
342curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89
343```
344
345**Windows PowerShell**
346
347```powershell theme={null}
348& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89
349```
350
351**Windows CMD**
352
353```batch theme={null}
354curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 2.1.89 && del install.cmd
355```
339> [tab] macOS, Linux, WSL
340>
341> ```bash theme={null}
342> curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89
343> ```
344
345> [tab] Windows PowerShell
346>
347> ```powershell theme={null}
348> & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89
349> ```
350
351> [tab] Windows CMD
352>
353> ```batch theme={null}
354> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 2.1.89 && del install.cmd
355> ```
356356
357357To confirm which version installed, run `claude --version`: the command prints the exact version you passed, such as `2.1.89 (Claude Code)`.
358358
from line 362
362362
363363All repositories are signed with the [Claude Code release signing key](#binary-integrity-and-code-signing). Before trusting the key, verify it as described in each tab.
364364
365**apt**
366
367For Debian and Ubuntu. The install commands below download the signing key with `curl` and verify it with `gpg`, which fresh Debian and Ubuntu installations may not include. If either command reports `command not found`, install both first:
368
369```bash theme={null}
370sudo apt install curl gnupg
371```
372
373Download the signing key:
374
375```bash theme={null}
376sudo install -d -m 0755 /etc/apt/keyrings
377sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
378 -o /etc/apt/keyrings/claude-code.asc
379```
380
381If this download fails, `apt update` later fails with `NO_PUBKEY BAA929FF1A7ECACE`. Confirm the key downloaded and belongs to Anthropic before continuing:
382
383```bash theme={null}
384gpg --show-keys /etc/apt/keyrings/claude-code.asc
385```
386
387The 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.
388
389Register the repository on the `stable` channel and install:
390
391```bash theme={null}
392echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
393 | sudo tee /etc/apt/sources.list.d/claude-code.list
394sudo apt update
395sudo apt install claude-code
396```
397
398To use the `latest` channel instead, both the URL path and the suite name change. Use this `deb` line:
399
400```bash theme={null}
401echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/latest latest main" \
402 | sudo tee /etc/apt/sources.list.d/claude-code.list
403```
404
405To upgrade later, run `sudo apt update && sudo apt upgrade claude-code`.
406
407**dnf**
408
409For Fedora and RHEL. The following commands configure the `stable` channel:
410
411```bash theme={null}
412sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
413[claude-code]
414name=Claude Code
415baseurl=https://downloads.claude.ai/claude-code/rpm/stable
416enabled=1
417gpgcheck=1
418gpgkey=https://downloads.claude.ai/keys/claude-code.asc
419EOF
420sudo dnf install claude-code
421```
422
423To use the `latest` channel instead, set `baseurl` to the `latest` repository:
424
425```ini theme={null}
426baseurl=https://downloads.claude.ai/claude-code/rpm/latest
427```
428
429dnf downloads the key on first install and prompts you to confirm the fingerprint. Verify it matches `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE` before accepting.
430
431To upgrade later, run `sudo dnf upgrade claude-code`.
432
433**apk**
434
435For Alpine Linux. The following commands configure the `stable` channel:
436
437```sh theme={null}
438wget -O /etc/apk/keys/claude-code.rsa.pub \
439 https://downloads.claude.ai/keys/claude-code.rsa.pub
440echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
441apk add claude-code
442```
443
444To switch to the `latest` channel, remove the `stable` repository line and add the `latest` repository:
445
446```sh theme={null}
447sed -i '\|downloads.claude.ai/claude-code/apk/stable|d' /etc/apk/repositories
448echo "https://downloads.claude.ai/claude-code/apk/latest" >> /etc/apk/repositories
449```
450
451Verify the downloaded key with `sha256sum /etc/apk/keys/claude-code.rsa.pub`, which should report `395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6`.
452
453To upgrade later, run `apk update && apk upgrade claude-code`.
365> [tab] apt
366>
367> For Debian and Ubuntu. The install commands below download the signing key with `curl` and verify it with `gpg`, which fresh Debian and Ubuntu installations may not include. If either command reports `command not found`, install both first:
368>
369> ```bash theme={null}
370> sudo apt install curl gnupg
371> ```
372>
373> Download the signing key:
374>
375> ```bash theme={null}
376> sudo install -d -m 0755 /etc/apt/keyrings
377> sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
378> -o /etc/apt/keyrings/claude-code.asc
379> ```
380>
381> If this download fails, `apt update` later fails with `NO_PUBKEY BAA929FF1A7ECACE`. Confirm the key downloaded and belongs to Anthropic before continuing:
382>
383> ```bash theme={null}
384> gpg --show-keys /etc/apt/keyrings/claude-code.asc
385> ```
386>
387> 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.
388>
389> Register the repository on the `stable` channel and install:
390>
391> ```bash theme={null}
392> echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
393> | sudo tee /etc/apt/sources.list.d/claude-code.list
394> sudo apt update
395> sudo apt install claude-code
396> ```
397>
398> To use the `latest` channel instead, both the URL path and the suite name change. Use this `deb` line:
399>
400> ```bash theme={null}
401> echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/latest latest main" \
402> | sudo tee /etc/apt/sources.list.d/claude-code.list
403> ```
404>
405> To upgrade later, run `sudo apt update && sudo apt upgrade claude-code`.
406
407> [tab] dnf
408>
409> For Fedora and RHEL. The following commands configure the `stable` channel:
410>
411> ```bash theme={null}
412> sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
413> [claude-code]
414> name=Claude Code
415> baseurl=https://downloads.claude.ai/claude-code/rpm/stable
416> enabled=1
417> gpgcheck=1
418> gpgkey=https://downloads.claude.ai/keys/claude-code.asc
419> EOF
420> sudo dnf install claude-code
421> ```
422>
423> To use the `latest` channel instead, set `baseurl` to the `latest` repository:
424>
425> ```ini theme={null}
426> baseurl=https://downloads.claude.ai/claude-code/rpm/latest
427> ```
428>
429> dnf downloads the key on first install and prompts you to confirm the fingerprint. Verify it matches `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE` before accepting.
430>
431> To upgrade later, run `sudo dnf upgrade claude-code`.
432
433> [tab] apk
434>
435> For Alpine Linux. The following commands configure the `stable` channel:
436>
437> ```sh theme={null}
438> wget -O /etc/apk/keys/claude-code.rsa.pub \
439> https://downloads.claude.ai/keys/claude-code.rsa.pub
440> echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
441> apk add claude-code
442> ```
443>
444> To switch to the `latest` channel, remove the `stable` repository line and add the `latest` repository:
445>
446> ```sh theme={null}
447> sed -i '\|downloads.claude.ai/claude-code/apk/stable|d' /etc/apk/repositories
448> echo "https://downloads.claude.ai/claude-code/apk/latest" >> /etc/apk/repositories
449> ```
450>
451> Verify the downloaded key with `sha256sum /etc/apk/keys/claude-code.rsa.pub`, which should report `395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6`.
452>
453> To upgrade later, run `apk update && apk upgrade claude-code`.
454454
455455### Install with npm
456456
from line 542
542542
543543Compare the SHA256 checksum of the binary with the value listed under `platforms.<platform>.checksum` in `manifest.json`. The commands below assume a `claude` binary in the current directory. To verify an installed native binary instead, run the command against `~/.local/share/claude/versions/VERSION`, replacing VERSION with the release you set in Step 2.
544544
545**Linux**
546
547```bash theme={null}
548sha256sum claude
549```
550
551**macOS**
552
553```bash theme={null}
554shasum -a 256 claude
555```
556
557**Windows PowerShell**
558
559```powershell theme={null}
560(Get-FileHash claude.exe -Algorithm SHA256).Hash.ToLower()
561```
545> [tab] Linux
546>
547> ```bash theme={null}
548> sha256sum claude
549> ```
550
551> [tab] macOS
552>
553> ```bash theme={null}
554> shasum -a 256 claude
555> ```
556
557> [tab] Windows PowerShell
558>
559> ```powershell theme={null}
560> (Get-FileHash claude.exe -Algorithm SHA256).Hash.ToLower()
561> ```
562562
563563> [!NOTE]
564564>
from line 580
580580
581581Remove the Claude Code binary and version files:
582582
583**macOS, Linux, WSL**
584
585```bash theme={null}
586rm -f ~/.local/bin/claude
587rm -rf ~/.local/share/claude
588```
589
590**Windows PowerShell**
591
592```powershell theme={null}
593Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
594Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force
595```
583> [tab] macOS, Linux, WSL
584>
585> ```bash theme={null}
586> rm -f ~/.local/bin/claude
587> rm -rf ~/.local/share/claude
588> ```
589
590> [tab] Windows PowerShell
591>
592> ```powershell theme={null}
593> Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
594> Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force
595> ```
596596
597597### Uninstall with Homebrew
598598
from line 620
620620
621621Remove the package and the repository configuration:
622622
623**apt**
624
625```bash theme={null}
626sudo apt remove claude-code
627sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc
628```
629
630**dnf**
631
632```bash theme={null}
633sudo dnf remove claude-code
634sudo rm /etc/yum.repos.d/claude-code.repo
635```
636
637**apk**
638
639```sh theme={null}
640apk del claude-code
641sed -i '\|downloads.claude.ai/claude-code/apk|d' /etc/apk/repositories
642rm /etc/apk/keys/claude-code.rsa.pub
643```
623> [tab] apt
624>
625> ```bash theme={null}
626> sudo apt remove claude-code
627> sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc
628> ```
629
630> [tab] dnf
631>
632> ```bash theme={null}
633> sudo dnf remove claude-code
634> sudo rm /etc/yum.repos.d/claude-code.repo
635> ```
636
637> [tab] apk
638>
639> ```sh theme={null}
640> apk del claude-code
641> sed -i '\|downloads.claude.ai/claude-code/apk|d' /etc/apk/repositories
642> rm /etc/apk/keys/claude-code.rsa.pub
643> ```
644644
645645### Uninstall with npm
646646
from line 660
660660
661661To remove Claude Code settings and cached data:
662662
663**macOS, Linux, WSL**
664
665```bash theme={null}
666# Remove user settings and state
667rm -rf ~/.claude
668rm ~/.claude.json
669
670# Remove project-specific settings (run from your project directory)
671rm -rf .claude
672rm -f .mcp.json
673```
674
675**Windows PowerShell**
676
677```powershell theme={null}
678# Remove user settings and state
679Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
680Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force
681
682# Remove project-specific settings (run from your project directory)
683Remove-Item -Path ".claude" -Recurse -Force
684Remove-Item -Path ".mcp.json" -Force
685```
663> [tab] macOS, Linux, WSL
664>
665> ```bash theme={null}
666> # Remove user settings and state
667> rm -rf ~/.claude
668> rm ~/.claude.json
669>
670> # Remove project-specific settings (run from your project directory)
671> rm -rf .claude
672> rm -f .mcp.json
673> ```
674
675> [tab] Windows PowerShell
676>
677> ```powershell theme={null}
678> # Remove user settings and state
679> Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
680> Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force
681>
682> # Remove project-specific settings (run from your project directory)
683> Remove-Item -Path ".claude" -Recurse -Force
684> Remove-Item -Path ".mcp.json" -Force
685> ```
686686
slack Changed · +12 / -12 lines
from line 1
11# Claude Code in Slack
22
3> Delegate coding tasks from Slack. This earlier version answers channel mentions only from Pro and Max accounts in workspaces not connected to Claude Tag.
3> Delegate coding tasks from Slack. This earlier version answers mentions only from Pro, Max, and Ultra accounts in workspaces not connected to Claude Tag.
44
55> [!WARNING]
66>
7> This page documents the earlier Claude Code in Slack, which runs each session under an individual user's account. It answers channel @mentions only from Pro and Max accounts, and only in a Slack workspace that no organization has connected to [Claude Tag](https://claude.com/product/tag). Claude Tag runs @Claude as your organization's shared identity with admin-configured access.
7> This earlier Claude Code in Slack answers channel @mentions only from Pro, Max, and Ultra accounts, and only in a Slack workspace that no organization has connected to [Claude Tag](https://claude.com/product/tag). Each session runs under an individual user's account. Claude Tag runs @Claude as your organization's shared identity with admin-configured access.
88>
9> * **Pro and Max plans:** Claude Tag isn't available on individual plans, so this page remains the setup path in a workspace that isn't connected to Claude Tag.
9> * **Pro, Max, and Ultra plans:** Claude Tag isn't available on individual plans, so [set up this version](#setting-up-claude-code-in-slack) in a workspace that isn't connected to Claude Tag.
1010> * **Team and Enterprise plans:** your existing Slack app and @Claude handle stay. [Set up Claude Tag](https://claude.com/docs/claude-tag/overview) for a new workspace; to move one that already uses this version, see [Migrate from the earlier Claude in Slack](https://claude.com/docs/claude-tag/admins/migrate-from-earlier).
1111> * **Notice instead of an answer:** look up the [setup notice](#this-workspace-isnt-set-up-for-claude-tag-yet) or the [retirement notice](#the-legacy-claude-in-slack-bot-is-retired) that @Claude replied with.
1212
from line 27
2727
2828| Requirement | Details |
2929| :- | :- |
30| Claude Plan | Pro or Max |
30| Claude Plan | Pro, Max, or Ultra |
3131| Slack workspace | Not connected to [Claude Tag](https://claude.com/docs/claude-tag/overview) by any organization. If @Claude replies with the [retirement notice](#the-legacy-claude-in-slack-bot-is-retired), the workspace is connected |
3232| Cloud sessions | [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) are enabled for your account |
3333| GitHub Account | Connected at [claude.ai/code](https://claude.ai/code) with at least one repository authenticated |
from line 176
176176@Claude replies in the thread with this notice instead of an answer when both of these are true:
177177
178178* No organization has connected your Slack workspace to [Claude Tag](https://claude.com/docs/claude-tag/overview).
179* The Claude account you linked in Slack isn't on a Pro or Max plan.
179* The Claude account you linked in Slack isn't on a Pro, Max, or Ultra plan.
180180
181181Claude Tag is available on Team and Enterprise plans. To connect the workspace, start with the `@Claude connect` command the notice names, then follow [Set up Claude Tag](https://claude.com/docs/claude-tag/overview).
182182
183183### "The legacy Claude in Slack bot is retired"
184184
185The notice opens with `The legacy Claude in Slack bot is retired effective October 5, 2026 and no longer responds in channels.` Your Slack workspace is connected to a Claude organization, and the earlier version is still selected for the channel, the workspace, or the organization default in that organization's Claude Tag settings. The notice doesn't depend on your own plan, so Pro and Max accounts get it too.
185The notice opens with `The legacy Claude in Slack bot is retired effective October 5, 2026 and no longer responds in channels.` Your Slack workspace is connected to a Claude organization. The earlier version is still selected for the channel, the workspace, or the organization default in that organization's Claude Tag settings. The notice doesn't depend on your own plan, so Pro, Max, and Ultra accounts get it too.
186186
187187If you're an Owner of that organization, open [Claude admin settings](https://claude.ai/admin-settings/claude-tag) and turn on Claude Tag for the channel. To fix every channel that inherits the setting, change it on the workspace or the organization default instead. For the full move, see [Migrate from the earlier Claude in Slack](https://claude.com/docs/claude-tag/admins/migrate-from-earlier). If you're not an Owner, send this entry to one.
188188
from line 233
233233
234234## Related resources
235235
236> **[Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md)**
236> [card] [Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md)
237237>
238238> Learn more about cloud sessions
239239
240> **[Claude for Slack](https://claude.com/claude-and-slack)**
240> [card] [Claude for Slack](https://claude.com/claude-and-slack)
241241>
242242> General Claude for Slack documentation
243243
244> **[Claude Tag](https://claude.com/docs/claude-tag/overview)**
244> [card] [Claude Tag](https://claude.com/docs/claude-tag/overview)
245245>
246246> Organization-managed @Claude in Slack with admin-configured access
247247
248> **[Slack App Marketplace](https://slack.com/marketplace/A08SF47R6P4)**
248> [card] [Slack App Marketplace](https://slack.com/marketplace/A08SF47R6P4)
249249>
250250> Install the Claude app from the Slack Marketplace
251251
252> **[Claude Help Center](https://support.claude.com)**
252> [card] [Claude Help Center](https://support.claude.com)
253253>
254254> Get additional support
255255
statusline Changed · +5 / -5 lines
from line 208
208208| `worktree.original_cwd` | The directory Claude was in before entering the worktree |
209209| `worktree.original_branch` | Git branch checked out before entering the worktree. Absent for hook-based worktrees |
210210
211> **Full JSON schema**
211> [accordion] Full JSON schema
212212>
213213> Your status line command receives this JSON structure via stdin:
214214>
from line 337
337337> * `agent`: appears only when running with the `--agent` flag or agent settings configured
338338> * `pr`: appears only while an open PR or GitLab merge request is found for the current branch, and is removed once it merges or closes. `pr.review_state` and `pr.kind` may be independently absent
339339> * `worktree`: appears only while the session is in a [worktree session](https://code.claude.com/docs/en/worktrees.md). When present, `branch` and `original_branch` may also be absent for hook-based worktrees
340> * `rate_limits`: appears only for claude.ai Pro and Max subscribers, or behind a Claude apps gateway that sets a spend limit for you, and only after the first API response in the session. Each window (`five_hour`, `seven_day`, `spend_limit`) may be independently absent, and Claude Code drops a window once its `resets_at` time passes. Use `jq -r '.rate_limits.five_hour.used_percentage // empty'` to handle absence gracefully.
340> * `rate_limits`: appears only for claude.ai Pro, Max, and Ultra subscribers, or behind a Claude apps gateway that sets a spend limit for you. Even then, it appears only after the first API response in the session. Each window (`five_hour`, `seven_day`, `spend_limit`) may be independently absent, and Claude Code drops a window once its `resets_at` time passes. Use `jq -r '.rate_limits.five_hour.used_percentage // empty'` to handle absence gracefully.
341341> * `prompt_cache`: appears after the main conversation's first API response. See [prompt cache fields](#prompt-cache-fields)
342342>
343343> **Fields that may be `null`**:
from line 815
815815
816816### Rate limit usage
817817
818Display claude.ai subscription rate limit usage, or your spend against a Claude apps gateway spend limit, in the status line. For subscribers, the `rate_limits` object contains a rolling `five_hour` window and a weekly `seven_day` window. Each window provides `used_percentage`, from 0 to 100, and `resets_at`, the Unix epoch seconds when the window resets. Behind a gateway, read the `spend_limit` object, described under [spend limit fields](#spend-limit-fields).
818Display claude.ai subscription rate limit usage, or your spend against a Claude apps gateway spend limit, in the status line. For subscribers, the `rate_limits` object can contain a rolling `five_hour` window and a weekly `seven_day` window. Each window provides `used_percentage`, from 0 to 100, and `resets_at`, the Unix epoch seconds when the window resets. Behind a gateway, read the `spend_limit` object, described under [spend limit fields](#spend-limit-fields).
819819
820The `rate_limits` object is only present for claude.ai Pro and Max subscribers, or behind a Claude apps gateway with spend limits, and only after the first API response. Each script handles the absent fields gracefully, and behind a gateway prints `spend: $314.12 / $500`, or `spend: 63%` while the dollar fields are absent:
820The `rate_limits` object is only present for claude.ai Pro, Max, and Ultra subscribers, or behind a Claude apps gateway with spend limits, and only after the first API response. Each script handles the absent fields gracefully, and behind a gateway prints `spend: $314.12 / $500`, or `spend: 63%` while the dollar fields are absent:
821821
822822```bash Bash theme={null}
823823#!/bin/bash
sub-agents Changed · +80 / -80 lines
from line 28
2828
2929Explore and Plan start without your CLAUDE.md files and the git status snapshot to keep research fast and inexpensive. Other built-in and [custom subagents](#configure-subagents) load both, unless you set [`omitClaudeMd`](#supported-frontmatter-fields) in a custom subagent's definition to start it without the user, project, and local CLAUDE.md files. For the full breakdown of what reaches a subagent, see [what loads at startup](#what-loads-at-startup).
3030
31**Explore**
31> [tab] Explore
32>
33> A fast, read-only agent optimized for searching and analyzing codebases.
34>
35> * **Model**: the main conversation's model. When the main conversation runs Fable, Explore's model depends on how you connect:
36> * With a Claude subscription, an Anthropic Console account, or an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`, Explore runs on the Opus model that the [`opus` alias](https://code.claude.com/docs/en/model-config#model-aliases) resolves to.
37> * On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), or a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway), Explore stays on the main conversation's model.
38> * **Tools**: read-only tools; Write and Edit are denied
39> * **Purpose**: file discovery, code search, codebase exploration
40>
41> A [user or project subagent](#choose-the-subagent-scope) named `Explore` overrides the built-in and keeps its own `model` field, so define one with `model: haiku` to run exploration on a lower-cost model. To force one model onto every subagent, Explore included, see [Run every subagent on one model](#run-every-subagent-on-one-model).
42>
43> Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context.
44>
45> When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis.
3246
33A fast, read-only agent optimized for searching and analyzing codebases.
47> [tab] Plan
48>
49> A research agent used during [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.
50>
51> * **Model**: inherits from the main conversation, unless you set `CLAUDE_CODE_SUBAGENT_MODEL` and [force it onto every subagent](#run-every-subagent-on-one-model)
52> * **Tools**: read-only tools; Write and Edit are denied
53> * **Purpose**: codebase research for planning
54>
55> When you're in plan mode and Claude needs to understand your codebase, it delegates research to the Plan subagent so that exploration output stays in a separate context window while the main conversation remains read-only.
3456
35* **Model**: the main conversation's model. When the main conversation runs Fable, Explore's model depends on how you connect:
36 * With a Claude subscription, an Anthropic Console account, or an [LLM gateway](https://code.claude.com/docs/en/llm-gateway) reached through `ANTHROPIC_BASE_URL`, Explore runs on the Opus model that the [`opus` alias](https://code.claude.com/docs/en/model-config#model-aliases) resolves to.
37 * On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), or a [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway), Explore stays on the main conversation's model.
38* **Tools**: read-only tools; Write and Edit are denied
39* **Purpose**: file discovery, code search, codebase exploration
57> [tab] General-purpose
58>
59> A capable agent for complex, multi-step tasks that require both exploration and action.
60>
61> * **Model**: the [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) model if you set one and nothing assigns a model another way, otherwise the main conversation's model; [Choose a model](#choose-a-model) states the full order, and [Run every subagent on one model](#run-every-subagent-on-one-model) shows how to make the variable override those sources
62> * **Tools**: every tool [available to subagents](#available-tools)
63> * **Purpose**: complex research, multi-step operations, code modifications
64>
65> Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.
4066
41A [user or project subagent](#choose-the-subagent-scope) named `Explore` overrides the built-in and keeps its own `model` field, so define one with `model: haiku` to run exploration on a lower-cost model. To force one model onto every subagent, Explore included, see [Run every subagent on one model](#run-every-subagent-on-one-model).
67> [tab] Other
68>
69> Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.
70>
71> | Agent | Model | When Claude uses it |
72> | :- | :- | :- |
73> | claude | None of its own; follows the [model order](#choose-a-model) when Claude spawns it as a subagent | When a task doesn't fit a more specialized agent. A catch-all with every tool [available to subagents](#available-tools). Also the default agent for a dispatched [background session](https://code.claude.com/docs/en/agent-view.md); [which permission mode it starts in](https://code.claude.com/docs/en/agent-view.md#permission-mode-model-and-effort) depends on how the session was started |
74> | statusline-setup | Sonnet | When you run `/statusline` to configure your status line |
75> | claude-code-guide | Haiku | When you ask questions about Claude Code features |
4276
43Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context.
44
45When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis.
46
47**Plan**
48
49A research agent used during [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.
50
51* **Model**: inherits from the main conversation, unless you set `CLAUDE_CODE_SUBAGENT_MODEL` and [force it onto every subagent](#run-every-subagent-on-one-model)
52* **Tools**: read-only tools; Write and Edit are denied
53* **Purpose**: codebase research for planning
54
55When you're in plan mode and Claude needs to understand your codebase, it delegates research to the Plan subagent so that exploration output stays in a separate context window while the main conversation remains read-only.
56
57**General-purpose**
58
59A capable agent for complex, multi-step tasks that require both exploration and action.
60
61* **Model**: the [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) model if you set one and nothing assigns a model another way, otherwise the main conversation's model; [Choose a model](#choose-a-model) states the full order, and [Run every subagent on one model](#run-every-subagent-on-one-model) shows how to make the variable override those sources
62* **Tools**: every tool [available to subagents](#available-tools)
63* **Purpose**: complex research, multi-step operations, code modifications
64
65Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.
66
67**Other**
68
69Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.
70
71| Agent | Model | When Claude uses it |
72| :- | :- | :- |
73| claude | None of its own; follows the [model order](#choose-a-model) when Claude spawns it as a subagent | When a task doesn't fit a more specialized agent. A catch-all with every tool [available to subagents](#available-tools). Also the default agent for a dispatched [background session](https://code.claude.com/docs/en/agent-view.md); [which permission mode it starts in](https://code.claude.com/docs/en/agent-view.md#permission-mode-model-and-effort) depends on how the session was started |
74| statusline-setup | Sonnet | When you run `/statusline` to configure your status line |
75| claude-code-guide | Haiku | When you ask questions about Claude Code features |
76
7777Built-in subagents are registered by default in interactive sessions. To restrict them:
7878
7979* To block a specific built-in type, add it to `permissions.deny` as shown in [Disable specific subagents](#disable-specific-subagents).
from line 175
175175
176176**CLI-defined subagents** are passed as JSON when launching Claude Code. They exist only for that session and aren't saved to disk, making them useful for quick testing or automation scripts. You can define multiple subagents in a single `--agents` call:
177177
178**macOS, Linux, WSL**
178> [tab] macOS, Linux, WSL
179>
180> ```bash theme={null}
181> claude --agents '{
182> "code-reviewer": {
183> "description": "Expert code reviewer. Use proactively after code changes.",
184> "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
185> "tools": ["Read", "Grep", "Glob", "Bash"],
186> "model": "sonnet"
187> },
188> "debugger": {
189> "description": "Debugging specialist for errors and test failures.",
190> "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
191> }
192> }'
193> ```
179194
180```bash theme={null}
181claude --agents '{
182 "code-reviewer": {
183 "description": "Expert code reviewer. Use proactively after code changes.",
184 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
185 "tools": ["Read", "Grep", "Glob", "Bash"],
186 "model": "sonnet"
187 },
188 "debugger": {
189 "description": "Debugging specialist for errors and test failures.",
190 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
191 }
192}'
193```
194
195**Windows PowerShell**
196
197```powershell theme={null}
198claude --agents @'
199{
200 "code-reviewer": {
201 "description": "Expert code reviewer. Use proactively after code changes.",
202 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
203 "tools": ["Read", "Grep", "Glob", "Bash"],
204 "model": "sonnet"
205 },
206 "debugger": {
207 "description": "Debugging specialist for errors and test failures.",
208 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
209 }
210}
211'@
212```
195> [tab] Windows PowerShell
196>
197> ```powershell theme={null}
198> claude --agents @'
199> {
200> "code-reviewer": {
201> "description": "Expert code reviewer. Use proactively after code changes.",
202> "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
203> "tools": ["Read", "Grep", "Glob", "Bash"],
204> "model": "sonnet"
205> },
206> "debugger": {
207> "description": "Debugging specialist for errors and test failures.",
208> "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
209> }
210> }
211> '@
212> ```
213213
214214In [non-interactive mode](https://code.claude.com/docs/en/headless.md), `--agents` also accepts the path to a JSON file holding the same object, for definitions too large to pass on the command line. For example, `claude -p --agents ./agents.json "Review my changes"` reads the definitions from that file. In an interactive session, Claude Code refuses a file path. The file form requires Claude Code v2.1.281 or later.
215215
terminal-config Changed · +18 / -18 lines
from line 44
4444
4545Some Claude Code shortcuts use the Option key, such as Option+Enter for a newline or Option+P to switch models. On macOS, most terminals do not send Option as a modifier by default, so these shortcuts do nothing until you enable it. The terminal setting for this is usually labeled "Use Option as Meta Key"; Meta is the historical Unix name for the key now labeled Option or Alt.
4646
47**Apple Terminal**
47> [tab] Apple Terminal
48>
49> Open Settings → Profiles → Keyboard and check "Use Option as Meta Key".
50>
51> If you accepted Claude Code's first-run terminal setup prompt, this is already done. That prompt runs `/terminal-setup` for you, which enables Option as Meta and turns off the audible bell in your Apple Terminal profile.
52>
53> In [screen reader mode](https://code.claude.com/docs/en/accessibility.md), `/terminal-setup` leaves the bell setting unchanged so the terminal bell stays audible. If an earlier run turned the bell off, turn it back on under Settings → Profiles → Advanced → "Audible bell".
4854
49Open Settings → Profiles → Keyboard and check "Use Option as Meta Key".
55> [tab] iTerm2
56>
57> Open Settings → Profiles → Keys → General and set Left Option key and Right Option key to "Esc+".
58>
59> Running `/terminal-setup` in iTerm2 enables "Applications in terminal may access clipboard" under Settings → General → Selection so the `/copy` command can write to your system clipboard. The command detects iTerm2 even when run from inside tmux. Restart iTerm2 for the change to take effect.
5060
51If you accepted Claude Code's first-run terminal setup prompt, this is already done. That prompt runs `/terminal-setup` for you, which enables Option as Meta and turns off the audible bell in your Apple Terminal profile.
61> [tab] VS Code
62>
63> Add `"terminal.integrated.macOptionIsMeta": true` to your VS Code settings.
5264
53In [screen reader mode](https://code.claude.com/docs/en/accessibility.md), `/terminal-setup` leaves the bell setting unchanged so the terminal bell stays audible. If an earlier run turned the bell off, turn it back on under Settings → Profiles → Advanced → "Audible bell".
54
55**iTerm2**
56
57Open Settings → Profiles → Keys → General and set Left Option key and Right Option key to "Esc+".
58
59Running `/terminal-setup` in iTerm2 enables "Applications in terminal may access clipboard" under Settings → General → Selection so the `/copy` command can write to your system clipboard. The command detects iTerm2 even when run from inside tmux. Restart iTerm2 for the change to take effect.
60
61**VS Code**
62
63Add `"terminal.integrated.macOptionIsMeta": true` to your VS Code settings.
64
6565For Ghostty, Kitty, and other terminals, look for an Option-as-Alt or Option-as-Meta setting in the terminal's configuration file.
6666
6767## Get a terminal bell or notification
from line 184
184184
185185The reference below covers the tokens you can set in `overrides`. The interactive editor in `/theme` shows the same tokens with a live preview, plus a few single-purpose accents such as onboarding screen colors that are omitted here.
186186
187> **Color token reference**
187> [accordion] Color token reference
188188>
189189> The following example combines tokens from several of the groups below: the brand accent, the plan mode border, the diff backgrounds, and the message background.
190190>
troubleshoot-install Changed · +285 / -285 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 71
7171
7272The installer downloads from `downloads.claude.ai`. Verify you can reach it:
7373
74**macOS/Linux**
75
76```bash theme={null}
77curl -sI https://downloads.claude.ai/claude-code-releases/latest
78```
79
80**Windows PowerShell**
81
82```powershell theme={null}
83curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest
84```
85
86PowerShell aliases `curl` to `Invoke-WebRequest`, which rejects the `-sI` flags, so call `curl.exe` explicitly.
74> [tab] macOS/Linux
75>
76> ```bash theme={null}
77> curl -sI https://downloads.claude.ai/claude-code-releases/latest
78> ```
79
80> [tab] Windows PowerShell
81>
82> ```powershell theme={null}
83> curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest
84> ```
85>
86> PowerShell aliases `curl` to `Invoke-WebRequest`, which rejects the `-sI` flags, so call `curl.exe` explicitly.
8787
8888You reached the server if the first line shows a `200` status. You see `HTTP/2 200` on macOS and Linux, and `HTTP/1.1 200 OK` from the `curl.exe` included with Windows. Other results point to the cause:
8989
from line 100
100100
101101This example sets both proxy variables, then runs the installer through your proxy:
102102
103**macOS/Linux**
104
105```bash theme={null}
106export HTTP_PROXY=http://proxy.example.com:8080
107export HTTPS_PROXY=http://proxy.example.com:8080
108curl -fsSL https://claude.ai/install.sh | bash
109```
110
111**Windows PowerShell**
112
113```powershell theme={null}
114$env:HTTP_PROXY = 'http://proxy.example.com:8080'
115$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
116irm https://claude.ai/install.ps1 | iex
117```
103> [tab] macOS/Linux
104>
105> ```bash theme={null}
106> export HTTP_PROXY=http://proxy.example.com:8080
107> export HTTPS_PROXY=http://proxy.example.com:8080
108> curl -fsSL https://claude.ai/install.sh | bash
109> ```
110
111> [tab] Windows PowerShell
112>
113> ```powershell theme={null}
114> $env:HTTP_PROXY = 'http://proxy.example.com:8080'
115> $env:HTTPS_PROXY = 'http://proxy.example.com:8080'
116> irm https://claude.ai/install.ps1 | iex
117> ```
118118
119119### Verify your PATH
120120
from line 128
128128
129129First check that the program is there at all, then check whether its folder is in your PATH. The PATH fix is permanent, so you apply it once. Pick your platform's tab and run its commands there: in your terminal on macOS and Linux, or in PowerShell or Command Prompt on Windows.
130130
131**macOS/Linux**
132
133Check that the installer put the program in place:
134
135```bash theme={null}
136ls -la ~/.local/bin/claude
137```
138
139* **`No such file or directory`**: there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
140* **A listing for the file**: the program is there. Check your PATH next.
141
142List your PATH entries and filter for the install folder:
143
144```bash theme={null}
145echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
146```
147
148If this prints `/Users/you/.local/bin` or `/home/you/.local/bin`, the directory is in your PATH and you can skip to [Check for conflicting installations](#check-for-conflicting-installations). If there's no output, add it to your shell configuration with the two commands for your shell. The `echo` command saves the setting for every new terminal, and `source` applies it to the window you're in. The `echo` command prints nothing when it succeeds.
149
150For Zsh, the default on macOS:
151
152```bash theme={null}
153echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
154source ~/.zshrc
155```
156
157For Bash on Linux, where it's the default on most distributions:
158
159```bash theme={null}
160echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
161source ~/.bashrc
162```
163
164For Bash on macOS, add the line to `~/.bash_profile` instead. Terminal on macOS starts Bash as a login shell, which ignores `~/.bashrc` and reads only the first of `~/.bash_profile`, `~/.bash_login`, or `~/.profile` that exists. If you already have a `~/.bash_login` or `~/.profile` and no `~/.bash_profile`, put the line in that file rather than creating `~/.bash_profile`:
165
166```bash theme={null}
167echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
168source ~/.bash_profile
169```
170
171Alternatively, close and reopen your terminal.
172
173If the `echo` command prints `permission denied`, see [`permission denied` when adding to your PATH](#permission-denied-when-adding-to-your-path).
174
175For other shells such as fish or Nushell, add `~/.local/bin` to your PATH using your shell's own configuration syntax, then restart your terminal.
176
177Verify the fix worked:
178
179```bash theme={null}
180claude --version
181```
182
183If `claude` is still not found, check these causes:
184
185* **The terminal predates the change**: a window that was already open keeps its old PATH, and a terminal inside an editor takes its PATH from the editor. Open a new window, or quit and reopen the editor.
186* **The line wasn't saved**: run `grep -n '.local/bin' ~/.zshrc`, using your shell's file name. It prints the line with its line number when the line is there. If it prints nothing, run the two PATH commands again.
187* **The line went to another shell's file**: run `echo $0` to see your shell, then run the two PATH commands for that shell.
188
189**Windows PowerShell**
190
191Check that the installer put the program in place:
192
193```powershell theme={null}
194Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
195```
196
197* **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
198* **`True`**: the program is there. Check your PATH next.
199
200List your PATH entries and filter for the install folder:
201
202```powershell theme={null}
203$env:PATH -split ';' | Select-String '\.local\\bin'
204```
205
206If this prints `C:\Users\you\.local\bin`, the directory is in your PATH and you can skip to [Check for conflicting installations](#check-for-conflicting-installations). If there's no output, add the install directory to your User PATH:
207
208```powershell theme={null}
209$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
210[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
211```
212
213Restart your terminal for the change to take effect.
214
215Verify the fix worked:
216
217```powershell theme={null}
218claude --version
219```
220
221If `claude` is still not found in a new terminal, check these causes:
222
223* **The terminal runs inside an editor**: it takes its PATH from the editor, so quit and reopen the editor.
224* **The change wasn't saved**: run `[Environment]::GetEnvironmentVariable('PATH', 'User')` and look for `.local\bin` in the PATH it prints. If it's missing, run the two commands again.
225
226**Windows CMD**
227
228Check that the installer put the program in place:
229
230```batch theme={null}
231dir "%USERPROFILE%\.local\bin\claude.exe"
232```
233
234* **`File Not Found` or `The system cannot find the path specified.`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
235* **A listing for `claude.exe`**: the program is there. Check your PATH next.
236
237List your PATH entries and filter for the install folder:
238
239```batch theme={null}
240echo %PATH% | findstr /i "local\bin"
241```
242
243If there's no output, open System Settings, go to Environment Variables, and add `%USERPROFILE%\.local\bin` to your User PATH variable. Restart your terminal.
244
245Verify the fix worked:
246
247```batch theme={null}
248claude --version
249```
250
251If `claude` is still not found in a new terminal, a terminal inside an editor takes its PATH from the editor, so quit and reopen the editor too.
131> [tab] macOS/Linux
132>
133> Check that the installer put the program in place:
134>
135> ```bash theme={null}
136> ls -la ~/.local/bin/claude
137> ```
138>
139> * **`No such file or directory`**: there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
140> * **A listing for the file**: the program is there. Check your PATH next.
141>
142> List your PATH entries and filter for the install folder:
143>
144> ```bash theme={null}
145> echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
146> ```
147>
148> If this prints `/Users/you/.local/bin` or `/home/you/.local/bin`, the directory is in your PATH and you can skip to [Check for conflicting installations](#check-for-conflicting-installations). If there's no output, add it to your shell configuration with the two commands for your shell. The `echo` command saves the setting for every new terminal, and `source` applies it to the window you're in. The `echo` command prints nothing when it succeeds.
149>
150> For Zsh, the default on macOS:
151>
152> ```bash theme={null}
153> echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
154> source ~/.zshrc
155> ```
156>
157> For Bash on Linux, where it's the default on most distributions:
158>
159> ```bash theme={null}
160> echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
161> source ~/.bashrc
162> ```
163>
164> For Bash on macOS, add the line to `~/.bash_profile` instead. Terminal on macOS starts Bash as a login shell, which ignores `~/.bashrc` and reads only the first of `~/.bash_profile`, `~/.bash_login`, or `~/.profile` that exists. If you already have a `~/.bash_login` or `~/.profile` and no `~/.bash_profile`, put the line in that file rather than creating `~/.bash_profile`:
165>
166> ```bash theme={null}
167> echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
168> source ~/.bash_profile
169> ```
170>
171> Alternatively, close and reopen your terminal.
172>
173> If the `echo` command prints `permission denied`, see [`permission denied` when adding to your PATH](#permission-denied-when-adding-to-your-path).
174>
175> For other shells such as fish or Nushell, add `~/.local/bin` to your PATH using your shell's own configuration syntax, then restart your terminal.
176>
177> Verify the fix worked:
178>
179> ```bash theme={null}
180> claude --version
181> ```
182>
183> If `claude` is still not found, check these causes:
184>
185> * **The terminal predates the change**: a window that was already open keeps its old PATH, and a terminal inside an editor takes its PATH from the editor. Open a new window, or quit and reopen the editor.
186> * **The line wasn't saved**: run `grep -n '.local/bin' ~/.zshrc`, using your shell's file name. It prints the line with its line number when the line is there. If it prints nothing, run the two PATH commands again.
187> * **The line went to another shell's file**: run `echo $0` to see your shell, then run the two PATH commands for that shell.
188
189> [tab] Windows PowerShell
190>
191> Check that the installer put the program in place:
192>
193> ```powershell theme={null}
194> Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
195> ```
196>
197> * **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
198> * **`True`**: the program is there. Check your PATH next.
199>
200> List your PATH entries and filter for the install folder:
201>
202> ```powershell theme={null}
203> $env:PATH -split ';' | Select-String '\.local\\bin'
204> ```
205>
206> If this prints `C:\Users\you\.local\bin`, the directory is in your PATH and you can skip to [Check for conflicting installations](#check-for-conflicting-installations). If there's no output, add the install directory to your User PATH:
207>
208> ```powershell theme={null}
209> $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
210> [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
211> ```
212>
213> Restart your terminal for the change to take effect.
214>
215> Verify the fix worked:
216>
217> ```powershell theme={null}
218> claude --version
219> ```
220>
221> If `claude` is still not found in a new terminal, check these causes:
222>
223> * **The terminal runs inside an editor**: it takes its PATH from the editor, so quit and reopen the editor.
224> * **The change wasn't saved**: run `[Environment]::GetEnvironmentVariable('PATH', 'User')` and look for `.local\bin` in the PATH it prints. If it's missing, run the two commands again.
225
226> [tab] Windows CMD
227>
228> Check that the installer put the program in place:
229>
230> ```batch theme={null}
231> dir "%USERPROFILE%\.local\bin\claude.exe"
232> ```
233>
234> * **`File Not Found` or `The system cannot find the path specified.`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
235> * **A listing for `claude.exe`**: the program is there. Check your PATH next.
236>
237> List your PATH entries and filter for the install folder:
238>
239> ```batch theme={null}
240> echo %PATH% | findstr /i "local\bin"
241> ```
242>
243> If there's no output, open System Settings, go to Environment Variables, and add `%USERPROFILE%\.local\bin` to your User PATH variable. Restart your terminal.
244>
245> Verify the fix worked:
246>
247> ```batch theme={null}
248> claude --version
249> ```
250>
251> If `claude` is still not found in a new terminal, a terminal inside an editor takes its PATH from the editor, so quit and reopen the editor too.
252252
253253### Check for conflicting installations
254254
255255Multiple Claude Code installations can cause version mismatches or unexpected behavior. Check what's installed:
256256
257**macOS/Linux**
258
259List all `claude` binaries found in your PATH:
260
261```bash theme={null}
262which -a claude
263```
264
265If this prints `claude not found`, a `no claude in` line, or nothing, no `claude` is on your PATH. The next checks show whether one is installed at all.
266
267Check the three locations a `claude` binary can come from. `~/.local/bin/claude` is the native installer, `~/.claude/local/` is a legacy local npm install created by older versions of Claude Code, and the npm global list shows a `-g` install:
268
269```bash theme={null}
270ls -la ~/.local/bin/claude
271```
272
273A native install shows a symlink into `~/.local/share/claude/versions/`. A script or a symlink you created yourself at this path is a custom launcher, which [auto-update leaves in place](https://code.claude.com/docs/en/setup.md#auto-updates).
274
275If either `ls` command prints `No such file or directory`, that's not an error. It means nothing is installed at that location, so move on to the next check.
276
277```bash theme={null}
278ls -la ~/.claude/local/
279```
280
281```bash theme={null}
282npm -g ls @anthropic-ai/claude-code 2>/dev/null
283```
284
285If `ls -la ~/.local/bin/claude` printed `No such file or directory`, there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If `~/.local/bin/claude` exists but `which -a claude` didn't list it, the folder isn't in your PATH: see [Verify your PATH](#verify-your-path).
286
287**Windows PowerShell**
288
289List all `claude` binaries found in your PATH:
290
291```powershell theme={null}
292where.exe claude
293```
294
295If this prints `INFO: Could not find files for the given pattern(s).`, no `claude` is on your PATH.
296
297Check whether the native installer placed a binary:
298
299```powershell theme={null}
300Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
301```
302
303* **`True`**: the native install is there. If `where.exe` found nothing, its folder isn't in your PATH: see [Verify your PATH](#verify-your-path).
304* **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code).
257> [tab] macOS/Linux
258>
259> List all `claude` binaries found in your PATH:
260>
261> ```bash theme={null}
262> which -a claude
263> ```
264>
265> If this prints `claude not found`, a `no claude in` line, or nothing, no `claude` is on your PATH. The next checks show whether one is installed at all.
266>
267> Check the three locations a `claude` binary can come from. `~/.local/bin/claude` is the native installer, `~/.claude/local/` is a legacy local npm install created by older versions of Claude Code, and the npm global list shows a `-g` install:
268>
269> ```bash theme={null}
270> ls -la ~/.local/bin/claude
271> ```
272>
273> A native install shows a symlink into `~/.local/share/claude/versions/`. A script or a symlink you created yourself at this path is a custom launcher, which [auto-update leaves in place](https://code.claude.com/docs/en/setup.md#auto-updates).
274>
275> If either `ls` command prints `No such file or directory`, that's not an error. It means nothing is installed at that location, so move on to the next check.
276>
277> ```bash theme={null}
278> ls -la ~/.claude/local/
279> ```
280>
281> ```bash theme={null}
282> npm -g ls @anthropic-ai/claude-code 2>/dev/null
283> ```
284>
285> If `ls -la ~/.local/bin/claude` printed `No such file or directory`, there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code). If `~/.local/bin/claude` exists but `which -a claude` didn't list it, the folder isn't in your PATH: see [Verify your PATH](#verify-your-path).
286
287> [tab] Windows PowerShell
288>
289> List all `claude` binaries found in your PATH:
290>
291> ```powershell theme={null}
292> where.exe claude
293> ```
294>
295> If this prints `INFO: Could not find files for the given pattern(s).`, no `claude` is on your PATH.
296>
297> Check whether the native installer placed a binary:
298>
299> ```powershell theme={null}
300> Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
301> ```
302>
303> * **`True`**: the native install is there. If `where.exe` found nothing, its folder isn't in your PATH: see [Verify your PATH](#verify-your-path).
304> * **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](https://code.claude.com/docs/en/setup.md#install-claude-code).
305305
306306If you find multiple installations, keep only one. The native install at `~/.local/bin/claude` on macOS/Linux or `%USERPROFILE%\.local\bin\claude.exe` on Windows is recommended. Remove the extras:
307307
from line 313
313313
314314Remove the legacy local npm install:
315315
316**macOS/Linux**
317
318```bash theme={null}
319rm -rf ~/.claude/local
320```
321
322**Windows PowerShell**
323
324```powershell theme={null}
325Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"
326```
316> [tab] macOS/Linux
317>
318> ```bash theme={null}
319> rm -rf ~/.claude/local
320> ```
321
322> [tab] Windows PowerShell
323>
324> ```powershell theme={null}
325> Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"
326> ```
327327
328328Remove a Homebrew install on macOS. If you installed the `claude-code@latest` cask, substitute that name:
329329
from line 372
372372
373373Confirm the binary exists and is executable:
374374
375**macOS/Linux**
376
377```bash theme={null}
378ls -la "$(command -v claude)"
379```
380
381**Windows PowerShell**
382
383```powershell theme={null}
384Get-Command claude | Select-Object Source
385```
375> [tab] macOS/Linux
376>
377> ```bash theme={null}
378> ls -la "$(command -v claude)"
379> ```
380
381> [tab] Windows PowerShell
382>
383> ```powershell theme={null}
384> Get-Command claude | Select-Object Source
385> ```
386386
387387On Linux, check for missing shared libraries. If `ldd` shows missing libraries, you may need to install system packages. On Alpine Linux and other musl-based distributions, see [Alpine Linux setup](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions).
388388
from line 564
564564
5655653. **Check for proxy or firewall interference**: corporate proxies that perform TLS inspection can cause these errors, including `unable to get local issuer certificate` and `SELF_SIGNED_CERT_IN_CHAIN`. For the install step, make the install download trust your corporate proxy's CA:
566566
567 **macOS/Linux**
568
569 ```bash theme={null}
570 curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
571 ```
572
573 **Windows PowerShell**
574
575 The PowerShell installer downloads through .NET, which validates TLS against the Windows certificate store. Ask your IT team to add the proxy's CA certificate to the Windows store if it isn't already there, then run the installer:
576
577 ```powershell theme={null}
578 irm https://claude.ai/install.ps1 | iex
579 ```
567 > [tab] macOS/Linux
568 >
569 > ```bash theme={null}
570 > curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
571 > ```
572
573 > [tab] Windows PowerShell
574 >
575 > The PowerShell installer downloads through .NET, which validates TLS against the Windows certificate store. Ask your IT team to add the proxy's CA certificate to the Windows store if it isn't already there, then run the installer:
576 >
577 > ```powershell theme={null}
578 > irm https://claude.ai/install.ps1 | iex
579 > ```
580580
581581 For Claude Code itself once installed, set `NODE_EXTRA_CA_CERTS` so API requests trust the same bundle:
582582
583 **macOS/Linux**
584
585 ```bash theme={null}
586 export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
587 ```
588
589 **Windows PowerShell**
590
591 ```powershell theme={null}
592 $env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'
593 ```
583 > [tab] macOS/Linux
584 >
585 > ```bash theme={null}
586 > export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
587 > ```
588
589 > [tab] Windows PowerShell
590 >
591 > ```powershell theme={null}
592 > $env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'
593 > ```
594594
595595 Ask your IT team for the certificate file if you don't have it. You can also try on a direct connection to confirm the proxy is the cause.
596596
from line 823
823823
824824In every other configuration, rerunning the installer gets past this error, because the script runs the latest release's `install` command even when you ask it to install an older version. Rerun the command for your platform:
825825
826**macOS/Linux**
827
828```bash theme={null}
829curl -fsSL https://claude.ai/install.sh | bash
830```
831
832**Windows PowerShell**
833
834```powershell theme={null}
835irm https://claude.ai/install.ps1 | iex
836```
826> [tab] macOS/Linux
827>
828> ```bash theme={null}
829> curl -fsSL https://claude.ai/install.sh | bash
830> ```
831
832> [tab] Windows PowerShell
833>
834> ```powershell theme={null}
835> irm https://claude.ai/install.ps1 | iex
836> ```
837837
838838`claude --version` prints the version the rerun installed.
839839
from line 1104
11041104
11051105The `npm error path` line names the directory npm couldn't move. Delete that directory and any leftover `.claude-code-*` directories next to it, which earlier interrupted runs can leave behind. The commands below find your global package directory with `npm root -g`; if the directory the `npm error path` line names is not under the directory `npm root -g` prints, for example because you switched Node versions with nvm, delete the directories the error names instead:
11061106
1107**macOS/Linux**
1108
1109```bash theme={null}
1110rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
1111```
1112
1113Then remove any leftover temp directories. If Zsh prints `no matches found`, there were none to remove:
1114
1115```bash theme={null}
1116rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*
1117```
1118
1119**Windows PowerShell**
1120
1121```powershell theme={null}
1122Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"
1123```
1107> [tab] macOS/Linux
1108>
1109> ```bash theme={null}
1110> rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
1111> ```
1112>
1113> Then remove any leftover temp directories. If Zsh prints `no matches found`, there were none to remove:
1114>
1115> ```bash theme={null}
1116> rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*
1117> ```
1118
1119> [tab] Windows PowerShell
1120>
1121> ```powershell theme={null}
1122> Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"
1123> ```
11241124
11251125Then reinstall. On npm 12, follow [Fix an npm 12 install](#fix-an-npm-12-install). Otherwise, run:
11261126
from line 1158
11581158
11591159If you see `API Error: 403 Request not allowed` after logging in:
11601160
1161* **Claude Pro/Max users**: verify your subscription is active at [claude.ai/settings](https://claude.ai/settings)
1161* **Claude Pro/Max/Ultra users**: verify your subscription is active at [claude.ai/settings](https://claude.ai/settings)
11621162* **Anthropic Console users**: confirm your account has the "Claude Code" or "Developer" role. Admins assign this on the Console's Members page at [platform.claude.com/settings/members](https://platform.claude.com/settings/members).
11631163* **Behind a proxy**: corporate proxies can interfere with API requests. See [network configuration](https://code.claude.com/docs/en/network-config.md) for proxy setup.
11641164
from line 1179
11791179
11801180To use your subscription instead, unset the environment variable and remove it from your shell profile:
11811181
1182**macOS/Linux**
1183
1184```bash theme={null}
1185unset ANTHROPIC_API_KEY
1186claude
1187```
1188
1189**Windows PowerShell**
1190
1191```powershell theme={null}
1192Remove-Item Env:ANTHROPIC_API_KEY
1193claude
1194```
1182> [tab] macOS/Linux
1183>
1184> ```bash theme={null}
1185> unset ANTHROPIC_API_KEY
1186> claude
1187> ```
1188
1189> [tab] Windows PowerShell
1190>
1191> ```powershell theme={null}
1192> Remove-Item Env:ANTHROPIC_API_KEY
1193> claude
1194> ```
11951195
11961196Check `~/.zshrc`, `~/.bashrc`, or `~/.profile` for `export ANTHROPIC_API_KEY=...` lines and remove them to make the change permanent. On Windows, check your PowerShell profile at `$PROFILE` and your User environment variables for `ANTHROPIC_API_KEY`. Run `/status` inside Claude Code to confirm which authentication method is active.
11971197
11981198
troubleshooting Changed · +31 / -31 lines
from line 130
130130
131131If the Search tool, `@file` mentions, custom agents, or custom skills aren't finding files, the bundled `ripgrep` binary may not run on your system. Install your platform's `ripgrep` package and tell Claude Code to use it instead:
132132
133**macOS**
133> [tab] macOS
134>
135> ```bash theme={null}
136> brew install ripgrep
137> ```
134138
135```bash theme={null}
136brew install ripgrep
137```
139> [tab] Ubuntu/Debian
140>
141> ```bash theme={null}
142> sudo apt install ripgrep
143> ```
138144
139**Ubuntu/Debian**
145> [tab] Alpine
146>
147> ```bash theme={null}
148> apk add ripgrep
149> ```
150>
151> `ripgrep` is in Alpine's community repository. If `apk` reports that the package is missing, see [Alpine Linux setup](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions).
140152
141```bash theme={null}
142sudo apt install ripgrep
143```
153> [tab] Arch
154>
155> ```bash theme={null}
156> pacman -S ripgrep
157> ```
144158
145**Alpine**
146
147```bash theme={null}
148apk add ripgrep
149```
150
151`ripgrep` is in Alpine's community repository. If `apk` reports that the package is missing, see [Alpine Linux setup](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions).
152
153**Arch**
154
155```bash theme={null}
156pacman -S ripgrep
157```
158
159**Windows**
160
161```powershell theme={null}
162winget install BurntSushi.ripgrep.MSVC
163```
159> [tab] Windows
160>
161> ```powershell theme={null}
162> winget install BurntSushi.ripgrep.MSVC
163> ```
164164
165165Then set `USE_BUILTIN_RIPGREP` to `0`, either in your shell [environment](https://code.claude.com/docs/en/env-vars.md) or in the `env` block of your [`settings.json`](https://code.claude.com/docs/en/settings-reference#all-settings):
166166
ultrareview Changed · +3 / -2 lines
from line 116
116116| - | - | - |
117117| Pro | 3 free runs | billed as [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |
118118| Max | 3 free runs | billed as [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |
119| Ultra | 3 free runs | billed as [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |
119120
120* **Free runs**: the three Pro and Max runs are a one-time allotment per account and don't refresh.
121* **Free runs**: the three Pro, Max, and Ultra runs are a one-time allotment per account and don't refresh.
121122* **Cost per review**: after you use the free runs, typically \$5 to \$25 in usage credits depending on the size of the change, matching the estimate the launch dialog shows before each run.
122123* **When a run counts**: once the cloud session starts. A review you stop early or that fails to complete still uses a free run; a paid review bills only for the portion that ran.
123124
vs-code Changed · +30 / -30 lines
from line 19
1919Before installing, make sure you have:
2020
2121* VS Code 1.94.0 or later
22* An Anthropic account: any paid Claude subscription (Pro, Max, Team, or Enterprise) or a Claude Console account works, and no API key is required. You'll [sign in](https://code.claude.com/docs/en/authentication.md#log-in-to-claude-code) with this account when you first open the extension. If you access Claude through a third-party provider like Amazon Bedrock or Google Cloud's Agent Platform, see [Use third-party providers](#use-third-party-providers) for setup instructions.
22* An Anthropic account: any paid Claude subscription (Pro, Max, Ultra, Team, or Enterprise) or a Claude Console account works, and no API key is required. You'll [sign in](https://code.claude.com/docs/en/authentication.md#log-in-to-claude-code) with this account when you first open the extension. If you access Claude through a third-party provider like Amazon Bedrock or Google Cloud's Agent Platform, see [Use third-party providers](#use-third-party-providers) for setup instructions.
2323
2424> [!TIP]
2525>
from line 113
113113
114114The prompt box supports several features:
115115
116* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch permission modes. With Claude Code v2.1.283 or later, Auto is the built-in starting permission mode, and on earlier versions only on Pro, Max, and Team plans. See [how the extension chooses the starting permission mode](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes) for what changes that, and every permission mode the indicator offers.
116* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch permission modes. With Claude Code v2.1.283 or later, Auto is the built-in starting permission mode, and on earlier versions only on Pro, Max, Ultra, and Team plans. See [how the extension chooses the starting permission mode](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes) for what changes that, and every permission mode the indicator offers.
117117 * **Auto**: a classifier reviews most actions instead of asking you. See [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) for what it reviews and blocks.
118118 * **Manual**: Claude asks permission before file edits and most shell commands.
119119 * **Plan**: Claude describes what it will do and waits for approval before making changes. VS Code automatically opens the plan as a full Markdown document where you can add inline comments to give feedback before Claude begins.
from line 652
652652
653653Invoke the handler with your operating system's URL opener.
654654
655**macOS**
655> [tab] macOS
656>
657> ```bash theme={null}
658> open "vscode://anthropic.claude-code/open"
659> ```
656660
657```bash theme={null}
658open "vscode://anthropic.claude-code/open"
659```
661> [tab] Linux
662>
663> ```bash theme={null}
664> xdg-open "vscode://anthropic.claude-code/open"
665> ```
666>
667> The `xdg-open` command comes from the `xdg-utils` package. If the shell reports it isn't found, see [xdg-open is not found on Linux](https://code.claude.com/docs/en/deep-links.md#xdg-open-is-not-found-on-linux).
660668
661**Linux**
669> [tab] Windows
670>
671> In PowerShell:
672>
673> ```powershell theme={null}
674> Start-Process "vscode://anthropic.claude-code/open"
675> ```
676>
677> In `cmd.exe`, `start` treats its first quoted argument as a window title, so pass an empty title before the URL:
678>
679> ```cmd theme={null}
680> start "" "vscode://anthropic.claude-code/open"
681> ```
662682
663```bash theme={null}
664xdg-open "vscode://anthropic.claude-code/open"
665```
666
667The `xdg-open` command comes from the `xdg-utils` package. If the shell reports it isn't found, see [xdg-open is not found on Linux](https://code.claude.com/docs/en/deep-links.md#xdg-open-is-not-found-on-linux).
668
669**Windows**
670
671In PowerShell:
672
673```powershell theme={null}
674Start-Process "vscode://anthropic.claude-code/open"
675```
676
677In `cmd.exe`, `start` treats its first quoted argument as a window title, so pass an empty title before the URL:
678
679```cmd theme={null}
680start "" "vscode://anthropic.claude-code/open"
681```
682
683683The handler accepts two optional query parameters:
684684
685685| Parameter | Description |
from line 700
700700You configure the extension in two places, VS Code's extension settings and the Claude Code settings file:
701701
702702* **Extension settings** in VS Code: control the extension's behavior within VS Code. Open with `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux), then go to **Extensions > Claude Code**. You can also type `/` and select **General config…** to open settings.
703* **Claude Code settings** in `~/.claude/settings.json`: shared between the extension and CLI. Use it for allowed commands, environment variables, hooks, and MCP servers. With Claude Code v2.1.283 or later, it's also one input to the permission mode conversations start in, and on earlier versions only on Pro, Max, and Team plans. [Switch permission modes](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes) lists the order. See [Settings](https://code.claude.com/docs/en/settings.md) for details.
703* **Claude Code settings** in `~/.claude/settings.json`: shared between the extension and CLI. Use it for allowed commands, environment variables, hooks, and MCP servers. With Claude Code v2.1.283 or later, you can also use it as one input to the permission mode conversations start in. On earlier versions, you can do this only on Pro, Max, Ultra, and Team plans. [Switch permission modes](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes) lists the order. See [Settings](https://code.claude.com/docs/en/settings.md) for details.
704704
705705> [!TIP]
706706>
agent-sdk/agent-loop Changed · +2 / -2 lines
from line 73
7373* **Python:** check message types with `isinstance()` against classes imported from `claude_agent_sdk` (for example, `isinstance(message, ResultMessage)`).
7474* **TypeScript:** check the `type` string field (for example, `message.type === "result"`). `AssistantMessage` and `UserMessage` wrap the raw API message in a `.message` field, so content blocks are at `message.message.content`, not `message.content`.
7575
76> **Example: Check message types and handle results**
76> [accordion] Example: Check message types and handle results
7777>
7878> ```python Python theme={null}
7979> import asyncio
from line 269
269269* **`PreCompact` hook:** Run custom logic before compaction occurs, for example to archive the full transcript. The hook receives a `trigger` field (`manual` or `auto`). See [hooks](https://code.claude.com/docs/en/agent-sdk/hooks.md).
270270* **Manual compaction:** Send `/compact` as a prompt string to trigger compaction on demand. Commands sent this way are ordinary SDK inputs. See [dispatch commands by name](https://code.claude.com/docs/en/agent-sdk/skills.md#dispatch-commands-by-name).
271271
272> **Example: Summarization instructions in CLAUDE.md**
272> [accordion] Example: Summarization instructions in CLAUDE.md
273273>
274274> Add a section to your project's CLAUDE.md telling the compactor what to preserve. The header name isn't special; use any clear label.
275275>
agent-sdk/structured-outputs Changed · +2 / -2 lines
from line 12
1212
1313Consider a recipe app where an agent searches the web and brings back recipes. Without structured outputs, you get free-form text that you'd need to parse yourself. With structured outputs, you define the shape you want and get typed data you can use directly in your app.
1414
15> **Without structured outputs**
15> [accordion] Without structured outputs
1616>
1717> ```text theme={null}
1818> Here's a classic chocolate chip cookie recipe!
from line 28
2828>
2929> To use this in your app, you'd need to parse out the title, convert "15 minutes" to a number, separate ingredients from instructions, and handle inconsistent formatting across responses.
3030
31> **With structured outputs**
31> [accordion] With structured outputs
3232>
3333> ```jsonc theme={null}
3434> {
agents Changed · +1 / -1 lines
from line 9
99| [Subagents](https://code.claude.com/docs/en/sub-agents.md) | Delegated workers inside one session that do a side task in their own context and return a summary | A side task would flood your main conversation with search results, logs, or file contents you won't reference again |
1010| [Agent view](https://code.claude.com/docs/en/agent-view.md) | One screen to dispatch and monitor sessions running in the background, opened with `claude agents`. Research preview | You have several independent tasks and want to hand them off, check status at a glance, and step in only when one needs you |
1111| [Agent teams](https://code.claude.com/docs/en/agent-teams.md) | Multiple coordinated sessions with a shared task list and inter-agent messaging, managed by a lead. Experimental and disabled by default | You want Claude to split a project into pieces, assign them, and keep the workers in sync |
12| [Projects](https://code.claude.com/docs/en/claude-projects.md) | One ongoing conversation at claude.ai/code or in the desktop app. Claude starts parallel sessions called threads, in the cloud or, when you ask, on your computer through Remote Control, gives each one the project's instructions, and shows you which ones need you. Public beta on Pro and Max | The work spans many tasks over days or weeks, should keep running when your machine is off, and you'd rather describe it once than dispatch and track each session |
12| [Projects](https://code.claude.com/docs/en/claude-projects.md) | One ongoing conversation at claude.ai/code or in the desktop app. Claude starts parallel sessions called threads, in the cloud or, when you ask, on your computer through Remote Control. It gives each one the project's instructions and shows you which ones need you. Public beta on Pro, Max, and Ultra | The work spans many tasks over days or weeks, should keep running when your machine is off, and you'd rather describe it once than dispatch and track each session |
1313| [Dynamic workflows](https://code.claude.com/docs/en/workflows.md) | A script that runs many subagents and cross-checks their results, for work too big to coordinate one turn at a time or that needs more than a single pass | A job outgrows a handful of subagents, or you want findings verified against each other: a codebase-wide audit, a 500-file migration, cross-checked research, or a plan drafted from several angles |
1414
1515In every approach the workers are Claude sessions. To involve a different tool, expose it to Claude as an [MCP server](https://code.claude.com/docs/en/mcp.md).
auto-mode-classifier-billing Changed · +1 / -1 lines
from line 39
3939
4040## Why the notice appears
4141
42[Server-side classifier review](https://code.claude.com/docs/en/permission-modes.md#server-side-classifier-review) lists which sessions ask the server for the classifier checks. Pro, Max, and Team plans never show the notice. When it appears, the usual causes are:
42On a Pro, Max, Ultra, or Team plan, you never see the notice. To find out which sessions ask the server for the classifier checks, see [Server-side classifier review](https://code.claude.com/docs/en/permission-modes.md#server-side-classifier-review). If you see the notice, check for these usual causes:
4343
4444* **An LLM gateway or proxy is in the path**: one that strips or rewrites request headers, drops request fields it doesn't recognize, or edits responses. The server then never receives the request for checks, or Claude Code never receives the results. When your configuration or the responses identify the gateway, the notice names it.
4545* **Server-side checks haven't reached your platform, region, or credential yet**: whether a platform or region performs them depends on that platform's rollout. If you see the notice with no gateway or proxy in the path and it keeps appearing, this is the likely cause. To confirm, contact support or your company's admin, or report it with `/feedback`.
auto-mode-config Changed · +1 / -1 lines
from line 157
157157
158158> [!NOTE]
159159>
160> `/auto-mode-setup` is available on Pro, Max, Team, and Enterprise plans and with a Claude Console API key. On a Pro, Max, or Team plan, you need v2.1.228 or later, or v2.1.233 or later on native Windows. On an Enterprise plan or with a Claude Console API key, you need v2.1.283 or later. If the command is missing from your session, see [`/auto-mode-setup` returns "Unknown command"](#auto-mode-setup-returns-unknown-command).
160> `/auto-mode-setup` is available on Pro, Max, Ultra, Team, and Enterprise plans and with a Claude Console API key. On a Pro, Max, Ultra, or Team plan, you need v2.1.228 or later, or v2.1.233 or later on native Windows. On an Enterprise plan or with a Claude Console API key, you need v2.1.283 or later. If the command is missing from your session, see [`/auto-mode-setup` returns "Unknown command"](#auto-mode-setup-returns-unknown-command).
161161
162162### What `/auto-mode-setup` reads
163163
best-practices Changed · +1 / -1 lines
from line 485
485485
486486With a 1M-token window on most current models and compaction near the top of it, you'll rarely run out of context. You can still *pay* for context you don't need, though. Every request sends the whole conversation, so a session that's collected three unrelated tasks re-reads all three on every turn of the fourth. That's [discounted while the cache is warm](https://code.claude.com/docs/en/costs.md#why-usage-climbs-in-a-long-session) and full price once it expires.
487487
488[`/usage`](https://code.claude.com/docs/en/costs) is the first place to look. On Pro, Max, Team, and Enterprise it breaks your usage down by skill, subagent, plugin, and MCP server. It also flags patterns like long context or frequent cache misses once one of them passes 10% of your usage. From there, the usual fixes:
488[`/usage`](https://code.claude.com/docs/en/costs) is the first place to look. On Pro, Max, Ultra, Team, and Enterprise it breaks your usage down by skill, subagent, plugin, and MCP server. It also flags patterns like long context or frequent cache misses once one of them passes 10% of your usage. From there, the usual fixes:
489489
490490* `/clear` between unrelated tasks. It costs nothing, and it means the next task doesn't keep paying for the previous one's history. `/clear oauth-migration` names the session you're leaving, so you can come back to it later.
491491* `/compact` with a focus, like `/compact keep the API changes and the test commands`. On a long session `/compact` is itself a big request, since it reads the whole conversation to summarize it, and even more so once the cache has expired.
chrome Changed · +1 / -1 lines
from line 35
3535* [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge](https://www.microsoft.com/edge), or another Chromium-based browser such as Brave, Arc, Vivaldi, or Opera
3636* [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or later, available in the Chrome Web Store
3737* [Claude Code](https://code.claude.com/docs/en/quickstart.md#step-1-install-claude-code)
38* A direct Anthropic plan (Pro, Max, Team, or Enterprise)
38* A direct Anthropic plan (Pro, Max, Ultra, Team, or Enterprise)
3939
4040In Enterprise organizations that have HIPAA enabled, Claude in Chrome is off by default, and an [Owner](https://code.claude.com/docs/en/server-managed-settings.md#access-control) can turn it on in [**Organization settings > Claude in Chrome**](https://claude.ai/admin-settings/browser-extension). Your Business Associate Agreement (BAA) with Anthropic doesn't cover data sent to third-party sites through Claude in Chrome. See the [Implementation Guide](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide) for a list of Eligible Services.
4141
computer-use Changed · +2 / -2 lines
from line 4
44
55> [!NOTE]
66>
7> Computer use is a research preview on macOS that requires a Pro or Max plan. It is not available on Team or Enterprise plans. It requires an interactive session, so it is not available in non-interactive mode with the `-p` flag.
7> Computer use is a research preview on macOS that requires a Pro, Max, or Ultra plan. It is not available on Team or Enterprise plans. It requires an interactive session, so it is not available in non-interactive mode with the `-p` flag.
88
99Computer use lets Claude open apps, control your screen, and work on your machine the way you would. From the CLI, Claude can compile a Swift app, launch it, click through every button, and screenshot the result, all in the same conversation where it wrote the code.
1010
from line 194
194194The server only appears on eligible setups. Check that:
195195
196196* You're on macOS. Computer use in the CLI is not available on Linux or Windows. On Windows, use [computer use in Desktop](https://code.claude.com/docs/en/desktop.md#let-claude-use-your-computer) instead.
197* You're on a Pro or Max plan. Run `/status` to confirm your subscription.
197* You're on a Pro, Max, or Ultra plan. Run `/status` to confirm your subscription.
198198* You're authenticated through claude.ai. Computer use is not available with third-party providers like Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. If you access Claude exclusively through a third-party provider, you need a separate claude.ai account to use this feature.
199199* You're in an interactive session. Computer use is not available in non-interactive mode with the `-p` flag.
200200
desktop-ios-simulator Changed · +1 / -1 lines
from line 4
44
55> [!NOTE]
66>
7> The iOS Simulator pane is in public beta in Claude Code Desktop on macOS. It's available on Pro, Max, Team, and Enterprise plans, except in Enterprise organizations that have a HIPAA configuration enabled.
7> The iOS Simulator pane is in public beta in Claude Code Desktop on macOS. It's available on Pro, Max, Ultra, Team, and Enterprise plans, except in Enterprise organizations that have a HIPAA configuration enabled.
88
99The iOS Simulator pane shows your app running in Apple's iOS Simulator next to your conversation in Claude Code Desktop. When Claude builds, installs, launches, or checks your app in a simulator, the pane opens automatically and streams the device screen live. Use it to watch Claude run and test your app, or to tap through the app yourself while Claude keeps working.
1010