Capture
One read of Claude Code CLI
5 pages moved out of 191 read.
plugin-relevance Changed · +3 / -1 lines
from line 22
* **Session-start suggestion**: if the `cwd` signal matches the working directory, a one-line `plugin suggestion: <name>@<marketplace> · /plugin` notification appears before the first turn. This surface requires Claude Code v2.1.153 or later. * **`/plugin` Discover tab**: the plugin is pinned to the top of the Discover list with an annotation such as "suggested for this directory" or "suggested for stripe commands". This surface requires Claude Code v2.1.154 or later. -The spinner tip and the session-start notification are part of the spinner-tips system. Both are disabled when the user or project sets `spinnerTipsEnabled` to `false`, or when a custom `spinnerTipsOverride` is configured with `excludeDefault`. The Discover-tab pin is independent of tip settings. +The spinner tip and the session-start notification are part of the spinner-tips system. Claude Code disables both when `spinnerTipsEnabled` resolves to `false` across your settings files, or when `excludeDefault` resolves to `true` across the [`spinnerTipsOverride`](/docs/en/settings-reference#spinnertipsoverride) keys in user, `--settings`, and managed settings and those keys configure at least one tip or a `tipsFile`. + +The Discover-tab pin is independent of tip settings. Claude Code never installs a plugin automatically. The user always confirms.
agent-sdk/python Changed · +29 / -5 lines
### `ResultError`
from line 1855
"""Base error for Claude SDK.""" ``` -When a single-shot `query()` ends with an error result, for example a turn-limit error, the SDK raises a plain `Exception` after yielding the final result message, not a `ClaudeSDKError` subclass. +When a single-shot `query()` ends with an error result, for example a turn-limit error, the SDK raises a [`ResultError`](#resulterror) after yielding the final result message. Python Agent SDK versions before 0.2.140 raised a plain `Exception` that wasn't a `ClaudeSDKError` subclass. ### `CLINotFoundError`
from line 1895
self.stderr = stderr ``` +### `ResultError` + +Raised after the final [`ResultMessage`](#resultmessage) when the Claude Code process exits because the run ended with an error result, such as a turn-limit error or an API error. `ResultError` subclasses `ProcessError`, so an existing `except ProcessError` handler also catches it. Its attributes carry the fields of that result message, so you can branch on why the run failed without parsing the message text. Requires Python Agent SDK 0.2.140 or later. + +```python theme={null} +class ResultError(ProcessError): + subtype: str | None # for example "error_max_turns" or "error_during_execution" + errors: list[str] # an empty list when the result message reported none + result: str | None + api_error_status: int | None + terminal_reason: str | None # for example "max_turns" or "api_error" + session_id: str | None + data: dict[str, Any] # the raw result message payload +``` + ### `CLIJSONDecodeError` Raised when JSON parsing fails.
from line 3362
### Error handling +This example catches [`ResultError`](#resulterror), which requires Python Agent SDK 0.2.140 or later. + ```python theme={null} import asyncio -from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeError +from claude_agent_sdk import ( + query, + CLINotFoundError, + ProcessError, + ResultError, + CLIJSONDecodeError, +) async def main():
from line 3384
print( "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk" ) + # Catch ResultError before ProcessError, which it subclasses. Its message + # carries the error text; branch on e.subtype or e.terminal_reason. + except ResultError as e: + print(f"Query ended with an error result ({e.subtype}): {e}") except ProcessError as e: print(f"Process failed with exit code: {e.exit_code}") except CLIJSONDecodeError as e: print(f"Failed to parse response: {e}") - # A single-shot query() raises a plain Exception after yielding an error result - except Exception as e: - print(f"Query ended with an error result: {e}") asyncio.run(main())
keybindings Changed · +14 / -6 lines
from line 282
Actions available in the `Select` context: -| Action | Default | Description | -| :---------------- | :-------------- | :--------------- | -| `select:next` | Down, J, Ctrl+N | Next option | -| `select:previous` | Up, K, Ctrl+P | Previous option | -| `select:accept` | Enter | Accept selection | -| `select:cancel` | Escape | Cancel selection | +| Action | Default | Description | +| :---------------- | :-------------- | :---------------------------- | +| `select:next` | Down, J, Ctrl+N | Next option | +| `select:previous` | Up, K, Ctrl+P | Previous option | +| `select:pageUp` | PageUp | Move up one page of options | +| `select:pageDown` | PageDown | Move down one page of options | +| `select:first` | Home | First option | +| `select:last` | End | Last option | +| `select:accept` | Enter | Accept selection | +| `select:cancel` | Escape | Cancel selection | +Claude Code applies your `select:pageUp`, `select:pageDown`, `select:first`, and `select:last` bindings in the `/skills` menu. In most other lists, such as the `/model` picker, Claude Code pages with PageUp and PageDown regardless of your bindings and ignores Home and End. + ### Plugin actions Actions available in the `Plugin` context:
from line 390
* `tab` - Tab key * `space` - Space bar * `up`, `down`, `left`, `right` - Arrow keys +* `pageup`, `pagedown` - Page Up and Page Down keys +* `home`, `end` - Home and End keys * `backspace`, `delete` - Delete keys * `wheelup`, `wheeldown` - Mouse wheel scroll events
settings-reference Changed · +54 / -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 760
| [`skipWebFetchPreflight`](#skipwebfetchpreflight) | Skip the [WebFetch hostname check](/docs/en/tools-reference#webfetch-tool-behavior) when Anthropic is unreachable | Privacy and telemetry | Any file | | [`spellcheck`](#spellcheck) | Underline misspelled words in the prompt input with a [spell checker](/docs/en/interactive-mode#check-spelling-as-you-type) you install | Interface and terminal | User or managed | | [`spinnerTipsEnabled`](#spinnertipsenabled) | Hide tips in the spinner while Claude works | Interface and terminal | Any file | -| [`spinnerTipsOverride`](#spinnertipsoverride) | Replace or extend spinner tips with your own strings | Interface and terminal | Any file | +| [`spinnerTipsOverride`](#spinnertipsoverride) | Add your own tips to the spinner rotation, or replace the built-in tips | Interface and terminal | Any file | | [`spinnerVerbs`](#spinnerverbs) | Add or replace the verbs shown while a turn runs | Interface and terminal | Any file | | [`sshConfigs`](#sshconfigs) | Add [SSH connections](/docs/en/desktop#pre-configure-ssh-connections-for-your-team) to the Desktop environment dropdown | Remote, desktop, and notifications | User or managed | | [`sshHostAllowlist`](#sshhostallowlist) | Limit which hosts [Desktop SSH sessions](/docs/en/desktop#restrict-which-ssh-hosts-users-can-connect-to) can reach | Remote, desktop, and notifications | Managed |
from line 3055
### `spinnerTipsOverride` -Replace or extend the [spinner tips](#spinnertipsenabled), the short hints Claude Code rotates through while Claude works, with your own strings, such as a team reminder to run a review skill. Set `excludeDefault` to `true` and list at least one tip to show only your tips; when it's `false` or absent, or `tips` is empty, Claude Code keeps the built-in tips and adds yours. +Add your own tips to the [spinner tips](#spinnertipsenabled) that Claude Code shows while Claude works, or replace the built-in tips with yours. Claude Code puts your tips in the same rotation as the built-in ones: it picks the tip that has gone unshown the longest, skips tips still in their cooldown, and breaks ties by priority. -* **Scope**: [`Any file`](#scopes) -* **Type**: object with a `tips` array of strings and an optional `excludeDefault` Boolean +If you set [`spinnerTipsEnabled`](#spinnertipsenabled) to `false`, Claude Code hides all tips, yours included. + +* **Scope**: [`Any file`](#scopes). Claude Code honors tip objects, `tipsFile`, `label`, and `excludeDefault` from user settings, the `--settings` flag, and managed settings; from project and local settings it reads plain string tips only. +* **Type**: object with `tips`, `tipsFile`, `label`, and `excludeDefault` fields, each optional * **Default**: unset, so Claude Code shows only the built-in tips -This example replaces the built-in tips with a single tip of your own: +Tip objects, `tipsFile`, `label`, and the Scope line's rule that project and local settings contribute plain strings only require Claude Code v2.1.247 or later. On earlier versions, a project or local file's `excludeDefault` applies too. +Each `tips` entry is a plain string or an object with these fields: + +| Field | Required | Description | +| :----------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Yes | Up to 64 letters, digits, `.`, `_`, or `-`. Claude Code keys the tip's show history on it, so the tip's cooldown survives reordering the list. Of two entries with the same id, Claude Code uses the first | +| `text` | Yes | The tip, one line of up to 500 characters. Claude Code strips ANSI escapes and control characters and collapses whitespace | +| `cooldownSessions` | No | Sessions Claude Code waits before showing the tip again, `0` to `1000`, default `0` | +| `priority` | No | Order among tips that have gone unshown equally long, higher first, `-10` to `10`, default `0` | + +Claude Code reads a plain string as a tip with those defaults and a position-based id, so its show history resets when you reorder the list. Give a tip an `id` to keep its history across edits. + +Claude Code reads at most 200 tips across `tips` and `tipsFile`, and drops an invalid entry with a debug warning instead of rejecting the settings file. + +Use the remaining fields to name a tips file, set the prefix, and hide the built-in tips: + +* `tipsFile`: an absolute or `~/` path to a local JSON file holding an array of the same entries, or an object with a `tips` array, up to 256 KB. Claude Code reads the file once per process, so it loads your edits at the next start. You can't set it through [server-managed settings](/docs/en/server-managed-settings); deploy inline `tips` there, or deploy the path in an on-disk `managed-settings.json`. +* `label`: the prefix Claude Code shows before tips from user, `--settings`, and managed settings, up to 40 characters. The default is `Tip`, the same prefix as the built-in tips, and tips from project and local settings always use it. +* `excludeDefault`: set it to `true` to hide the built-in tips and show only yours. When Claude Code can't load any of your tips, for example because `tipsFile` doesn't exist or every entry is invalid, it keeps the built-in rotation instead of an empty spinner. + +When more than one settings file sets the key, Claude Code shows tips from all of them and takes `tipsFile`, `label`, and `excludeDefault` from whichever of managed settings, the `--settings` flag, and user settings is the highest-precedence one that sets each. + +This example, in your user settings, adds a plain string tip and an object tip to the rotation under the `Acme tip` prefix: + ```json settings.json theme={null} { "spinnerTipsOverride": { - "excludeDefault": true, - "tips": ["Run /review before opening a PR"] + "label": "Acme tip", + "tips": [ + "Run /review before opening a PR", + { + "id": "gateway-errors", + "text": "Seeing 5xx errors? Check the gateway status page first", + "cooldownSessions": 5, + "priority": 2 + } + ] } } ``` +Each field in the example changes one thing about how Claude Code shows the tips: + +* `label`: Claude Code shows both tips as `Acme tip: ...` instead of `Tip: ...`. +* The plain string: Claude Code gives it the defaults, so it can come up again in the very next session. +* `id`: Claude Code keys the second tip's show history on `gateway-errors`, so its cooldown still applies after you add or reorder tips. +* `cooldownSessions`: after Claude Code shows the `gateway-errors` tip, it doesn't show that tip again until five sessions later. +* `priority`: when the `gateway-errors` tip and another tip have gone unshown for the same number of sessions, for example when neither has been shown yet, Claude Code shows `gateway-errors` first. The plain string has the default priority, `0`. + +While Claude works, Claude Code shows your tips in the spinner with your prefix, such as `Acme tip: Run /review before opening a PR`. + ### `spinnerVerbs` While a turn is in progress, the spinner shows a rotating verb such as "Accomplishing", "Architecting", or "Baking". Use this key to add your own verbs to that rotation or replace the built-in list with yours.
from line 3567
#### What runs under `allowManagedHooksOnly` -When you set it to `true`, Claude Code changes which hooks and hook-like commands load: - -* **Managed and SDK hooks run**: hooks from managed settings and hooks the [Agent SDK](/docs/en/agent-sdk/overview) registers in process -* **Force-enabled plugin hooks run**: hooks from plugins your managed settings force-enable through [`enabledPlugins`](#enabledplugins). Claude Code matches on the full `plugin@marketplace` ID, so a plugin with the same name from a different marketplace stays blocked. This lets you distribute vetted hooks through an organization marketplace while blocking everything else -* **Everything else is blocked**: user, project, and local hooks, hooks from other plugins, and hooks declared in agent frontmatter -* **Command-sourced plugins are disabled**: Claude Code also disables plugins with a [`command` source](/docs/en/plugin-marketplaces#command-sources), including plugins force-enabled in managed `enabledPlugins`, unless you set [`disableCommandPluginSources`](#disablecommandpluginsources) to `false` explicitly -* **Marketplace `headersHelper` commands are blocked**: Claude Code also blocks marketplace [`headersHelper` commands](/docs/en/plugin-marketplaces#authenticate-archive-downloads) unless [`disableCommandPluginSources`](#disablecommandpluginsources) is explicitly set to `false`, except for a marketplace that managed settings themselves declare. Requires Claude Code v2.1.238 or later -* **Status line and file suggestion narrow to managed settings**: Claude Code reads [`statusLine`](/docs/en/statusline), [`fileSuggestion`](#filesuggestion), and [`subagentStatusLine`](/docs/en/statusline#subagent-status-lines) from managed settings only, following the [status line and file suggestion gates](#status-line-and-file-suggestion-gates) - -The [`/goal`](/docs/en/goal) command can't run while this key is set, because it depends on hooks. - -### `disableAllHooks` - -Turn off [hooks](/docs/en/hooks#disable-or-remove-hooks), any custom [status line](/docs/en/statusline), and any custom [file suggestion](#filesuggestion) command. Use it to turn all of these off temporarily without deleting them from your settings. - -* **Scope**: [`Any file`](#scopes). Only managed settings can disable managed hooks. -* **Type**: Boolean - * `true`: Claude Code turns off hooks, any custom status line, and any custom file suggestion command - * `false`: hooks, the status line, and the file suggestion command run -* **Default**: unset, so hooks run - -```json settings.json theme={null} -{ - "disableAllHooks": true -} -``` - -The reach depends on which file carries the key: - -* **In managed settings**: Claude Code disables every configured hook, including managed ones, and keeps running the hooks the [Agent SDK](/docs/en/agent-sdk/overview) registers in process -* **In any other settings file**: Claude Code disables user, project, local, and plugin hooks; managed hooks, Agent SDK hooks, and hooks from plugins force-enabled in managed [`enabledPlugins`](#enabledplugins) keep running - -Keeping Agent SDK hooks running when managed settings set this key requires Claude Code v2.1.242 or later. - -The [`/goal`](/docs/en/goal) command can't run while hooks are disabled, and the `/hooks` menu shows a notice instead of your hooks. - -#### Status line and file suggestion gates - -Claude Code makes two decisions for `statusLine`, `fileSuggestion`, and `subagentStatusLine`, in this order: - -* **Off entirely**: when managed settings set `disableAllHooks`, or when the folder isn't trusted under the same [workspace trust rule as hooks in settings files](/docs/en/permissions#what-runs-before-you-trust-a-folder) -* **Narrowed to managed settings**: when [`allowManagedHooksOnly`](#allowmanagedhooksonly) is set, when `disableAllHooks` is `true` outside managed settings after [settings precedence](/docs/en/hooks#disable-or-remove-hooks) applies, or when you start Claude Code with `--safe-mode` - -Under narrowing, Claude Code runs a managed value if one is deployed. Otherwise it skips your value without warning: the status line is disabled, and `@` autocomplete falls back to the built-in file suggestion. - -### `disableWorkflows` - -Turn off [dynamic workflows](/docs/en/workflows#turn-workflows-off) and the bundled workflow commands for everyone your settings reach, such as an organization through managed settings. To turn workflows on or off just for yourself, use [`enableWorkflows`](#enableworkflows) instead, which the **Dynamic workflows** toggle in `/config` writes to your user settings. - -* **Scope**: [`Any file`](#scopes) -* **Type**: Boolean - * `true`: Claude Code turns off dynamic workflows and the bundled workflow commands for everyone your settings reach - * `false`: the same as unset; whether workflows are on then follows [`enableWorkflows`](#enableworkflows) and your plan's default -* **Def +When you set it to `true`, Claude Cod
agent-sdk/streaming-vs-single-mode Changed · +1 / -2 lines
from line 272
async def single_message_example(): # Simple one-shot query using query() function - # query() raises after an error result, such as error_max_turns + # query() raises ResultError after an error result, such as error_max_turns try: async for message in query( prompt="Explain the authentication flow",
from line 280
): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) - # The SDK raises a plain Exception for error results, so match Exception here except Exception as e: print(f"Query failed: {e}")