Home Docs Claude Code CLI

One capture · claude-code

One read of Claude Code CLIclaude-code-20260827T150701Z

8 pages moved out of 191 read.

Pages moved 8 significant first

Pages read 191 in this capture

Captured 27 Aug 2026 15:07 UTC

Corpus hash 1704eacb530d corpus-hash

What this read moved

1-8 of 8

agent-sdk/python Changed · +10 / -4 lines

from line 1901

19011901

19021902```python theme={null}

19031903class ResultError(ProcessError):

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

1904 subtype: str | None # "error_max_turns", "error_during_execution", ...; "success" when the run ended on a failed request

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

19061906 result: str | None

19071907 api_error_status: int | None

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

1908 terminal_reason: str | None # "max_turns", "api_error", ...; check this before subtype

19091909 session_id: str | None

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

19111911```

19121912

1913To tell failures apart, check `terminal_reason` before `subtype`. When the final request fails, such as on an API error, Claude Code reports `subtype` `"success"` with the cause in `terminal_reason`, for example `"api_error"`; when a limit you set ends the run, such as `max_turns` or `max_budget_usd`, it reports an `error_*` subtype.

1914

19131915### `CLIJSONDecodeError`

19141916

19151917Raised when JSON parsing fails.

from line 3387

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

33863388 )

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

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

3390 # carries the error text. A failed final request, such as an API error,

3391 # arrives with subtype "success", so branch on terminal_reason first.

33893392 except ResultError as e:

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

3393 if e.terminal_reason == "api_error":

3394 print(f"API request failed: {e}")

3395 else:

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

33913397 except ProcessError as e:

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

33933399 except CLIJSONDecodeError as e:

cross-session-messaging Changed · +20 / -8 lines

from line 123

123123

