Documentation 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

4091. **Check your version**: Run `claude --version` to see what's installed.4091. **Check your version**: Run `claude --version` to see what's installed.

4102. **Update Claude Code**:4102. **Update Claude Code**:

411 * **Homebrew**: `brew upgrade claude-code` (or `brew upgrade claude-code@latest` if you installed that cask)411 * **Homebrew**: `brew upgrade claude-code` (or `brew upgrade claude-code@latest` if you installed that cask)

412 * **npm**: `npm update -g @anthropic-ai/claude-code`412 * **npm**: `npm install -g @anthropic-ai/claude-code@latest`

413 * **Native installer**: Re-run the install command from [Setup](/en/setup)413 * **Native installer**: Re-run the install command from [Setup](/en/setup)

4143. **Restart Claude Code**: After updating, restart your terminal and run `claude` again.4143. **Restart Claude Code**: After updating, restart your terminal and run `claude` again.

415 415 

2413```2413```

2414 2414 

2415| Field | Description |2415| Field | Description |

2416| :------- | :--------------------------------------------------------- |2416| :------- | :------------------------------------------------------- |

2417| `ok` | `true` allows the action, `false` prevents it |2417| `ok` | `true` allows the action, `false` blocks it |

2418| `reason` | Required when `ok` is `false`. Explanation shown to Claude |2418| `reason` | Required when `ok` is `false`. Explanation for the block |

2419 

2420What happens on `ok: false` depends on the event:

2421 

2422* `Stop` and `SubagentStop`: the reason is fed back to Claude as its next instruction and the turn continues

2423* `PreToolUse`: the tool call is denied and the reason is returned to Claude as the tool error, equivalent to a command hook's `permissionDecision: "deny"`

2424* `PostToolUse`, `PostToolBatch`, `UserPromptSubmit`, and `UserPromptExpansion`: the turn ends and the reason appears in the chat as a warning line, equivalent to returning `"continue": false` from a command hook

2425* `PostToolUseFailure`, `TaskCreated`, and `TaskCompleted`: the reason is returned to Claude as a tool error, similar to `PreToolUse`

