claude-code-20260918T013702Z / documentation capture

What this read moved

1–5 of 5

discover-plugins Changed · +33 / -2 lines

### Add from claude.ai ### Add a marketplace and install in one command

from line 213

213213* **Git URLs**: any git repository URL, including GitLab, Bitbucket, and self-hosted servers

214214* **Local paths**: directories or direct paths to `marketplace.json` files

215215* **Remote URLs**: direct URLs to hosted `marketplace.json` files

216* **claude.ai**: marketplaces hosted on claude.ai for your account, such as your organization's plugin library, which you [add by name from the **Marketplaces** tab or your shell](#add-from-claude-ai) rather than by source

216217

217218### Add from GitHub

218219

from line 283

282283 URL-based marketplaces have some limitations compared to Git-based marketplaces. If plugin installs from a URL-based marketplace fail, see [Troubleshooting](/docs/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces).

283284</Note>

284285

286### Add from claude.ai

287

288In terminal sessions where [plugins sync from your claude.ai account](/docs/en/plugins-reference#synced-plugins), claude.ai can also list marketplaces for you, such as your organization's plugin library and your own claude.ai uploads. `claude plugin marketplace list` prints them in a `From claude.ai:` section, and the `/plugin` **Marketplaces** tab lists them. Select one there to add it. Adding a marketplace from claude.ai requires Claude Code v2.1.273 or later.

289

290To add one from your shell, run `claude plugin marketplace add` with the `--claudeai` flag and the name shown in the list:

291

292```bash theme={null}

293claude plugin marketplace add --claudeai claudeai-organization-library

294```

295

296Claude Code registers the marketplace under a local name that starts with `claudeai-`, derived from the name that claude.ai lists it under: a marketplace listed as "Organization library" registers as `claudeai-organization-library`. Install its plugins by that name, for example with `claude plugin install <plugin>@claudeai-organization-library`.

297

298If you sign out or sign in with a different account, the marketplace stays configured but shows no plugins, and the plugins you already installed from it keep loading.

299

300The `From claude.ai:` section can also list git-based marketplaces shared through claude.ai. You add those with the ordinary `marketplace add` command, using the source that the list prints.

301

285302## Install plugins

286303

287Once you've added marketplaces, you can install a plugin by name:

304Once you've added marketplaces, you can install a plugin by name. For a marketplace you haven't added yet, you can instead [add it and install in one command](#add-a-marketplace-and-install-in-one-command).

288305

306To install by name:

307

289308```shell theme={null}

290309/plugin install plugin-name@marketplace-name

291310```

from line 345

326345 Make sure you trust a plugin before installing it. Anthropic doesn't control what MCP servers, files, or other software are included in plugins and can't verify that they work as intended. Check each plugin's homepage for more information.

327346</Warning>

328347

348### Add a marketplace and install in one command

349

350To install a plugin from a marketplace you haven't added yet, name the marketplace source with `--marketplace`. Requires Claude Code v2.1.275 or later.

351

352```shell theme={null}

353/plugin install quality-review-plugin --marketplace your-org/plugins

354```

355

356The source takes [the same forms as `/plugin marketplace add`](#add-marketplaces), such as GitHub `owner/repo`, a git URL, or a local path, except that it can't contain spaces. Give the plugin name bare, without an `@marketplace` suffix.

357

358If you haven't added that marketplace yet, Claude Code shows the source it resolved and asks you to confirm before adding it. Declining cancels the install and adds nothing. Once the marketplace is added, the plugin's details open and you choose an [installation scope](/docs/en/settings#where-settings-live).

359

329360## Manage installed plugins

330361

331362Run `/plugin` and go to the **Installed** tab to view, enable, disable, or uninstall your plugins. The list is grouped by scope and sorted so you see problems first: plugins with load errors or unresolved dependencies appear at the top, followed by your favorites, with disabled plugins folded behind a collapsed header at the bottom.

from line 509

4785093. Choose a marketplace from the list

4795104. Select **Enable auto-update** or **Disable auto-update**

480511

481`claude-plugins-official` and most other official Anthropic marketplaces have auto-update enabled by default. Third-party and local development marketplaces have auto-update disabled by default.

512`claude-plugins-official`, most other official Anthropic marketplaces, and [marketplaces added from claude.ai](#add-from-claude-ai) have auto-update enabled by default. Other third-party marketplaces and local development marketplaces have auto-update disabled by default.

482513

483514Administrators can also set `"autoUpdate": true` on each [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) entry in managed settings to enable auto-update for an organization marketplace without requiring each user to toggle it.

484515

plugin-marketplaces Changed · +27 / -6 lines

from line 162

162162 **Reserved names**: the following marketplace names are reserved for official Anthropic use and can't be used by third-party marketplaces: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `claude-plugins-community`, `claude-community`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`, `first-party-plugins`, `claude-tag-plugins`, `healthcare`. Names that impersonate official marketplaces, such as `official-claude-plugins` or `anthropic-plugins-v2`, are also blocked. Reserving these names prevents a third-party marketplace from presenting itself as an Anthropic-published source.

163163

164164 Claude Code re-checks reserved names every time it loads a marketplace, not only when you add one. A marketplace that was registered under one of these names before the name became reserved stops loading and reports that it is [registered from an untrusted source](/docs/en/errors#marketplace-is-registered-from-an-untrusted-source). Remove that marketplace and re-add it from the official Anthropic source. A third-party marketplace affected by a newly reserved name loads again as soon as you re-add it under a different name. Before v2.1.205, `first-party-plugins` and `healthcare` weren't reserved, and a marketplace already registered under a reserved name kept loading. Before v2.1.265, `claude-tag-plugins` wasn't reserved.

165

166 You also can't name a marketplace `npm`, `pip`, `uv`, `cargo`, `github`, or `gh`, in any casing. This check requires Claude Code v2.1.275 or later.

165167</Note>

166168

167169### Owner fields

from line 258

262264

from line 403

401403

402404### npm packages

403405

404Plugins distributed as npm packages are installed using `npm install`. This works with any package on the public npm registry or a private registry your team hosts.

406An npm source can name any package on the public npm registry or on a private registry your team hosts. Claude Code resolves the package with your npm client, downloads the tarball, and unpacks it into the plugin cache.

405407

408The package's install scripts, such as `preinstall` or `postinstall`, never run, and its dependencies aren't installed during the fetch.

409

410If the package ships a supported lockfile beside its `package.json`, Claude Code installs those [Node.js package dependencies](/docs/en/plugins-reference#node-js-package-dependencies) in a separate step, also with scripts disabled. Otherwise, publish the plugin with everything it needs already built. An MCP server that needs other packages can launch through `npx`, which installs them at first run.

411

406412```json theme={null}

407413{

408414 "name": "my-npm-plugin",

from line 1066

10601066

10611067The allowlist's exact matching treats URLs that differ only by a trailing slash, a `.git` suffix, or the `ssh://` and `https://` scheme as different values. If your organization's marketplace can be cloned by more than one URL form, prefer a `hostPattern` entry over a literal URL so the `https://`, `ssh://`, and `user@host:path` forms all match.

10621068

1069A [marketplace hosted on claude.ai](/docs/en/discover-plugins#add-from-claude-ai) is matched by host: a `hostPattern` entry that matches `claude.ai` governs it, in `strictKnownMarketplaces` and in `blockedMarketplaces`. On the allowlist, such an entry doesn't admit a member's personal claude.ai uploads. Requires Claude Code v2.1.273 or later.

1070

10631071Because `strictKnownMarketplaces` is set in [managed settings](/docs/en/managed-settings), individual users and project configurations can't override these restrictions.

10641072

10651073For complete configuration details including all supported source types and comparison with `extraKnownMarketplaces`, see the [strictKnownMarketplaces reference](/docs/en/settings-reference#strictknownmarketplaces).

from line 1251

12431251

12441252**Options:**

12451253

1246| Option | Description | Default |

1247| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |

1248| `--scope <scope>` | Where to declare the marketplace: `user`, `project`, or `local`. See [Plugin installation scopes](/docs/en/plugins-reference#plugin-installation-scopes) | `user` |

1249| `--sparse <paths...>` | Limit checkout to specific directories via git sparse-checkout. Useful for monorepos | |

1254| Option | Description | Default |

1255| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |

1256| `--scope <scope>` | Where to declare the marketplace: `user`, `project`, or `local`. See [Plugin installation scopes](/docs/en/plugins-reference#plugin-installation-scopes) | `user` |

1257| `--sparse <paths...>` | Limit checkout to specific directories via git sparse-checkout. Useful for monorepos | |

1258| `--claudeai` | Read the argument as the name of a [marketplace hosted on claude.ai](/docs/en/discover-plugins#add-from-claude-ai) instead of a source. Requires Claude Code v2.1.273 or later | |

12501259

12511260Add a marketplace from GitHub using `owner/repo` shorthand:

12521261

from line 1299

12901299claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

12911300```

12921301

1302Add a [marketplace hosted on claude.ai](/docs/en/discover-plugins#add-from-claude-ai) by the name printed in the `From claude.ai:` section of `claude plugin marketplace list`:

1303

1304```bash theme={null}

1305claude plugin marketplace add --claudeai claudeai-organization-library

1306```

1307

1308With `--claudeai`, the command refuses `--scope` and `--sparse`. The marketplace is hosted for your account, not declared in a settings file, so you can't share it through a project's `.claude/settings.json`.

1309

12931310### Plugin marketplace list

12941311

12951312List all configured marketplaces.

from line 1322

13051322| `--json` | Output as JSON |

13061323

13071324With `--json`, each entry includes `name`, `source`, an `installLocation` field with the local cache path where the marketplace is stored, and source-specific fields: `repo` for GitHub sources, `url` for git and URL sources, and `path` for local sources. GitHub and git sources also include a `ref` field when the marketplace was added with a pinned branch or tag.

1325

1326An added [claude.ai marketplace](/docs/en/discover-plugins#add-from-claude-ai) has no local clone, so its entry carries its claude.ai identifiers, `marketplaceId` and `organizationUuid`, in place of `installLocation`.

1327

1328In terminal sessions where [plugins sync from your claude.ai account](/docs/en/plugins-reference#synced-plugins), the text listing ends with a `From claude.ai:` section naming what claude.ai lists for your account beyond the marketplaces you've added. To add one of them, see [Add from claude.ai](/docs/en/discover-plugins#add-from-claude-ai). The `--json` output covers configured marketplaces only and leaves that section out. Requires Claude Code v2.1.273 or later.

13081329

13091330### Plugin marketplace remove

13101331

plugins-reference Changed · +9 / -5 lines

from line 89

8989

9090**Format**: JSON configuration with event matchers and actions

9191

92`hooks/hooks.json` can carry a top-level `$schema` key that names a JSON Schema URL for editor autocomplete and validation. Claude Code ignores the key at load time.

9294**Hook configuration**:

9395

9496```json theme={null}

from line 831

829831| `bun.lock` or `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |

830832| `npm-shrinkwrap.json` or `package-lock.json` | `npm ci --ignore-scripts` |

831833

832If a plugin contains more than one of these lockfiles, Claude Code uses the first match, checking in order: `bun.lock`, `bun.lockb`, `npm-shrinkwrap.json`, `package-lock.json`. Claude Code skips `yarn.lock` and `pnpm-lock.yaml` because Yarn and pnpm support resolution-time configuration hooks that bypass `--ignore-scripts`.

834If a plugin contains more than one of these lockfiles, Claude Code uses the first match, checking in order: `bun.lock`, `bun.lockb`, `npm-shrinkwrap.json`, `package-lock.json`.

833835

836Claude Code skips `yarn.lock` and `pnpm-lock.yaml` because Yarn and pnpm support resolution-time configuration hooks that bypass `--ignore-scripts`. When a `bunfig.toml` sits beside the matched bun lockfile, Claude Code skips the install entirely, because the file can configure a security scanner that Bun loads and runs during the install. The filename match ignores letter case. Remove the `bunfig.toml`, or ship an npm lockfile in place of the bun lockfile.

837

834838Ship an npm lockfile for the widest reach. Claude Code runs the matched lockfile's package manager from the user's PATH and doesn't fall back to the other lockfile if it's missing. For a plugin distributed through an npm source, use `npm-shrinkwrap.json`; npm excludes `package-lock.json` from published packages.

835839

836840Claude Code constrains this dependency install so that no code from the plugin or its packages executes during it, and bounds how long it can run:

from line 843

839843* **No lifecycle scripts:** `--ignore-scripts` keeps `preinstall`, `install`, and `postinstall` scripts from running, so dependencies that build native modules in those scripts download but don't compile during this install.

840844* **60-second timeout:** Claude Code stops an install that runs longer and treats it as failed.

841845

842Fetching an npm-source plugin itself runs `npm install` with lifecycle scripts enabled, before this dependency install runs.

846Claude Code fetches an npm-source plugin before this dependency install, and none of the package's own install scripts run during the fetch. See [npm packages](/docs/en/plugin-marketplaces#npm-packages).

843847

844A failed or skipped install never blocks the plugin. When the install fails, or Claude Code skips a yarn or pnpm lockfile, it records the reason as a warning in [debug output](#debugging-commands). A plugin with a `package.json` and no lockfile is skipped without a log entry. A timed-out install can leave a partial `node_modules` tree in the cached copy.

848A failed or skipped install never blocks the plugin. When the install fails, or Claude Code skips a yarn or pnpm lockfile or a bun lockfile with a `bunfig.toml` beside it, it records the reason as a warning in [debug output](#debugging-commands). A plugin with a `package.json` and no lockfile is skipped without a log entry. A timed-out install can leave a partial `node_modules` tree in the cached copy.

845849

846850You can't turn the automatic install off; no setting or environment variable disables it. In restricted networks, see the [network access requirements](/docs/en/network-config#network-access-requirements) for the hosts to allow.

847851

from line 1462

145814622. The `version` field in the plugin's marketplace entry in `marketplace.json`

145914633. The git commit SHA of the plugin's source, for `github`, `url`, `git-subdir`, and relative-path sources in a git-hosted marketplace

146014644. The SHA-256 digest, for [`archive` sources](/docs/en/plugin-marketplaces#zip-archives): the `sha256` pin in the marketplace entry, or the digest of the downloaded file when you set no pin. Claude Code shortens it to the first 12 characters

14615. `unknown`, for `npm` sources or local directories not inside a git repository

14655. `unknown`, for `npm` sources, or for local directories when neither the plugin directory nor its marketplace is a git repository. Claude Code doesn't take the version from a repository that encloses the install path, such as a git-managed `~/.claude`

14621466

14631467For a [`command` source](/docs/en/plugin-marketplaces#command-sources), Claude Code always derives the version from what the command produced: a 12-character content hash on its own, or appended to the `plugin.json` version as `<version>-<hash>` when one is set. Claude Code ignores the marketplace entry's `version` field for command sources. A command whose hashed output changes therefore produces a new version, even when the authored version string stays the same. In [link mode](/docs/en/plugin-marketplaces#copy-mode-and-link-mode), the hash covers the printed directory's real path and its top-level entries rather than the file contents.

14641468

plugin-dependencies Changed · +1 / -1 lines

from line 65

6565

6666Installing `backend-standard` resolves and installs all four dependencies.

6767

68To add a tool to the standard set later, publish a new `backend-standard` version with the extra dependency. Auto-update is off by default for non-Anthropic marketplaces, so engineers pick up the new version in one of two ways:

68To add a tool to the standard set later, publish a new `backend-standard` version with the extra dependency. Unless the marketplace [auto-updates](/docs/en/discover-plugins#configure-auto-updates), engineers pick up the new version in one of two ways:

6969

7070* Enable auto-update for the marketplace in `/plugin`. The next auto-update moves the bundle to the new version and installs any dependencies it adds.

7171* Run `claude plugin update backend-standard`, then `/reload-plugins` to install the newly added dependencies.

sandboxing Changed · +1 / -1 lines

from line 500

500500

501501* **In your working directory and the directories above it**: the `.claude` settings files, the `.claude/skills`, `.claude/agents`, `.claude/commands`, and `.claude/hooks` directories, `.mcp.json`, and the files Claude Code runs on its own, such as `.claude/workflows` and `.claude/scheduled_tasks.json`

502502* **In your working directory only**: shell startup files such as `.bashrc` and `.zshrc`, `.gitconfig`, the `.vscode` and `.idea` directories, and `hooks` and `config` inside `.git`

503* **Files that would turn your working directory into a bare git repository**: `HEAD`, `objects`, and `refs` at the top level, plus `config` and `hooks` there when they already exist, even when the `config` directory belongs to your project rather than to git. On Linux and WSL2, the sandbox deletes a top-level `HEAD` file or `objects` or `refs` directory that appears while a sandboxed command is running

503* **Files that would turn your working directory into a bare git repository**: `HEAD`, `objects`, and `refs` at the top level, plus `config` and `hooks` there when a `HEAD` sits beside them. A file named `config` is denied even with no `HEAD`. On Linux and WSL2, the sandbox deletes a top-level `HEAD` file or `objects` or `refs` directory that appears while a sandboxed command is running

504504* **In `~/.claude`, or the directory `CLAUDE_CONFIG_DIR` points to**: most of its contents, plus `~/.claude.json` and the `.credentials.json` credential store

505505

506506If a symlink appears at a protected settings file's path during the session, the sandbox also denies writes to the file it points to, starting with the next command.