One read of Claude Code CLIclaude-code-20261106T003701Z
17 pages moved out of 228 read.
Pages moved
17
significant first
Pages read
228
in this capture
Captured
00:37 UTC
Corpus hash
5874a7c189a2
corpus-hash
What this read moved
1-17 of 17agent-sdk/plugins Changed · +4 / -0 lines
### Reload plugins in a running session
from line 66
6666>
6767> The path should point to the plugin's root directory: the parent of `skills/`, `agents/`, `hooks/`, `commands/`, or `.claude-plugin/`.
6868
69### Reload plugins in a running session
70
71To apply a change to a plugin's skills, commands, agents, or hooks without starting a new session, call [`reloadPlugins()`](https://code.claude.com/docs/en/agent-sdk/typescript#query-object) on the TypeScript SDK's `Query` object. The Python SDK doesn't expose an equivalent method; send [`/reload-plugins`](https://code.claude.com/docs/en/plugins/cli-reference#reload-plugins) as a prompt in the session instead.
72
6973### Add plugins to a running session
7074
7175In the TypeScript SDK, call [`reloadPlugins()`](https://code.claude.com/docs/en/agent-sdk/typescript#load-more-plugin-folders-with-addplugins) on the `Query` object that `query()` returned, and list the plugin directory in that call's `addPlugins` option. Each `addPlugins` entry is a `{ type: "local", path }` object with an absolute `path`. Requires TypeScript Agent SDK v0.3.301 or later.
claude-projects Changed · +7 / -6 lines
from line 91
9191Scope the project to one stream of work you'll keep adding to, such as everything it takes to keep one API under its latency target. [When to use a project](#when-to-use-a-project) has more examples. Then fill in the dialog's fields:
9292
9393* **Name**: how the project appears in the **Projects** list.
94* **Goal** (optional): one line of what you're trying to get done, such as "Hold p95 API latency under 200 ms". Claude in the conversation works toward it. Without a goal, Claude works from the tasks you send, and you can add a goal later in **Project settings > General**.
94* **What do you want to work on?** (optional): one line that becomes the project's goal, such as "Hold p95 API latency under 200 ms". Claude in the conversation works toward it. Without a goal, Claude works from the tasks you send, and you can add a goal later in **Project settings > General**.
9595* **Context** (optional): the GitHub repositories this project works on, plus any files, folders, or Google Drive folders threads should read. Click **Add** for each. Add the repositories most tasks need rather than every one the work might touch; [Decide which repositories to add](#decide-which-repositories-to-add) covers the choice, and you can add more later in **Project settings > Environment**.
9696
9797Standing rules for how threads should work go in [project instructions](#give-a-project-standing-context), which you set after the project exists.
from line 384
384384| Plugins | Plugins | The plugins that load into each new cloud thread |
385385| Usage | Usage | [Token use](#usage-and-cost) by thread and by model |
386386| Memory | Memory | The project's [memory files](#give-a-project-standing-context) |
387| Auto-continue when usage limits reset | General | Whether a thread or the project conversation that [stops at a usage limit](#usage-limit-reached) continues on its own when the limit resets. On by default. |
387388| Restart Claude | General | Restarts the project conversation when [Claude stops responding there](#claude-hasnt-responded) |
388389| Pause, Archive, Delete | General | Stops, hides, or removes the project; see [Pause, archive, or delete a project](#pause-archive-or-delete-a-project) |
389390
from line 400
399400
400401Project usage counts against the same [plan limits](https://code.claude.com/docs/en/errors.md#youve-hit-your-session-limit) as your other Claude Code sessions, and a project can't spend past those limits on its own.
401402
402A thread that reaches your plan's limit waits and continues on its own when the limit resets, so work you left running starts using your next usage window without a message from you. [A thread hit the usage limit](#usage-limit-reached) covers what you see, how to stop it, and the one case that doesn't wait.
403A thread that stops at your plan's limit waits and by default continues on its own when the limit resets. Its work then counts against your next usage window. To keep threads from continuing, see [A thread hit the usage limit](#usage-limit-reached).
403404
404405Work goes past your plan's limits only if you have turned on [usage credits](https://code.claude.com/docs/en/costs.md#add-usage-credits-to-your-subscription) for your account. A thread can't turn them on for you.
405406
from line 481
480481
481482### A thread hit the usage limit
482483
483When a thread or the project conversation reaches your plan's five-hour or weekly limit, it keeps retrying on its own and continues when the limit resets. A thread that a scheduled task started doesn't wait: its turn stops with a limit error, and you send it a message after the limit resets.
484When a thread or the project conversation stops at your plan's five-hour or weekly limit, it waits and by default continues on its own when the limit resets.
484485
485While a thread waits, it shows **Service is busy** with "Claude is still retrying and will continue automatically." You don't need to do anything for the work to continue. If you'd rather it not use your next usage window, click **Stop** in the thread, or [pause the project](#pause-archive-or-delete-a-project) to hold every thread. [Usage limit errors](https://code.claude.com/docs/en/errors.md#youve-hit-your-session-limit) explain the limits and when they reset.
486To keep a thread or conversation from continuing at the reset time its message shows, turn off **Auto-continue when usage limits reset** in [**Project settings > General**](#project-settings-reference) before then. The setting is for the whole project, not only the thread you're looking at. To continue with the setting off, send the thread or conversation a message after the reset. [Usage limit errors](https://code.claude.com/docs/en/errors.md#youve-hit-your-session-limit) explain the limits and when they reset.
486487
487488### Additional usage credits are required
488489
from line 506
505506| "Unable to connect to repository" with "Claude couldn't access your repository or environment" | Your GitHub account needs push access to the repository, and the environment must still exist. Check both in **Project settings > Environment**, then retry |
506507| "Couldn't show the setup proposal" | The app you have open is older than the **Setup recommendations** Claude sent. Refresh the page or restart the desktop app, or ask Claude to propose the setup again |
507508| "The project's environment was removed" | Choose a different environment in **Project settings > Environment**; the change applies to new threads |
508| "Setup script failed" | Click **Edit setup script** on the error, fix the script in the environment, then send another message. [Setup script failed](https://code.claude.com/docs/en/web-quickstart.md#setup-script-failed) lists common causes |
509| "Setup script failed" | [Setup script failed](https://code.claude.com/docs/en/web-quickstart.md#setup-script-failed) lists common causes. Fix the script in the environment, then ask Claude in the project conversation to run the task in a new thread, so the script runs again |
509510| "Claude ran out of context on this turn" | The thread filled its context window. If the message says the thread continues in a fresh session, it carries on by itself; otherwise ask Claude in the project conversation to start a new thread for the remaining work |
510511| "Couldn't start in" followed by your folder's name | You allowed a thread to run on your computer, but the session couldn't start there. When a line under the message gives the reason, fix that, then ask Claude to run the task again |
511512| "Claude is out of date on your device" | The computer you picked to run a thread has a Claude Code version older than v2.1.280. Update Claude Code there, or update the desktop app if that's what connects the folder, then ask Claude to run the task again |
claude-tag Changed · +333 / -3083 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.
code-review-customize Changed · +16 / -3 lines
### When a subdirectory REVIEW\.md doesn't apply
from line 21
2121
2222## Use REVIEW\.md for review-only rules
2323
24`REVIEW.md` is a file at your repository root that tailors Code Review to your repository. You can also add a `REVIEW.md` in a subdirectory to add checks for changes under that path, on top of the root file.
24`REVIEW.md` is a file at your repository root that tailors Code Review to your repository. On a [protected branch](#what-a-review-reads-for-each-branch-setup), you can also add a `REVIEW.md` in [most subdirectories](#when-a-subdirectory-review-md-doesnt-apply) to add checks for changes under that subdirectory, on top of the root file.
2525
2626The agents that find issues and the agents that verify them receive its contents as your repository's review instructions, alongside Code Review's default review guidance. The step that writes the final review consults it before settling severity and writing the summary.
2727
from line 42
4242>
4343> The Code Review service and the local [`/code-review` command](https://code.claude.com/docs/en/code-review-local) are two separate tools, and they read different files. The service reads both `CLAUDE.md` and `REVIEW.md`. The `/code-review` command, which you run inside a Claude Code session on your own machine, reads your `CLAUDE.md` files and not `REVIEW.md`. Put guidance you want applied in both places in `CLAUDE.md`, and keep `REVIEW.md` for rules specific to pull request review.
4444
45### When a subdirectory REVIEW\.md doesn't apply
46
47Code Review doesn't apply a `REVIEW.md` in or below a subdirectory with one of these names, whatever the subdirectory holds. A subdirectory name matches only as a whole, in any letter case and at any depth, so `Tests` matches and `integration-tests` doesn't:
48
49* **Tests**: `test`, `tests`, `__tests__`, `testdata`, `fixtures`, `__fixtures__`, `golden`, `corpus`, `snapshots`, `__snapshots__`
50* **Examples**: `example`, `examples`, `sample`, `samples`, `demo`, `demos`
51* **Generated code**: `generated`
52* **Third-party code**: `vendor`, `third_party`, `third-party`, `thirdparty`, `node_modules`, `bower_components`, `external`, `extern`, `deps`, `godeps`, `pods`, `carthage`, `site-packages`, `contrib`
53
54Put checks for those subdirectories in the root `REVIEW.md`, or in a parent subdirectory's `REVIEW.md` when neither that parent nor anything above it is on the list.
55
56The remaining subdirectory `REVIEW.md` files on the paths a pull request changes share a limit of 150,000 bytes, not counting the root file. If the [check run](https://code.claude.com/docs/en/code-review-pull-requests.md#check-run-output) reports that some of them didn't fit, shorten the files to fit that limit.
57
4558### Example REVIEW\.md
4659
4760This `REVIEW.md` recalibrates severity for a backend service, caps nits, skips generated files, and adds repo-specific checks.
from line 226
213226
214227| Branch protection | Copy read | Files read |
215228| :- | :- | :- |
216| The default branch is protected, and the pull request targets it or targets a branch no ruleset protects | Default branch | Root file, the files it includes, and subdirectory files |
217| The pull request targets another branch that a ruleset protects | That base branch | Root file, the files it includes, and subdirectory files |
229| The default branch is protected, and the pull request targets it or targets a branch no ruleset protects | Default branch | Root file, the files it includes, and [most subdirectory files](#when-a-subdirectory-review-md-doesnt-apply) |
230| The pull request targets another branch that a ruleset protects | That base branch | Root file, the files it includes, and [most subdirectory files](#when-a-subdirectory-review-md-doesnt-apply) |
218231| The default branch isn't protected, and the base branch has no protection rule of either kind | Default branch | Root file |
219232| Code Review can't confirm the protection settings. This includes an unprotected default branch with a base branch that has only a classic rule | None | None |
220233
errors Changed · +20 / -11 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.
from line 57
5757| `Could not resolve authentication method` | [Authentication](#could-not-resolve-authentication-method) |
5858| `Invalid API key` | [Authentication](#invalid-api-key) |
5959| `Your apiKeyHelper script is failing` | [Authentication](#your-apikeyhelper-script-is-failing) |
60| `Claude Code didn't send your claude.ai login, because the API key helper your administrator set isn't in effect` | [Authentication](#claude-code-didnt-send-your-claude-ai-login) |
60| `Your organization's settings need an update` | [Authentication](#claude-code-didnt-send-your-claude-ai-login) |
61| `Couldn't load your organization's settings. Check your connection` | [Authentication](#claude-code-didnt-send-your-claude-ai-login) |
62| `Restart Claude Code to finish signing in` | [Authentication](#claude-code-didnt-send-your-claude-ai-login) |
6163| `Invalid auth token · Fix external auth token` | [Authentication](#invalid-request-header-value) |
6264| `Invalid ANTHROPIC_CUSTOM_HEADERS · Fix the environment variable` | [Authentication](#invalid-request-header-value) |
6365| `Invalid request header from the environment · Fix the environment variable` | [Authentication](#invalid-request-header-value) |
from line 1115
11131115
11141116### Claude Code didn't send your claude.ai login
11151117
1116Send this full message to your administrator. It lists the changes they can make. The message means Claude Code refused your prompt. While you use your claude.ai login, Claude Code keeps refusing prompts, after a restart too:
1118These messages mean Claude Code refused your request and didn't send your claude.ai login:
11171119
11181120```text theme={null}
1119Claude Code didn't send your claude.ai login, because the API key helper your administrator set isn't in effect. Your organization's managed settings may be overriding it. Ask your administrator to keep the key helper and its API address in effect, to name Anthropic's API address in those managed settings, or to remove the key helper. Run /status to see your setting sources.
1121Your organization's settings need an update. Ask your administrator to fix the API key helper configuration.
1122Couldn't load your organization's settings. Check your connection, then restart Claude Code.
1123Restart Claude Code to finish signing in.
11201124```
11211125
11221126**What to do:**
11231127
1124* To tell your administrator which managed sources your machine has, run `/status` at the Claude Code prompt and copy the [`Setting sources` line](https://code.claude.com/docs/en/managed-settings#read-the-source-in-/status). If a `Skipped sources` line appears, copy it too
1125* If you administer the settings, see [why the machine's key helper isn't in effect](https://code.claude.com/docs/en/server-managed-settings.md#machine-apikeyhelper-not-in-effect)
1128* `Your organization's settings need an update`: ask your administrator to fix the API key helper configuration
1129 * To tell your administrator which managed sources your machine has, run `/status` at the Claude Code prompt and copy the [`Setting sources` line](https://code.claude.com/docs/en/managed-settings#read-the-source-in-/status). If a `Skipped sources` line appears, copy it too
1130 * If you administer the settings and the helper is in a machine's managed settings file or MDM policy, see [When a machine's `apiKeyHelper` isn't in effect](https://code.claude.com/docs/en/server-managed-settings#machine-apikeyhelper-not-in-effect)
1131* `Couldn't load your organization's settings`: check your connection, then restart Claude Code. If the message comes back after a restart, tell your administrator
1132* `Restart Claude Code to finish signing in`: restart Claude Code
11261133
1134Before v2.1.315, a refused prompt or file upload printed one message that began `Claude Code didn't send your claude.ai login`.
1135
11271136### Invalid request header value
11281137
11291138A value Claude Code was about to send as a request header contains a character that HTTP headers can't carry: a line break, a NUL byte, or a character above `U+00FF`, such as a curly quote or a zero-width space. Claude Code stops the request before anything is sent and names the variable or setting to fix. The usual cause is a credential pasted from a document or chat that carried an invisible character or a stray line break.
from line 2509
25002509
25012510**What to do:**
25022511
2503* If the message asks you to convert the image, convert it to PNG, JPEG, GIF, or WebP and attach it again. Claude Code can verify dimensions for these formats from the file header, without decoding the image.
2504* If the message reports a dimension or size limit, resize or recompress the image below that limit before attaching.
2505* If the message names a cause, such as a CMYK JPEG, an animated WebP, or a possibly damaged file, re-save the image in the format the message sugge
2512* If the message as
self-hosted-environments-configuration Changed · +11 / -3 lines
### Pin a permission mode from your wrapper ### Pre-approve specific tools
from line 42
4242| `CLAUDE_CODE_REMOTE_SLACK_CHANNEL_ID` | For a Claude Tag session, the ID of the Slack channel or direct message that the session serves or that its thread is in, such as `C0123ABCDE`. A Slack timestamp identifies a message within one channel, so record this ID together with `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS`. Unset for other sessions, and can be unset for a Claude Tag session too. |
4343| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Absolute path to a per-session file holding the current session JWT, kept fresh across token refreshes. Shell subprocesses read it for their `Authorization` header when downloading attachments the user added to the session. `exec` preserves the variable automatically; a wrapper that rebuilds the child's environment must carry the variable over, or attachment downloads silently stop working. |
4444| `CLAUDE_CONFIG_DIR` | Per-session Claude config directory, written at session start from the snapshot of the runner host's config that the runner captures at startup; see [Permissions and tool approval](#permissions-and-tool-approval). Writes here are isolated to this session. The directory stays under `<base-dir>/_sessions/` after the session ends unless you start the runner with [`--remove-session-state`](https://code.claude.com/docs/en/self-hosted-environments-reference#runner-cli-flags); see [Reuse a pre-warmed checkout](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout). |
45| `CLAUDE_CODE_REMOTE_MCP_CONFIG` | Path to a file in `CLAUDE_CONFIG_DIR` holding the MCP server definitions that Anthropic's control plane delivered for this session. If your wrapper rebuilds the child's environment, carry this variable over. Without it, when the control plane updates the delivered servers, the child shuts down any stdio, HTTP, or SSE server your wrapper adds with [`--mcp-config`](https://code.claude.com/docs/en/cli-reference#cli-flags) that isn't in the update. Requires Claude Code v2.1.299 or later. |
45| `CLAUDE_CODE_REMOTE_MCP_CONFIG` | Path to a file in `CLAUDE_CONFIG_DIR` holding the control plane's delivered MCP servers. If your wrapper rebuilds the child's environment, carry this variable, [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/en/env-vars#variables), and `CLAUDE_CODE_ENVIRONMENT_KIND` over unchanged; the runner sets all three. If `CLAUDE_CODE_REMOTE` arrives but this variable or `CLAUDE_CODE_ENVIRONMENT_KIND` doesn't, the child stops stdio, HTTP, and SSE servers your wrapper adds with [`--mcp-config`](https://code.claude.com/docs/en/cli-reference#cli-flags) that an update of the delivered servers omits. Requires Claude Code v2.1.299 or later. |
4646| `ANTHROPIC_BASE_URL` | The API base URL the child will use, delivered by the control plane per session and normally `https://api.anthropic.com`. Don't override it: the session's inference credential is an Anthropic-issued OAuth token that other providers don't accept. |
4747| `CLAUDE_CODE_OAUTH_TOKEN` | The short-lived OAuth access token the child uses for model inference, with a lifetime of about 30 minutes. The runner re-mints it before expiry and delivers the rotation over the child's stdin, so a wrapper that doesn't [keep stdin attached](#keep-stdin-and-file-descriptor-3-attached) sees only the initial value. Don't rely on your organization's IP allowlist to bound this token's use: treat it as a bearer credential that stays usable for roughly 30 minutes if it leaks, and don't log it, write it to disk, or forward it outside the session container. |
4848| `CLAUDE_RUNNER_ALIVE_EVERY_MS` | The runner sets how often, in milliseconds, the child reports that it's alive when a [turn starts before the child initializes](https://code.claude.com/docs/en/self-hosted-environments-reference.md#session-startup-timeout). If your wrapper rebuilds the child's environment, carry this variable over, or the runner can release the session during that turn and log `no child output for <n> — releasing`. Requires v2.1.309 or later on the runner and child. |
from line 824
824824
825825A self-hosted session has no terminal attached, so an unanswered permission prompt stalls the turn until the user responds in the UI. Anthropic's control plane sends each session's tool list and permission rules with the work payload; the default configuration pre-approves routine tool calls, including `Bash`, and cloud sessions [pre-approve file edits regardless of mode](https://code.claude.com/docs/en/permission-modes.md#switch-permission-modes). A call that nothing pre-approves prompts through the session UI.
826826
827### Pin a permission mode from your wrapper
828
827829> [!NOTE]
828830>
829831> Only pin auto mode on an environment whose session containers run with [default-deny network egress](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#default-deny-egress) and the rest of the [hardening section](https://code.claude.com/docs/en/self-hosted-environments-deploy.md#harden-your-deployment) in place. Routine tool calls, including `Bash` network requests, run without a human in the loop on both the default pre-approved tool set and in auto mode, so the network boundary is what limits where those calls can reach.
830832
831To keep prompts to a minimum regardless of what the control plane sends, pin [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) from your wrapper script or [`command` hook](#command). Auto mode lets sessions run without routine permission prompts: a separate classifier model reviews actions before they run and blocks the ones it rejects, and explicit ask rules still force a prompt; the permission modes page covers what the classifier checks. The runner appends server-computed flags before invoking the wrapper, and for single-value flags such as `--permission-mode` the parser honors the last occurrence, so a flag you append after `"$@"` overrides the server-sent value:
833To start sessions in [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) until claude.ai/code or another client sets a permission mode for them, pin it from your wrapper script or [`command` hook](#command). The runner invokes the wrapper with its own flags as arguments, and Claude Code applies the last `--permission-mode` on the command line, so append yours after `"$@"`:
832834
833835```bash theme={null}
834836#!/bin/bash
from line 837
835837exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto
836838```
837839
838To pre-approve specific tools instead, append `--allowed-tools` with your rules, for example `--allowed-tools "Bash(bazel *) Bash(yarn *) mcp__internal__*"`. List flags such as `--allowed-tools` and `--disallowed-tools` accumulate across occurrences rather than overriding, so your rules apply on top of any rules the control plane sends. To narrow, append `--disallowed-tools`, which denies tools even if another rule allows them.
840Once a client sets a mode, your appended mode no longer applies, even after the session restarts on the runner. claude.ai/code, for example, sets one with the session's first message when its mode dropdown shows Auto, or when someone picked a mode there.
841
842In auto mode, a separate classifier model reviews actions before they run and blocks the ones it rejects. An explicit ask rule still forces a prompt. A call that a [deny rule](https://code.claude.com/docs/en/permissions.md#manage-permissions) blocks stays blocked in every mode.
843
844### Pre-approve specific tools
845
846To pre-approve specific tools, append `--allowed-tools` with your rules after `"$@"` in your wrapper script, for example `--allowed-tools "Bash(bazel *) Bash(yarn *) mcp__internal__*"`. List flags such as `--allowed-tools` and `--disallowed-tools` accumulate across occurrences rather than overriding, so your rules apply on top of any rules the control plane sends. To narrow, append `--disallowed-tools`, which denies tools even if another rule allows them.
839847
840848### How each session's config is assembled
841849
slack Changed · +8 / -11 lines
from line 16
1616
1717## Use cases
1818
19* **Bug investigation and fixes**: Ask Claude to investigate and fix bugs as soon as they're reported in Slack channels.
20* **Quick code reviews and modifications**: Have Claude implement small features or refactor code based on team feedback.
21* **Collaborative debugging**: When team discussions provide crucial context (for example, error reproductions or user reports), Claude can use that information to inform its debugging approach.
19* **Bug investigation and fixes**: Describe a bug and ask Claude to investigate and fix it.
20* **Quick code reviews and modifications**: Have Claude implement small features or refactor code.
2221* **Parallel task execution**: Kick off coding tasks in Slack while you continue other work, receiving notifications when complete.
2322
2423## Prerequisites
from line 86
8786
8887### Context gathering
8988
90**From threads**: When you @mention Claude in a thread, it gathers context from all messages in that thread to understand the full conversation.
89* **From threads**: when you first @mention Claude in a thread, it gathers context from your messages and its own in that thread.
90* **From channels**: when you @mention Claude directly in a channel, it looks at your recent messages and its own in that channel, and at the channel's name, topic, and description.
9191
92**From channels**: When mentioned directly in a channel, Claude looks at recent channel messages for relevant context.
92This context helps Claude understand the problem, select the appropriate repository, and inform its approach to the task. To give Claude something a teammate wrote, such as an error report, paste its text into the message where you @mention Claude.
9393
94This context helps Claude understand the problem, select the appropriate repository, and inform its approach to the task.
95
9694> [!WARNING]
9795>
9896> When @Claude is invoked in Slack, Claude is given access to the conversation context to better understand your request. Claude may follow directions from other messages in the context, so users should make sure to only use Claude in trusted Slack conversations.
from line 156
158156### Writing effective requests
159157
160158* **Be specific**: Include file names, function names, or error messages when relevant.
161* **Provide context**: Mention the repository or project if it's not clear from the conversation.
159* **Provide context**: Mention the repository or project.
162160* **Define success**: Explain what "done" looks like. Should Claude write tests? Update documentation? Create a PR?
163* **Use threads**: Reply in threads when discussing bugs or features so Claude can gather the full context.
164161
165162### When to use Slack vs. web
166163
167**Use Slack when**: Context already exists in a Slack discussion, you want to start a task asynchronously, or you're collaborating with teammates who need visibility.
164**Use Slack when**: You want to start a task asynchronously, or you're collaborating with teammates who need visibility.
168165
169166**Use the web directly when**: You need to upload files, want real-time interaction during development, or are working on longer, more complex tasks.
170167
terminal-config Changed · +4 / -4 lines
from line 70
7070
7171By default, Claude Code sends a desktop notification in some terminals, and a bell character or nothing in others:
7272
73* **Ghostty, Kitty, and iTerm2**: a desktop notification, which iTerm2 shows only after you turn on its alert settings.
73* **Ghostty, Kitty, and iTerm2, when Claude Code detects them**: a desktop notification, which iTerm2 shows only after you turn on its alert settings.
7474* **Apple Terminal**: no sound; a silent bell character when Claude Code finds "Audible bell" off in the front Terminal window's profile, otherwise nothing. That bell character shows as a window flash, or a Dock bounce while Terminal is in the background, if that profile's "Visual bell" or Dock bounce option is on.
7575* **Other terminals**: nothing.
7676
from line 82
8282}
8383```
8484
85The desktop notification reaches your local machine over SSH, so a remote session can still alert you. Ghostty and Kitty forward it to your OS notification center without further setup. iTerm2 requires you to enable forwarding:
85Over SSH from a terminal running outside tmux, set [`preferredNotifChannel`](https://code.claude.com/docs/en/settings-reference#preferrednotifchannel) to your local terminal's value, `"iterm2"`, `"kitty"`, or `"ghostty"`, on the machine running Claude Code. The desktop notification then reaches your local machine. Ghostty and Kitty forward it to your OS notification center without further setup. iTerm2 requires you to enable forwarding:
8686
8787**1. Open iTerm2 notification settings**
8888
from line 127
127127
128128## Configure tmux
129129
130When Claude Code runs inside tmux, by default Shift+Enter submits instead of inserting a newline, and desktop notifications and the [progress bar](https://code.claude.com/docs/en/settings-reference.md#terminalprogressbarenabled) never reach the outer terminal. Add these lines to `~/.tmux.conf`, then run `tmux source-file ~/.tmux.conf` to apply them to the running server:
130When Claude Code runs inside tmux, by default Shift+Enter submits instead of inserting a newline, and desktop notifications don't reach the outer terminal. Add these lines to `~/.tmux.conf`, then run `tmux source-file ~/.tmux.conf` to apply them to the running server:
131131
132132```bash ~/.tmux.conf theme={null}
133133set -g allow-passthrough on
from line 136
136136set -as terminal-features 'xterm*:extkeys'
137137```
138138
139The `allow-passthrough` line lets notifications and progress updates reach the outer terminal instead of being swallowed by tmux. The `extended-keys` lines let tmux distinguish Shift+Enter from plain Enter so the newline shortcut works.
139To send notifications from a visible pane to the outer terminal, keep the `allow-passthrough` line and set [`preferredNotifChannel`](https://code.claude.com/docs/en/settings-reference#preferrednotifchannel) to `"iterm2"`, `"kitty"`, or `"ghostty"`. With this sample, a pane in a window you aren't viewing sends none. The `extended-keys` lines let tmux distinguish Shift+Enter from plain Enter so the newline shortcut works.
140140
141141A [mod's `Image`](https://code.claude.com/docs/en/plugins/mods/reference#elements) needs the `allow-passthrough` and `focus-events` lines, along with the other [requirements for drawing inside tmux](https://code.claude.com/docs/en/plugins/mods/gallery.md#draw-an-image-inside-tmux). After you add the lines, also detach from tmux, attach again, and restart Claude Code.
142142
web-quickstart Changed · +4 / -2 lines
from line 238
238238
239239### Setup script failed
240240
241The setup script exited with a non-zero status, which blocks the session from starting. Common causes:
241The [setup script](https://code.claude.com/docs/en/cloud-environments.md#setup-scripts) exited with a non-zero status, so the session failed to start or started without whatever the script failed to install. If the session started, you can keep working in it.
242242
243Common causes:
244
243245* A package install failed because the registry isn't in your [network access level](https://code.claude.com/docs/en/cloud-environments.md#access-levels). `Trusted` covers most package managers; `None` blocks them all.
244246* The script references a file or path that doesn't exist in a fresh clone.
245247* A command that works locally needs a different invocation on Ubuntu.
246248
247To debug, add `set -x` at the top of the script to see which command failed. For non-critical commands, append `|| true` so they don't block session start.
249To debug, add `set -x` at the top of the script to see which command failed. For non-critical commands, append `|| true` so they don't fail the script. After you fix the cause, start a new session so the script runs again. If what failed to start was a run of a [cloud scheduled task](https://code.claude.com/docs/en/routines.md), click **Run now** on the task's detail page instead of starting a new session.
248250
249251### New sessions hang or time out during setup
250252
agent-teams Changed · +1 / -1 lines
from line 292
292292>
293293> To have it ask before it edits, press Enter on the `main` row in the agent panel and switch the lead to Manual mode too. The lead then asks too, as does any other teammate in Manual mode.
294294
295You can't set per-teammate permission modes at spawn time. A new teammate starts with the lead's mode, including `bypassPermissions` mode, which `--dangerously-skip-permissions` turns on. If the lead is in [`dontAsk` mode](https://code.claude.com/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), the teammate starts in [Manual mode](https://code.claude.com/docs/en/permission-modes.md#available-modes) instead.
295You can't set per-teammate permission modes at spawn time. A new teammate starts with the lead's mode, including `bypassPermissions` mode, which `--dangerously-skip-permissions` turns on. If the lead is in [`dontAsk` mode](https://code.claude.com/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), the teammate starts in [Manual mode](https://code.claude.com/docs/en/permission-modes.md#available-modes) instead. For a split-pane teammate of a lead in Manual or `dontAsk` mode, this requires Claude Code v2.1.317 or later.
296296
297297An [in-process](#choose-a-display-mode) teammate runs under the lead's live allow and deny rules, so [`--disallowedTools`](https://code.claude.com/docs/en/cli-reference#cli-flags), `--tools`, and `--allowedTools` all apply to it. For a split-pane teammate, check each flag:
298298
channels Changed · +1 / -1 lines
from line 350
350350| Feature | What it does | Good for |
351351| - | - | - |
352352| [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) | Run tasks in a fresh cloud sandbox, cloned from GitHub | Delegating self-contained async work you check on later |
353| [Claude in Slack](https://code.claude.com/docs/en/slack.md) | Spawns a cloud session from an `@Claude` mention in a channel or thread | Starting tasks directly from team conversation context |
353| [Claude in Slack](https://code.claude.com/docs/en/slack.md) | Spawns a cloud session from an `@Claude` mention in a channel or thread | Starting tasks directly from a team conversation |
354354| Standard [MCP server](https://code.claude.com/docs/en/mcp.md) | Claude queries it during a task; nothing is pushed to the session | Giving Claude on-demand access to read or query a system |
355355| [Remote Control](https://code.claude.com/docs/en/remote-control.md) | You drive your local session from claude.ai or the Claude mobile app | Steering an in-progress session while away from your desk |
356356
claude-apps-gateway-config Changed · +1 / -1 lines
from line 1647
16471647| `reply_tokens` | No | Default `750`. Roughly how many tokens of text each canned reply carries, a whole number from 1 to 100000. |
16481648| `reply_seconds` | No | Default `9.5`. How long a streamed reply takes, from 0 to 600. `0` sends the whole reply at once. A reply to a non-streaming request always comes back at once. |
16491649
1650A load test in this mode covers the gateway, your Postgres, and everything in front of the gateway. It doesn't cover the provider's limits, speed, or network path.
1650A load test in this mode covers the gateway, your Postgres, and everything in front of the gateway. It doesn't cover the provider's limits, speed, and network path, or the wait at each replica's [limit on concurrent upstream requests](https://code.claude.com/docs/en/claude-apps-gateway-deploy.md#concurrent-upstream-requests). A replica still logs the `client requests are open` warning when more requests are open than that limit, the point where production requests start to wait.
16511651
16521652No model request is sent to the provider, so a replica's CPU per request is an estimate and reads lower than production, which also encrypts its traffic to the provider. Confirm a replica count with a small pilot against the real provider. Before v2.1.283, the estimate reads much lower.
16531653
claude-apps-gateway-deploy Changed · +2 / -0 lines
from line 198
198198>
199199> Every open request holds memory in the gateway process while it streams and while it waits for a slot. If you keep the limit at 256, memory on an overloaded replica still grows, because waiting requests keep their request bodies. Size the container's memory for the number of requests open at peak, and watch memory when you change the limit. A replica that runs out of memory is killed and drops every stream it holds.
200200
201In a load test with [`load_test_mode`](https://code.claude.com/docs/en/claude-apps-gateway-config#load_test_mode), requests don't wait at this limit, but a replica still logs the `client requests are open` warning.
202
201203### Keep `API_TIMEOUT_MS` above the gateway's time to first byte
202204
203205If you lower [`API_TIMEOUT_MS`](https://code.claude.com/docs/en/network-config#streaming-idle-watchdogs) to retry an unanswered request sooner, keep it above the time the gateway takes to send the first bytes of a streaming response. A request that waits longer times out, and so does each retry that waits as long, until the turn ends with `Request timed out` unless the [first-byte deadline](#retry-an-unanswered-request-sooner-with-the-first-byte-deadline) ends it.
claude-apps-gateway-on-aws Changed · +1 / -0 lines
from line 624
624624
625625* [Configuration reference](https://code.claude.com/docs/en/claude-apps-gateway-config.md): every `gateway.yaml` option, including `managed.policies` and `telemetry`
626626* [Deployment and operations](https://code.claude.com/docs/en/claude-apps-gateway-deploy.md): IdP setup, health checks, JWT secret rotation, upgrades, and the security model
627* [Load-test mode](https://code.claude.com/docs/en/claude-apps-gateway-config.md#load_test_mode): load testing a gateway without calling a model provider
627628* [Claude apps gateway overview](https://code.claude.com/docs/en/claude-apps-gateway): quickstart and connecting developers
628629* [AWS samples for Claude apps gateway](https://github.com/aws-samples/anthropic-on-aws/tree/main/claude-apps-gateway): AWS-maintained deployment samples covering a range of customer environments
629630
claude-apps-gateway-on-gcp Changed · +1 / -0 lines
from line 312
312312
313313* [Configuration reference](https://code.claude.com/docs/en/claude-apps-gateway-config.md): every `gateway.yaml` option, including `managed.policies` and `telemetry`
314314* [Deployment and operations](https://code.claude.com/docs/en/claude-apps-gateway-deploy.md): IdP setup, health checks, JWT secret rotation, upgrades, and the security model
315* [Load-test mode](https://code.claude.com/docs/en/claude-apps-gateway-config.md#load_test_mode): load testing a gateway without calling a model provider
315316* [Claude apps gateway overview](https://code.claude.com/docs/en/claude-apps-gateway): quickstart and connecting developers
316317
cloud-environments Changed · +1 / -1 lines
from line 441
441441
442442A setup script has four constraints to write around:
443443
444* **Exit zero**: if the script exits non-zero, the session fails to start. Append `|| true` to non-critical commands so an intermittent install failure doesn't block the session.
444* **Exit zero**: if the script exits non-zero, the session [fails to start](https://code.claude.com/docs/en/web-quickstart.md#setup-script-failed) or starts without whatever the script failed to install. Append `|| true` to non-critical commands so an intermittent install failure doesn't fail the script.
445445* **Finish within five minutes**: keep the script's total runtime under roughly five minutes so the [environment cache](#environment-caching) can build. When setup takes longer than that, the environment isn't cached. Run independent installs in parallel with `&` and `wait`, and move any single download that won't fit into a [SessionStart hook](#setup-scripts-vs-sessionstart-hooks) that launches it in the background. If new sessions stall or fail during setup, see [New sessions hang or time out during setup](https://code.claude.com/docs/en/web-quickstart.md#new-sessions-hang-or-time-out-during-setup).
446446* **Network access for installs**: package installs need to reach registries. The default **Trusted** level covers [common package registries](#default-allowed-domains) including npm, PyPI, RubyGems, and crates.io; with **None** network access, installs fail.
447447* **The environment's variables aren't set yet**: the script runs before the session sets the environment's [environment variables](#set-environment-variables). Set any value the script needs in the script itself.
settings-reference Changed · +2 / -2 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.