Home Docs Claude Code CLI

One capture · claude-code

One read of Claude Code CLIclaude-code-20260826T233701Z

5 pages moved out of 191 read.

Pages moved 5 significant first

Pages read 191 in this capture

Captured 26 Aug 2026 23:37 UTC

Corpus hash 4063383804e1 corpus-hash

What this read moved

1-5 of 5

agent-sdk/python Changed · +29 / -5 lines

### `ResultError`

from line 1855

18551855 """Base error for Claude SDK."""

18561856```

18571857

1858When 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.

1858When 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.

18591859

18601860### `CLINotFoundError`

18611861

from line 1895

18951895 self.stderr = stderr

18961896```

18971897

1898### `ResultError`

1899

1900Raised 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.

1901

1902```python theme={null}

1903class ResultError(ProcessError):

1904 subtype: str | None # for example "error_max_turns" or "error_during_execution"

1905 errors: list[str] # an empty list when the result message reported none

1906 result: str | None

1907 api_error_status: int | None

1908 terminal_reason: str | None # for example "max_turns" or "api_error"

1909 session_id: str | None

1910 data: dict[str, Any] # the raw result message payload

1911```

1912

18981913### `CLIJSONDecodeError`

18991914

19001915Raised when JSON parsing fails.

from line 3362

33473362

33483363### Error handling

33493364

