One read of Claude Code CLIclaude-code-20261009T210702Z
17 pages moved out of 221 read.
Pages moved
17
significant first
Pages read
221
in this capture
Captured
21:07 UTC
Corpus hash
ca39e126a7cc
corpus-hash
What this read moved
1-17 of 17agent-sdk/mcp Changed · +7 / -3 lines
### Add a server in code ### Add a server from a config file ### In code ### From a config file
from line 70
7070
7171You can configure MCP servers in code when calling `query()`, or in a `.mcp.json` file loaded via [`settingSources`](#from-a-config-file).
7272
73### In code
73<span id="in-code" />
7474
75### Add a server in code
76
7577Pass MCP servers directly in the `mcpServers` option. This example starts a local filesystem MCP server for `/Users/me/projects`. Replace that path with a directory on your machine:
7678
7779<CodeGroup>
from line 127
125127 ```
126128</CodeGroup>
127129
128### From a config file
130<span id="from-a-config-file" />
129131
132### Add a server from a config file
133
130134Create a `.mcp.json` file at your project root. The file is picked up when the `project` setting source is enabled, which it is for default `query()` options. If you set `settingSources` explicitly, include `"project"` for this file to load. Replace `/Users/me/projects` with a directory on your machine:
131135
132136```json theme={null}
from line 279
275279
276280### stdio servers
277281
278Local processes that communicate via stdin/stdout. Use this for MCP servers you run on the same machine. For the `.mcp.json` form, use the same fields shown at [From a config file](#from-a-config-file). In code, pass the command and its arguments. Replace `/Users/me/projects` with a directory on your machine:
282Local processes that communicate via stdin/stdout. Use this for MCP servers you run on the same machine. For the `.mcp.json` form, use the same fields shown at [Add a server from a config file](#from-a-config-file). In code, pass the command and its arguments. Replace `/Users/me/projects` with a directory on your machine:
279283
280284<CodeGroup>
281285 ```typescript TypeScript hidelines={1,-1} theme={null}
agent-sdk/migration-guide Changed · +6 / -2 lines
### Migrate a TypeScript or JavaScript project ### Migrate a Python project ### For TypeScript/JavaScript Projects ### For Python Projects
from line 18
1818
1919## Migration Steps
2020
21### For TypeScript/JavaScript Projects
21<span id="for-typescript/javascript-projects" />
2222
23### Migrate a TypeScript or JavaScript project
24
2325**1. Uninstall the old package:**
2426
2527```bash theme={null}
from line 54
5254
5355Make any code changes needed to complete the migration.
5456
55### For Python Projects
57<span id="for-python-projects" />
58
59### Migrate a Python project
5660
5761**1. Uninstall the old package:**
5862
agent-view Changed · +9 / -3 lines
### Dispatch an agent from agent view ### Send or copy a session to the background ### Dispatch an agent from your shell ### From agent view ### From inside a session ### From your shell
from line 361
361361
362362You can dispatch new background sessions from agent view, send or copy an existing interactive session to the background, or start one directly from the shell.
363363
364### From agent view
364<span id="from-agent-view" />
365365
366### Dispatch an agent from agent view
367
366368Type a prompt in the input at the bottom of agent view and press `Enter` to start a new background session. The session is named automatically from the prompt; rename it later with `Ctrl+R`.
367369
368370The automatic name is a short label written by a [Haiku-class model](/docs/en/model-config). A name the session gets later also appears on its row, including the [generated title](/docs/en/sessions#name-your-sessions) the session gets when you [accept a plan](/docs/en/permission-modes#review-and-approve-a-plan) in that session.
from line 414
412414
413415When agent view is grouped by directory, dispatching sends the prompt to the selected row's directory, so you can select a group and dispatch into it without retyping the path.
414416
415### From inside a session
417<span id="from-inside-a-session" />
416418
419### Send or copy a session to the background
420
417421Two commands move work from the session you're in to the background: `/background` sends the current conversation there and frees your terminal, and `/fork` sends a copy while you keep working where you are.
418422
419423#### Send the session to the background
from line 473
469473
470474Directories you added during the session with [`/add-dir`](/docs/en/permissions#additional-directories-grant-file-access-not-configuration) also carry through. Carrying `--allow-dangerously-skip-permissions` keeps `bypassPermissions` reachable in the backgrounded session, but it doesn't grant anything new: the mode still requires the one-time interactive acceptance described in [Permission mode, model, and effort](#permission-mode-model-and-effort).
471475
472### From your shell
476<span id="from-your-shell" />
477
478### Dispatch an agent from your shell
473479
474480Pass `--bg` or its long form `--background` to start a session that goes straight to the background:
475481
chrome Changed · +35 / -2 lines
### Project settings can't turn on Chrome ### Extension signed in to a different organization
from line 172
172172and attach logs/session.log to it
173173```
174174
175Three restrictions apply to uploads:
175If Claude refuses to attach a file or an upload fails, check for these causes:
176176
177177* **Permissions**: Claude can upload a file only when the session is allowed to read it, so [permission rules](/docs/en/settings-reference#permission-settings) that deny `Read` access to a file also block uploading it.
178178* **Size**: a single upload can include up to 10 MB of files in total.
179179* **Hard links**: Claude refuses files that have multiple hard links, which is common inside package-manager stores like `node_modules`. Copy the file and upload the copy.
180* **Credential names**: Claude refuses a file whose name or folder is one that credentials are kept under, such as `.env`, a `.pem` or `.key` file, or anything under `.ssh`. Requires Claude Code v2.1.293 or later.
180181
181182### Draft content in Google Docs
182183
from line 266
265266
266267Other Chromium-based browsers read the same file from their own configuration directory, named after the browser. For example, Brave on macOS uses `~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts/`, and on Windows each browser has its own registry key, such as `HKCU\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\`.
267268
269### Project settings can't turn on Chrome
270
271This warning in your terminal means the project you're working in tried to turn on Chrome integration, and Claude Code didn't allow it:
272
273```text wrap theme={null}
274Claude Code ignored CLAUDE_CODE_ENABLE_CFC in this project's settings: a project can't turn on Claude in Chrome. To turn it on yourself, run /chrome or start with --chrome.
275```
276
277The project's `.claude/settings.json` or `.claude/settings.local.json` sets [`CLAUDE_CODE_ENABLE_CFC`](/docs/en/env-vars#variables) to `1` in its `env` block to turn Chrome integration on. Claude Code didn't apply that setting, so Chrome integration is off in this session and Claude has no browser tools.
278
279Claude Code skips the setting because those files are stored in the project directory, and a repository you check out must not be able to connect Claude to your browser.
280
281You can keep working as you are. If you want browser tools, or want the warning gone, do one of these:
282
283* **To get browser tools now**: exit and start again with `claude --chrome` in your shell.
284* **To get browser tools in later sessions**: run `/chrome` at the Claude Code prompt and select [**Enabled by default**](#enable-chrome-by-default). This applies to sessions you start afterward, not the one that's running.
285* **To stop the warning without browser tools**: remove the `CLAUDE_CODE_ENABLE_CFC` line from the project's settings file.
286
268287### Browser not responding
269288
270289If Claude's browser commands stop working:
from line 296
277296
278297The Chrome extension's service worker can go idle during extended sessions, which breaks the connection. If browser tools stop working after a period of inactivity, run `/chrome` and select "Reconnect extension".
279298
299When you run `/chrome`, check its `Status` line. If it reads "Not connected", the running session's own connection to Chrome has failed. Select "Reconnect extension" to restart that connection. After the connection succeeds, the extension's reconnect page opens in Chrome. Before v2.1.290, "Reconnect extension" only opened that page and didn't restart a failed connection, so if browser tools don't return on an earlier version, update Claude Code.
300
301### Extension signed in to a different organization
302
303If you belong to more than one claude.ai organization, the extension must be signed in to the same organization as Claude Code. If the two differ, Claude's browser tools return "Browser extension is not connected", even when both use the same claude.ai account.
304
305To see which organization Claude Code is signed in to, run [`/status`](/docs/en/commands) at the Claude Code prompt and read the `Organization` row.
306
307<Warning>
308 If you log out of the extension, you lose the shortcuts and scheduled tasks saved in it. Try the other fixes under [Common error messages](#common-error-messages) first.
309</Warning>
310
311To change the extension's organization, log out in the extension's settings, then log in and select the organization that `/status` shows.
312
280313### Windows-specific issues
281314
282315On Windows, you may encounter:
from line 324
291324
292325| Error | Cause | Fix |
293326| - | - | - |
294| "Browser extension is not connected" | Native messaging host cannot reach the extension, or your organization's IP allowlist rejects the connection to `bridge.claudeusercontent.com` | Check that the extension is signed in to the same claude.ai account as Claude Code, restart Chrome and Claude Code, then run `/chrome` to reconnect. If your organization uses IP allowlisting and the error persists, see [Organization IP allowlists and proxy egress](/docs/en/network-config#organization-ip-allowlists-and-proxy-egress) |
327| "Browser extension is not connected" | The extension isn't installed and running in Chrome, the extension is signed in to a different claude.ai account or organization than Claude Code, or your organization's IP allowlist rejects the connection to `bridge.claudeusercontent.com` | Check that the extension is signed in to the same claude.ai account and [organization](#extension-signed-in-to-a-different-organization) as Claude Code, restart Chrome and Claude Code, then run `/chrome` to reconnect. If your organization uses IP allowlisting and the error persists, see [Organization IP allowlists and proxy egress](/docs/en/network-config#organization-ip-allowlists-and-proxy-egress) |
295328| Extension shows "Not detected" in `/chrome` | Chrome extension is not installed or is disabled | Install or enable the extension in `chrome://extensions` |
296329| "No tab available" | Claude tried to act before a tab was ready | Ask Claude to create a new tab and retry |
297330| "Receiving end does not exist" | Extension service worker went idle | Run `/chrome` and select "Reconnect extension" |
claude-code-on-the-web Changed · +6 / -2 lines
### Start a cloud session from your terminal ### Continue a cloud session in your terminal ### From terminal to cloud ### From cloud to terminal
from line 79
7979 From the CLI, session handoff is one-way: you can pull cloud sessions into your terminal with `--teleport`, but you can't push an existing terminal session to the cloud. The `--cloud` flag with a task description creates a new cloud session for your current repository; with `-p` and a session ID or claude.ai/code URL it instead [queues a message into that existing session](/docs/en/claude-code-on-the-web#send-follow-ups-from-the-cli). The [Desktop app](/docs/en/desktop#continue-in-another-surface) can send a local session in its Code tab to the cloud from its **Open in** menu.
8080</Note>
8181
82### From terminal to cloud
82<span id="from-terminal-to-cloud" />
8383
84### Start a cloud session from your terminal
85
8486Start a cloud session from the command line with the `--cloud` flag:
8587
8688```bash theme={null}
from line 195
193195
194196If the send fails, see [Errors when sending to a cloud session](#errors-when-sending-to-a-cloud-session).
195197
196### From cloud to terminal
198<span id="from-cloud-to-terminal" />
199
200### Continue a cloud session in your terminal
197201
198202Pull a cloud session into your terminal using any of these:
199203
errors Changed · +3 / -44 lines
## Installation errors ### Installation was killed before it could finish ### The connection dropped while downloading the update
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 183
183183| `<model> has safety measures that flagged this message for a cybersecurity topic` | [Request errors](#safety-measures-flagged-a-cybersecurity-topic) |
184184| `` Details: `[reasoning_extraction]` `` | [Request errors](#safeguards-flagged-a-request-for-claudes-reasoning) |
185185| `API Error: Output blocked by content filtering policy` | [Request errors](#output-blocked-by-content-filtering-policy) |
186| `Installation was killed before it could finish (exit code 137)` | [Installation errors](#installation-was-killed-before-it-could-finish) |
187| `The connection dropped while downloading the update` | [Installation errors](#the-connection-dropped-while-downloading-the-update) |
188| `Download timed out: exceeded the total deadline` | [Installation errors](#the-connection-dropped-while-downloading-the-update) |
186| `Installation was killed before it could finish (exit code 137)` | [Troubleshoot installation and login](/docs/en/troubleshoot-install#installation-was-killed-before-it-could-finish) |
187| `The connection dropped while downloading the update` | [Troubleshoot installation and login](/docs/en/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |
188| `Download timed out: exceeded the total deadline` | [Troubleshoot installation and login](/docs/en/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |
189189| `--bg and --print conflict` | [Command-line errors](#conflict-between-bg-and-print) |
190190| `Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.` | [Command-line errors](#conflict-between-a-system-prompt-flag-and-its-file-form) |
191191| `Cloud sessions cannot be created from a --restricted session` | [Command-line errors](#cloud-sessions-cannot-be-created-from-a-restricted-session) |
from line 2739
27392739* Rephrase your last message or take a different approach
27402740* To step back to a checkpoint before the turn that triggered the block, press Esc twice or run `/rewind`. See [Checkpointing](/docs/en/checkpointing)
27412741
2742## Installation errors
2742## Command-line errors
27432743
2744These errors appear while installing or updating Claude Code, from the [install script](/docs/en/setup#install-claude-code), `claude install`, or `claude update`. For `command not found`, PATH, permission, and TLS problems during setup, see [Troubleshoot installation and login](/docs/en/troubleshoot-install).
2744These errors come from the `claude` command line and its subcommands, from a command name you submit at the prompt, and from commands such as `/security-review` that gather context by running shell commands before their prompt runs. They also come from `/tui`, which relaunches the CLI.
27452745
2746### Installation was killed before it could finish
2746<h3 id="conflict-between-bg-and-print">
2747 Conflict between `--bg` and `--print`
2748</h3>
27472749
2748The install script reports when the `claude install` step is terminated by a signal. On Linux, exit code 137 means the process received SIGKILL, and on a low-memory host that's usually the kernel out-of-memory (OOM) killer. The script prints this explanation and exits with code 137:
2750This message requires Claude Code v2.1.198 or later. You combined `--bg` with `-p` or `--print` in the same `claude` invocation. `--bg` starts a [background session](/docs/en/agent-view#from-your-shell) that you later attach to with `claude agents`, while `--print` runs [non-interactively](/docs/en/headless) and never starts the interactive session that `claude agents` attaches to. Before v2.1.198 this combination silently created a background job that could never be attached to.
27492751
27502752```text theme={null}
2751Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
2752Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.
2753--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.
27532754```
27542755
2755For any other fatal signal, and for exit code 137 on macOS, the script prints `Installation was killed before it could finish (exit code <N>)` with the actual exit code and omits the out-of-memory explanation. The message comes from the install script macOS and Linux use, which also covers installs inside WSL; the native Windows install scripts never print it. Before v2.1.200, the script exited with only the shell's bare `Killed` line.
2756
27572756**What to do:**
27582757
2759* Stop other processes to free memory, then rerun the installer
2760* Add swap space or move to a larger instance. See [Install killed on low-memory Linux servers](/docs/en/troubleshoot-install#install-killed-on-low-memory-linux-servers) for the swap-file commands.
2758* Drop `-p` or `--print`. `--bg` takes the prompt as its positional argument, so `claude --bg "<task>"` is the complete command. See [Dispatch new agents from your shell](/docs/en/agent-view#from-your-shell).
2759* To run the prompt non-interactively and print the result instead of creating a background session, drop `--bg` and run `claude -p "<task>"`
27612760
2762### The connection dropped while downloading the update
2761<h3 id="conflict-between-a-system-prompt-flag-and-its-file-form">
2762 Conflict between a system prompt flag and its file form
2763</h3>
27632764
2764The connection to the download server closed while `claude install` or `claude update` was fetching the Claude Code binary, and the retries didn't recover. Claude Code retries the download when the connection drops, the transfer stalls, or the downloaded file fails its checksum, up to three attempts in total. A completed HTTP error, such as a 404, isn't retried because the server already answered. Before v2.1.202, a single dropped connection failed the download immediately with the bare error `aborted` instead of retrying.
2765You passed [`--append-subagent-system-prompt`](/docs/en/cli-reference#cli-flags) together with `--append-subagent-system-prompt-file` in one `claude` invocation, so `claude` exits with code 1 instead of starting the session:
27652766
27662767```text theme={null}
2767The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.
2768Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.
27682769```
27692770
2770The text in parentheses names which attempt failed and the underlying network error. `claude update` precedes the message with `Error: Failed to install native update` on stderr.
2771Before v2.1.283, `claude` exited the same way when you passed `--system-prompt` with `--system-prompt-file`, or `--append-system-prompt` with `--append-system-prompt-file`, because those pairs conflicted instead of [combining](/docs/en/cli-reference#system-prompt-flags). On those versions the message names the pair you combined.
27712772
2772A download that stays connected but doesn't finish within 10 minutes fails with `Download timed out: exceeded the total deadline` instead. Claude Code doesn't retry a timed-out download, because a connection too slow to finish inside the deadline won't finish on an immediate retry either. The steps below apply to both messages.
2773**What to do:**
27732774
2774A proxy or gateway can close a long transfer before it finishes, and the Claude Code binary is a large download.
2775* Keep one form of the flag and drop the other. To combine a fixed prompt file with per-run text, merge the text into the file before launching instead of passing both flags
27752776
2776**What to do:**
2777<h3 id="invalid-agents-configuration">
2778 Invalid `--agents` configuration
2779</h3>
27772780
2778* Run `claude update` again. On an otherwise healthy network, the download usually succeeds on the next run. For the timed-out message, run it again from a faster or less throttled network.
2779* If your network requires a proxy, set `HTTPS_PROXY` before running the installer or `claude update`. See [Check network connectivity](/docs/en/troubleshoot-install#check-network-connectivity).
2780* If a corporate proxy keeps closing the transfer, ask your network team to allow the full download from `downloads.claude.ai`. See [Network access requirements](/docs/en/network-config#network-access-requirements).
2781* Run `claude doctor` from your shell for installation diagnostics
2781The value you passed to `--agents` is invalid, so `claude` exits with code 1 instead of starting the session. When you pass `--safe-mode` or set [`CLAUDE_CODE_SAFE_MODE`](/docs/en/env-vars#variables), Claude Code ignores `--agents` entirely. With `--resume` or `--continue`, an inline JSON value isn't checked and the session starts; a value read from a file is checked on every launch. Before v2.1.242, Claude Code started the session anyway.
27822782
2783## Command-line errors
2783```text theme={null}
2784Error: Invalid --agents configuration:
2785<what failed>
2786```
27842787
2785These errors come from the `claude` command line and its subcommands, from a command name you submit at the prompt, and from commands such as `/security-review`
2788What follows the first line depends on how the value failed. Claude Code runs these checks in order and stops at the first one that fails. If your value has two kinds of problem, you see the second only after you fix the first:
2789
27901. When the value begins with `{` but doesn't parse as JSON, or the contents of an `--agents` file don't parse, Claude Code prints one `invalid JSON:` line carrying the JSON parser's own message
27912. When it parses but an agent definition doesn't match the schema for [CLI-defined subagents](/docs/en/sub-agents#choose-the-subagent-scope), Claude Code prints one line per problem
27923. When an agent name st
jetbrains Changed · +6 / -2 lines
### Run Claude Code from your IDE ### Connect from an external terminal ### From your IDE ### From external terminals
from line 43
4343
4444## Usage
4545
46### From your IDE
46<span id="from-your-ide" />
4747
48### Run Claude Code from your IDE
49
4850Run `claude` from your IDE's integrated terminal, and all integration features will be active.
4951
50### From external terminals
52<span id="from-external-terminals" />
53
54### Connect from an external terminal
5155
5256Use the `/ide` command in any external terminal to connect Claude Code to your JetBrains IDE and activate all features:
5357
mcp Changed · +12 / -4 lines
#### Add a server from a URL #### Add a server from an `npx`, `uvx`, or binary command #### Add a server from an `mcpServers` JSON block ### Tool search for MCP server authors #### From a URL #### From an `npx`, `uvx`, or binary command #### From an `mcpServers` JSON block ### For MCP server authors
from line 161
161161
162162Each is one of the inputs the four options in [Installing MCP servers](#installing-mcp-servers) take. Find the shape you have below to turn it into the command Claude Code accepts. Each command writes to [local scope](#local-scope) unless you add `--scope project` or `--scope user`.
163163
164#### From a URL
164<span id="from-a-url" />
165165
166#### Add a server from a URL
167
166168A URL means the server is remote. For an `https://` endpoint, add it with `--transport http`, or follow [Option 2](#option-2-add-a-remote-sse-server) when the instructions say the endpoint uses SSE. For a `wss://` endpoint, use [Option 4](#option-4-add-a-remote-websocket-server) instead, since `--transport` doesn't accept `ws`:
167169
168170```bash theme={null}
from line 173
171173
172174If the instructions also give an API key or token header, pass it with `--header` as shown in [Option 1](#option-1-add-a-remote-http-server).
173175
174#### From an `npx`, `uvx`, or binary command
176<span id="from-an-npx-uvx-or-binary-command" />
175177
178#### Add a server from an `npx`, `uvx`, or binary command
179
176180A launch command means the server runs as a local stdio process. Put the whole command after `--`, so Claude Code passes flags such as `-y` to the command that starts the server instead of reading them as its own options. Pass any environment variables the instructions ask for with `--env`, after the server name and before `--`:
177181
178182```bash theme={null}
from line 185
181185
182186[Option 3](#option-3-add-a-local-stdio-server) covers the `--` separator in full.
183187
184#### From an `mcpServers` JSON block
188<span id="from-an-mcpservers-json-block" />
185189
190#### Add a server from an `mcpServers` JSON block
191
186192An `mcpServers` block written for another MCP client, such as Claude Desktop, uses the wrapper key and entry shape Claude Code reads. Pass `claude mcp add-json` the object inside `mcpServers`, not the wrapper. Two entries need a repair first:
187193
188194* **A `url` with no `type`**: add `"type": "http"`, `"type": "sse"`, or `"type": "ws"` to match the endpoint. Claude Code reads an entry with no `type` as a stdio server, so a `url` entry without a `type` fails.
from line 1439
14331439 Tool search isn't supported on Microsoft Foundry [deployments hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options), which reject it server-side: Claude Code detects the rejection and loads MCP tools upfront for that deployment instead. [`ENABLE_TOOL_SEARCH`](#configure-tool-search) can't override this, since the rejection comes from the deployment itself.
14341440</Note>
14351441
1436### For MCP server authors
1442<span id="for-mcp-server-authors" />
1443
1444### Tool search for MCP server authors
14371445
14381446If you're building an MCP server, the server instructions field becomes more useful with tool search enabled. Server instructions help Claude understand when to search for your tools, similar to how [skills](/docs/en/skills) work.
14391447
monitoring-usage Changed · +9 / -3 lines
### Backends for metrics ### Backends for events and logs ### Backends for traces ### For metrics ### For events/logs ### For traces
from line 1553
15531553
15541554Your choice of metrics, logs, and traces backends determines the types of analyses you can perform:
15551555
1556### For metrics
1556<span id="for-metrics" />
15571557
1558### Backends for metrics
1559
15581560* **Time series databases**: Rate calculations, aggregated metrics
15591561* **Columnar stores**: Complex queries, unique user analysis
15601562* **Full-featured observability platforms**: Advanced querying, visualization, alerting
15611563
1562### For events/logs
1564<span id="for-events/logs" />
15631565
1566### Backends for events and logs
1567
15641568* **Log aggregation systems**: Full-text search, log analysis
15651569* **Columnar stores**: Structured event analysis
15661570* **Full-featured observability platforms**: Correlation between metrics and events
15671571
1568### For traces
1572<span id="for-traces" />
1573
1574### Backends for traces
15691575
15701576Choose a backend that supports distributed trace storage and span correlation:
15711577
plugins/create Changed · +10 / -8 lines
#### Load a plugin from a directory or `.zip` #### Load a folder of plugins #### Load a plugin from a URL #### Load plugins from an environment variable #### From a directory or `.zip` #### From an environment variable
from line 173
173173
174174You can load a plugin for a single session in three ways: from a directory or `.zip` archive on disk with `--plugin-dir`, from a URL with `--plugin-url`, or from an environment variable when you can't add a flag. Each plugin loads for that session only, and nothing is written to your settings for it. When you edit the plugin's files during the session, run `/reload-plugins` to load the changes.
175175
176#### From a directory or `.zip`
176<span id="from-a-directory-or-zip" />
177177
178#### Load a plugin from a directory or `.zip`
179
178180When you start `claude` from your shell, pass `--plugin-dir` with the plugin's root directory or a `.zip` archive of it. Repeat the flag to load several plugins:
179181
180182```bash theme={null}
from line 183
181183claude --plugin-dir ./my-first-plugin --plugin-dir ./other-plugin.zip
182184```
183185
184<h4 id="load-a-folder-of-plugins">
185 From a folder of plugins
186</h4>
186#### Load a folder of plugins
187187
188188To load several plugins from one place, pass a folder that holds them, such as `--plugin-dir ./plugins`. Loading a folder of plugins requires Claude Code v2.1.265 or later.
189189
from line 198
198198
199199A message appears in the session for each of these changes. If loading or unloading a plugin mid-conversation would [invalidate the prompt cache](/docs/en/prompt-caching#enabling-or-disabling-a-plugin), the change is held instead, and the message tells you to run `/reload-plugins` to apply it.
200200
201<h4 id="fetch-an-archive-from-a-url-for-one-session">
202 From a URL
203</h4>
201<span id="fetch-an-archive-from-a-url-for-one-session" />
204202
203#### Load a plugin from a URL
204
205205When you start `claude` from your shell, pass `--plugin-url` with the address of a `.zip` archive, such as a build artifact your CI publishes:
206206
207207```bash theme={null}
from line 214
214214
215215If Claude Code can't fetch the archive, or the archive is invalid, it starts without the plugin and records a plugin load error that you can review in the `/plugin` manager's **Errors** tab.
216216
217#### From an environment variable
217<span id="from-an-environment-variable" />
218
219#### Load plugins from an environment variable
218220
219221To load plugins in a session where you can't add the `--plugin-dir` flag, list their absolute paths in the [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/en/env-vars#variables) environment variable instead. Claude Code loads each path as it loads a `--plugin-dir` path. These plugins load in addition to any you pass with `--plugin-dir`. [Project and local settings can't set this variable](/docs/en/settings-reference#variables-claude-code-ignores-in-env). `CLAUDE_CODE_PLUGIN_DIRS` requires Claude Code v2.1.280 or later.
220222
security-guidance Changed · +9 / -3 lines
### Checks on each file edit ### Checks at the end of each turn ### Checks on each commit or push Claude makes ### On each file edit ### At the end of each turn ### On each commit or push Claude makes
from line 62
6262
6363You can extend each layer by [adding your own rules](#add-your-own-rules). Built-in checks cannot be removed individually, but you can [disable each layer](#disable-or-uninstall) independently.
6464
65### On each file edit
65<span id="on-each-file-edit" />
6666
67### Checks on each file edit
68
6769When Claude writes to a file, the plugin scans the new content for known risky patterns. This is a pattern match with no model call, so it adds no usage cost.
6870
6971Example pattern categories:
from line 79
7779
7880You can [add your own patterns](#add-custom-per-edit-patterns) to this layer with a `security-patterns.yaml` file.
7981
80### At the end of each turn
82<span id="at-the-end-of-each-turn" />
8183
84### Checks at the end of each turn
85
8286A turn is one round of Claude responding: you send a message, Claude works and replies, and the turn ends. After each turn, the plugin computes a git diff of everything that changed in the working tree during the turn, including changes from Claude's edit tools, Bash commands, and subagents, and sends it to a separate Claude review focused on security. The review runs in the background, so Claude's reply is not delayed. If the review finds issues, Claude is re-prompted with the findings and addresses them as a follow-up.
8387
8488This catches issues a string match cannot, such as:
from line 95
9195
9296You see both the finding and Claude's resolution directly in your session. The review covers up to 30 changed files per turn and fires at most three times in a row before yielding back to you.
9397
94### On each commit or push Claude makes
98<span id="on-each-commit-or-push-claude-makes" />
99
100### Checks on each commit or push Claude makes
95101
96102When Claude runs `git commit` or `git push` through its Bash tool, the plugin runs a deeper agentic review of the change in the background. This review reads surrounding code, including callers, sanitizers, and related files, to decide whether a finding is real before reporting it. The extra context keeps false positives low on patterns that look dangerous in isolation but are safe in your codebase.
97103
setup Changed · +20 / -10 lines
### Uninstall a native installation ### Uninstall with Homebrew ### Uninstall with WinGet ### Uninstall with apt, dnf, or apk ### Uninstall with npm ### Native installation ### Homebrew installation ### WinGet installation ### apt / dnf / apk ### npm
from line 35
3535 <Tab title="Native Install (Recommended)">
3636 **macOS, Linux, WSL:**
3737
38 ```bash theme={null}
38 ```bash theme={null} theme={null}
3939 curl -fsSL https://claude.ai/install.sh | bash
4040 ```
4141
from line 43
4343
4444 **Windows PowerShell:**
4545
46 ```powershell theme={null}
46 ```powershell theme={null} theme={null}
4747 irm https://claude.ai/install.ps1 | iex
4848 ```
4949
5050 **Windows CMD:**
5151
52 ```batch theme={null}
52 ```batch theme={null} theme={null}
5353 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
5454 ```
5555
from line 67
6767 </Tab>
6868
6969 <Tab title="Homebrew">
70 ```bash theme={null}
70 ```bash theme={null} theme={null}
7171 brew install --cask claude-code
7272 ```
7373
from line 79
7979 </Tab>
8080
8181 <Tab title="WinGet">
82 ```powershell theme={null}
82 ```powershell theme={null} theme={null}
8383 winget install Anthropic.ClaudeCode
8484 ```
8585
from line 586
586586
587587To remove Claude Code, follow the instructions for your installation method. If `claude` still runs afterward, you likely have a second installation or a leftover shell alias from an older installer. See [Check for conflicting installations](/docs/en/troubleshoot-install#check-for-conflicting-installations) to find and remove it.
588588
589### Native installation
589<span id="native-installation" />
590590
591### Uninstall a native installation
592
591593Remove the Claude Code binary and version files:
592594
593595<Tabs>
from line 608
606608 </Tab>
607609</Tabs>
608610
609### Homebrew installation
611<span id="homebrew-installation" />
610612
613### Uninstall with Homebrew
614
611615Remove the Homebrew cask you installed. If you installed the stable cask:
612616
613617```bash theme={null}
from line 624
620624brew uninstall --cask claude-code@latest
621625```
622626
623### WinGet installation
627<span id="winget-installation" />
624628
629### Uninstall with WinGet
630
625631Remove the WinGet package:
626632
627633```powershell theme={null}
from line 634
628634winget uninstall Anthropic.ClaudeCode
629635```
630636
631### apt / dnf / apk
637<span id="apt-/-dnf-/-apk" />
632638
639### Uninstall with apt, dnf, or apk
640
633641Remove the package and the repository configuration:
634642
635643<Tabs>
from line 664
656664 </Tab>
657665</Tabs>
658666
659### npm
667<span id="npm" />
668
669### Uninstall with npm
660670
661671Remove the global npm package:
662672
troubleshoot-install Changed · +169 / -13 lines
### `permission denied` when adding to your PATH ### The connection dropped while downloading the update ### Installation was killed before it could finish
from line 11
1111| What you see | Solution |
1212| :- | :- |
1313| `command not found: claude` or `'claude' is not recognized` | [Fix your PATH](#command-not-found-claude-after-installation) |
14| `Native installation exists but ... is not in your PATH` | [Add the install directory to your PATH](#verify-your-path) |
15| `INFO: Could not find files for the given pattern(s).` from `where.exe claude` | [Check whether Claude Code is installed](#check-for-conflicting-installations) |
16| `zsh: permission denied: /Users/you/.zshrc` or `bash: /home/you/.bashrc: Permission denied` | [Make your shell config file writable](#permission-denied-when-adding-to-your-path) |
1417| `syntax error near unexpected token '<'` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
18| `< was unexpected at this time` in CMD | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
19| `The term 'System.Xml.XmlDocument' is not recognized` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
1520| `curl: (22) The requested URL returned error: 403` | [Install script returned 403](#install-script-returns-html-instead-of-a-shell-script) |
1621| `curl: (23)` or `curl: (56) Failure writing output to destination` | [Check connectivity or use an alternative installer](#curl-56-failure-writing-output-to-destination) |
17| `Killed` during install on Linux, or `Installation was killed before it could finish (exit code 137)` | [Free memory or add swap space](#install-killed-on-low-memory-linux-servers) |
22| `Killed` during install on Linux | [Free memory or add swap space](#install-killed-on-low-memory-linux-servers) |
23| `Installation was killed before it could finish` | [Free memory, then rerun the installer](#installation-was-killed-before-it-could-finish) |
1824| `Raw mode is not supported` during install | [Rerun the installer](#raw-mode-is-not-supported-during-install) |
1925| `EACCES: permission denied` during install | [Fix the install directory's permissions](#permission-errors-during-installation) |
2026| `TLS connect error` or `SSL/TLS secure channel` | [Update CA certificates](#tls-or-ssl-connection-errors) |
27| `CRYPT_E_NO_REVOCATION_CHECK` or `CRYPT_E_REVOCATION_OFFLINE` | [Work around blocked revocation checks](#tls-or-ssl-connection-errors) |
2128| `Failed to fetch version` or can't reach download server | [Check network and proxy settings](#check-network-connectivity) |
29| `The connection dropped while downloading the update` or `Download timed out: exceeded the total deadline` | [Run the update again or set your proxy](#the-connection-dropped-while-downloading-the-update) |
2230| `irm is not recognized` or `The token '&&' is not a valid statement separator` | [Use the right command for your shell](#wrong-install-command-on-windows) |
2331| `Cask 'claude-code' is unavailable: No Cask with this name exists` | [Update Homebrew](#homebrew-cask-unavailable-or-outdated) |
32| `Cask 'claude-code@latest' is not installed` | [Upgrade the cask you installed](#cask-is-not-installed) |
2433| `'bash' is not recognized as the name of a cmdlet` | [Use the Windows installer command](#wrong-install-command-on-windows) |
2534| `A parameter cannot be found that matches parameter name 'fsSL'` | [Use the Windows installer command](#wrong-install-command-on-windows) |
2635| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [Install a shell](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |
from line 122
113122
114123If installation succeeded but you get a `command not found` or `not recognized` error when running `claude`, the install directory isn't in your PATH. Your shell searches for programs in directories listed in PATH, and the installer places `claude` at `~/.local/bin/claude` on macOS/Linux or `%USERPROFILE%\.local\bin\claude.exe` on Windows.
115124
125The installer detects this case and reports it under `Setup notes:` in its output: `Native installation exists but ~/.local/bin is not in your PATH.` on macOS and Linux, or `Native installation exists but C:\Users\you\.local\bin is not in your PATH.` on Windows. It prints the fix with that note but doesn't change PATH itself.
126
116127<Note>
117128 The [VS Code extension](/docs/en/vs-code) does not place `claude` at this location. It bundles a private copy of the CLI inside the extension directory for its own chat panel and does not add it to PATH. If you have only installed the extension, `~/.local/bin/claude` will not exist. Run the [standalone install](/docs/en/setup) to use `claude` from a terminal, then continue below.
118129</Note>
119130
120Check if the install directory is in your PATH by listing your PATH entries and filtering for `local/bin`:
131First 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.
121132
122133<Tabs>
123134 <Tab title="macOS/Linux">
135 Check that the installer put the program in place:
136
124137 ```bash theme={null}
138 ls -la ~/.local/bin/claude
139 ```
140
141 * **`No such file or directory`**: there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](/docs/en/setup#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
142 * **A listing for the file**: the program is there. Check your PATH next.
143
144 List your PATH entries and filter for the install folder:
145
146 ```bash theme={null}
125147 echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
126148 ```
127149
128 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.
150 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.
129151
130152 For Zsh, the default on macOS:
131153
from line 172
150172
151173 Alternatively, close and reopen your terminal.
152174
175 If the `echo` command prints `permission denied`, see [`permission denied` when adding to your PATH](#permission-denied-when-adding-to-your-path).
176
153177 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.
154178
155179 Verify the fix worked:
from line 181
157181 ```bash theme={null}
158182 claude --version
159183 ```
184
185 If `claude` is still not found, check these causes:
186
187 * **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.
188 * **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.
189 * **The line went to another shell's file**: run `echo $0` to see your shell, then run the two PATH commands for that shell.
160190 </Tab>
161191
162192 <Tab title="Windows PowerShell">
193 Check that the installer put the program in place:
194
163195 ```powershell theme={null}
196 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
197 ```
198
199 * **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](/docs/en/setup#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
200 * **`True`**: the program is there. Check your PATH next.
201
202 List your PATH entries and filter for the install folder:
203
204 ```powershell theme={null}
164205 $env:PATH -split ';' | Select-String '\.local\\bin'
165206 ```
166207
167 If there's no output, add the install directory to your User PATH:
208 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:
168209
169210 ```powershell theme={null}
170211 $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
from line 219
178219 ```powershell theme={null}
179220 claude --version
180221 ```
222
223 If `claude` is still not found in a new terminal, check these causes:
224
225 * **The terminal runs inside an editor**: it takes its PATH from the editor, so quit and reopen the editor.
226 * **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.
181227 </Tab>
182228
183229 <Tab title="Windows CMD">
230 Check that the installer put the program in place:
231
184232 ```batch theme={null}
233 dir "%USERPROFILE%\.local\bin\claude.exe"
234 ```
235
236 * **`File Not Found` or `The system cannot find the path specified.`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](/docs/en/setup#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
237 * **A listing for `claude.exe`**: the program is there. Check your PATH next.
238
239 List your PATH entries and filter for the install folder:
240
241 ```batch theme={null}
185242 echo %PATH% | findstr /i "local\bin"
186243 ```
187244
from line 249
192249 ```batch theme={null}
193250 claude --version
194251 ```
252
253 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.
195254 </Tab>
196255</Tabs>
197256
from line 266
207266 which -a claude
208267 ```
209268
210 If this prints nothing, no `claude` is on your PATH yet. Go back to [Verify your PATH](#verify-your-path).
269 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.
211270
212271 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:
213272
from line 285
226285 ```bash theme={null}
227286 npm -g ls @anthropic-ai/claude-code 2>/dev/null
228287 ```
288
289 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](/docs/en/setup#install-claude-code). If `~/.local/bin/claude` exists but `which -a claude` didn't list it, the folder isn't in your PATH: see [Verify your PATH](#verify-your-path).
229290 </Tab>
230291
231292 <Tab title="Windows PowerShell">
from line 296
235296 where.exe claude
236297 ```
237298
299 If this prints `INFO: Could not find files for the given pattern(s).`, no `claude` is on your PATH.
300
238301 Check whether the native installer placed a binary:
239302
240303 ```powershell theme={null}
241304 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
242305 ```
306
307 * **`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).
308 * **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](/docs/en/setup#install-claude-code).
243309 </Tab>
244310</Tabs>
245311
from line 412
346412
347413### Install script returns HTML instead of a shell script
348414
349When running the install command, you may see one of these errors:
415The install command fails with one of these errors when what it downloaded isn't the install script.
350416
417**Bash or Zsh**: the error quotes the first line of the returned page.
418
351419```text theme={null}
352420bash: line 1: syntax error near unexpected token `<'
353421bash: line 1: `<!DOCTYPE html>'
354422```
355423
356On PowerShell, the same problem appears as parse errors pointing into the returned page, with `iex` trying to run HTML and CSS as PowerShell:
424**PowerShell, parse errors**: the errors point into the returned page, with `iex` trying to run HTML and CSS as PowerShell.
357425
358426```text theme={null}
359427iex : At line:1 char:2310
from line 432
364432
365433The wording varies with the PowerShell version and system language: you may see `Missing expression after unary operator '--'` or a `ParserError` with `ParseException` instead. HTML tags or CSS in the quoted text identify this failure. If you download with `-OutFile install.ps1` instead, the saved file is the same web page, so that doesn't help either.
366434
367Depending on how the request was routed, you may instead see a 403 with no HTML body:
435**PowerShell, `System.Xml.XmlDocument`**: the error names this type instead of quoting the page.
368436
369437```text theme={null}
438System.Xml.XmlDocument : The term 'System.Xml.XmlDocument' is not recognized as the name of a cmdlet, function, script
439file, or operable program.
440```
441
442When `irm` can parse the response as XML, it returns an XML object instead of text, and `iex` then tries to run that object's type name as a command. The install script is PowerShell code and doesn't parse as XML, so this error also means the response was something other than the script. The wording around the type name varies with the PowerShell version and system language, but `System.Xml.XmlDocument` itself stays the same, so match on the type name.
443
444**CMD**: you see this error, followed by the HTML of the returned page.
445
446```text theme={null}
447< was unexpected at this time.
448
449C:\Users\you><!DOCTYPE html>...
450```
451
452The first line appears in your system language, so look for the HTML that follows it.
453
454**A 403 with no page**: depending on how the request was routed, curl reports a 403 status with no HTML body.
455
456```text theme={null}
370457curl: (22) The requested URL returned error: 403
371458```
372459
373These all mean the install URL returned an HTML page or an error status instead of the install script. If the HTML page says "App unavailable in region," Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries).
460These all mean the install URL returned a web page, an XML document, or an error status instead of the install script. If the error output quotes "App unavailable in region," Claude Code isn't available in your country. See [supported countries](https://www.anthropic.com/supported-countries).
374461
375462A bare 403 with no body often has the same cause, but it can also come from a corporate proxy or firewall blocking the download. If you are in a supported country and still see the 403, work through [Check network connectivity](#check-network-connectivity) before trying the alternative installers below, since those reach the same hosts.
376463
from line 465
378465
379466**Solutions:**
380467
3811. **Use an alternative install method**:
4681. **Retry after a few minutes**: the issue is often temporary. Wait and try the original command again.
382469
4702. **Use an alternative install method**: unlike a native install, a Homebrew or WinGet install [doesn't update itself by default](/docs/en/setup#auto-updates).
471
383472 On macOS, install via Homebrew:
384473
385474 ```bash theme={null}
from line 483
394483
395484 Then run `claude --version` to confirm: the command prints a version number such as `2.1.211 (Claude Code)`. If the shell reports `claude` isn't found, open a new terminal window and retry: the session you installed from keeps its old `PATH`.
396485
3972. **Retry after a few minutes**: the issue is often temporary. Wait and try the original command again.
398
399486### `command not found: claude` after installation
400487
401488The install finished but `claude` doesn't work. The exact error varies by platform:
from line 498
411498
412499Otherwise, see [Verify your PATH](#verify-your-path) for the fix on each platform.
413500
501### `permission denied` when adding to your PATH
502
503If the `echo` command that adds `~/.local/bin` to your PATH prints `zsh: permission denied: /Users/you/.zshrc` or `bash: /home/you/.bashrc: Permission denied`, your user can't write to that file and nothing was saved. In your terminal, check who owns the file, using your shell's file name in place of `~/.zshrc`:
504
505```bash theme={null}
506ls -l ~/.zshrc
507```
508
509The third field of the output is the owner.
510
511* **The owner is another user, such as `root`**: take ownership with `sudo chown $(whoami) ~/.zshrc`, which requires administrator rights.
512* **The owner is you**: the file is read-only. Make it writable with `chmod u+w ~/.zshrc`.
513
514Then run the two PATH commands for your shell in [Verify your PATH](#verify-your-path) again.
515
414516### `curl: (56) Failure writing output to destination`
415517
416518The `curl ... | bash` command downloads the script and pipes it to Bash for execution. This error, and the related `curl: (23) Failure writing output to destination`, means Bash did not receive the complete script. Exit code 56 indicates the download itself was interrupted, and exit code 23 indicates curl could not write what it received to the pipe, usually because Bash exited early.
from line 530
428530
429531If Homebrew installs an older Claude Code version than you expect, the same stale index is usually the cause. The `claude-code` cask tracks the stable channel and is typically about one week behind the latest release; for the newest version run `brew install --cask claude-code@latest` instead. See [Configure release channel](/docs/en/setup#configure-release-channel) for the difference between the two casks.
430532
533<h3 id="cask-is-not-installed">
534 `Cask 'claude-code@latest' is not installed`
535</h3>
536
537Homebrew offers two casks, `claude-code` and `claude-code@latest`. Running `brew upgrade --cask claude-code@latest` when that cask isn't the one installed prints `Error: Cask 'claude-code@latest' is not installed.` To see which cask you have, run this in your terminal:
538
539```bash theme={null}
540brew list --cask | grep claude-code
541```
542
543Upgrade the cask it prints. If it prints nothing, neither cask is installed.
544
431545### TLS or SSL connection errors
432546
433547Errors such as these mean the TLS handshake failed:
from line 551
437551* PowerShell's `Could not create SSL/TLS secure channel`
438552* PowerShell's `Could not establish trust relationship for the SSL/TLS secure channel`
439553
554For `CRYPT_E_NO_REVOCATION_CHECK` or `CRYPT_E_REVOCATION_OFFLINE`, go to step 4.
555
440556**Solutions:**
441557
4425581. **Update your system CA certificates**:
from line 565
449565
450566 On macOS, the system curl uses the Keychain trust store; updating macOS itself updates the root certificates.
451567
4522. **On Windows, enable TLS 1.2** in PowerShell before running the installer:
5682. **In Windows PowerShell 5.1, enable TLS 1.2**:
453569 ```powershell theme={null}
454570 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
571 ```
572 Then run the installer in the same window:
573 ```powershell theme={null}
455574 irm https://claude.ai/install.ps1 | iex
456575 ```
457576
from line 624
505624
506625The installer couldn't reach the download server. This typically means `downloads.claude.ai` is blocked on your network. See [Check network connectivity](#check-network-connectivity).
507626
627### The connection dropped while downloading the update
628
629The connection to the download server closed while `claude install` or `claude update` was fetching the Claude Code binary, and the retries didn't recover. Claude Code retries the download when the connection drops, the transfer stalls, or the downloaded file fails its checksum, up to three attempts in total. A completed HTTP error, such as a 404, isn't retried because the server already answered. Before v2.1.202, a single dropped connection failed the download immediately with the bare error `aborted` instead of retrying.
630
631```text theme={null}
632The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.
633```
634
635The text in parentheses names which attempt failed and the underlying network error. `claude update` precedes the message with `Error: Failed to install native update` on stderr.
636
637A download that stays connected but doesn't finish within 10 minutes fails with `Download timed out: exceeded the total deadline` instead. Claude Code doesn't retry a timed-out download, because a connection too slow to finish inside the deadline won't finish on an immediate retry either. The steps below apply to both messages.
638
639A proxy or gateway can close a long transfer before it finishes, and the Claude Code binary is a large download.
640
641**What to do:**
642
643* Run `claude update` again. On an otherwise healthy network, the download usually succeeds on the next run. For the timed-out message, run it again from a faster or less throttled network.
644* If your network requires a proxy, set `HTTPS_PROXY` before running the installer or `claude update`. See [Check network connectivity](#check-network-connectivity).
645* If a corporate proxy keeps closing the transfer, ask your network team to allow the full download from `downloads.claude.ai`. See [Network access requirements](/docs/en/network-config#network-access-requirements).
646* Run `claude doctor` from your shell for installation diagnostics
647
508648### Wrong install command on Windows
509649
510650If you see `'irm' is not recognized`, `The token '&&' is not a valid statement separator`, `A parameter cannot be found that matches parameter name 'fsSL'`, or `'bash' is not recognized as the name of a cmdlet`, you copied the install command for a different shell or operating system. If the command prints the script's text instead of installing anything, you ran only part of it.
from line 783
6437832. **Close other processes** to free memory before installing.
644784
6457853. **Use a larger instance** if possible. Claude Code requires at least 4 GB of RAM.
786
787### Installation was killed before it could finish
788
789The install script reports when the `claude install` step is terminated by a signal. On Linux, exit code 137 means the process received SIGKILL, and on a low-memory host that's usually the kernel out-of-memory (OOM) killer. The script prints this explanation and exits with code 137:
790
791```text theme={null}
792Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
793Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.
794```
795
796For any other fatal signal, and for exit code 137 on macOS, the script prints `Installation was killed before it could finish (exit code <N>)` with the actual exit code and omits the out-of-memory explanation. The message comes from the install script macOS and Linux use, which also covers installs inside WSL; the native Windows install scripts never print it. Before v2.1.200, the script exited with only the shell's bare `Killed` line.
797
798**What to do:**
799
800* Stop other processes to free memory, then rerun the installer
801* Add swap space or move to a larger instance. See [Install killed on low-memory Linux servers](#install-killed-on-low-memory-linux-servers) for the swap-file commands.
646802
647803### Install hangs in Docker
648804
claude-tag Changed · +1 / -1 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.
glossary Changed · +1 / -1 lines
from line 339
339339
340340A command, `/teleport`, that pulls a cloud Claude Code session into your local terminal. Claude fetches the branch, loads the conversation history, and resumes from the cloud session's last state. The reverse direction is `--cloud`, which sends a local task to run in the cloud.
341341
342Learn more: [From cloud to terminal](/docs/en/claude-code-on-the-web#from-cloud-to-terminal)
342Learn more: [Continue a cloud session in your terminal](/docs/en/claude-code-on-the-web#from-cloud-to-terminal)
343343
344344### Tool
345345
troubleshooting Changed · +1 / -1 lines
from line 7
77| Symptom | Go to |
88| :- | :- |
99| `command not found`, install fails, PATH issues, `EACCES`, TLS errors | [Troubleshoot installation and login](/docs/en/troubleshoot-install) |
10| Update or install download fails with `The connection dropped while downloading the update` or `aborted` | [Error reference](/docs/en/errors#the-connection-dropped-while-downloading-the-update) |
10| Update or install download fails with `The connection dropped while downloading the update` or `aborted` | [Troubleshoot installation and login](/docs/en/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |
1111| Login loops, OAuth errors, `403 Forbidden`, "organization disabled", Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry credentials | [Troubleshoot installation and login](/docs/en/troubleshoot-install#login-and-authentication) |
1212| Settings not applying, hooks not firing, MCP servers not loading | [Debug your configuration](/docs/en/debug-your-config) |
1313| Session started in auto mode, or Claude edits files and runs commands without asking | [Which mode a session starts in](/docs/en/permission-modes#which-mode-a-session-starts-in) |
vs-code Changed · +1 / -0 lines
from line 542
542542| `useCtrlEnterToSend` | `false` | Use Ctrl/Cmd+Enter instead of Enter to send prompts |
543543| `scrollToBottomOnSend` | `true` | Scroll the conversation to the bottom when you send a message. When off, the conversation stays where you left it. Requires Claude Code v2.1.275 or later |
544544| `showMessageTimestamps` | `true` | Show when each message was sent. A date line marks where the day changes. Requires Claude Code v2.1.284 or later. Before v2.1.290, the default was `false` |
545| `spinnerVerbs` | `{"mode": "append", "verbs": []}` | Set the verbs the conversation spinner rotates through while a turn runs, with the same `mode` and `verbs` fields as the CLI's [`spinnerVerbs`](/docs/en/settings-reference#spinnerverbs). |
545546| `enableNewConversationShortcut` | `false` | Enable Cmd/Ctrl+N to start a new conversation |
546547| `enableReopenClosedSessionShortcut` | `true` | Use Cmd/Ctrl+Shift+T to reopen the most recently closed Claude session tab. When the last closed tab wasn't a Claude session, the shortcut runs VS Code's normal reopen-closed-editor command instead. |
547548| `archiveInactiveSessions` | `14` | [Archive a session automatically](#resume-past-conversations) after this many days without activity: `1`, `2`, `7`, or `14`. Set `0` to turn it off. Requires Claude Code v2.1.265 or later |