2426* `PermissionRequest`: `ok: false` has no effect. To deny an approval from a hook, use a [command hook](#command-hook-fields) returning `hookSpecificOutput.decision.behavior: "deny"`

2427 

2428If you need finer control on any event, use a [command hook](#command-hook-fields) with the per-event fields described in [Decision control](#decision-control).

2419 2429 

2420### Example: Multi-criteria Stop hook2430### Example: Multi-criteria Stop hook

2421 2431 

735The model's only job is to return a yes/no decision as JSON:735The model's only job is to return a yes/no decision as JSON:

736 736 

737* `"ok": true`: the action proceeds737* `"ok": true`: the action proceeds

738* `"ok": false`: the action is blocked. The model's `"reason"` is fed back to Claude so it can adjust.738* `"ok": false`: what happens depends on the event:

739 * `Stop` and `SubagentStop`: the `reason` is fed back to Claude so it keeps working

740 * `PreToolUse`: the tool call is denied and the `reason` is returned to Claude as the tool error, so it can adjust and continue

741 * `PostToolUse`, `PostToolBatch`, `UserPromptSubmit`, and `UserPromptExpansion`: the turn ends and the `reason` appears in the chat as a warning line

739 742 

740This example uses a `Stop` hook to ask the model whether all requested tasks are complete. If the model returns `"ok": false`, Claude keeps working and uses the `reason` as its next instruction:743This example uses a `Stop` hook to ask the model whether all requested tasks are complete. If the model returns `"ok": false`, Claude keeps working and uses the `reason` as its next instruction:

741 744 

319 319 

320Each project gets its own memory directory at `~/.claude/projects/<project>/memory/`. The `<project>` path is derived from the git repository, so all worktrees and subdirectories within the same repo share one auto memory directory. Outside a git repo, the project root is used instead.320Each project gets its own memory directory at `~/.claude/projects/<project>/memory/`. The `<project>` path is derived from the git repository, so all worktrees and subdirectories within the same repo share one auto memory directory. Outside a git repo, the project root is used instead.

321 321 

322To store auto memory in a different location, set `autoMemoryDirectory` in your user or local settings:322To store auto memory in a different location, set `autoMemoryDirectory` in your user settings at `~/.claude/settings.json`:

323 323 

324```json theme={null}324```json theme={null}

325{325{

327}327}

328```328```

329 329 

330This setting is accepted from policy, local, and user settings. It is not accepted from project settings (`.claude/settings.json`) to prevent a shared project from redirecting auto memory writes to sensitive locations.330The value must be an absolute path or start with `~/`. This setting is accepted from policy and user settings, and from the `--settings` flag. It is not accepted from project or local settings, since both files live inside the project directory and a cloned repository could supply either to redirect auto memory writes to sensitive locations.

331 331 

332The directory contains a `MEMORY.md` entrypoint and optional topic files:332The directory contains a `MEMORY.md` entrypoint and optional topic files:

333 333 

198**`claude_code.tool.blocked_on_user`**198**`claude_code.tool.blocked_on_user`**

199 199 

200| Attribute | Description | Gated by |200| Attribute | Description | Gated by |

201| ------------- | --------------------------------------------------- | -------- |201| ------------- | ------------------------------------------------------------------------- | -------- |

202| `duration_ms` | Time spent waiting for the permission decision | |202| `duration_ms` | Time spent waiting for the permission decision | |

203| `decision` | `accept` or `reject` | |203| `decision` | `accept` or `reject` | |

204| `source` | Decision source, matching the `tool_decision` event | |204| `source` | Decision source, matching the [Tool decision event](#tool-decision-event) | |

205 205 

206**`claude_code.tool.execution`**206**`claude_code.tool.execution`**

207 207 

458* All [standard attributes](#standard-attributes)458* All [standard attributes](#standard-attributes)

459* `tool_name`: Tool name (`"Edit"`, `"Write"`, `"NotebookEdit"`)459* `tool_name`: Tool name (`"Edit"`, `"Write"`, `"NotebookEdit"`)

460* `decision`: User decision (`"accept"`, `"reject"`)460* `decision`: User decision (`"accept"`, `"reject"`)

461* `source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`461* `source`: Where the decision came from. One of `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`. See the [Tool decision event](#tool-decision-event) for what each value means.

462* `language`: Programming language of the edited file, such as `"TypeScript"`, `"Python"`, `"JavaScript"`, or `"Markdown"`. Returns `"unknown"` for unrecognized file extensions.462* `language`: Programming language of the edited file, such as `"TypeScript"`, `"Python"`, `"JavaScript"`, or `"Markdown"`. Returns `"unknown"` for unrecognized file extensions.

463 463 

464#### Active time counter464#### Active time counter

524* `error_type`: Error category string when the tool failed, such as `"Error:ENOENT"` or `"ShellError"`524* `error_type`: Error category string when the tool failed, such as `"Error:ENOENT"` or `"ShellError"`

525* `error` (when `OTEL_LOG_TOOL_DETAILS=1`): Full error message when the tool failed525* `error` (when `OTEL_LOG_TOOL_DETAILS=1`): Full error message when the tool failed

526* `decision_type`: Either `"accept"` or `"reject"`526* `decision_type`: Either `"accept"` or `"reject"`

527* `decision_source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`527* `decision_source`: Where the decision came from. One of `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`. See the [Tool decision event](#tool-decision-event) for what each value means.

528* `tool_input_size_bytes`: Size of the JSON-serialized tool input in bytes528* `tool_input_size_bytes`: Size of the JSON-serialized tool input in bytes

529* `tool_result_size_bytes`: Size of the tool result in bytes529* `tool_result_size_bytes`: Size of the tool result in bytes

530* `mcp_server_scope`: MCP server scope identifier (for MCP tools)530* `mcp_server_scope`: MCP server scope identifier (for MCP tools)

635* `tool_name`: Name of the tool (for example, "Read", "Edit", "Write", "NotebookEdit")635* `tool_name`: Name of the tool (for example, "Read", "Edit", "Write", "NotebookEdit")

636* `tool_use_id`: Unique identifier for this tool invocation. Matches the `tool_use_id` passed to hooks, allowing correlation between OTel events and hook-captured data.636* `tool_use_id`: Unique identifier for this tool invocation. Matches the `tool_use_id` passed to hooks, allowing correlation between OTel events and hook-captured data.

637* `decision`: Either `"accept"` or `"reject"`637* `decision`: Either `"accept"` or `"reject"`

638* `source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`638* `source`: Where the decision came from:

639 * `"config"`: Decided automatically without prompting, based on project settings, enterprise managed policy, `--allowedTools` or `--disallowedTools` flags, the active permission mode, or because the tool is inherently safe.

640 * `"hook"`: A `PreToolUse` or `PermissionRequest` hook returned the decision.

641 * `"user_permanent"`: Emitted when the user chose "Always allow" when prompted, saving a rule to their personal settings. Also emitted for later calls that match that saved rule. Treated as an accept.

642 * `"user_temporary"`: Emitted when the user chose "Yes" or "Yes, for this session" when prompted, without saving a rule. Also emitted for later calls in the same session that match that session-scoped allow. Treated as an accept.

643 * `"user_abort"`: Emitted when the user dismissed the permission prompt without answering. Treated as a reject.

644 * `"user_reject"`: Emitted when the user chose "No" when prompted, or a call matched a deny rule in their personal settings. Treated as a reject.

639 645 

640#### Permission mode changed event646#### Permission mode changed event

641 647 

168| `alwaysThinkingEnabled` | Enable [extended thinking](/en/model-config#extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |168| `alwaysThinkingEnabled` | Enable [extended thinking](/en/model-config#extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |

169| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |169| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |

170| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |170| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

171| `autoMemoryDirectory` | Custom directory for [auto memory](/en/memory#storage-location) storage. Accepts `~/`-expanded paths. Not accepted in project settings (`.claude/settings.json`) to prevent shared repos from redirecting memory writes to sensitive locations. Accepted from policy, local, and user settings | `"~/my-memory-dir"` |171| `autoMemoryDirectory` | Custom directory for [auto memory](/en/memory#storage-location) storage. Accepts an absolute path or a `~/`-prefixed path. Accepted from policy and user settings, and from the `--settings` flag. Not accepted from project or local settings, since a cloned repository could supply either file to redirect memory writes to sensitive locations | `"~/my-memory-dir"` |

172| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, and `soft_deny` arrays of prose rules. Include the literal string `"$defaults"` in an array to inherit the built-in rules at that position. See [Configure auto mode](/en/auto-mode-config). Not read from shared project settings | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, and `soft_deny` arrays of prose rules. Include the literal string `"$defaults"` in an array to inherit the built-in rules at that position. See [Configure auto mode](/en/auto-mode-config). Not read from shared project settings | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

173| `autoScrollEnabled` | In [fullscreen rendering](/en/fullscreen), follow new output to the bottom of the conversation. Default: `true`. Appears in `/config` as **Auto-scroll**. Permission prompts still scroll into view when this is off | `false` |173| `autoScrollEnabled` | In [fullscreen rendering](/en/fullscreen), follow new output to the bottom of the conversation. Default: `true`. Appears in `/config` as **Auto-scroll**. Permission prompts still scroll into view when this is off | `false` |

174| `autoUpdatesChannel` | Release channel to follow for updates. Use `"stable"` for a version that is typically about one week old and skips versions with major regressions, or `"latest"` (default) for the most recent release | `"stable"` |174| `autoUpdatesChannel` | Release channel to follow for updates. Use `"stable"` for a version that is typically about one week old and skips versions with major regressions, or `"latest"` (default) for the most recent release | `"stable"` |

149 149 

150Claude Code watches `~/.claude/themes/` and reloads when a file changes, so edits made in your editor apply to a running session without a restart.150Claude Code watches `~/.claude/themes/` and reloads when a file changes, so edits made in your editor apply to a running session without a restart.

151 151 

152Below is the full list of customizations you can set in `overrides`. The interactive editor in `/theme` shows the same tokens with a live preview, including a small number of internal tokens not covered here.152The reference below covers the tokens you can set in `overrides`. The interactive editor in `/theme` shows the same tokens with a live preview, plus a few single-purpose accents such as onboarding screen colors that are omitted here.

153 153 

154<Accordion title="Color token reference">154<Accordion title="Color token reference">

155 The following example combines tokens from several of the groups below: the brand accent, the plan mode border, the diff backgrounds, and the fullscreen message background.155 The following example combines tokens from several of the groups below: the brand accent, the plan mode border, the diff backgrounds, and the fullscreen message background.

179 | `inverseText` | Text drawn on top of a colored background, such as status badges |179 | `inverseText` | Text drawn on top of a colored background, such as status badges |

180 | `inactive` | Secondary text such as hints, timestamps, and disabled items |180 | `inactive` | Secondary text such as hints, timestamps, and disabled items |

181 | `subtle` | Faint borders and de-emphasized secondary text |181 | `subtle` | Faint borders and de-emphasized secondary text |

182 | `suggestion` | Autocomplete suggestions and selection highlight in pickers |

182 | `permission` | Dialog borders, including permission prompts and pickers |183 | `permission` | Dialog borders, including permission prompts and pickers |

183 | `remember` | Memory and `CLAUDE.md` indicators |184 | `remember` | Memory and `CLAUDE.md` indicators |

184 185 

224 Apply only in [fullscreen rendering mode](/en/fullscreen), where messages have a background fill.225 Apply only in [fullscreen rendering mode](/en/fullscreen), where messages have a background fill.

225 226 

226 | Token | Controls |227 | Token | Controls |

227 | :---------------------- | :------------------------------------------------ |228 | :--------------------------- | :----------------------------------------------------------------- |

228 | `userMessageBackground` | Background behind your messages in the transcript |229 | `userMessageBackground` | Background behind your messages in the transcript |

230 | `userMessageBackgroundHover` | Background behind a message while hovered or expanded |

231 | `messageActionsBackground` | Background behind the selected message when the action bar is open |

232 | `bashMessageBackgroundColor` | Background behind `!` shell command entries in the transcript |

233 | `memoryBackgroundColor` | Background behind `#` memory entries in the transcript |

229 | `selectionBg` | Background of text selected with the mouse |234 | `selectionBg` | Background of text selected with the mouse |

230 235 

236 #### Usage meter and speaker labels

237 

238 Adjust the bar shown in the `/usage` view and the labels that distinguish your messages from Claude's.

239 

240 | Token | Controls |

241 | :----------------- | :------------------------------------------------ |

242 | `rate_limit_fill` | Filled portion of the usage meter |

243 | `rate_limit_empty` | Unfilled portion of the usage meter |

244 | `briefLabelYou` | Color of the `You` label on your messages |

245 | `briefLabelClaude` | Color of the `Claude` label on assistant messages |

246 

231 #### Shimmer variants and subagent colors247 #### Shimmer variants and subagent colors

232 248 

233 Several tokens have a paired `Shimmer` variant, such as `claudeShimmer` and `warningShimmer`, that supplies the lighter color used in the spinner's animated gradient. Override the shimmer alongside its base token if the animation looks mismatched.249 Several tokens have a paired shimmer variant that supplies the lighter color used in the spinner's animated gradient. Override the shimmer alongside its base token if the animation looks mismatched.

250 

251 * `claude` and `claudeShimmer`

252 * `warning` and `warningShimmer`

253 * `permission` and `permissionShimmer`

254 * `promptBorder` and `promptBorderShimmer`

255 * `inactive` and `inactiveShimmer`

256 * `fastMode` and `fastModeShimmer`

234 257 

235 Each [subagent](/en/sub-agents) and parallel task is shown in one of eight named colors so you can tell them apart in the transcript. The token names follow the pattern `<color>_FOR_SUBAGENTS_ONLY`, where `<color>` is `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan`. Override these to change what each named color looks like. For example, a subagent with `color: blue` in its definition is drawn using the `blue_FOR_SUBAGENTS_ONLY` value.258 Each [subagent](/en/sub-agents) and parallel task is shown in one of eight named colors so you can tell them apart in the transcript. The token names follow the pattern `<color>_FOR_SUBAGENTS_ONLY`, where `<color>` is `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, or `cyan`. Override these to change what each named color looks like. For example, a subagent with `color: blue` in its definition is drawn using the `blue_FOR_SUBAGENTS_ONLY` value.

259 

260 The [`ultrathink`](/en/model-config#use-ultrathink-for-one-off-deep-reasoning) and [`ultraplan`](/en/ultraplan) keywords in the prompt input are rendered with a seven-color rainbow gradient. The token names follow the pattern `rainbow_<color>` and `rainbow_<color>_shimmer`, where `<color>` is `red`, `orange`, `yellow`, `green`, `blue`, `indigo`, or `violet`.

236</Accordion>261</Accordion>

237 262 

238## Switch to fullscreen rendering263## Switch to fullscreen rendering

589 589 

590**Architecture mismatch.** The installer downloaded the wrong binary, for example x86 on an ARM server. Check with `uname -m` on macOS or Linux, or `$env:PROCESSOR_ARCHITECTURE` in PowerShell. If the result doesn't match the binary you received, [file a GitHub issue](https://github.com/anthropics/claude-code/issues) with the output.590**Architecture mismatch.** The installer downloaded the wrong binary, for example x86 on an ARM server. Check with `uname -m` on macOS or Linux, or `$env:PROCESSOR_ARCHITECTURE` in PowerShell. If the result doesn't match the binary you received, [file a GitHub issue](https://github.com/anthropics/claude-code/issues) with the output.

591 591 

592**Missing instruction set on older CPUs.** If your architecture is correct but you still see `Illegal instruction`, your CPU likely lacks AVX or another instruction the binary requires. This affects roughly pre-2013 Intel and AMD processors. There is currently no native-binary workaround; track [issue #50384](https://github.com/anthropics/claude-code/issues/50384) for status, and include your CPU model from `cat /proc/cpuinfo | grep "model name" | head -1` on Linux or `sysctl -n machdep.cpu.brand_string` on macOS when reporting.592**Missing AVX instruction set.** If your architecture is correct but you still see `Illegal instruction`, your CPU likely lacks AVX or another instruction the binary requires. This affects roughly pre-2013 Intel and AMD processors, and virtual machines where the hypervisor does not pass AVX through to the guest.

593 

594On a VPS or VM, run `grep -m1 -ow avx /proc/cpuinfo`; an empty result means AVX is not available to the guest.

595 

596There is no native-binary workaround; track [issue #50384](https://github.com/anthropics/claude-code/issues/50384) for status, and include your CPU model from `grep -m1 "model name" /proc/cpuinfo` on Linux or `sysctl -n machdep.cpu.brand_string` on macOS when reporting.

593 597 

594Alternative install methods download the same native binary and won't resolve either cause.598Alternative install methods download the same native binary and won't resolve either cause.

595 599 

144 144 

145Setting `"space": null` removes the default binding. Omit it if you want both keys active.145Setting `"space": null` removes the default binding. Omit it if you want both keys active.

146 146 

147In hold mode, avoid binding a bare letter key like `v` since hold detection relies on key-repeat and the letter types into the prompt during warmup. Use `Space`, or use a modifier combination like `meta+k` to start recording on the first keypress with no warmup. Tap mode has no warmup, so any key works. See [customize keyboard shortcuts](/en/keybindings) for the full keybinding syntax.147In hold mode, avoid binding a bare letter key like `v` since hold detection relies on key-repeat and the letter types into the prompt during warmup. Use `Space`, or use a modifier combination like `meta+k` to start recording on the first keypress with no warmup. Tap mode has no warmup, so most keys work.

148 

149Some keys are not delivered to terminal applications and cannot be bound at all. For example, `Caps Lock` shows an error if you try to bind it. See [customize keyboard shortcuts](/en/keybindings) for the full keybinding syntax and the list of reserved shortcuts.

148 150 

149## Troubleshooting151## Troubleshooting

150 152