3365This example catches [`ResultError`](#resulterror), which requires Python Agent SDK 0.2.140 or later.

3366

33503367```python theme={null}

33513368import asyncio

33523369

3353from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeError

3370from claude_agent_sdk import (

3371 query,

3372 CLINotFoundError,

3373 ProcessError,

3374 ResultError,

3375 CLIJSONDecodeError,

3376)

33543377

33553378

33563379async def main():

from line 3384

33613384 print(

33623385 "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"

33633386 )

3387 # Catch ResultError before ProcessError, which it subclasses. Its message

3388 # carries the error text; branch on e.subtype or e.terminal_reason.

3389 except ResultError as e:

3390 print(f"Query ended with an error result ({e.subtype}): {e}")

33643391 except ProcessError as e:

33653392 print(f"Process failed with exit code: {e.exit_code}")

33663393 except CLIJSONDecodeError as e:

33673394 print(f"Failed to parse response: {e}")

3368 # A single-shot query() raises a plain Exception after yielding an error result

3369 except Exception as e:

3370 print(f"Query ended with an error result: {e}")

33713395

33723396

33733397asyncio.run(main())

keybindings Changed · +14 / -6 lines

from line 282

282282

283283Actions available in the `Select` context:

284284

285| Action | Default | Description |

286| :---------------- | :-------------- | :--------------- |

287| `select:next` | Down, J, Ctrl+N | Next option |

288| `select:previous` | Up, K, Ctrl+P | Previous option |

289| `select:accept` | Enter | Accept selection |

290| `select:cancel` | Escape | Cancel selection |

285| Action | Default | Description |

286| :---------------- | :-------------- | :---------------------------- |

287| `select:next` | Down, J, Ctrl+N | Next option |

288| `select:previous` | Up, K, Ctrl+P | Previous option |

289| `select:pageUp` | PageUp | Move up one page of options |

290| `select:pageDown` | PageDown | Move down one page of options |

291| `select:first` | Home | First option |

292| `select:last` | End | Last option |

293| `select:accept` | Enter | Accept selection |

294| `select:cancel` | Escape | Cancel selection |

291295

296Claude 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.

297

292298### Plugin actions

293299

294300Actions available in the `Plugin` context:

from line 390

384390* `tab` - Tab key

385391* `space` - Space bar

386392* `up`, `down`, `left`, `right` - Arrow keys

393* `pageup`, `pagedown` - Page Up and Page Down keys

394* `home`, `end` - Home and End keys

387395* `backspace`, `delete` - Delete keys

388396* `wheelup`, `wheeldown` - Mouse wheel scroll events

389397

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

761761| [`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 |

from line 3055

30553055

30563056### `spinnerTipsOverride`

30573057

3058Replace 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.

3058Add 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.

30593059

3060* **Scope**: [`Any file`](#scopes)

3061* **Type**: object with a `tips` array of strings and an optional `excludeDefault` Boolean

3060If you set [`spinnerTipsEnabled`](#spinnertipsenabled) to `false`, Claude Code hides all tips, yours included.

3061

3062* **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.

3063* **Type**: object with `tips`, `tipsFile`, `label`, and `excludeDefault` fields, each optional

30623064* **Default**: unset, so Claude Code shows only the built-in tips

30633065

3064This example replaces the built-in tips with a single tip of your own:

3066Tip 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.

30653067

3068Each `tips` entry is a plain string or an object with these fields:

3069

3070| Field | Required | Description |

3071| :----------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3072| `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 |

3073| `text` | Yes | The tip, one line of up to 500 characters. Claude Code strips ANSI escapes and control characters and collapses whitespace |

3074| `cooldownSessions` | No | Sessions Claude Code waits before showing the tip again, `0` to `1000`, default `0` |

3075| `priority` | No | Order among tips that have gone unshown equally long, higher first, `-10` to `10`, default `0` |

3076

3077Claude 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.

3078

3079Claude 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.

3080

3081Use the remaining fields to name a tips file, set the prefix, and hide the built-in tips:

3082

3083* `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`.

3084* `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.

3085* `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.

3086

3087When 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.

3088

3089This example, in your user settings, adds a plain string tip and an object tip to the rotation under the `Acme tip` prefix:

3090

30663091```json settings.json theme={null}

30673092{

30683093 "spinnerTipsOverride": {

3069 "excludeDefault": true,

3070 "tips": ["Run /review before opening a PR"]

3094 "label": "Acme tip",

3095 "tips": [

3096 "Run /review before opening a PR",

3097 {

3098 "id": "gateway-errors",

3099 "text": "Seeing 5xx errors? Check the gateway status page first",

3100 "cooldownSessions": 5,

3101 "priority": 2

3102 }

3103 ]

30713104 }

30723105}

30733106```

30743107

3108Each field in the example changes one thing about how Claude Code shows the tips:

3109

3110* `label`: Claude Code shows both tips as `Acme tip: ...` instead of `Tip: ...`.

3111* The plain string: Claude Code gives it the defaults, so it can come up again in the very next session.

3112* `id`: Claude Code keys the second tip's show history on `gateway-errors`, so its cooldown still applies after you add or reorder tips.

3113* `cooldownSessions`: after Claude Code shows the `gateway-errors` tip, it doesn't show that tip again until five sessions later.

3114* `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`.

3115

3116While Claude works, Claude Code shows your tips in the spinner with your prefix, such as `Acme tip: Run /review before opening a PR`.

3117

30753118### `spinnerVerbs`

30763119

30773120While 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

35243567

35253568#### What runs under `allowManagedHooksOnly`

35263569

3527When you set it to `true`, Claude Code changes which hooks and hook-like commands load:

3528

3529* **Managed and SDK hooks run**: hooks from managed settings and hooks the [Agent SDK](/docs/en/agent-sdk/overview) registers in process

3530* **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

3531* **Everything else is blocked**: user, project, and local hooks, hooks from other plugins, and hooks declared in agent frontmatter

3532* **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

3533* **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

3534* **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)

3535

3536The [`/goal`](/docs/en/goal) command can't run while this key is set, because it depends on hooks.

3537

3538### `disableAllHooks`

3539

3540Turn 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.

3541

3542* **Scope**: [`Any file`](#scopes). Only managed settings can disable managed hooks.

3543* **Type**: Boolean

3544 * `true`: Claude Code turns off hooks, any custom status line, and any custom file suggestion command

3545 * `false`: hooks, the status line, and the file suggestion command run

3546* **Default**: unset, so hooks run

3547

3548```json settings.json theme={null}

3549{

3550 "disableAllHooks": true

3551}

3552```

3553

3554The reach depends on which file carries the key:

3555

3556* **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

3557* **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

3558

3559Keeping Agent SDK hooks running when managed settings set this key requires Claude Code v2.1.242 or later.

3560

3561The [`/goal`](/docs/en/goal) command can't run while hooks are disabled, and the `/hooks` menu shows a notice instead of your hooks.

3562

3563#### Status line and file suggestion gates

3564

3565Claude Code makes two decisions for `statusLine`, `fileSuggestion`, and `subagentStatusLine`, in this order:

3566

3567* **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)

3568* **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`

3569

3570Under 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.

3571

3572### `disableWorkflows`

3573

3574Turn 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.

3575

3576* **Scope**: [`Any file`](#scopes)

3577* **Type**: Boolean

3578 * `true`: Claude Code turns off dynamic workflows and the bundled workflow commands for everyone your settings reach

3579 * `false`: the same as unset; whether workflows are on then follows [`enableWorkflows`](#enableworkflows) and your plan's default

3580* **Def

3570When you set it to `true`, Claude Cod

agent-sdk/streaming-vs-single-mode Changed · +1 / -2 lines

from line 272

272272

273273 async def single_message_example():

274274 # Simple one-shot query using query() function

275 # query() raises after an error result, such as error_max_turns

275 # query() raises ResultError after an error result, such as error_max_turns

276276 try:

277277 async for message in query(

278278 prompt="Explain the authentication flow",

from line 280

280280 ):

281281 if isinstance(message, ResultMessage) and message.subtype == "success":

282282 print(message.result)

283 # The SDK raises a plain Exception for error results, so match Exception here

284283 except Exception as e:

285284 print(f"Query failed: {e}")

286285

plugin-relevance Changed · +3 / -1 lines

from line 22

2222* **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.

2323* **`/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.

2424

25The 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.

25The 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`.

27The Discover-tab pin is independent of tip settings.

2628

2729Claude Code never installs a plugin automatically. The user always confirms.

2830