One read of Claude Code CLIclaude-code-20261021T023701Z
13 pages moved out of 228 read.
Pages moved
13
significant first
Pages read
228
in this capture
Captured
02:37 UTC
Corpus hash
a9d1686d850a
corpus-hash
What this read moved
1-13 of 13code-review-customize Changed · +40 / -2 lines
### Include other files in REVIEW\.md
from line 88
8888
8989Keep `REVIEW.md` to instructions that change review behavior, and leave general project context in `CLAUDE.md`.
9090
91### Include other files in REVIEW\.md
92
93You can split review instructions across several files and pull them into your root `REVIEW.md`. Use this when `REVIEW.md` grows long or when you already keep review rules in another file.
94
95To include a file, add a line to the root `REVIEW.md` with only `@` and the file name on it. Code Review puts the file's contents in place of that line, so they apply as part of `REVIEW.md`. In this example, the root file gives one instruction of its own and then includes two rule files:
96
97```markdown theme={null}
98# Review instructions
99
100Report at most five Nits per review.
101
102@review-security.md
103@review-api.md
104```
105
106Save the included files at the repository root, beside `REVIEW.md`:
107
108```text theme={null}
109your-repo/
110├── REVIEW.md
111├── review-security.md
112└── review-api.md
113```
114
115Code Review includes the files when it reads `REVIEW.md` from a protected branch, so check [which branch a review reads for your repository](#what-a-review-reads-for-each-branch-setup):
116
117* **Protected branch**: Code Review puts the included file in place of its `@` line
118* **Unprotected default branch**: the `@` line stays in `REVIEW.md` as plain text. If the pull request changes the file the line names, the line is left out.
119
120When a review doesn't apply an included file, check each of these:
121
122* **Location**: move the file to the repository root. A path into a subdirectory such as `@docs/review-rules.md` isn't included.
123* **Name**: match the file name exactly, including case, and use a name without spaces. A line whose name matches no file beside `REVIEW.md` stays in `REVIEW.md` as plain text, and the check run doesn't report it as a skipped include.
124* **One level**: list every file in the root `REVIEW.md`. An `@` line in an included file or in a subdirectory `REVIEW.md` stays as plain text, and a Markdown link to another file isn't an include.
125* **Limits**: include at most eight different files, and keep `REVIEW.md` and the files it includes under 150,000 bytes combined. A file that would reach the byte limit is skipped whole, not cut short. The check run reports how many include lines it skipped for either limit.
126* **Links**: keep Markdown links at 64 or fewer across `REVIEW.md` and the files it includes. Links to `http`, `https`, or `mailto` addresses and to `#` anchors don't count. Past that limit, the review skips your whole root `REVIEW.md`, not only the included files. The check run then [says the instructions weren't applied](/docs/en/code-review-troubleshooting#the-check-run-mentions-review-md).
127* **Merged copy**: merge the included file into the [branch `REVIEW.md` is read from](#which-branch-review-md-is-read-from). The review reads both from the same commit, never from the pull request's own changes.
128
91129### Which branch REVIEW\.md is read from
92130
93131Code Review reads `REVIEW.md` from the pull request's base branch or from the default branch, never from the pull request's own changes. To change review behavior, merge the `REVIEW.md` change first.
from line 151
113151
114152| Branch protection | Copy read | Files read |
115153| :- | :- | :- |
116| The default branch is protected, and the pull request targets it or targets a branch no ruleset protects | Default branch | Root and subdirectory files |
117| The pull request targets another branch that a ruleset protects | That base branch | Root and subdirectory files |
154| 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 |
155| The pull request targets another branch that a ruleset protects | That base branch | Root file, the files it includes, and subdirectory files |
118156| The default branch isn't protected, and the base branch has no protection rule of either kind | Default branch | Root file |
119157| 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 |
120158
code-review-troubleshooting Changed · +5 / -1 lines
from line 62
6262
6363## The check run mentions REVIEW\.md
6464
65Two of the messages a check run can carry about `REVIEW.md` concern branch protection:
65These are three of the messages a check run can carry about `REVIEW.md`:
6666
6767* **"This review applied the repository's review instructions (REVIEW\.md) from its default branch, which is not protected against direct pushes."**: the review read the root file only. See [Which branch REVIEW.md is read from](/docs/en/code-review-customize#which-branch-review-md-is-read-from) for what protecting the branch changes.
6868* **"were not applied to this review: branch protection could not be confirmed"**: the review read no `REVIEW.md`.
69* **"they link to a file this pull request modifies, or carry more links than the review checks"**: the review skipped the root `REVIEW.md`, or the number of subdirectory `REVIEW.md` files the message gives. Check the skipped file for each cause. For the root `REVIEW.md`, check the [files it includes](/docs/en/code-review-customize#include-other-files-in-review-md) too:
70 * **Too many links**: it carries more than 64 Markdown links. Cut links to [64 or fewer](/docs/en/code-review-customize#include-other-files-in-review-md).
71 * **A link the review can't parse**: it has a malformed Markdown link. Fix or remove the link.
72 * **A link to a changed file**: it links to a file or folder this pull request changes, and the review couldn't leave out only the lines with that link. Write the rule in `REVIEW.md` itself.
6973
7074## Setup problems
7175
llm-gateway-protocol Changed · +5 / -3 lines
from line 227
227227
228228### Automatic retry and error forwarding
229229
230When the upstream rejects one of these capabilities, Claude Code can retry the request on its own without the rejected part:
230When the upstream rejects one of these capabilities, Claude Code can retry the request on its own with the rejected part removed or changed:
231231
232* When the upstream rejects the `thinking` field, a mid-conversation system message, or the `cache_control` marker on such a message, Claude Code retries the request and disables the rejected capability for the rest of the conversation
232* When a `400` says the `thinking.type` value `enabled` or `adaptive` isn't supported, Claude Code retries once with the other type and keeps the `thinking` field. Later requests to that model keep the switched type until Claude Code exits. Before v2.1.121, Claude Code didn't retry, so [`thinking.type.enabled is not supported`](/docs/en/errors#thinking-type-enabled-is-not-supported-for-this-model) reached the developer
233* When the upstream rejects a `role: "system"` entry inside `messages`, Claude Code retries once without those mid-conversation system messages and carries their text in user messages instead. Later requests in the conversation keep that shape until the developer runs `/clear` or the conversation compacts
234* When the upstream rejects only the `cache_control` marker on a mid-conversation system message, Claude Code keeps the system messages and retries once with the marker moved. The marker goes on the last entry in `messages` that isn't a system message, in that retry and in later requests until Claude Code exits
233235* When the upstream rejects a [thinking signature](https://platform.claude.com/docs/en/build-with-claude/extended-thinking), including with a `400` whose message says the block is `bound to a different conversation`, Claude Code removes earlier thinking blocks from the request, retries, and keeps them out of every later request. New responses still include thinking
234236* When the gateway or its upstream rejects the [advisor tool](/docs/en/advisor) entry in `tools` as an unrecognized tool type, Claude Code retries the request once without that entry and its `anthropic-beta` value. Later requests to that base URL leave the advisor out until Claude Code exits, and `/advisor` is unavailable to the developer for that time. Claude Code recognizes this rejection by a `400` or `422` response whose message names the tool type after `Input tag`, such as `Input tag 'advisor_20260301'`. Before v2.1.280, Claude Code didn't retry this rejection
235237* When the upstream rejects `output_config.effort`, Claude Code retries the request without effort and leaves it out of later requests to that model until Claude Code exits. Claude Code recognizes this rejection by a `400` whose message names `output_config.effort` together with `Extra inputs are not permitted`, or says the model doesn't support the effort parameter
plugins/mods/api Changed · +36 / -0 lines
from line 207
207207| `$.ui.status(text)` | One line under the prompt that stays until you change it. It starts with `⚠` and the mod's name, as in `⚠ my-mod: checks: 3 passing`. |
208208| `$.ui.toast(text)` | A toast notification with the mod's name that disappears after a few seconds. It's a box at the top right in [fullscreen rendering](/docs/en/fullscreen), and one line at the right under the prompt in the classic renderer. |
209209| `$.ui.log(text)` | A dim line in the transcript that Claude doesn't read. It starts with `●` and the mod's name, as in `● my-mod: build finished`. |
210| `$.ui.notify(text)` | A notification from their terminal, outside Claude Code, sent the way their [`preferredNotifChannel`](/docs/en/settings-reference#preferrednotifchannel) setting says. The mod's name is its title unless you pass a non-empty `{ title }`, which is shown as you give it. |
211
212`$.ui.notify` is the only one of these that answers. It resolves to `{ isSent: true, channel }` when the user's channel wrote the notification to their terminal. `channel` is the setting's value that sent it, such as `kitty` or `terminal_bell`. The `terminal_bell` channel rings the bell and shows neither your text nor the title.
213
214Otherwise the call resolves to `{ isSent: false, reason }`:
215
216| `reason` | Meaning |
217| :- | :- |
218| `disabled` | The user set `preferredNotifChannel` to `notifications_disabled` |
219| `no-channel` | The setting is `auto` and their terminal has no notification Claude Code can send |
220| `no-surface` | The session has no terminal, as in a `-p` run, the Agent SDK, the desktop app, the VS Code extension, or a cloud session. Also the answer to a call made before the session starts, while your mod is loading, and to a call made while Claude Code is exiting |
221| `refused` | Another mod's hook on `ui.notify` answered in Claude Code's place without sending |
222
223The call rejects instead of resolving when `text` isn't a string, when another mod's hook on `ui.notify` returns `{ deny }`, or when writing to the terminal fails.
224
225Your mod can't choose the channel, and Claude Code doesn't limit how often a mod notifies. The user's setting is the only switch.
226
227When the call reaches a running session, the user's [`Notification` hooks](/docs/en/hooks#notification) run with the type `plugin_notification`. They run even when the answer is `disabled`, and in a session with no terminal, where the answer is `no-surface`. No hook runs for a call made before the session starts or while Claude Code is exiting. The hook your mod called `$.ui.notify` from is left out of that run, so a `classic.Notification` hook that notifies isn't called again for its own notification.
228
229A terminal doesn't report whether it showed the notification, so `isSent: true` means it was sent, not that the user saw it.
230
231This example notifies when the main conversation's turn ends without an interruption, and falls back to a toast when no notification with text went out. It doesn't wait for the notification before passing the event on, because the user's `Notification` hooks run first and can take a while:
232
233```javascript theme={null}
234on('turn.complete', ($, e, next) => {
235 const isMainTurn = e.agentId === undefined && !e.isAborted
236 const fallBack = () => $.ui.toast('Turn finished')
237 if (isMainTurn) {
238 $.ui.notify('Turn finished').then(sent => {
239 const hasText = sent.isSent && sent.channel !== 'terminal_bell'
240 if (!hasText) fallBack()
241 }, fallBack)
242 }
243 return next(e)
244})
245```
210246
211247In the [VS Code extension](/docs/en/plugins/mods/interface#draw-in-the-vs-code-extension), status lines and toasts show above the prompt box instead, and log lines in the conversation.
212248
agent-sdk/hooks Changed · +1 / -0 lines
from line 634
634634
635635* [`permission_prompt`](/docs/en/hooks#notification) once a permission request has waited about six seconds on your [`canUseTool` callback](/docs/en/agent-sdk/user-input). Requires TypeScript Agent SDK v0.3.233 or later, or Python Agent SDK v0.2.139 or later
636636* `elicitation_complete` and `elicitation_response` for user-prompt elicitation flows
637* `plugin_notification` when a [mod](/docs/en/plugins/mods/api#show-something-without-starting-a-turn) calls `$.ui.notify`
637638
638639Claude Code emits the other types, such as `idle_prompt`, `auth_success`, and `elicitation_dialog`, from interactive UI that SDK sessions don't run.
639640
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.
cross-session-messaging Changed · +1 / -1 lines
from line 224
224224* **Before the deadline**: if a mode or settings change allows the message, Claude Code delivers it.
225225* **Past the deadline**: Claude Code drops the message and reports it as expired to a sender it can reach.
226226
227Set `dialogExpiry` to `"never"` to keep default-held messages until the session ends. A message held by an explicit `hold` setting doesn't expire; Claude Code delivers it only when an `accept` later applies.
227Set `dialogExpiry` to `"never"` to keep default-held messages until the session ends. A message held by an explicit `hold` setting doesn't expire; Claude Code delivers it when an `accept` later applies.
228228
229229To let a `-p` worker take messages unattended, start it with `crossSessionInbound` set to `accept` in its `--settings` value. An `accept` in your user settings also works but applies to every session you run.
230230
hooks Changed · +2 / -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.
from line 290
290290| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact`, `fork` |
291291| `Setup` | which CLI flag triggered setup | `init`, `maintenance` |
292292| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` |
293| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` |
293| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`, `plugin_notification` |
294294| `SubagentStart` | agent type | `general-purpose`, `Explore`, `Plan`, custom agent names, or plugin-scoped names like `^my-plugin:reviewer$` |
295295| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` |
296296| `PreModelSwitch`, `PostModelSwitch` | canonical name of the model the session switches to, as described under [PreModelSwitch](#premodelswitch) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |
from line 2425
24252425| `quota_auto_resume_fired` | Claude Code continues your task after a claude.ai usage limit paused it: at the reset, or sooner when something you do in Claude Code during the wait, such as adding usage credits, upgrading your plan, or switching models, makes usage available again, with the [model-setting exception](/docs/en/interactive-mode#wait-for-a-usage-limit-to-reset) |
24262426| `quota_auto_resume_stale` | A claude.ai usage limit reset while your computer slept for more than about 30 minutes. Claude Code waits for you to press `Enter` instead of continuing. After a shorter sleep it continues and fires `quota_auto_resume_fired` instead |
24272427| `quota_auto_resume_disabled` | Claude Code ends its wait for a claude.ai usage limit without continuing your task: [`autoContinueAtUsageLimit`](/docs/en/settings-reference#autocontinueatusagelimit) turned off or the reset moved more than 24 hours away during a wait Claude Code started on its own, the continued task kept hitting the limit, or the continuation was blocked before it reached the model. Doesn't fire when you press `Esc` or `Ctrl+C`, or pick **Don't continue automatically** |
2428| `plugin_notification` | A [mod](/docs/en/plugins/mods/api#show-something-without-starting-a-turn) raises a notification with `$.ui.notify`. The hook's `title` is the mod's name unless the mod set one |
24282429
24292430The `quota_auto_resume_fired`, `quota_auto_resume_stale`, and `quota_auto_resume_disabled` types require Claude Code v2.1.234 or later.
24302431
from line 4054
40534054
40544055Claude Code validates that JSON response against the same [output schema](#json-output) as synchronous hooks, and drops any field whose value has the wrong type, such as a `systemMessage` that isn't a string, instead of delivering it. Run with `--debug` to see a warning naming each dropped field.
40554056
4056Async hook completion notifications are suppressed by default. To see them, enable verbose mode with `Ctrl+O` or start Claude Code with `--verbose`.
4057
4058### Run tests after file changes
4059
4060This hook starts a test suite in the background whenever Claude writes a f
4057Async hook completion notificat
hooks-guide Changed · +2 / -1 lines
from line 189
189189| `quota_auto_resume_fired` | Claude Code continues your task after a claude.ai usage limit paused it: at the reset, or sooner when something you do in Claude Code during the wait, such as adding usage credits, upgrading your plan, or switching models, makes usage available again, with the [model-setting exception](/docs/en/interactive-mode#wait-for-a-usage-limit-to-reset) |
190190| `quota_auto_resume_stale` | A claude.ai usage limit reset while your computer slept for more than about 30 minutes. Claude Code waits for you to press `Enter` instead of continuing. After a shorter sleep it continues and fires `quota_auto_resume_fired` instead |
191191| `quota_auto_resume_disabled` | Claude Code ends its wait for a claude.ai usage limit without continuing your task: [`autoContinueAtUsageLimit`](/docs/en/settings-reference#autocontinueatusagelimit) turned off or the reset moved more than 24 hours away during a wait Claude Code started on its own, the continued task kept hitting the limit, or the continuation was blocked before it reached the model. Doesn't fire when you press `Esc` or `Ctrl+C`, or pick **Don't continue automatically** |
192| `plugin_notification` | A [mod](/docs/en/plugins/mods/api#show-something-without-starting-a-turn) raises a notification with `$.ui.notify`. The hook's `title` is the mod's name unless the mod set one |
192193
193194Claude Code times `permission_prompt` differently in a terminal and in Claude Desktop, the VS Code extension, and other hosts that answer permission requests through the Agent SDK. See [when each notification type fires](/docs/en/hooks#notification) for both timings.
194195
from line 683
682683| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact`, `fork` |
683684| `Setup` | which CLI flag triggered setup | `init`, `maintenance` |
684685| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` |
685| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` |
686| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`, `plugin_notification` |
686687| `SubagentStart` | agent type | `general-purpose`, `Explore`, `Plan`, or custom agent names |
687688| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` |
688689| `PreModelSwitch`, `PostModelSwitch` | canonical name of the model the session switches to, as described under [PreModelSwitch](/docs/en/hooks#premodelswitch) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |
plugins/mods/reference Changed · +1 / -1 lines
from line 198
198198| Namespace | Methods |
199199| :- | :- |
200200| `$.plugin` | `name`, `root`: this plugin's name and directory |
201| [`$.ui`](/docs/en/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit` |
201| [`$.ui`](/docs/en/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit` |
202202| [`$.command`](/docs/en/plugins/mods/api#add-a-command) | `register`, `run`, `list` |
203203| [`$.tool`](/docs/en/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list` |
204204| `$.agent` | `register`, `spawn`, `list`. `list()` returns this session's subagents and teammates, each with a `status` of `pending`, `running`, `waiting`, `idle`, `completed`, `failed`, or `killed`, where `idle` and `waiting` require Claude Code v2.1.289 or later. |
plugins/mods/test Changed · +1 / -0 lines
from line 183
183183| `prompt.fill` | `() => ({ isFilled: true })` |
184184| `$.prompt.read` | `() => ({ value: { text: '...', cursor: 0 } })` |
185185| `$.ui.copy` | `() => ({ value: { isCopied: true } })` |
186| `$.ui.notify` | `() => ({ value: { isSent: true, channel: 'terminal_bell' } })`. The text is `e.text` and the title is `e.title`. |
186187| `$.session.messages` | `() => ({ value: [{ role: 'assistant', text: '...', toolUses: [] }] })` |
187188| `$.session.id`, `$.agent.list` | `() => ({ value: 'abc123' })`, `() => ({ value: [] })` |
188189| `session.send` | `() => ({ isDelivered: true })`. `e.to` arrives as a string even when your mod passed `{ sessionId }`. |
prompt-caching Changed · +1 / -1 lines
from line 51
5151When your requests pass through an [LLM gateway](/docs/en/llm-gateway), a custom `ANTHROPIC_BASE_URL`, or a cloud provider base-URL override such as [`ANTHROPIC_BEDROCK_BASE_URL`](/docs/en/env-vars), what stays cached depends on how the gateway handles the [`cache_control` markers](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) Claude Code sends:
5252
5353* **Forwards them unchanged**: the block and your conversation cache the same as at the provider's own endpoint.
54* **Rejects the marked request with a `400` error naming `cache_control`**: Claude Code re-sends the request with the marker moved off the block and onto your last conversation message, and keeps it there for the rest of the conversation. The block bills as uncached input; your conversation stays cached.
54* **Rejects the marked request with a `400` error naming `cache_control`**: Claude Code re-sends the request with the marker moved off the block and onto your last conversation message, and keeps it there until Claude Code exits. The block bills as uncached input; your conversation stays cached.
5555* **Removes the markers while returning success**: your entire conversation history bills as uncached input on every turn. A gateway that converts block-form system content to a plain string drops the marker the same way.
5656
5757For what each provider stores and processes, see [data usage](/docs/en/data-usage). Wherever the cache lives, entries expire after a period of inactivity, and [Cache lifetime](#cache-lifetime) below covers the TTL and how to extend it.
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.
from line 721
721721
722722### `showThinkingSummaries`
723723
724See summaries of Claude's [extended thinking](/docs/en/model-config#extended-thinking) in interactive sessions. Set it if you want the full summaries when you expand thinking with `Ctrl+O`. When unset or `false`, the Anthropic API redacts thinking blocks and Claude Code shows a collapsed stub; third-party providers don't redact.
724See summaries of Claude's [extended thinking](/docs/en/model-config#extended-thinking) in interactive sessions. Set it if you want the full summaries when you expand thinking with `Ctrl+O`. When unset or `false`, the Anthropic API redacts thinking blocks and Claude Code shows a collapsed stub.
725725
726726* **Scope**: [`Any file`](#scopes)
727727* **Type**: Boolean
from line 3766
37663766
37673767```json managed-settings.json theme={null}
37683768{
3769 "blo
3769 "blockedMarketplaces": [
3770 { "source":