124124A session answers to the name you set with the [`/rename`](/docs/en/commands) command or the [`--name`](/docs/en/cli-reference#cli-flags) flag. When you don't set one, Claude Code names the session itself. For an interactive session, that is the name shown in [listings of running sessions](/docs/en/sessions#name-your-sessions).

125125

126When you rename a session, Claude Code also updates the shared record your other sessions use to look up the session's name. If it can't update that record, it warns you in the `/rename` output that other sessions may still show the old name. Run the session with [`--debug`](/docs/en/cli-reference#cli-flags), and Claude Code logs the cause of the failed update.

127

126128When you rename a session, or start or resume an interactive one, with a name another live session on this machine already uses, Claude Code leaves the name with the session that already has it and [renames yours to a variant](/docs/en/sessions#name-your-sessions). Sessions can still share a name, for example when one of them runs an earlier version of Claude Code or the shared name is one Claude Code generated. Claude Code shows each local session's working directory in the `/list-agents` output, so you can tell same-named sessions apart when they run in different directories. Claude addresses the message in one of two ways, depending on how many live sessions answer to the name:

127129

128130* **One session answers to the name**: Claude Code delivers the message on the name alone.

from line 165

163165 What a message looks like

164166</h3>

165167

166When the message arrives, it appears in the conversation under the sender's session name and stays there. Claude Code queues it while Claude is mid-turn, or starts a new turn with it right away when the session is idle.

168When a message arrives, Claude Code shows it in the conversation as a dim one-line preview, and the preview line stays in the conversation afterward. The preview carries the sender's name and the first line of the message, cut with `…` when it's long, such as `› Message from @api-worker: Schema migration finished (ctrl+o to expand)`. Before v2.1.247, Claude Code showed the arriving message in full instead of a preview.

167169

168A message is a piece of text one Claude writes to another. Claude receives it with the sender's name and a reply address, except for a [one-way cross-machine message](#message-sessions-on-other-machines), which carries no reply address. You see the name and the text, and the receiving session gets only that text, never the sender's conversation history or files.

170Either of these shows you the full text:

169171

170This example is a message one Claude wrote to another, as the receiving session sees it:

172* Press `Ctrl+O` to open the [transcript viewer](/docs/en/interactive-mode#transcript-viewer) and read the full text under the sender's session name.

173* In a session started with [`--verbose`](/docs/en/cli-reference#cli-flags), Claude Code shows the full text instead of the preview.

171174

175The preview shortens only what you see. Whether or not you expand it, Claude reads the full message.

176

177Claude receives the message with the sender's name and a reply address, except for a [one-way cross-machine message](#message-sessions-on-other-machines), which carries no reply address. Beyond the name and reply address, the receiving Claude gets only the message's text, never the sender's conversation history or files.

178

179This example is a message one Claude wrote to another, as its full text reads when you expand it:

180

172181```text wrap theme={null}

173Schema migration finished: the new column is tenant_id, and rebasing on main is safe now.

182Schema migration finished

183The new column is tenant_id, and rebasing on main is safe now.

174184```

175185

176186### Control inbound messages

from line 249

239249

240250* **macOS and Linux, including WSL 2**: the line is optional. Claude Code accepts a connection with or without it.

241251* **Native Windows**: the line is required. Claude Code closes any connection whose first line isn't a valid auth line and delivers nothing from that connection.

252

253Open the connection only when the message you're posting is ready. Claude Code closes a connection that hasn't sent a complete line within 30 seconds, so capture a slow command's output first and then open the connection to send it.

242254

243255The [own-child rules](#own-child-messages) below say when Claude Code consults the token and how it treats a message it can't verify.

244256

errors Changed · +22 / -0 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 85

8585| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [Network](#host-not-allowed-in-a-cloud-session) |

8686| `proxy refused the connection` | [Network](#the-proxy-refused-the-connection) |

8787| `403` with `This GraphQL query is not enabled for this session` in a cloud session | [GitHub proxy](/docs/en/cloud-environments#github-proxy) |

88| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [Network](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |

8889| `Couldn't reconnect to your Remote Control session` | [Network](#couldnt-reconnect-to-your-remote-control-session) |

8990| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [Network](#sessions-ended-while-this-machine-was-offline) |

9091| `Couldn't share the transcript.` | [Network](#couldnt-share-the-transcript) |

from line 1240

12391240

12401241Before v2.1.238, Claude Code reported a refused tunnel as a generic network error.

12411242

1243<h3 id="the-cloud-environments-service-returned-an-empty-or-unexpected-response">

1244 The cloud environments service returned an empty or unexpected response

1245</h3>

1246

1247Claude Code requests your [cloud environments](/docs/en/cloud-environments) list at several points, such as when you create a cloud session from the CLI or run [`/remote-env`](/docs/en/cloud-environments#select-an-environment-from-the-cli). When it can't read the server's answer, it shows one of these messages:

1248

1249```text theme={null}

1250The cloud environments service returned an empty response (HTTP 200 with no body). This is usually temporary — try again in a moment.

1251The cloud environments service returned a response in an unexpected format (HTTP 200 with a non-JSON body). This is usually temporary — try again in a moment.

1252The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.

1253```

1254

1255The server accepted the request but answered with a body that isn't the environments list: empty, not JSON, or JSON without the list. This usually accompanies a service-side disruption and clears on its own. Depending on the surface that requested the list, Claude Code may add a prefix, such as `couldn't list environments:` in the `/remote-env` dialog.

1256

1257**What to do:**

1258

1259* Retry the action. Claude Code requests the list again each time

1260* If the message keeps appearing, check [status.claude.com](https://status.claude.com) for active incidents

1261

1262Before v2.1.236, Claude Code showed a raw JavaScript TypeError instead of these messages.

1263

12421264<h3 id="couldnt-reconnect-to-your-remote-control-session">

12431265 Couldn't reconnect to your Remote Control session

12441266</h3>

from line 2510

24882510

24892511### EUNKNOWN when starting a background session

24902512

2491Windows refused to start a program with an error code that has no standard name, so the failure surfaces as `EUNKNOWN`. The usual trigger is a software restriction policy, such as Group Policy or AppLocker, blocking the program being started. The error appears when you start a [background session](/docs/en/agent-view) with `/background` or `claude --bg`:

2492

2493```text theme={null}

2494Couldn't reach the background service (spawn background service: EUNKNOWN: unknown error, uv_spawn) — run 'claude daemon status'

2495```

2496

2497On some accounts the message says `daemon` in place of `background service`.

2498

2499Claude Code starts the background service through PowerShell so the service survives closing the terminal, using PowerShell 7 when it's installed and Windows PowerShell 5.1 otherwise. When neither PowerShell can run, Claude Code starts the service directly instead, so a policy that blocks only PowerShell doesn't cause this error. If you see it, the policy is blocking the Claude Code executable itself.

2500

2501Before v2.1.212, Claude Code used only Windows PowerShell 5.1 to start the service, so any machine where Group Policy blocked PowerShell 5.1 failed with `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`, even with PowerShell 7 installed.

2502

2503**What to do:**

2504

2505* If the message reads `Couldn't start the session`, upgrade to v2.1.212 or later. On earlier versions you can also run `claude daemon run` in a separate terminal first, then start the background session again. That command runs the background service in the terminal's foreground, so the service lasts only as long as that terminal stays open.

2506* If the error appears on v2.1.212 or later, ask your Windows administrator to allow the Claude Code executable in the restriction policy

2507* If the background service stops when you close the terminal, Claude Code started it without PowerShell. Install PowerShell 7, or ask your administrator to unblock PowerShell, so the service can outlive the terminal.

2508

2509## Wrapper and IDE errors

2510

2511These errors come from the program that launched Claude Code for you, such as an IDE extension or an [Agent SDK](/docs/en/agent-sdk/overview) application, rather than from Claude Code itself.

2512

2513### Claude Code pro

2513Windows refused to start a program with an error code that has no standard name, so the failure surfaces as `EUNKNOWN`. The usual trigger is a software restriction policy, such as Group Policy or AppLocker, blocking the program being started. The error appears when you start a

keybindings Changed · +40 / -23 lines

### Non-US keyboard layouts

from line 92

9292

9393Actions available in the `Chat` context:

9494

95| Action | Default | Description |

96| :-------------------- | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

97| `chat:cancel` | Escape | Cancel current input |

98| `chat:clearInput` | Ctrl+L | Force a full screen redraw, preserving input and conversation |

99| `chat:clearScreen` | Cmd+K | Force a full screen redraw, preserving input and conversation. See [Clear the conversation](/docs/en/fullscreen#clear-the-conversation) for how Cmd+K behaves on iTerm2 and Terminal.app |

100| `chat:killAgents` | Ctrl+X Ctrl+K | Stop all running [background subagents](/docs/en/sub-agents#run-subagents-in-foreground-or-background) in this session and turn off [artifact auto-replies](/docs/en/artifacts#let-claude-reply-to-comments-on-its-own) for the rest of it |

101| `chat:cycleMode` | Shift+Tab\* | Cycle permission modes |

102| `chat:modelPicker` | Meta+P | Open model picker |

103| `chat:fastMode` | Meta+O | Toggle fast mode |

104| `chat:thinkingToggle` | Meta+T | Toggle extended thinking |

105| `chat:submit` | Enter | Submit message |

106| `chat:newline` | Ctrl+J | Insert a newline without submitting |

107| `chat:undo` | Ctrl+\_, Ctrl+Shift+- | Undo last action |

108| `chat:externalEditor` | Ctrl+G, Ctrl+X Ctrl+E | Open in external editor |

109| `chat:stash` | Ctrl+S | Stash current prompt |

110| `chat:imagePaste` | Ctrl+V (Alt+V on Windows and WSL) | Paste image from clipboard. On WSL, both shortcuts are bound by default |

95| Action | Default | Description |

97| `chat:cancel` | Escape | Cancel current input |

98| `chat:clearInput` | Ctrl+L | Force a full screen redraw, preserving input and conversation |

101| `chat:cycleMode` | Shift+Tab\* | Cycle permission modes |

102| `chat:modelPicker` | Meta+P | Open model picker |

103| `chat:fastMode` | Meta+O | Toggle fast mode |

104| `chat:thinkingToggle` | Meta+T | Toggle extended thinking |

105| `chat:submit` | Enter | Submit message |

106| `chat:queueSubmit` | Ctrl+X Enter | Submit the message, marked to wait its turn: while Claude is working, Claude Code [queues it](/docs/en/interactive-mode#queue-messages-while-claude-works) and never interrupts the turn. Unlike `chat:submit`, it submits the draft even while autocomplete suggestions are open. Requires v2.1.247 or later |

107| `chat:newline` | Ctrl+J | Insert a newline without submitting |

108| `chat:undo` | Ctrl+\_, Ctrl+Shift+- | Undo last action |

109| `chat:externalEditor` | Ctrl+G, Ctrl+X Ctrl+E | Open in external editor |

110| `chat:stash` | Ctrl+S | Stash current prompt |

111| `chat:imagePaste` | Ctrl+V (Alt+V on Windows and WSL) | Paste image from clipboard. On WSL, both shortcuts are bound by default |

111112

112113\*On Windows without VT mode (Node \<24.2.0/\<22.17.0, Bun \<1.2.23), defaults to Meta+M.

113114

from line 376

375376

376377Claude Code parses key names case-insensitively, so `K` is the same binding as `k` and `ctrl+K` is the same as `ctrl+k`. To bind Shift and a letter, write `shift+k`.

377378

379### Non-US keyboard layouts

380

381Write the key names of Ctrl shortcuts as Latin characters even when your active keyboard layout types other characters.

382

383How Claude Code matches the key you press to a binding depends on the kind of layout:

384

385* Under a non-Latin layout such as Cyrillic, in a terminal that uses the Kitty keyboard protocol and reports the key's US-layout position, Claude Code matches Ctrl shortcuts by that position, so with a Russian layout active, pressing Ctrl and the physical W key triggers `ctrl+w`. In a terminal that doesn't report the position, Claude Code matches whatever the terminal sends for the keypress: an ASCII control code triggers the Latin shortcut, and a keypress that arrives as the Cyrillic character matches no binding

386* Under layouts that rearrange Latin letters, such as AZERTY, Claude Code matches the letter that the key types, so pressing Ctrl and the key labeled A triggers `ctrl+a`

387

388Before v2.1.247, pressing a Ctrl shortcut under a non-Latin layout didn't trigger its binding in terminals that use the Kitty keyboard protocol, such as Ghostty, Kitty, WezTerm, and iTerm2.

389

378390### Chords

379391

380392Chords are sequences of keystrokes separated by spaces:

from line 426

414426

415427This also works for chord bindings. Unbinding every chord that shares a prefix frees that prefix for use as a single-key binding. A chord in any active context keeps its prefix reserved, so you must unbind each chord in the context that defines it.

416428

417The default `Ctrl+X` family spans two contexts: `ctrl+x ctrl+k` and `ctrl+x ctrl+e` in `Chat`, and `ctrl+x ctrl+b` in `Task`. To reclaim `ctrl+x` itself as a single-key binding, unbind all of them:

429Claude Code binds these default chords on the `ctrl+x` prefix: `ctrl+x ctrl+k`, `ctrl+x ctrl+e`, and `ctrl+x enter` in `Chat`, and `ctrl+x ctrl+b` in `Task`. The `ctrl+x enter` chord requires v2.1.247 or later. To reclaim `ctrl+x` itself as a single-key binding, unbind all of them:

418430

419431```json theme={null}

420432{

from line 442

430442 "bindings": {

431443 "ctrl+x ctrl+k": null,

432444 "ctrl+x ctrl+e": null,

445 "ctrl+x enter": null,

433446 "ctrl+x": "chat:newline"

434447 }

435448 }

from line 456

443456

444457These shortcuts cannot be rebound:

445458

446| Shortcut | Reason |

447| :-------- | :--------------------------------------------- |

448| Ctrl+C | Hardcoded interrupt/cancel |

449| Ctrl+D | Hardcoded exit |

450| Ctrl+M | Identical to Enter in terminals (both send CR) |

451| Caps Lock | Not delivered to terminal applications |

459| Shortcut | Reason |

460| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

461| Ctrl+C | Hardcoded interrupt/cancel |

462| Ctrl+D | Hardcoded exit |

463| Ctrl+M | Claude Code always receives it as Enter |

464| Ctrl+\[ | Claude Code always receives it as Escape |

465| Ctrl+I | Claude Code always receives it as Tab |

466| Ctrl+H | Sends the ASCII backspace byte. [How Claude Code reads it on Windows](/docs/en/terminal-config#fix-backspace-deleting-a-whole-word-on-windows) depends on your terminal and the [`CLAUDE_CODE_BS_AS_CTRL_BACKSPACE`](/docs/en/env-vars) environment variable |

467| Caps Lock | Not delivered to terminal applications |

452468

453469## Terminal conflicts

454470

from line 495

479495* Parse errors (invalid JSON or structure)

480496* Invalid context names

481497* Invalid action values, such as an action that isn't a string or `null`

498* Unknown action names, such as a typo of a registered action. Claude Code skips the binding and keeps any default binding for that key in effect. Before v2.1.246, a binding with an unknown action name silently disabled that key

482499* Reserved shortcut conflicts

483500* Duplicate bindings in the same context

484501

worktrees Changed · +26 / -1 lines

from line 114

114114

115115### Clean up subagent and background-session worktrees

116116

117A periodic sweep removes worktrees that Claude created for subagents and [background sessions](/docs/en/agent-view#how-file-edits-are-isolated) once they are older than your [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) setting, following the [retention sweep rules](/docs/en/claude-directory#cleaned-up-automatically). The sweep skips a worktree that still holds work: changed or untracked files, or unpushed commits. It never removes worktrees you create with `--worktree`.

117Claude Code runs a periodic sweep that removes worktrees that Claude created for subagents and [background sessions](/docs/en/agent-view#how-file-edits-are-isolated) once they are older than your [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) setting, following the [retention sweep rules](/docs/en/claude-directory#cleaned-up-automatically).

118118

119When you [background](/docs/en/agent-view#send-the-session-to-the-background) a `--worktree` session, its worktree becomes a background-session worktree that the sweep can remove. The sweep leaves a worktree in place in these cases:

120

121* The worktree still holds work: changed or untracked files, or unpushed commits.

122* Claude Code can't determine which filter drivers the repository config defines, in any of the [three cases that also block worktree creation](#git-lfs-content-is-missing-from-a-worktree-claude-code-created).

123* The worktree belongs to a `--worktree` session you haven't backgrounded, whatever its age.

124* You created the worktree yourself with `git worktree add`, even if you then ran a `--worktree <name>` session in it and backgrounded that session.

125

126Claude Code writes a marker into the git metadata of every worktree it creates with git, and the sweep keeps any worktree without one, including a worktree a [`WorktreeCreate` hook](#non-git-version-control) created. Before v2.1.246, the sweep didn't check for the marker, and could remove a worktree you created yourself when an old background-session record pointed at it.

127

119128While an agent is running, Claude runs `git worktree lock` on its worktree so that concurrent cleanup cannot remove it. The lock is released when the agent finishes.

120129

121130The sweep also releases a lock Claude Code set for a session whose process has exited, so a killed background session doesn't leave its worktree permanently locked. The sweep never releases a lock you set yourself with `git worktree lock`. Before v2.1.210, a lock left by a killed session stayed in place until you ran `git worktree unlock`.

from line 298

289298### Worktree creation fails on a symlinked path

290299

291300Claude Code refuses to create a worktree when `.claude`, `.claude/worktrees`, or the worktree directory itself is a symlink, and the error names the symlinked path. Remove the symlink and retry. Before v2.1.212, if the repository already contained a committed symlink at one of those paths, worktree creation followed it and could create files outside the repository.

301

302<h3 id="git-lfs-content-is-missing-from-a-worktree-claude-code-created">

303 Git LFS files are pointer files in a worktree Claude Code created

304</h3>

305

306If you set up [Git LFS](https://git-lfs.com) with `git lfs install --local`, a worktree that Claude Code creates contains LFS pointer files instead of the real files. The `--local` flag writes the LFS filter into the repository's own `.git/config` rather than your global git config. A plain `git lfs install` writes to your global config and isn't affected. The same applies to any other [filter driver](https://git-scm.com/docs/gitattributes) defined in the repository's own config.

307

308Claude Code skips the repository's own filter drivers when it creates a worktree because a filter driver is a shell command, and anything that can write to the repository, including Claude, could have put one there. Before v2.1.247, Claude Code ran those drivers during worktree creation.

309

310To get the real files, run `git lfs pull` inside the worktree.

311

312In three rare cases, Claude Code can't tell which filter drivers the repository's config defines, and creates no worktree at all. Match the error to its fix:

313

314* **`Could not read the repository git config to neutralize filter drivers`**: Claude Code couldn't read the repository's `.git/config`, for example because of its permissions. Fix that and retry.

315* **`The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline)`**: rename or remove that filter driver in `.git/config` and retry.

316* **`The repository git config has a conditional include (includeIf)`**: move the settings the `includeIf` in `.git/config` pulls in directly into that file, remove the `includeIf`, and retry. An `includeIf` in your global git config doesn't trigger this.

292317

293318### Claude Code refuses to use a worktree

294319

interactive-mode Changed · +1 / -1 lines

from line 19

1919| `Ctrl+D` | Exit Claude Code session | The first press shows a confirmation hint and a second press within 800ms exits. When the prompt has text, `Ctrl+D` deletes the character after the cursor instead |

2020| `Ctrl+G` or `Ctrl+X Ctrl+E` | Open in default text editor | Edit your prompt or custom response in your default text editor. `Ctrl+X Ctrl+E` is the readline-native binding. Turn on **Show last response in external editor** in `/config` to prepend Claude's previous reply as `#`-commented context above your prompt; Claude Code strips the comment block when you save |

2121| `Ctrl+L` | Redraw screen | Forces a full terminal redraw, keeping input and conversation history. Use this to recover if the display becomes garbled or partially blank |

22| `Ctrl+O` | Toggle transcript viewer | Shows detailed tool usage and execution, with a timestamp and the model used on each assistant message. Also expands MCP calls, which collapse to a single line like "Called slack 3 times" by default |

22| `Ctrl+O` | Toggle transcript viewer | Shows detailed tool usage and execution, with a timestamp and the model used on each assistant message. Also expands lines that collapse by default, such as MCP calls, shown as a single `Called slack 3 times` line, and [messages from your other sessions](/docs/en/cross-session-messaging#what-a-message-looks-like), shown as a one-line `Message from @<sender>` preview |

2323| `Ctrl+R` | Reverse search command history | Search through previous commands interactively |

2424| `Ctrl+V` or `Cmd+V` (iTerm2) or `Alt+V` (Windows and WSL) | Paste image from clipboard | Inserts an `[Image #N]` chip at the cursor so you can reference it positionally in your prompt. On WSL, both `Ctrl+V` and `Alt+V` are bound; use `Alt+V` if your terminal intercepts `Ctrl+V` |

2525| `Ctrl+B` | Background running tasks | Backgrounds Bash commands and agents. Tmux users press twice |

plugin-dependencies Changed · +1 / -1 lines

from line 4

55A plugin can depend on other plugins by listing them in `plugin.json` or in its marketplace entry. By default, a dependency tracks the latest available version, so an upstream release can change the dependency under your plugin without warning. Version constraints let you hold a dependency at a tested version range until you choose to move.

7When you install a plugin that declares dependencies, Claude Code resolves and installs them automatically, apart from a dependency whose marketplace entry has a [`command` source](/docs/en/plugin-marketplaces#how-users-accept-the-command) or a [`headersHelper`](/docs/en/plugin-marketplaces#how-users-accept-a-headershelper-command), which you install yourself first. If a dependency later goes missing, `/reload-plugins` and the background plugin auto-update reinstall it, provided its marketplace is already in your configured marketplaces. Re-running `claude plugin install` on the dependent plugin, or adding a marketplace with `claude plugin marketplace add`, also resolves any outstanding missing dependencies. Dependencies from a marketplace you have not added are left unresolved.

7When you install a plugin that declares dependencies, Claude Code resolves and installs them automatically, apart from a dependency whose marketplace entry has a [`command` source](/docs/en/plugin-marketplaces#how-users-accept-the-command) or a [`headersHelper`](/docs/en/plugin-marketplaces#how-users-accept-a-headershelper-command), which you install yourself first. Later, `/reload-plugins`, auto-update of the dependent plugin's marketplace, re-running `claude plugin install` on the dependent plugin, and `claude plugin marketplace add` each install any declared dependency that isn't installed yet, under the same rules; if one stays unresolved, see [Resolve dependency errors](#resolve-dependency-errors).

99This guide is for plugin authors who declare dependencies in `plugin.json` and for marketplace maintainers who tag releases. Dependencies here are other plugins; for the npm and Bun packages a plugin itself uses, see [Node.js package dependencies](/docs/en/plugins-reference#node-js-package-dependencies). To install plugins that have dependencies, see [Discover and install plugins](/docs/en/discover-plugins). For the full manifest schema, see the [Plugins reference](/docs/en/plugins-reference).

1010

plugin-marketplaces Changed · +1 / -1 lines

from line 823

823823

824824Don't include a top-level `bin/` directory in any plugin you distribute through organization settings. claude.ai rejects a plugin that has one, whether the plugin arrives by marketplace sync or by direct upload:

825825

826* **Marketplace sync**: organization sync rejects that plugin and syncs the rest of the marketplace. The error code is `marketplace_sync_bin_directory_not_allowed` and the message starts with `Plugin contains a top-level bin/ directory`.

826* **Marketplace sync**: organization sync rejects that plugin and syncs the rest of the marketplace. The error message starts with `Plugin contains a top-level bin/ directory`.

827827* **Direct upload**: if you upload the plugin in [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins) instead, claude.ai rejects the upload with the same message.

828828

829829Keep executables in another directory, such as `scripts/`, and reference them as `${CLAUDE_PLUGIN_ROOT}/scripts/<name>` from your [skills, hooks, or MCP server configs](/docs/en/plugins-reference#environment-variables).