Follow Discord
Sweep 28 Sep 2026 · 18:16Z Build v2.1.284 505 read Stable v2.1.277 Latest v2.1.284 Next v2.1.284 Feeds RSS JSON llms.txt llms-full.txt Unofficial
HomeDocsClaude Code CLI
One capture · claude-code

One read of Claude Code CLIclaude-code-20260928T233702Z

154 pages moved out of 210 read.

Pages moved 154 significant first
Pages read 210 in this capture
Captured 23:37 UTC
Corpus hash 82a8d4497843 corpus-hash

What this read moved

101-125 of 154, page 5 of 7

This capture is too large to show at once. Changes 101-125 of 154 are below, significant first; the rest are on the following screens.

permissions Changed · +90 / -90 lines

from line 8
88 
99Claude Code uses a tiered permission system to balance power and safety. The table shows, for each tool type, whether Manual mode asks before the action runs. The other [permission modes](#permission-modes) change which of these ask you; in auto mode a classifier reviews actions instead of you, and [how the classifier evaluates actions](/docs/en/permission-modes#how-the-classifier-evaluates-actions) lists which ones it sees.
1010 
11| Tool type | Example | Approval required | "Yes, and don't ask again" behavior |
12| :---------------- | :--------------- | :------------------------------------------------------------------------------------------------------------ | :------------------------------------- |
13| Read-only | File reads, Grep | No, within the [working directory and additional directories](#working-directories) | N/A |
14| Bash commands | Shell execution | Yes, except a built-in set of [read-only commands](#read-only-commands) | Permanently per repository and command |
15| File modification | Edit/write files | Yes | Until session end |
16| Web fetch | WebFetch | Yes, except a built-in set of [preapproved documentation domains](/docs/en/tools-reference#webfetch-tool-behavior) | Permanently per repository and domain |
17| Web search | WebSearch | Yes | Permanently per repository |
11| Tool type | Example | Approval required | "Yes, and don't ask again" behavior |
12| :- | :- | :- | :- |
13| Read-only | File reads, Grep | No, within the [working directory and additional directories](#working-directories) | N/A |
14| Bash commands | Shell execution | Yes, except a built-in set of [read-only commands](#read-only-commands) | Permanently per repository and command |
15| File modification | Edit/write files | Yes | Until session end |
16| Web fetch | WebFetch | Yes, except a built-in set of [preapproved documentation domains](/docs/en/tools-reference#webfetch-tool-behavior) | Permanently per repository and domain |
17| Web search | WebSearch | Yes | Permanently per repository |
1818 
1919When you choose "Yes, and don't ask again" and the approval saves permanently, such as for a Bash command or a WebFetch domain, Claude Code saves the rule to `.claude/settings.local.json` at the root of the git repository, resolved through [worktrees](/docs/en/worktrees) to the main checkout. The rule applies to future sessions anywhere in that repository, including sessions started in subdirectories and in worktrees. A file-modification approval isn't saved to the file: as the table shows, it lasts until the session ends. In some cases, such as outside a git repository or on Windows, Claude Code doesn't use the repository root; [Where Claude Code looks for each file](/docs/en/settings#where-claude-code-looks-for-each-file) lists those cases and where it saves the rule instead.
2020 
from line 63
6363 
6464Claude Code supports several permission modes that control how it approves tool calls. See [Permission modes](/docs/en/permission-modes) for when to use each one. To change the mode sessions start in, set `defaultMode` in your [settings files](/docs/en/settings#where-settings-live). [Which mode a session starts in](/docs/en/permission-modes#which-mode-a-session-starts-in) covers the built-in default for each plan and what the VS Code extension reads.
6565 
66| Mode | Description |
67| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68| `default` | Prompts for permission on first use of each tool. Labeled Manual in the CLI, the VS Code and JetBrains extensions, and the desktop app, and Claude Code accepts `manual` as an alias. The label and alias require Claude Code v2.1.200 or later. The desktop app's label doesn't depend on your CLI version |
69| `acceptEdits` | Automatically accepts file edits and common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp` for paths in the working directory or `additionalDirectories` |
70| `plan` | Claude reads files and runs read-only shell commands to explore but doesn't edit your source files; with [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) available, classifier-approved commands also run. Labeled Plan in the CLI and the VS Code extension |
71| `auto` | Auto-approves tool calls with background safety checks that verify actions align with your request |
72| `dontAsk` | Auto-denies every call that would otherwise prompt; file reads in your working directories and other actions that need no approval still run, as do tools pre-approved via `/permissions` or `permissions.allow` rules. `AskUserQuestion`, MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool), and connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) in sessions where that setting reaches Claude Code are denied even if you've allowed them |
73| `bypassPermissions` | Skips permission prompts, except for the [actions no mode auto-approves](/docs/en/permission-modes#actions-no-mode-auto-approves) |
66| Mode | Description |
67| :- | :- |
68| `default` | Prompts for permission on first use of each tool. Labeled Manual in the CLI, the VS Code and JetBrains extensions, and the desktop app, and Claude Code accepts `manual` as an alias. The label and alias require Claude Code v2.1.200 or later. The desktop app's label doesn't depend on your CLI version |
69| `acceptEdits` | Automatically accepts file edits and common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp` for paths in the working directory or `additionalDirectories` |
70| `plan` | Claude reads files and runs read-only shell commands to explore but doesn't edit your source files; with [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) available, classifier-approved commands also run. Labeled Plan in the CLI and the VS Code extension |
71| `auto` | Auto-approves tool calls with background safety checks that verify actions align with your request |
72| `dontAsk` | Auto-denies every call that would otherwise prompt; file reads in your working directories and other actions that need no approval still run, as do tools pre-approved via `/permissions` or `permissions.allow` rules. `AskUserQuestion`, MCP tools marked [`requiresUserInteraction`](/docs/en/mcp#require-approval-for-a-specific-tool), and connector tools [your organization set to `ask`](/docs/en/mcp#organization-controls-on-connector-tools) in sessions where that setting reaches Claude Code are denied even if you've allowed them |
73| `bypassPermissions` | Skips permission prompts, except for the [actions no mode auto-approves](/docs/en/permission-modes#actions-no-mode-auto-approves) |
7474 
7575<Warning>
7676 In `bypassPermissions` mode, Claude Code skips permission prompts, including for writes to [protected paths](/docs/en/permission-modes#protected-paths) such as `.git` and `.claude`. The [cross-session messaging safeguards](/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) still apply. Only use this mode in isolated environments like containers or VMs where Claude Code can't cause damage.
from line 86
8686 
8787To match all uses of a tool, use only the tool name without parentheses:
8888 
89| Rule | Effect |
90| :--------- | :----------------------------- |
91| `Bash` | Matches all Bash commands |
89| Rule | Effect |
90| :- | :- |
91| `Bash` | Matches all Bash commands |
9292| `WebFetch` | Matches all web fetch requests |
93| `Read` | Matches all file reads |
93| `Read` | Matches all file reads |
9494 
9595`Bash(*)` is equivalent to `Bash` and matches all Bash commands. As a deny rule, both forms remove the tool from Claude's context.
9696 
from line 98
9898 
9999Add a specifier in parentheses to match specific tool uses:
100100 
101| Rule | Effect |
102| :----------------------------- | :------------------------------------------------------- |
103| `Bash(npm run build)` | Matches the exact command `npm run build` |
104| `Read(./.env)` | Matches reading the `.env` file in the current directory |
105| `WebFetch(domain:example.com)` | Matches fetch requests to example.com |
101| Rule | Effect |
102| :- | :- |
103| `Bash(npm run build)` | Matches the exact command `npm run build` |
104| `Read(./.env)` | Matches reading the `.env` file in the current directory |
105| `WebFetch(domain:example.com)` | Matches fetch requests to example.com |
106106 
107107### Match by input parameter
108108 
from line 112
112112 
113113A parameter rule matches when Claude calls the tool with that parameter set to that exact value. An allow rule for one parameter value wouldn't establish that the call is safe overall, so allow rules continue to use each tool's own specifier syntax. This works for any scalar parameter the tool accepts:
114114 
115| Rule | Matches |
116| :----------------------------- | :------------------------------------------- |
117| `Agent(model:opus)` | Agent calls that request the Opus model tier |
118| `Agent(isolation:worktree)` | Agent calls that request a git worktree |
119| `Bash(run_in_background:true)` | Bash calls that run in the background |
115| Rule | Matches |
116| :- | :- |
117| `Agent(model:opus)` | Agent calls that request the Opus model tier |
118| `Agent(isolation:worktree)` | Agent calls that request a git worktree |
119| `Bash(run_in_background:true)` | Bash calls that run in the background |
120120 
121121Parameter matching follows these rules:
122122 
from line 155
155155 
156156A `*` can go anywhere in the rule: at the start, in the middle, or at the end. Each row shows a rule, commands it matches, and nearby commands it doesn't match:
157157 
158| You write | Matches | Doesn't match |
159| :--------------------- | :----------------------------------------------------------------------------------- | :------------------------------------- |
160| `Bash(npm run build)` | `npm run build` | `npm run build --watch` |
161| `Bash(npm run *)` | `npm run build`, `npm run test --watch`, `npm run` | `npm install` |
162| `Bash(git log * main)` | `git log --oneline main`, `git log -5 main`, `git log --output=<file> main` | `git log main`, `git push origin main` |
163| `Bash(git * main)` | `git merge main`, `git push origin main`, `git -c core.fsmonitor=<script> diff main` | `git log` |
164| `Bash(* --version)` | `node --version`, `bash -c 'echo hi' --version` | `node -v` |
165| `Bash(ls *)` | `ls -la`, `ls` | `lsof` |
166| `Bash(ls*)` | `ls -la`, `lsof` | |
167| `Bash(* --help *)` | `npm --help x` | `npm --help` |
158| You write | Matches | Doesn't match |
159| :- | :- | :- |
160| `Bash(npm run build)` | `npm run build` | `npm run build --watch` |
161| `Bash(npm run *)` | `npm run build`, `npm run test --watch`, `npm run` | `npm install` |
162| `Bash(git log * main)` | `git log --oneline main`, `git log -5 main`, `git log --output=<file> main` | `git log main`, `git push origin main` |
163| `Bash(git * main)` | `git merge main`, `git push origin main`, `git -c core.fsmonitor=<script> diff main` | `git log` |
164| `Bash(* --version)` | `node --version`, `bash -c 'echo hi' --version` | `node -v` |
165| `Bash(ls *)` | `ls -la`, `ls` | `lsof` |
166| `Bash(ls*)` | `ls -la`, `lsof` | |
167| `Bash(* --help *)` | `npm --help x` | `npm --help` |
168168 
169169Three matching rules produce those rows:
170170 
from line 234
234234 
235235A Bash rule matches the command text Claude writes, after Claude Code splits [compound commands](#compound-commands) and strips [wrappers](#process-wrappers). It doesn't match the same program invoked in a different form, so a deny or ask rule covers the invocation Claude usually produces and isn't a security boundary around the program. These rules in `deny` or `ask` stop the first form and not the others:
236236 
237| Rule | Stops | Doesn't stop |
238| :----------------- | :------------------------- | :---------------------------------------------------------------------------------------------------- |
239| `Bash(curl *)` | `curl https://example.com` | `/usr/bin/curl https://example.com`, `sh -c 'curl https://example.com'` |
240| `Bash(rm *)` | `rm -rf build/` | `/bin/rm -rf build/`, `bash -c 'rm -rf build/'` |
241| `Bash(git push *)` | `git push origin main` | `git -C . push origin main`, `git -c push.default=current push origin main`, `git 'push' origin main` |
237| Rule | Stops | Doesn't stop |
238| :- | :- | :- |
239| `Bash(curl *)` | `curl https://example.com` | `/usr/bin/curl https://example.com`, `sh -c 'curl https://example.com'` |
240| `Bash(rm *)` | `rm -rf build/` | `/bin/rm -rf build/`, `bash -c 'rm -rf build/'` |
241| `Bash(git push *)` | `git push origin main` | `git -C . push origin main`, `git -c push.default=current push origin main`, `git 'push' origin main` |
242242 
243243Your other rules and the permission mode decide the commands in the last column.
244244 
from line 331
331331 
332332Read and Edit rules both use [gitignore](https://git-scm.com/docs/gitignore) pattern syntax with four distinct pattern types; for single-segment directory patterns, the matching depth also depends on the rule type, described later in this section:
333333 
334| Pattern | Meaning | Example | Matches |
335| ------------------ | ------------------------------------ | -------------------------------- | ------------------------------------------------------------- |
336| `//path` | Absolute path from filesystem root | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |
337| `~/path` | Path from home directory | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |
338| `/path` | Path relative to the settings source | `Edit(/src/**/*.ts)` | `<primary working directory>/src/**/*.ts` in project settings |
339| `path` or `./path` | Path relative to current directory | `Read(*.env)` | `<cwd>/*.env` |
334| Pattern | Meaning | Example | Matches |
335| - | - | - | - |
336| `//path` | Absolute path from filesystem root | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |
337| `~/path` | Path from home directory | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |
338| `/path` | Path relative to the settings source | `Edit(/src/**/*.ts)` | `<primary working directory>/src/**/*.ts` in project settings |
339| `path` or `./path` | Path relative to current directory | `Read(*.env)` | `<cwd>/*.env` |
340340 
341341<Warning>
342342 A pattern like `/Users/alice/file` isn't an absolute path. The single leading slash anchors at the settings source, not the filesystem root. Use `//Users/alice/file` for absolute paths.
from line 344
344344 
345345A `/path` pattern anchors at a directory associated with the settings source that defines it, so the same rule matches different locations depending on where you put it:
346346 
347| Rule defined in | `/path` resolves to |
348| :---------------------------------------------- | :--------------------------------- |
349| Project settings at `.claude/settings.json` | `<primary working directory>/path` |
347| Rule defined in | `/path` resolves to |
348| :- | :- |
349| Project settings at `.claude/settings.json` | `<primary working directory>/path` |
350350| Local settings at `.claude/settings.local.json` | `<primary working directory>/path` |
351| User settings at `~/.claude/settings.json` | `~/.claude/path` |
352| A file passed with `--settings <file>` | `<directory of file>/path` |
353| CLI flags or session rules | `<primary working directory>/path` |
351| User settings at `~/.claude/settings.json` | `~/.claude/path` |
352| A file passed with `--settings <file>` | `<directory of file>/path` |
353| CLI flags or session rules | `<primary working directory>/path` |
354354 
355355A rule you add through `/permissions` follows the row for the settings file you save it to.
356356 
from line 369
369369 
370370A rule only matches files under its anchor; within that bound, matching depth depends on the pattern shape and, for single-segment directory patterns, the rule type, described below. Bare filenames follow gitignore semantics and match at any depth, so `Read(.env)` and `Read(**/.env)` are equivalent:
371371 
372| Deny rule | Blocks | Does not block |
373| ------------------------------- | -------------------------------------------- | ---------------------------------------------------- |
374| `Read(.env)` or `Read(**/.env)` | any `.env` at or under the current directory | `.env` in a parent directory or another project |
375| `Read(//**/.env)` | any `.env` anywhere on the filesystem | nothing; the rule is anchored at the filesystem root |
372| Deny rule | Blocks | Does not block |
373| - | - | - |
374| `Read(.env)` or `Read(**/.env)` | any `.env` at or under the current directory | `.env` in a parent directory or another project |
375| `Read(//**/.env)` | any `.env` anywhere on the filesystem | nothing; the rule is anchored at the filesystem root |
376376 
377377A relative pattern with a single directory segment, such as `src/**`, matches at different depths depending on the rule type:
378378 
from line 393
393393 └── lib.js
394394```
395395 
396| Rule | Matches `src/app.ts` | Matches `vendor/pkg/src/lib.js` |
397| :----------------------------------- | :------------------- | :------------------------------ |
398| `Edit(src/**)` as an allow rule | Yes | No |
399| `Edit(src/**)` as a deny or ask rule | Yes | Yes |
400| `Edit(/src/**)` in any rule type | Yes | No |
401| `Edit(**/src/**)` in any rule type | Yes | Yes |
396| Rule | Matches `src/app.ts` | Matches `vendor/pkg/src/lib.js` |
397| :- | :- | :- |
398| `Edit(src/**)` as an allow rule | Yes | No |
399| `Edit(src/**)` as a deny or ask rule | Yes | Yes |
400| `Edit(/src/**)` in any rule type | Yes | No |
401| `Edit(**/src/**)` in any rule type | Yes | Yes |
402402 
403403<Note>
404404 In gitignore patterns, `*` matches within a single path segment and can appear at any position in the pattern, while `**` matches across directories.
from line 467
467467 
468468Each row shows what a rule does in the `allow` list and in the `deny` list:
469469 
470| Rule | In `allow` | In `deny` |
471| :------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
472| `WebFetch` | Claude fetches without prompting you. Doesn't change which hosts sandboxed commands can reach. | Claude Code removes the `WebFetch` tool, so Claude can't fetch at all. Doesn't change which hosts sandboxed commands can reach. |
473| `WebFetch(domain:*)` | Claude fetches without prompting you, and sandboxed commands can reach any host. | Claude Code keeps the tool and refuses each fetch, and sandboxed commands can't reach any host. |
470| Rule | In `allow` | In `deny` |
471| :- | :- | :- |
472| `WebFetch` | Claude fetches without prompting you. Doesn't change which hosts sandboxed commands can reach. | Claude Code removes the `WebFetch` tool, so Claude can't fetch at all. Doesn't change which hosts sandboxed commands can reach. |
473| `WebFetch(domain:*)` | Claude fetches without prompting you, and sandboxed commands can reach any host. | Claude Code keeps the tool and refuses each fetch, and sandboxed commands can't reach any host. |
474474 
475475The two forms also differ on reads of [artifacts](/docs/en/artifacts), the pages the Artifact tool publishes on claude.ai. A bare `WebFetch` deny or ask rule doesn't apply to those reads. A `domain:` rule covering `claude.ai` or the `*.claudeusercontent.com` content host, such as `WebFetch(domain:claude.ai)` or `WebFetch(domain:*)`, denies each read or prompts before it. An [`Artifact` rule](/docs/en/artifacts#disable-artifacts) does the same.
476476 
from line 530
530530 
531531Path patterns share the `//`, `~/`, and `/` anchors from [Read and Edit rules](#read-and-edit), but matching is anchored to the whole directory path rather than gitignore-style. `*` matches exactly one path segment and `**` matches across segments. A trailing `/**` also matches its named root.
532532 
533| Rule | Matches | Does not match |
534| --------------------- | --------------------------------------------------------------------- | ---------------------------- |
535| `Cd(~/code/*)` | `~/code/app` | `~/code/app/src`, `~/code` |
536| `Cd(~/code/**)` | `~/code` and any directory under it | directories outside `~/code` |
537| `Cd(**/node_modules)` | any `node_modules` directory at any depth under the current directory | `node_modules/pkg` |
533| Rule | Matches | Does not match |
534| - | - | - |
535| `Cd(~/code/*)` | `~/code/app` | `~/code/app/src`, `~/code` |
536| `Cd(~/code/**)` | `~/code` and any directory under it | directories outside `~/code` |
537| `Cd(**/node_modules)` | any `node_modules` directory at any depth under the current directory | `node_modules/pkg` |
538538 
539539## Extend permissions with hooks
540540 
from line 589
589589 
590590The following configuration types are loaded from `--add-dir` directories:
591591 
592| Configuration | Loaded from `--add-dir` |
593| :------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
594| [Skills](/docs/en/skills) in `.claude/skills/` | Yes, with live reload |
595| [Command files](/docs/en/skills#where-skills-live) in `.claude/commands/` | Yes, without live reload. When the added directory and your project both define a command with the same name, Claude Code runs your project's command |
596| [Subagents](/docs/en/sub-agents) in `.claude/agents/` | Yes, without live reload |
597| [Settings](/docs/en/settings) in `.claude/settings.json` and `.claude/settings.local.json` | `enabledPlugins` and [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) keys only |
598| [CLAUDE.md](/docs/en/memory) files, `.claude/rules/`, and `CLAUDE.local.md` | Only when `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` is set. `CLAUDE.local.md` additionally requires the `local` setting source, which is enabled by default |
592| Configuration | Loaded from `--add-dir` |
593| :- | :- |
594| [Skills](/docs/en/skills) in `.claude/skills/` | Yes, with live reload |
595| [Command files](/docs/en/skills#where-skills-live) in `.claude/commands/` | Yes, without live reload. When the added directory and your project both define a command with the same name, Claude Code runs your project's command |
596| [Subagents](/docs/en/sub-agents) in `.claude/agents/` | Yes, without live reload |
597| [Settings](/docs/en/settings) in `.claude/settings.json` and `.claude/settings.local.json` | `enabledPlugins` and [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) keys only |
598| [CLAUDE.md](/docs/en/memory) files, `.claude/rules/`, and `CLAUDE.local.md` | Only when `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` is set. `CLAUDE.local.md` additionally requires the `local` setting source, which is enabled by default |
599599 
600600To load the skills, commands, and subagents from a subdirectory of your [primary working directory](#working-directories) mid-session, run `/add-dir` with that subdirectory's path. Claude Code loads them for the rest of the session without prompting you or adding a working directory, because the subdirectory is already readable. This requires Claude Code v2.1.257 or later.
601601 
from line 681
681681 
682682Each row is one kind of content a repository can supply. The columns are the two situations in which you haven't trusted the folder itself: you trusted only a parent folder, or you ran `claude -p` or the SDK there, which never shows the trust dialog. The parent-folder column doesn't apply inside a [nested repository](#project-allow-rules-and-workspace-trust): in an interactive session Claude Code shows the trust dialog for it, and a `claude -p` or SDK run there follows the `claude -p` column.
683683 
684| What the repository supplies | You trusted only a parent folder | `claude -p` or the SDK, folder never trusted |
685| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
686| [Hooks](/docs/en/hooks) in settings files, the [`env`](/docs/en/settings-reference#env) block and helper commands such as [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper), and a project skill's [hooks](/docs/en/hooks#hooks-in-skills-and-agents) and [`allowed-tools`](/docs/en/skills#pre-approve-tools-for-a-skill) | Used | Used. Workspace trust never gates a skill's `allowed-tools` in any session |
687| `permissions.allow` rules and `additionalDirectories` in `.claude/settings.json` | Not used until you accept the trust dialog, which appears again listing them | Not used. Claude Code prints a [`this workspace has not been trusted`](/docs/en/errors#workspace-has-not-been-trusted) warning to stderr |
688| Frontmatter hooks in a project [subagent](/docs/en/sub-agents#hooks-in-subagent-frontmatter), a project [`@skills-dir` plugin](/docs/en/plugins/loading#plugins-shared-through-a-repository), and [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) entries from the repository or an `--add-dir` directory | Not used, and no dialog is offered | Not used |
689| Inline [`mcpServers`](/docs/en/sub-agents#scope-mcp-servers-to-a-subagent) in the frontmatter of a subagent from the repository or an `--add-dir` directory. Before v2.1.238, Claude Code loaded these servers in both situations | Not used, and no dialog is offered | Not used |
690| Servers in `.mcp.json`, including ones the repository [approves in its own settings](/docs/en/mcp#project-server-approvals-and-workspace-trust) | Claude Code asks you before connecting them. The repository's own approvals don't count | Connected without asking, approved or not. The SDK loads them only when `settingSources` includes project settings. `claude mcp list` in the same folder still reports such a server as pending |
691| A [`headersHelper`](/docs/en/mcp#trust-a-folder-before-its-headershelper-runs) on a server in `.mcp.json`. Before v2.1.238, Claude Code ran the helper in both situations | Not run until you accept the trust dialog, which appears again naming where the helper is declared. Claude Code connects the server with its static `headers` alone until then | Not run. Claude Code connects the server with its static `headers` alone and prints a [`headersHelper not run`](/docs/en/errors#headershelper-not-run) line per server to stderr |
684| What the repository supplies | You trusted only a parent folder | `claude -p` or the SDK, folder never trusted |
685| :- | :- | :- |
686| [Hooks](/docs/en/hooks) in settings files, the [`env`](/docs/en/settings-reference#env) block and helper commands such as [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper), and a project skill's [hooks](/docs/en/hooks#hooks-in-skills-and-agents) and [`allowed-tools`](/docs/en/skills#pre-approve-tools-for-a-skill) | Used | Used. Workspace trust never gates a skill's `allowed-tools` in any session |
687| `permissions.allow` rules and `additionalDirectories` in `.claude/settings.json` | Not used until you accept the trust dialog, which appears again listing them | Not used. Claude Code prints a [`this workspace has not been trusted`](/docs/en/errors#workspace-has-not-been-trusted) warning to stderr |
688| Frontmatter hooks in a project [subagent](/docs/en/sub-agents#hooks-in-subagent-frontmatter), a project [`@skills-dir` plugin](/docs/en/plugins/loading#plugins-shared-through-a-repository), and [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) entries from the repository or an `--add-dir` directory | Not used, and no dialog is offered | Not used |
689| Inline [`mcpServers`](/docs/en/sub-agents#scope-mcp-servers-to-a-subagent) in the frontmatter of a subagent from the repository or an `--add-dir` directory. Before v2.1.238, Claude Code loaded these servers in both situations | Not used, and no dialog is offered | Not used |
690| Servers in `.mcp.json`, including ones the repository [approves in its own settings](/docs/en/mcp#project-server-approvals-and-workspace-trust) | Claude Code asks you before connecting them. The repository's own approvals don't count | Connected without asking, approved or not. The SDK loads them only when `settingSources` includes project settings. `claude mcp list` in the same folder still reports such a server as pending |
691| A [`headersHelper`](/docs/en/mcp#trust-a-folder-before-its-headershelper-runs) on a server in `.mcp.json`. Before v2.1.238, Claude Code ran the helper in both situations | Not run until you accept the trust dialog, which appears again naming where the helper is declared. Claude Code connects the server with its static `headers` alone until then | Not run. Claude Code connects the server with its static `headers` alone and prints a [`headersHelper not run`](/docs/en/errors#headershelper-not-run) line per server to stderr |
692692 
693693For the rows that need this exact folder trusted, trust it by hand: set `projects["<path>"].hasTrustDialogAccepted` to `true` in `~/.claude.json`, where `<path>` is the repository root, or the folder itself outside a repository. Claude Code prints the exact key in the debug log line for a skipped subagent hook or inline MCP server, in the stderr warning for skipped allow rules, and in the `headersHelper not run` line for a skipped helper.
694694 

platforms Changed · +23 / -23 lines

from line 8
88 
99Choose a platform based on how you like to work and where your project lives.
1010 
11| Platform | Best for | What you get |
12| :-------------------------------- | :------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13| [CLI](/docs/en/quickstart) | Terminal workflows, scripting, remote servers | Full feature set, [Agent SDK](/docs/en/headless), [computer use](/docs/en/computer-use) on macOS (Pro and Max), third-party providers |
14| [Desktop](/docs/en/desktop) | Visual review, parallel sessions, managed setup | Diff viewer, app preview, [computer use](/docs/en/desktop#let-claude-use-your-computer) and [Dispatch](/docs/en/desktop#sessions-from-dispatch) on Pro and Max |
15| [VS Code](/docs/en/vs-code) | Working inside VS Code without switching to a terminal | Inline diffs, integrated terminal, file context |
16| [JetBrains](/docs/en/jetbrains) | Working inside IntelliJ, PyCharm, WebStorm, or other JetBrains IDEs | Diff viewer, selection sharing, terminal session |
17| [Web](/docs/en/claude-code-on-the-web) | Long-running tasks that don't need much steering, or work that should continue when you're offline | Cloud, Anthropic-managed by default; continues after you disconnect |
18| [Mobile](/docs/en/mobile) | Starting and monitoring tasks while away from your computer | Cloud sessions from the Claude app for iOS and Android, [Remote Control](/docs/en/remote-control) for local sessions, [Dispatch](/docs/en/desktop#sessions-from-dispatch) to Desktop on Pro and Max |
11| Platform | Best for | What you get |
12| :- | :- | :- |
13| [CLI](/docs/en/quickstart) | Terminal workflows, scripting, remote servers | Full feature set, [Agent SDK](/docs/en/headless), [computer use](/docs/en/computer-use) on macOS (Pro and Max), third-party providers |
14| [Desktop](/docs/en/desktop) | Visual review, parallel sessions, managed setup | Diff viewer, app preview, [computer use](/docs/en/desktop#let-claude-use-your-computer) and [Dispatch](/docs/en/desktop#sessions-from-dispatch) on Pro and Max |
15| [VS Code](/docs/en/vs-code) | Working inside VS Code without switching to a terminal | Inline diffs, integrated terminal, file context |
16| [JetBrains](/docs/en/jetbrains) | Working inside IntelliJ, PyCharm, WebStorm, or other JetBrains IDEs | Diff viewer, selection sharing, terminal session |
17| [Web](/docs/en/claude-code-on-the-web) | Long-running tasks that don't need much steering, or work that should continue when you're offline | Cloud, Anthropic-managed by default; continues after you disconnect |
18| [Mobile](/docs/en/mobile) | Starting and monitoring tasks while away from your computer | Cloud sessions from the Claude app for iOS and Android, [Remote Control](/docs/en/remote-control) for local sessions, [Dispatch](/docs/en/desktop#sessions-from-dispatch) to Desktop on Pro and Max |
1919 
2020The CLI is the most complete surface for terminal-native work: scripting and the Agent SDK are CLI-only. Third-party providers also work in [VS Code](/docs/en/vs-code#use-third-party-providers) and in [JetBrains](/docs/en/feature-availability#features-available-on-every-provider), which runs the CLI in your IDE's terminal. Enterprise [Desktop](/docs/en/desktop) deployments support Google Cloud's Agent Platform, and Desktop supports [gateway providers](/docs/en/llm-gateway-connect#desktop-app); for Amazon Bedrock or Microsoft Foundry, use the CLI or an IDE extension, or [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview), which runs the Code tab on those providers. Desktop and the IDE extensions trade some CLI-only features for visual review and tighter editor integration. The web runs in the cloud, so tasks keep going after you disconnect. Mobile is a thin client into those same cloud sessions or into a local session via Remote Control, and can send tasks to Desktop with Dispatch.
2121 
from line 25
2525 
2626Integrations let Claude work with services outside your codebase.
2727 
28| Integration | What it does | Use it for |
29| :----------------------------------------------- | :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- |
30| [Chrome](/docs/en/chrome) | Controls your browser with your logged-in sessions | Testing web apps, filling forms, automating sites without an API |
31| [GitHub Actions](/docs/en/github-actions) | Runs Claude in your CI pipeline | Automated PR reviews, issue triage, scheduled maintenance |
32| [GitLab CI/CD](/docs/en/gitlab-ci-cd) | Same as GitHub Actions for GitLab | CI-driven automation on GitLab |
33| [Code Review](/docs/en/code-review) | Reviews every PR automatically | Catching bugs before human review |
34| [Slack](/docs/en/slack) | Responds to `@Claude` mentions in your channels | Turning bug reports into pull requests from team chat |
28| Integration | What it does | Use it for |
29| :- | :- | :- |
30| [Chrome](/docs/en/chrome) | Controls your browser with your logged-in sessions | Testing web apps, filling forms, automating sites without an API |
31| [GitHub Actions](/docs/en/github-actions) | Runs Claude in your CI pipeline | Automated PR reviews, issue triage, scheduled maintenance |
32| [GitLab CI/CD](/docs/en/gitlab-ci-cd) | Same as GitHub Actions for GitLab | CI-driven automation on GitLab |
33| [Code Review](/docs/en/code-review) | Reviews every PR automatically | Catching bugs before human review |
34| [Slack](/docs/en/slack) | Responds to `@Claude` mentions in your channels | Turning bug reports into pull requests from team chat |
3535| [Claude Tag](https://claude.com/docs/claude-tag) | Runs `@Claude` as your organization's shared identity with admin-configured access | Shared team access on Team and Enterprise plans, instead of per-user Slack sessions |
3636 
3737For integrations not listed here, [MCP servers](/docs/en/mcp) and [connectors](/docs/en/desktop#connect-external-tools) let you connect almost anything: Linear, Notion, Google Drive, or your own internal APIs.
from line 40
4040 
4141Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.
4242 
43| | Trigger | Claude runs on | Setup | Best for |
44| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
45| [Dispatch](/docs/en/desktop#sessions-from-dispatch) | Message a task from the Claude mobile app | Your machine (Desktop) | [Pair the mobile app with Desktop](https://support.claude.com/en/articles/13947068) | Delegating work while you're away, minimal setup |
46| [Remote Control](/docs/en/remote-control) | Drive a running session from [claude.ai/code](https://claude.ai/code) or the Claude mobile app | Your machine (CLI, Desktop, or VS Code) | Run [`claude remote-control` or `/remote-control`](/docs/en/remote-control#start-a-remote-control-session) | Steering in-progress work from another device |
47| [Channels](/docs/en/channels) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](/docs/en/channels#quickstart) or [build your own](/docs/en/channels-reference) | Reacting to external events like CI failures or chat messages |
48| [Slack](/docs/en/slack) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](/docs/en/slack#setting-up-claude-code-in-slack) with [Claude Code on the web](/docs/en/claude-code-on-the-web) enabled | PRs and reviews from team chat |
49| [Self-hosted environments](/docs/en/self-hosted-environments) | Start a [cloud session](/docs/en/claude-code-on-the-web) and pick your organization's environment | Your organization's infrastructure | [Deploy runners](/docs/en/self-hosted-environments-quickstart), on Team and Enterprise plans | Cloud sessions that must run inside your network |
50| [Scheduled tasks](/docs/en/scheduled-tasks) | Set a schedule | [CLI](/docs/en/scheduled-tasks), [Desktop](/docs/en/desktop-scheduled-tasks), or [cloud](/docs/en/routines) | Pick a frequency | Recurring automation like daily reviews |
43| | Trigger | Claude runs on | Setup | Best for |
44| :- | :- | :- | :- | :- |
45| [Dispatch](/docs/en/desktop#sessions-from-dispatch) | Message a task from the Claude mobile app | Your machine (Desktop) | [Pair the mobile app with Desktop](https://support.claude.com/en/articles/13947068) | Delegating work while you're away, minimal setup |
46| [Remote Control](/docs/en/remote-control) | Drive a running session from [claude.ai/code](https://claude.ai/code) or the Claude mobile app | Your machine (CLI, Desktop, or VS Code) | Run [`claude remote-control` or `/remote-control`](/docs/en/remote-control#start-a-remote-control-session) | Steering in-progress work from another device |
47| [Channels](/docs/en/channels) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](/docs/en/channels#quickstart) or [build your own](/docs/en/channels-reference) | Reacting to external events like CI failures or chat messages |
48| [Slack](/docs/en/slack) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](/docs/en/slack#setting-up-claude-code-in-slack) with [Claude Code on the web](/docs/en/claude-code-on-the-web) enabled | PRs and reviews from team chat |
49| [Self-hosted environments](/docs/en/self-hosted-environments) | Start a [cloud session](/docs/en/claude-code-on-the-web) and pick your organization's environment | Your organization's infrastructure | [Deploy runners](/docs/en/self-hosted-environments-quickstart), on Team and Enterprise plans | Cloud sessions that must run inside your network |
50| [Scheduled tasks](/docs/en/scheduled-tasks) | Set a schedule | [CLI](/docs/en/scheduled-tasks), [Desktop](/docs/en/desktop-scheduled-tasks), or [cloud](/docs/en/routines) | Pick a frequency | Recurring automation like daily reviews |
5151 
5252If you're not sure where to start, [install the CLI](/docs/en/quickstart) and run it in a project directory. If you'd rather not use a terminal, [Desktop](/docs/en/desktop-quickstart) gives you the same engine with a graphical interface.
5353 

plugin-evals Changed · +91 / -91 lines

from line 332
332332 
333333Most of the time you run `claude plugin eval .` from the plugin root, which runs every case in the suite with the plugin you're standing in loaded. To run a single case file, or to evaluate a plugin you installed rather than one you're developing, pass a different target:
334334 
335| Target | What runs |
336| :-------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
337| A plugin's root directory, such as `.` | Every case under its eval directory, with that plugin loaded |
338| A single `prompt.md` or `case.yaml` file | That case, with its enclosing plugin loaded |
335| Target | What runs |
336| :- | :- |
337| A plugin's root directory, such as `.` | Every case under its eval directory, with that plugin loaded |
338| A single `prompt.md` or `case.yaml` file | That case, with its enclosing plugin loaded |
339339| An installed plugin by name, `name` or `name@marketplace` | The cases in the installed copy's eval directory, with the installed copy loaded. Results are written under `./evals/results/` in your current directory, or `./<dir>/results/` with `--eval-dir` |
340| `name@skills-dir` | The same, for a [skills-directory plugin](/docs/en/plugins/loading#plugins-shared-through-a-repository) |
341| Omitted | The current directory as a path |
340| `name@skills-dir` | The same, for a [skills-directory plugin](/docs/en/plugins/loading#plugins-shared-through-a-repository) |
341| Omitted | The current directory as a path |
342342 
343343Add `--case <glob>` to filter by case name and `--tag <tag>` to keep cases with any of the given tags.
344344 
from line 362
362362 
363363This table covers the options for run count, models, scoring, cost, tool grants, mocks, and output. Run `claude plugin eval --help` for the complete list, which also includes `--case`, `--tag`, `--eval-dir`, `--no-scaffold`, `--report`, and `--verbose`.
364364 
365| Option | Default | Effect |
366| :------------------------- | :----------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
367| `--runs <n>` | Each case's `runs`, else 3 | Runs per case per arm |
368| `-j`, `--concurrency <n>` | `1` | Run up to this many agent runs at once, from 1 to 8. They share your account's rate limit, so this shortens wall-clock time rather than raising throughput past that limit. Results keep case order |
369| `--model <model>` | Each case's `model`, else `ANTHROPIC_MODEL` if set, else Claude Code's default | Model for the agent under test. Pin it in CI so a model rollout isn't mistaken for a plugin regression |
370| `--judge-model <model>` | A small fast model | Model for `llm` and `baseline` graders |
371| `--ablation <mode>` | `with-without` when a plugin resolves, else `none` | Whether to also run each case without the plugin to measure what it adds. `none` runs one arm; `with-without` adds the no-plugin baseline |
372| `--threshold <0..1>` | `1.0` | A case passes when its with-arm score is at least this. Any case below it makes the command exit 1 |
373| `--max-cost-usd <usd>` | No ceiling | A ceiling on the run's list-price cost estimate, not on plan usage. Checked before each run starts. Once spent, nothing further starts; runs that already started finish, so spend can pass the ceiling by those runs. If any run is left unstarted, the command exits 2 with partial results |
374| `--allow-tools <tools...>` | None | Grant tools beyond the read-only set. See [Grant tools](#grant-tools) |
375| `--scaffold` | Off | Run each case's [`scaffold_script`](#add-setup-or-history-with-case-yaml) |
376| `--trust-plugin` | Off | Skip the first-run trust prompt for a plugin whose code and suite you'd run yourself. Pass it in CI so the job is never refused by or left waiting at the prompt. See [What a run can access](#security) |
377| `--mocks <mode>` | `record` | `record` answers MCP tool calls from [mocks](#mock-mcp-servers), doesn't start the plugin's real servers, and saves agent-mock answers for replay. `off` ignores mocks and starts the plugin's real MCP servers |
378| `--allow-real-servers` | Off | With `--mocks record`, also start the plugin's real MCP servers for servers that have no mock |
379| `--json [path]` | Off | Print the [result document](#json-result) to stdout, or write it to a path ending in `.json`. The run is quiet: no progress lines or summary table |
380| `--output-dir <dir>` | `<eval dir>/results/<timestamp>/` | Where `aggregate-result.json` and `report.html` go |
381| `--no-publish` | | Keep the HTML report local. See [HTML report](#html-report) |
382| `--publish-report` | | Publish the report even where it would stay local by default, such as a run a Claude Code session started |
383| `--keep-temp` | Off | Keep every run's sandbox directory and print its path, for debugging what Claude produced |
365| Option | Default | Effect |
366| :- | :- | :- |
367| `--runs <n>` | Each case's `runs`, else 3 | Runs per case per arm |
368| `-j`, `--concurrency <n>` | `1` | Run up to this many agent runs at once, from 1 to 8. They share your account's rate limit, so this shortens wall-clock time rather than raising throughput past that limit. Results keep case order |
369| `--model <model>` | Each case's `model`, else `ANTHROPIC_MODEL` if set, else Claude Code's default | Model for the agent under test. Pin it in CI so a model rollout isn't mistaken for a plugin regression |
370| `--judge-model <model>` | A small fast model | Model for `llm` and `baseline` graders |
371| `--ablation <mode>` | `with-without` when a plugin resolves, else `none` | Whether to also run each case without the plugin to measure what it adds. `none` runs one arm; `with-without` adds the no-plugin baseline |
372| `--threshold <0..1>` | `1.0` | A case passes when its with-arm score is at least this. Any case below it makes the command exit 1 |
373| `--max-cost-usd <usd>` | No ceiling | A ceiling on the run's list-price cost estimate, not on plan usage. Checked before each run starts. Once spent, nothing further starts; runs that already started finish, so spend can pass the ceiling by those runs. If any run is left unstarted, the command exits 2 with partial results |
374| `--allow-tools <tools...>` | None | Grant tools beyond the read-only set. See [Grant tools](#grant-tools) |
375| `--scaffold` | Off | Run each case's [`scaffold_script`](#add-setup-or-history-with-case-yaml) |
376| `--trust-plugin` | Off | Skip the first-run trust prompt for a plugin whose code and suite you'd run yourself. Pass it in CI so the job is never refused by or left waiting at the prompt. See [What a run can access](#security) |
377| `--mocks <mode>` | `record` | `record` answers MCP tool calls from [mocks](#mock-mcp-servers), doesn't start the plugin's real servers, and saves agent-mock answers for replay. `off` ignores mocks and starts the plugin's real MCP servers |
378| `--allow-real-servers` | Off | With `--mocks record`, also start the plugin's real MCP servers for servers that have no mock |
379| `--json [path]` | Off | Print the [result document](#json-result) to stdout, or write it to a path ending in `.json`. The run is quiet: no progress lines or summary table |
380| `--output-dir <dir>` | `<eval dir>/results/<timestamp>/` | Where `aggregate-result.json` and `report.html` go |
381| `--no-publish` | | Keep the HTML report local. See [HTML report](#html-report) |
382| `--publish-report` | | Publish the report even where it would stay local by default, such as a run a Claude Code session started |
383| `--keep-temp` | Off | Keep every run's sandbox directory and print its path, for debugging what Claude produced |
384384 
385385<h3 id="run-evals-in-ci">
386386 Run evals in CI
from line 401
401401 
402402The job's exit code tells you what happened:
403403 
404| Exit code | Meaning |
405| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
406| 0 | Every case scored at or above `--threshold` and every case file loaded |
407| 1 | A case scored below the threshold, a case file failed to load, no cases were found, a run couldn't be started, the plugin directory isn't trusted and `--trust-plugin` wasn't passed, or an option was invalid |
408| 2 | Partial run: the `--max-cost-usd` ceiling was hit, or your credential was rejected before or at the first run. `results.json` is still written with `partial: true` and the reason |
409| 130 | Interrupted. Partial results are written |
410| 143 | Terminated, such as by a CI timeout |
404| Exit code | Meaning |
405| :- | :- |
406| 0 | Every case scored at or above `--threshold` and every case file loaded |
407| 1 | A case scored below the threshold, a case file failed to load, no cases were found, a run couldn't be started, the plugin directory isn't trusted and `--trust-plugin` wasn't passed, or an option was invalid |
408| 2 | Partial run: the `--max-cost-usd` ceiling was hit, or your credential was rejected before or at the first run. `results.json` is still written with `partial: true` and the reason |
409| 130 | Interrupted. Partial results are written |
410| 143 | Terminated, such as by a CI timeout |
411411 
412412The with-minus-without delta is reported but never changes the exit code, and neither do problems writing or publishing the HTML report.
413413 
from line 448
448448 
449449These are the fields a gating script usually reads. The document also carries the suite configuration, every grader definition, and per-run grader results with explanations and evidence:
450450 
451| Field | Meaning |
452| :------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
453| `partial`, `partialReason` | `true` with `cost_ceiling`, `interrupted`, or `auth_failed` when the suite didn't finish. Leave partial results out of trend charts |
454| `aggregates.overallScore` | Mean case score across the suite |
455| `aggregates.casesPassed`, `aggregates.casesTotal` | Cases at or above `--threshold`, and the total |
456| `aggregates.meanDelta` | Mean `Δ` across cases, under the two-arm mode |
457| `cases[].name` | Case name |
458| `cases[].aggregates.score` | Mean with-arm run score for the case |
459| `cases[].aggregates.delta` | With-arm score minus without-arm score. Omitted when the arms aren't comparable |
460| `cases[].arms.with[].error` | `null`, or why a run ended abnormally, such as `timed out after 300s`. A run that started but ended badly is still graded on what it produced, so a non-null error doesn't imply score 0 |
461| `cases[].arms.with[].aborted` | Present when a [mock](#mock-mcp-servers)'s `expect:` or `abort_when` stopped the run, with `server`, `tool`, and `reason`. The run scores 0 and `error` stays `null` |
462| `cases[].arms.with[].skippedPaidGraders` | `true` when the cost ceiling skipped this run's judge graders, so its score isn't comparable |
463| `costUsd`, `durationSeconds`, `claudeVersion` | Estimated cost at list price including judge calls, wall-clock seconds, and the Claude Code version that ran the suite |
451| Field | Meaning |
452| :- | :- |
453| `partial`, `partialReason` | `true` with `cost_ceiling`, `interrupted`, or `auth_failed` when the suite didn't finish. Leave partial results out of trend charts |
454| `aggregates.overallScore` | Mean case score across the suite |
455| `aggregates.casesPassed`, `aggregates.casesTotal` | Cases at or above `--threshold`, and the total |
456| `aggregates.meanDelta` | Mean `Δ` across cases, under the two-arm mode |
457| `cases[].name` | Case name |
458| `cases[].aggregates.score` | Mean with-arm run score for the case |
459| `cases[].aggregates.delta` | With-arm score minus without-arm score. Omitted when the arms aren't comparable |
460| `cases[].arms.with[].error` | `null`, or why a run ended abnormally, such as `timed out after 300s`. A run that started but ended badly is still graded on what it produced, so a non-null error doesn't imply score 0 |
461| `cases[].arms.with[].aborted` | Present when a [mock](#mock-mcp-servers)'s `expect:` or `abort_when` stopped the run, with `server`, `tool`, and `reason`. The run scores 0 and `error` stays `null` |
462| `cases[].arms.with[].skippedPaidGraders` | `true` when the cost ceiling skipped this run's judge graders, so its score isn't comparable |
463| `costUsd`, `durationSeconds`, `claudeVersion` | Estimated cost at list price including judge calls, wall-clock seconds, and the Claude Code version that ran the suite |
464464 
465465<h2 id="security">
466466 What a run can access
from line 528
528528 
529529`prompt.md` frontmatter accepts these fields. An unknown key is an error:
530530 
531| Field | Default | Purpose |
532| :--------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
533| `schema_version` | `"1.1"`, set for you | Case format version. Cases written as `prompt.md` get it automatically, so you rarely set it |
534| `name` | The directory name | Case name. `--case` globs match it and the report keys on it |
535| `description` | | For humans. Not used at run time |
536| `tags` | `[]` | Labels for `--tag` filtering. A case runs if any of its tags matches |
537| `plugins` | The nearest enclosing plugin | Plugin directories under test, relative to the case directory. Set `plugins: ["../.."]` when auto-detection doesn't find your plugin; see [the plugin didn't load](#the-baseline-arm-shows-no-plugin-or-delta-is-zero) |
538| `runs` | `3` | Runs per arm, 1 to 50. `--runs` overrides it |
539| `expected_outcome` | | For humans. Not used at run time |
540| `model` | The child session's default | Model for the agent under test. `--model` overrides it |
541| `max_turns` | `10` | Turn cap, up to 200. Hitting it is recorded as a run error and usually lowers the score, so set it generously |
542| `timeout_seconds` | `300` | Wall-clock cap per run, up to 3600 |
543| `allowed_tools` | `[]` | Tools the case wants, such as `[Read, Glob, Grep, Skill]`. Read-only tools are granted when listed here; for anything else, see [Grant tools](#grant-tools) |
544| `append_system_prompt` | | Text appended to the child session's system prompt |
545| `env` | `{}` | Extra environment variables for the child session. Keys must match `EVAL_[A-Z0-9_]*`; any other key fails the run. The run inherits only an allowlist from your shell: basics such as `PATH` and locale, proxy and certificate settings, the variables that select and authenticate your model provider, most `ANTHROPIC_*` and `CLAUDE_CODE_*` configuration, and `EVAL_*`. To pass the plugin anything else, such as a toolchain setting, export it as an `EVAL_*` variable |
531| Field | Default | Purpose |
532| :- | :- | :- |
533| `schema_version` | `"1.1"`, set for you | Case format version. Cases written as `prompt.md` get it automatically, so you rarely set it |
534| `name` | The directory name | Case name. `--case` globs match it and the report keys on it |
535| `description` | | For humans. Not used at run time |
536| `tags` | `[]` | Labels for `--tag` filtering. A case runs if any of its tags matches |
537| `plugins` | The nearest enclosing plugin | Plugin directories under test, relative to the case directory. Set `plugins: ["../.."]` when auto-detection doesn't find your plugin; see [the plugin didn't load](#the-baseline-arm-shows-no-plugin-or-delta-is-zero) |
538| `runs` | `3` | Runs per arm, 1 to 50. `--runs` overrides it |
539| `expected_outcome` | | For humans. Not used at run time |
540| `model` | The child session's default | Model for the agent under test. `--model` overrides it |
541| `max_turns` | `10` | Turn cap, up to 200. Hitting it is recorded as a run error and usually lowers the score, so set it generously |
542| `timeout_seconds` | `300` | Wall-clock cap per run, up to 3600 |
543| `allowed_tools` | `[]` | Tools the case wants, such as `[Read, Glob, Grep, Skill]`. Read-only tools are granted when listed here; for anything else, see [Grant tools](#grant-tools) |
544| `append_system_prompt` | | Text appended to the child session's system prompt |
545| `env` | `{}` | Extra environment variables for the child session. Keys must match `EVAL_[A-Z0-9_]*`; any other key fails the run. The run inherits only an allowlist from your shell: basics such as `PATH` and locale, proxy and certificate settings, the variables that select and authenticate your model provider, most `ANTHROPIC_*` and `CLAUDE_CODE_*` configuration, and `EVAL_*`. To pass the plugin anything else, such as a toolchain setting, export it as an `EVAL_*` variable |
546546 
547547<h3 id="case-yaml-fields">
548548 case.yaml fields
from line 552
552552 
553553These fields exist only in `case.yaml`:
554554 
555| Field | Purpose |
556| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
555| Field | Purpose |
556| :- | :- |
557557| `context.scaffold_script` | A Bash script in the case directory that runs in the empty workspace before Claude starts, to create fixture files or a git repository. It runs only when you pass [`--scaffold`](#add-setup-or-history-with-case-yaml) |
558| `context.history_file` | A `.jsonl` transcript in the case directory to resume. The case's prompt becomes the next user turn |
559| `context.add_dirs` | Directories inside the case directory that Claude may read during the run, granted read-only |
560| `execution.prompt` | The prompt, when you keep the whole case in `case.yaml` and omit `prompt.md` |
561| `graders` | A list of graders, each with a `name` plus the same keys a `graders/*.md` file takes in frontmatter. For `llm` graders, put the rubric in `criteria` |
558| `context.history_file` | A `.jsonl` transcript in the case directory to resume. The case's prompt becomes the next user turn |
559| `context.add_dirs` | Directories inside the case directory that Claude may read during the run, granted read-only |
560| `execution.prompt` | The prompt, when you keep the whole case in `case.yaml` and omit `prompt.md` |
561| `graders` | A list of graders, each with a `name` plus the same keys a `graders/*.md` file takes in frontmatter. For `llm` graders, put the rubric in `criteria` |
562562 
563563### Grader frontmatter
564564 
565565Every grader file under `graders/` takes these keys in frontmatter, plus the options for its type. The grader's name is the filename without `.md`:
566566 
567| Key | Default | Purpose |
568| :------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
569| `type` | required | One of the [grader types](#grader-types) |
570| `weight` | `1` | Relative weight in the run's score. Any positive number |
571| `arm` | unset | `with-only` excludes the grader from scoring in a [two-arm run](#compare-against-a-no-plugin-baseline); `both` forces a grader Claude Code would otherwise exclude to be scored in both arms |
567| Key | Default | Purpose |
568| :- | :- | :- |
569| `type` | required | One of the [grader types](#grader-types) |
570| `weight` | `1` | Relative weight in the run's score. Any positive number |
571| `arm` | unset | `with-only` excludes the grader from scoring in a [two-arm run](#compare-against-a-no-plugin-baseline); `both` forces a grader Claude Code would otherwise exclude to be scored in both arms |
572572 
573573#### What a grader can look at
574574 
575575`regex` graders take a `target` and `llm` graders take a `focus`. Both accept the same values:
576576 
577| Value | What the grader sees |
578| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
579| `last_message` | Claude's final response text. This is the default |
580| `trace` | The session as JSON, one message per line. A `regex` grader sees every message; an `llm` judge sees the first 12 and the last 12. Quotes and newlines inside it are JSON-escaped, so a regex matches `\"` rather than `"` |
581| `files` | The list of paths Claude created during the run, one per line. Not their contents, and not files that a scaffold created or that Claude only modified |
577| Value | What the grader sees |
578| :- | :- |
579| `last_message` | Claude's final response text. This is the default |
580| `trace` | The session as JSON, one message per line. A `regex` grader sees every message; an `llm` judge sees the first 12 and the last 12. Quotes and newlines inside it are JSON-escaped, so a regex matches `\"` rather than `"` |
581| `files` | The list of paths Claude created during the run, one per line. Not their contents, and not files that a scaffold created or that Claude only modified |
582582| `{ source: file, path: <path> }` | The contents of one file in the workspace after the run. Use this to grade what the plugin produced. A PNG, JPEG, GIF, or WebP file is shown to an `llm` judge as an image. An `llm` judge refuses other binary files such as `.pptx` or PDF; render them to an image or write them out as text and grade that |
583| `mock_calls` | Each call Claude made to a [mocked MCP tool](#mock-mcp-servers), with its input and the mock's answer |
583| `mock_calls` | Each call Claude made to a [mocked MCP tool](#mock-mcp-servers), with its input and the mock's answer |
584584 
585585#### Grader types
586586 
587587Each grader type below lists its options and when it passes:
588588 
589| Type | Options | Passes when |
590| :------------ | :------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
591| `regex` | `pattern`, `flags`, `match`, `target` | The JavaScript regex `pattern` is found in the target. Set `match: not_contains` to require absence or `match: "count:N"` to require exactly N matches. Put case-insensitivity in `flags: i`; inline `(?i)` isn't supported |
592| `tool_used` | `tool`, `input_match`, `min`, `max` | The number of calls to `tool` whose JSON-encoded input matches the optional `input_match` regex is between `min`, default 1, and `max`, default unlimited. To assert a tool was never called, set both `min: 0` and `max: 0` |
593| `tool_order` | `before`, `after` | Both tools were called and the first matching `before` call precedes the first matching `after` call. Each is a tool name or `{ tool, input_match }` |
594| `file_exists` | `path`, `exists` | A file Claude created matches the `path` glob, or none does with `exists: false`. Only files created during the run count |
595| `llm` | `criteria`, `focus` | A judge model votes PASS on the rubric in at least two of three votes. In the `.md` layout the file body is the criteria |
596| `baseline` | `baseline_file`, `criteria` | A judge finds the run satisfies the criteria at least as well as the reference transcript at `baseline_file`, a `.jsonl` in the case directory |
589| Type | Options | Passes when |
590| :- | :- | :- |
591| `regex` | `pattern`, `flags`, `match`, `target` | The JavaScript regex `pattern` is found in the target. Set `match: not_contains` to require absence or `match: "count:N"` to require exactly N matches. Put case-insensitivity in `flags: i`; inline `(?i)` isn't supported |
592| `tool_used` | `tool`, `input_match`, `min`, `max` | The number of calls to `tool` whose JSON-encoded input matches the optional `input_match` regex is between `min`, default 1, and `max`, default unlimited. To assert a tool was never called, set both `min: 0` and `max: 0` |
593| `tool_order` | `before`, `after` | Both tools were called and the first matching `before` call precedes the first matching `after` call. Each is a tool name or `{ tool, input_match }` |
594| `file_exists` | `path`, `exists` | A file Claude created matches the `path` glob, or none does with `exists: false`. Only files created during the run count |
595| `llm` | `criteria`, `focus` | A judge model votes PASS on the rubric in at least two of three votes. In the `.md` layout the file body is the criteria |
596| `baseline` | `baseline_file`, `criteria` | A judge finds the run satisfies the criteria at least as well as the reference transcript at `baseline_file`, a `.jsonl` in the case directory |
597597 
598598<h3 id="mock-files">
599599 Mock files
from line 601
601601 
602602A `<tool>.md` file under `mocks/<server>/` answers one tool. Its body is the tool result, with `{{input.<field>}}` and `{{file:fixtures/<name>}}` substitutions. Its frontmatter accepts these keys:
603603 
604| Key | Default | Purpose |
605| :----------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
606| `type` | `fixed` | `fixed` returns the body as written. `agent` treats the body as instructions for a small model that acts as the server for the run and sees earlier calls as history |
607| `expect` | unset | A map from dotted input paths to a type name such as `string`, `number`, `boolean`, `array`, or `object`, a `/regex/`, a literal, or a list of allowed literals. A call that violates it aborts the run with score 0 and is reported as `aborted` with the server, tool, and reason |
608| `error` | `false` | `fixed` only. Return the body as a tool error |
609| `abort_when` | unset | `agent` only. Prose listing the only conditions under which the agent may abort the run |
604| Key | Default | Purpose |
605| :- | :- | :- |
606| `type` | `fixed` | `fixed` returns the body as written. `agent` treats the body as instructions for a small model that acts as the server for the run and sees earlier calls as history |
607| `expect` | unset | A map from dotted input paths to a type name such as `string`, `number`, `boolean`, `array`, or `object`, a `/regex/`, a literal, or a list of allowed literals. A call that violates it aborts the run with score 0 and is reported as `aborted` with the server, tool, and reason |
608| `error` | `false` | `fixed` only. Return the body as a tool error |
609| `abort_when` | unset | `agent` only. Prose listing the only conditions under which the agent may abort the run |
610610 
611611Two optional files sit beside the tool files in a server's directory:
612612 

plugins/anthropic-marketplaces Changed · +6 / -6 lines

from line 24
2424 
2525This table gives each marketplace's repository and marketplace name, which is what you type after `@` when you install a plugin from that marketplace. The community marketplace's name is `claude-community`, not its repository name.
2626 
27| | Official | Community | Demo |
28| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- |
29| Repository | [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official) | [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) | [`anthropics/claude-code`](https://github.com/anthropics/claude-code/tree/main/plugins) |
30| Marketplace name | `claude-plugins-official` | `claude-community` | `claude-code-plugins` |
31| What's in it | Plugins Anthropic maintains, plus plugins from partners and other authors | Third-party plugins that their authors submitted to Anthropic | A small set of example plugins that show what a plugin can contain |
32| How you get it | Claude Code adds it the first time you start an interactive terminal session, unless a [managed policy](/docs/en/plugins/org#allow-the-official-marketplace-and-your-own) or `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` blocks it. See [Marketplace `claude-plugins-official` not found](/docs/en/plugins/troubleshooting#marketplace-claude-plugins-official-not-found) if it's missing | You add it in a Claude Code session with `/plugin marketplace add anthropics/claude-plugins-community` | You add it in a Claude Code session with `/plugin marketplace add anthropics/claude-code` |
27| | Official | Community | Demo |
28| :- | :- | :- | :- |
29| Repository | [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official) | [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) | [`anthropics/claude-code`](https://github.com/anthropics/claude-code/tree/main/plugins) |
30| Marketplace name | `claude-plugins-official` | `claude-community` | `claude-code-plugins` |
31| What's in it | Plugins Anthropic maintains, plus plugins from partners and other authors | Third-party plugins that their authors submitted to Anthropic | A small set of example plugins that show what a plugin can contain |
32| How you get it | Claude Code adds it the first time you start an interactive terminal session, unless a [managed policy](/docs/en/plugins/org#allow-the-official-marketplace-and-your-own) or `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` blocks it. See [Marketplace `claude-plugins-official` not found](/docs/en/plugins/troubleshooting#marketplace-claude-plugins-official-not-found) if it's missing | You add it in a Claude Code session with `/plugin marketplace add anthropics/claude-plugins-community` | You add it in a Claude Code session with `/plugin marketplace add anthropics/claude-code` |
3333 
3434If you wrote a plugin and want other people to install it, see [Publish a plugin](/docs/en/plugins/publish), which covers your own marketplace and submitting to Anthropic's directory.
3535 

plugins/cli-hints Changed · +5 / -5 lines

from line 68
6868 
6969The tag takes three attributes, all required:
7070 
71| Attribute | Description |
72| :-------- | :------------------------------------------------ |
73| `v` | Protocol version. `1` is the only supported value |
74| `type` | Hint kind. `plugin` is the only supported value |
75| `value` | Plugin identifier in `name@marketplace` form |
71| Attribute | Description |
72| :- | :- |
73| `v` | Protocol version. `1` is the only supported value |
74| `type` | Hint kind. `plugin` is the only supported value |
75| `value` | Plugin identifier in `name@marketplace` form |
7676 
7777Values may be double-quoted or unquoted; an unquoted value can't contain whitespace.
7878 

plugins/cli-reference Changed · +166 / -166 lines

from line 42
4242 
4343The command has no flag for another location. To scaffold inside a project instead, see [Create a plugin](/docs/en/plugins/create).
4444 
45| Flag | Description |
46| :----------------------- | :------------------------------------------------------------------------------------------------------ |
47| `--description <text>` | Manifest description |
48| `--author <name>` | Author name. Defaults to `git config user.name` |
49| `--author-email <email>` | Author email. Defaults to `git config user.email` |
45| Flag | Description |
46| :- | :- |
47| `--description <text>` | Manifest description |
48| `--author <name>` | Author name. Defaults to `git config user.name` |
49| `--author-email <email>` | Author email. Defaults to `git config user.email` |
5050| `--with <components...>` | Also scaffold starter files for `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, or `channel` |
51| `-f, --force` | Overwrite an existing `.claude-plugin/` at the target |
51| `-f, --force` | Overwrite an existing `.claude-plugin/` at the target |
5252 
5353Scaffold a plugin with starter skill and hook files:
5454 
from line 74
7474 
7575Most plugins install without a prompt. For a plugin whose marketplace entry [runs a command to install it](/docs/en/plugins/host-marketplace) or [sets a `headersHelper` for its download](/docs/en/plugins/host-marketplace#how-users-accept-a-headershelper-command), Claude Code first prints the command and asks `Run this command now? [y/N]`.
7676 
77| Flag | Description |
78| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79| `-s, --scope <scope>` | Installation scope: `user`, `project`, or `local`. Defaults to `user` |
80| `--config <key=value>` | Set a [`userConfig`](/docs/en/plugins/manifest-reference) option the plugin's manifest declares. Repeat the flag for each option. Requires Claude Code v2.1.147 or later |
81| `-y, --yes` | Accept the displayed install command without the `Run this command now?` prompt. Ignored when the command runs inside a Claude Code session, such as from the Bash tool or a hook. Requires Claude Code v2.1.229 or later |
77| Flag | Description |
78| :- | :- |
79| `-s, --scope <scope>` | Installation scope: `user`, `project`, or `local`. Defaults to `user` |
80| `--config <key=value>` | Set a [`userConfig`](/docs/en/plugins/manifest-reference) option the plugin's manifest declares. Repeat the flag for each option. Requires Claude Code v2.1.147 or later |
81| `-y, --yes` | Accept the displayed install command without the `Run this command now?` prompt. Ignored when the command runs inside a Claude Code session, such as from the Bash tool or a hook. Requires Claude Code v2.1.229 or later |
8282| `--accept-command <sha256>` | Accept the displayed install command whose `sha256` a previous [`--json` run](#plugin-json-result) reported in `shownCommand`, in place of `-y`. Can't be combined with `-y`. See [Accept a displayed install command](#accept-a-displayed-install-command). Requires Claude Code v2.1.271 or later |
83| `--json` | Print the result as one JSON object on the last line of stdout instead of the human-readable message, for use in scripts. See [JSON result format](#plugin-json-result). Requires Claude Code v2.1.268 or later |
83| `--json` | Print the result as one JSON object on the last line of stdout instead of the human-readable message, for use in scripts. See [JSON result format](#plugin-json-result). Requires Claude Code v2.1.268 or later |
8484 
8585Pass `-y` from your own terminal to accept the displayed command without the prompt. Here's what happens without a TTY and when Claude runs the command:
8686 
from line 135
135135claude plugin uninstall <plugin> [options]
136136```
137137 
138| Flag | Description |
139| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
140| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local`. Defaults to `user` |
141| `--keep-data` | Preserve the plugin's persistent data directory, `~/.claude/plugins/data/<id>/` |
142| `--prune` | Also remove auto-installed [dependencies](/docs/en/plugins/dependencies) that no remaining plugin needs |
143| `-y, --yes` | Skip the `--prune` confirmation prompt. Required with `--prune` when stdin or stdout isn't a TTY |
144| `--json` | Print the result as one JSON object on the last line of stdout, in the [same format as `plugin install --json`](#plugin-json-result). Can't be combined with `--prune`. Requires Claude Code v2.1.268 or later |
138| Flag | Description |
139| :- | :- |
140| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local`. Defaults to `user` |
141| `--keep-data` | Preserve the plugin's persistent data directory, `~/.claude/plugins/data/<id>/` |
142| `--prune` | Also remove auto-installed [dependencies](/docs/en/plugins/dependencies) that no remaining plugin needs |
143| `-y, --yes` | Skip the `--prune` confirmation prompt. Required with `--prune` when stdin or stdout isn't a TTY |
144| `--json` | Print the result as one JSON object on the last line of stdout, in the [same format as `plugin install --json`](#plugin-json-result). Can't be combined with `--prune`. Requires Claude Code v2.1.268 or later |
145145 
146146Uninstall a plugin from project scope:
147147 
from line 171
171171claude plugin enable <plugin> [options]
172172```
173173 
174| Flag | Description |
175| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
176| `-s, --scope <scope>` | Scope to enable at: `user`, `project`, or `local`. Auto-detected when omitted |
177| `--json` | Print the result as one JSON object on the last line of stdout, in the [same format as `plugin install --json`](#plugin-json-result). Requires Claude Code v2.1.268 or later |
174| Flag | Description |
175| :- | :- |
176| `-s, --scope <scope>` | Scope to enable at: `user`, `project`, or `local`. Auto-detected when omitted |
177| `--json` | Print the result as one JSON object on the last line of stdout, in the [same format as `plugin install --json`](#plugin-json-result). Requires Claude Code v2.1.268 or later |
178178 
179179Without `--scope`, the command checks your settings files in the order local, project, user, and uses the first scope that mentions the plugin.
180180 
from line 207
207207claude plugin disable [plugin] [options]
208208```
209209 
210| Flag | Description |
211| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
212| `-a, --all` | Disable every enabled plugin. Can't be combined with a plugin name or `--scope` |
213| `-s, --scope <scope>` | Scope to disable at: `user`, `project`, or `local`. Auto-detected when omitted |
214| `--json` | Print the result as one JSON object on the last line of stdout, in the [same format as `plugin install --json`](#plugin-json-result). Requires Claude Code v2.1.268 or later |
210| Flag | Description |
211| :- | :- |
212| `-a, --all` | Disable every enabled plugin. Can't be combined with a plugin name or `--scope` |
213| `-s, --scope <scope>` | Scope to disable at: `user`, `project`, or `local`. Auto-detected when omitted |
214| `--json` | Print the result as one JSON object on the last line of stdout, in the [same format as `plugin install --json`](#plugin-json-result). Requires Claude Code v2.1.268 or later |
215215 
216216Without `--scope`, the scope is auto-detected in the same local, project, user order as [`plugin enable`](#plugin-enable).
217217 
from line 238
238238claude plugin update <plugin> [options]
239239```
240240 
241| Flag | Description |
242| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
243| `-s, --scope <scope>` | Scope to update: `user`, `project`, `local`, or `managed`. Auto-detected when omitted |
244| `-y, --yes` | Accept a changed install command from a [command-source](/docs/en/plugins/host-marketplace) plugin, without the prompt. Required when stdin or stdout isn't a TTY, unless you pass `--accept-command`. Requires Claude Code v2.1.229 or later |
245| `--accept-command <sha256>` | Accept the marketplace-declared command whose `sha256` a previous [`--json` run](#plugin-json-result) reported in `shownCommand`, in place of `-y`. Can't be combined with `-y`. Requires Claude Code v2.1.271 or later |
246| `--json` | Print the result as one JSON object on the last line of stdout, in the [same format as `plugin install --json`](#plugin-json-result). Requires Claude Code v2.1.268 or later |
241| Flag | Description |
242| :- | :- |
243| `-s, --scope <scope>` | Scope to update: `user`, `project`, `local`, or `managed`. Auto-detected when omitted |
244| `-y, --yes` | Accept a changed install command from a [command-source](/docs/en/plugins/host-marketplace) plugin, without the prompt. Required when stdin or stdout isn't a TTY, unless you pass `--accept-command`. Requires Claude Code v2.1.229 or later |
245| `--accept-command <sha256>` | Accept the marketplace-declared command whose `sha256` a previous [`--json` run](#plugin-json-result) reported in `shownCommand`, in place of `-y`. Can't be combined with `-y`. Requires Claude Code v2.1.271 or later |
246| `--json` | Print the result as one JSON object on the last line of stdout, in the [same format as `plugin install --json`](#plugin-json-result). Requires Claude Code v2.1.268 or later |
247247 
248248If you omit `--scope`, the command updates the plugin at the most specific scope it's installed at for your current project, checking local, project, user, then managed.
249249 
from line 269
269269claude plugin list [options]
270270```
271271 
272| Flag | Description |
273| :------------ | :--------------------------------------------------------------------------------------------------- |
274| `--json` | Print the list as JSON |
272| Flag | Description |
273| :- | :- |
274| `--json` | Print the list as JSON |
275275| `--available` | Also list plugins your marketplaces offer that you haven't installed. Has no effect without `--json` |
276276 
277277Claude Code groups the human-readable output by how each plugin loads:
from line 287
287287 
288288With `--json`, Claude Code prints an array with one object per installation. Each object carries the fields below. `id`, `version`, `scope`, `enabled`, and `installPath` are always present, and the others appear only when they apply.
289289 
290| Field | Type | Description |
291| :------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
292| `id` | string | `name@marketplace` for installs, `name@inline` for session-only plugins, `name@skills-dir` for skills-directory plugins, `name@synced` for plugins synced from claude.ai |
293| `version` | string | For a marketplace install, the [version Claude Code computed](/docs/en/plugins/loading#versions-and-updates) at install. For a session-only, skills-directory, or synced plugin, the manifest's `version`, or `unknown` when it declares none |
294| `scope` | string | `user`, `project`, `local`, or `managed` for installs; `user` or `project` for skills-directory plugins; `session` for session-only plugins; `synced` for plugins synced from claude.ai |
295| `enabled` | boolean | Whether the plugin is enabled in your merged settings |
296| `installPath` | string | Directory the plugin loads from |
297| `installedAt` | string | ISO timestamp of the install. Marketplace installs only |
298| `lastUpdated` | string | ISO timestamp of the last update. Marketplace installs only |
299| `projectPath` | string | Project the install belongs to. `project` and `local` scope only |
300| `mcpServers` | object | The plugin's MCP server definitions, when a marketplace-installed plugin has any |
301| `errors` | array of strings | Load errors, when the plugin failed to load |
302| `notes` | array of strings | Authoring warnings for a plugin that loaded and works |
303| `errorDetails` | array of objects | One object per `errors` entry, giving its diagnostic `type` and the names it refers to, such as the plugin, marketplace, server, or file. Requires Claude Code v2.1.268 or later |
304| `noteDetails` | array of objects | The same detail objects for each `notes` entry. Requires Claude Code v2.1.268 or later |
290| Field | Type | Description |
291| :- | :- | :- |
292| `id` | string | `name@marketplace` for installs, `name@inline` for session-only plugins, `name@skills-dir` for skills-directory plugins, `name@synced` for plugins synced from claude.ai |
293| `version` | string | For a marketplace install, the [version Claude Code computed](/docs/en/plugins/loading#versions-and-updates) at install. For a session-only, skills-directory, or synced plugin, the manifest's `version`, or `unknown` when it declares none |
294| `scope` | string | `user`, `project`, `local`, or `managed` for installs; `user` or `project` for skills-directory plugins; `session` for session-only plugins; `synced` for plugins synced from claude.ai |
295| `enabled` | boolean | Whether the plugin is enabled in your merged settings |
296| `installPath` | string | Directory the plugin loads from |
297| `installedAt` | string | ISO timestamp of the install. Marketplace installs only |
298| `lastUpdated` | string | ISO timestamp of the last update. Marketplace installs only |
299| `projectPath` | string | Project the install belongs to. `project` and `local` scope only |
300| `mcpServers` | object | The plugin's MCP server definitions, when a marketplace-installed plugin has any |
301| `errors` | array of strings | Load errors, when the plugin failed to load |
302| `notes` | array of strings | Authoring warnings for a plugin that loaded and works |
303| `errorDetails` | array of objects | One object per `errors` entry, giving its diagnostic `type` and the names it refers to, such as the plugin, marketplace, server, or file. Requires Claude Code v2.1.268 or later |
304| `noteDetails` | array of objects | The same detail objects for each `notes` entry. Requires Claude Code v2.1.268 or later |
305305 
306306With `--json --available`, Claude Code prints one object instead of an array. Its `installed` field holds the array of installed-plugin objects, and its `available` field holds one object per uninstalled marketplace plugin with the fields below.
307307 
308| Field | Type | Description |
309| :---------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------- |
310| `pluginId` | string | `name@marketplace` |
311| `name` | string | The plugin's name in the marketplace |
312| `marketplaceName` | string | The marketplace that offers it |
313| `source` | string or object | The marketplace entry's [source](/docs/en/plugins/marketplace-reference): a string for a relative path, an object otherwise |
314| `description` | string | The entry's description, when it has one |
315| `version` | string | The entry's version, when it declares one |
316| `installCount` | number | Install count, when Claude Code has one for the plugin |
308| Field | Type | Description |
309| :- | :- | :- |
310| `pluginId` | string | `name@marketplace` |
311| `name` | string | The plugin's name in the marketplace |
312| `marketplaceName` | string | The marketplace that offers it |
313| `source` | string or object | The marketplace entry's [source](/docs/en/plugins/marketplace-reference): a string for a relative path, an object otherwise |
314| `description` | string | The entry's description, when it has one |
315| `version` | string | The entry's version, when it declares one |
316| `installCount` | number | Install count, when Claude Code has one for the plugin |
317317 
318318### plugin details
319319 
from line 351
351351claude plugin prune [options]
352352```
353353 
354| Flag | Description |
355| :-------------------- | :---------------------------------------------------------------------- |
356| `-s, --scope <scope>` | Prune at scope: `user`, `project`, or `local`. Defaults to `user` |
357| `--dry-run` | List what would be removed without removing it |
358| `-y, --yes` | Skip the confirmation prompt. Required when stdin or stdout isn't a TTY |
354| Flag | Description |
355| :- | :- |
356| `-s, --scope <scope>` | Prune at scope: `user`, `project`, or `local`. Defaults to `user` |
357| `--dry-run` | List what would be removed without removing it |
358| `-y, --yes` | Skip the confirmation prompt. Required when stdin or stdout isn't a TTY |
359359 
360360Preview what a prune would remove:
361361 
from line 371
371371 
372372What `prune` does depends on whether a terminal is attached and whether you pass `-y`:
373373 
374| Terminal and flags | What happens |
375| :------------------------------- | :-------------------------------------------------------------------------------------------- |
376| Interactive terminal, no `-y` | Lists the orphaned dependencies and asks `Remove? [y/N]` |
377| Any terminal, `-y` | Removes them and prints `Removed N auto-installed plugins: <names>` |
374| Terminal and flags | What happens |
375| :- | :- |
376| Interactive terminal, no `-y` | Lists the orphaned dependencies and asks `Remove? [y/N]` |
377| Any terminal, `-y` | Removes them and prints `Removed N auto-installed plugins: <names>` |
378378| Non-TTY stdin or stdout, no `-y` | Prints the list and ``Not a TTY — run `claude plugin prune -y` to remove.``, removing nothing |
379379 
380380### plugin eval
from line 400
400400 
401401This table lists the options most runs use. Run `claude plugin eval --help` for the complete set, including `--case`, `--tag`, `--output-dir`, `--report`, `--allow-real-servers`, `--keep-temp`, and `--verbose`.
402402 
403| Option | Description | Default |
404| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
405| `--runs <n>` | Runs per case in each [arm](/docs/en/plugin-evals#compare-against-a-no-plugin-baseline) | Each case's `runs`, else 3 |
406| `-j, --concurrency <n>` | Agent sessions to run at once, 1 to 8. They share your rate limit | `1` |
407| `--model <model>` | Model for the agent under test | Each case's `model`, else `ANTHROPIC_MODEL` if set, else Claude Code's default |
408| `--judge-model <model>` | Model for `llm` and `baseline` graders | A small fast model |
409| `--ablation <mode>` | `none` or `with-without`. See [Compare against a no-plugin baseline](/docs/en/plugin-evals#compare-against-a-no-plugin-baseline) | `with-without` when a plugin resolves, else `none` |
410| `--threshold <0..1>` | Exit 1 if any case scores below this | `1.0` |
411| `--max-cost-usd <usd>` | Stop before the next run once spend reaches this, exit 2, and report partial results | No limit |
412| `--allow-tools <tools...>` | Grant tools beyond the read-only set, such as `Bash`, `Write`, `Edit`, or `"mcp__plugin_<plugin>_<server>__*"`. See [Grant tools](/docs/en/plugin-evals#grant-tools) | |
413| `--scaffold` | Run each case's [`scaffold_script`](/docs/en/plugin-evals#add-setup-or-history-with-case-yaml) | Off |
414| `--trust-plugin` | Skip the first-run trust prompt, for CI. See [What a run can access](/docs/en/plugin-evals#security) | Off |
415| `--mocks <mode>` | `record` or `off`. See [Mock MCP servers](/docs/en/plugin-evals#mock-mcp-servers) | `record` |
416| `--eval-dir <dir>` | Directory below the plugin that holds the cases | The manifest's `experimental.evals`, else `evals` |
417| `--json [path]` | Print the [result document](/docs/en/plugin-evals#json-result) to stdout, or write it to a `.json` path | |
418| `--no-publish` | Keep the HTML report local | |
403| Option | Description | Default |
404| :- | :- | :- |
405| `--runs <n>` | Runs per case in each [arm](/docs/en/plugin-evals#compare-against-a-no-plugin-baseline) | Each case's `runs`, else 3 |
406| `-j, --concurrency <n>` | Agent sessions to run at once, 1 to 8. They share your rate limit | `1` |
407| `--model <model>` | Model for the agent under test | Each case's `model`, else `ANTHROPIC_MODEL` if set, else Claude Code's default |
408| `--judge-model <model>` | Model for `llm` and `baseline` graders | A small fast model |
409| `--ablation <mode>` | `none` or `with-without`. See [Compare against a no-plugin baseline](/docs/en/plugin-evals#compare-against-a-no-plugin-baseline) | `with-without` when a plugin resolves, else `none` |
410| `--threshold <0..1>` | Exit 1 if any case scores below this | `1.0` |
411| `--max-cost-usd <usd>` | Stop before the next run once spend reaches this, exit 2, and report partial results | No limit |
412| `--allow-tools <tools...>` | Grant tools beyond the read-only set, such as `Bash`, `Write`, `Edit`, or `"mcp__plugin_<plugin>_<server>__*"`. See [Grant tools](/docs/en/plugin-evals#grant-tools) | |
413| `--scaffold` | Run each case's [`scaffold_script`](/docs/en/plugin-evals#add-setup-or-history-with-case-yaml) | Off |
414| `--trust-plugin` | Skip the first-run trust prompt, for CI. See [What a run can access](/docs/en/plugin-evals#security) | Off |
415| `--mocks <mode>` | `record` or `off`. See [Mock MCP servers](/docs/en/plugin-evals#mock-mcp-servers) | `record` |
416| `--eval-dir <dir>` | Directory below the plugin that holds the cases | The manifest's `experimental.evals`, else `evals` |
417| `--json [path]` | Print the [result document](/docs/en/plugin-evals#json-result) to stdout, or write it to a `.json` path | |
418| `--no-publish` | Keep the HTML report local | |
419419 
420420The exit code reports how the run ended. To act on it in a pipeline, see [Run evals in CI](/docs/en/plugin-evals#run-evals-in-ci).
421421 
422| Exit code | Meaning |
423| :-------- | :------------------------------------------------------------- |
424| `0` | Every case meets the threshold |
425| `1` | A failing case, a load error, or an untrusted plugin directory |
426| `2` | A partial run |
427| `130` | Interrupted |
428| `143` | Terminated |
422| Exit code | Meaning |
423| :- | :- |
424| `0` | Every case meets the threshold |
425| `1` | A failing case, a load error, or an untrusted plugin directory |
426| `2` | A partial run |
427| `130` | Interrupted |
428| `143` | Terminated |
429429 
430430### plugin eval init
431431 
from line 449
449449 
450450The command accepts these options:
451451 
452| Option | Description | Default |
453| :------------------ | :------------------------------------------------------------------------------------------------ | :------------------------------------------------ |
454| `--bare` | Write a blank `prompt.md` and `graders/criteria.md` for `<name>` instead of running the interview | |
455| `-i, --interactive` | Require the interview. Fails without a terminal instead of writing a template | |
456| `--eval-dir <dir>` | Directory below the current directory to write cases into | The manifest's `experimental.evals`, else `evals` |
452| Option | Description | Default |
453| :- | :- | :- |
454| `--bare` | Write a blank `prompt.md` and `graders/criteria.md` for `<name>` instead of running the interview | |
455| `-i, --interactive` | Require the interview. Fails without a terminal instead of writing a template | |
456| `--eval-dir <dir>` | Directory below the current directory to write cases into | The manifest's `experimental.evals`, else `evals` |
457457 
458458### plugin tag
459459 
from line 467
467467 
468468The `[path]` is the plugin directory, defaulting to the current directory. The command finds the marketplace entry by walking up from that directory to a `.claude-plugin/marketplace.json` that lists the plugin.
469469 
470| Flag | Description |
471| :-------------------- | :---------------------------------------------------------------------------------- |
472| `--push` | Push the tag to `--remote` after creating it |
473| `--dry-run` | Print what would be tagged without creating the tag |
474| `-f, --force` | Skip the dirty-working-tree and tag-already-exists checks |
470| Flag | Description |
471| :- | :- |
472| `--push` | Push the tag to `--remote` after creating it |
473| `--dry-run` | Print what would be tagged without creating the tag |
474| `-f, --force` | Skip the dirty-working-tree and tag-already-exists checks |
475475| `-m, --message <msg>` | Tag annotation message. `%s` stands for the version. Defaults to `<name> <version>` |
476| `--remote <name>` | Remote to push to with `--push`. Defaults to `origin` |
476| `--remote <name>` | Remote to push to with `--push`. Defaults to `origin` |
477477 
478478Preview the tag for a plugin in a marketplace checkout:
479479 
from line 505
505505claude plugin validate <path> [options]
506506```
507507 
508| Flag | Description |
509| :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
508| Flag | Description |
509| :- | :- |
510510| `--strict` | Treat warnings as errors, so unrecognized fields and missing metadata that the runtime tolerates fail the run. Requires Claude Code v2.1.145 or later |
511| `--json` | Output the validation report as one JSON object with the same exit codes. Requires Claude Code v2.1.259 or later |
511| `--json` | Output the validation report as one JSON object with the same exit codes. Requires Claude Code v2.1.259 or later |
512512 
513513Validate a plugin before committing it:
514514 
from line 543
543543 
544544Claude Code prints the file it validated, any errors and warnings with their paths, and a verdict line. The exit code follows the verdict:
545545 
546| Exit code | Verdict line | Meaning |
547| :-------- | :------------------------------------------------------------------------------ | :--------------------------------------------------------- |
548| `0` | `Validation passed` or `Validation passed with warnings` | The manifest loads. With `--strict`, no warnings either |
549| `1` | `Validation failed` or `Validation failed (--strict treats warnings as errors)` | An error, or a warning under `--strict` |
550| `2` | `Unexpected error during validation: <reason>` | The validator itself failed, such as on an unreadable path |
546| Exit code | Verdict line | Meaning |
547| :- | :- | :- |
548| `0` | `Validation passed` or `Validation passed with warnings` | The manifest loads. With `--strict`, no warnings either |
549| `1` | `Validation failed` or `Validation failed (--strict treats warnings as errors)` | An error, or a warning under `--strict` |
550| `2` | `Unexpected error during validation: <reason>` | The validator itself failed, such as on an unreadable path |
551551 
552552With `--json`, Claude Code writes the report to stdout as one JSON object with these top-level fields:
553553 
from line 578
578578claude plugin marketplace add <source> [options]
579579```
580580 
581| Flag | Description |
582| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
583| `--scope <scope>` | Settings file to declare the marketplace in: `user`, `project`, or `local`. Defaults to `user` |
584| `--sparse <paths...>` | Limit the git checkout to these directories, for monorepos. `github` and `git` sources only |
585| `--claudeai` | Read the argument as the name of a [marketplace hosted on claude.ai](/docs/en/plugins/install#add-from-claude-ai) instead of a source. Requires Claude Code v2.1.273 or later |
581| Flag | Description |
582| :- | :- |
583| `--scope <scope>` | Settings file to declare the marketplace in: `user`, `project`, or `local`. Defaults to `user` |
584| `--sparse <paths...>` | Limit the git checkout to these directories, for monorepos. `github` and `git` sources only |
585| `--claudeai` | Read the argument as the name of a [marketplace hosted on claude.ai](/docs/en/plugins/install#add-from-claude-ai) instead of a source. Requires Claude Code v2.1.273 or later |
586586 
587587`<source>` takes any of the forms in the table below, and its form decides the source type and how Claude Code fetches the marketplace. For the resulting source object, see the [marketplace reference](/docs/en/plugins/marketplace-reference).
588588 
589| You type | Source type | How Claude Code fetches it |
590| :------------------------------------------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------- |
591| `owner/repo`, `owner/repo#ref`, or `owner/repo@ref` | `github` | Clones the GitHub repository, pinned to `ref` when given. Owner and repo must follow GitHub naming rules |
592| `user@host:path[.git][#ref]` | `git` | Clones over SSH |
593| `https://example.com/repo.git[#ref]`, or a URL containing `/_git/` | `git` | Clones over HTTPS, including Azure DevOps URLs |
594| `https://github.com/owner/repo` or `https://gitlab.com/namespace/project` | `git` | Clones over HTTPS after appending `.git` |
595| Any other `http://` or `https://` URL, including a self-hosted git host without `.git` | `url` | Fetches the URL as a `marketplace.json`. To clone a repository there instead, append `.git` |
596| `./path`, `../path`, `/path`, or `~/path` to a directory | `directory` | Reads the directory in place. On Windows, `.\`, `..\`, and `C:\` forms also work |
597| The same path forms, to a `.json` file | `file` | Reads the file in place |
589| You type | Source type | How Claude Code fetches it |
590| :- | :- | :- |
591| `owner/repo`, `owner/repo#ref`, or `owner/repo@ref` | `github` | Clones the GitHub repository, pinned to `ref` when given. Owner and repo must follow GitHub naming rules |
592| `user@host:path[.git][#ref]` | `git` | Clones over SSH |
593| `https://example.com/repo.git[#ref]`, or a URL containing `/_git/` | `git` | Clones over HTTPS, including Azure DevOps URLs |
594| `https://github.com/owner/repo` or `https://gitlab.com/namespace/project` | `git` | Clones over HTTPS after appending `.git` |
595| Any other `http://` or `https://` URL, including a self-hosted git host without `.git` | `url` | Fetches the URL as a `marketplace.json`. To clone a repository there instead, append `.git` |
596| `./path`, `../path`, `/path`, or `~/path` to a directory | `directory` | Reads the directory in place. On Windows, `.\`, `..\`, and `C:\` forms also work |
597| The same path forms, to a `.json` file | `file` | Reads the file in place |
598598 
599599For a host whose clone URLs don't carry the `.git` suffix, such as AWS CodeCommit, add the marketplace as a git entry in [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) instead. Claude Code clones a git entry whether or not its URL ends in `.git`.
600600 
from line 628
628628claude plugin marketplace list [options]
629629```
630630 
631| Flag | Description |
632| :------- | :--------------------- |
631| Flag | Description |
632| :- | :- |
633633| `--json` | Print the list as JSON |
634634 
635635Claude Code prints `Configured marketplaces:` and one `Source:` line per marketplace, or `No marketplaces configured`.
from line 636
636636 
637637With `--json`, Claude Code prints an array with one object per marketplace, carrying the fields below. Every field is a string.
638638 
639| Field | Description |
640| :---------------- | :--------------------------------------------------------------------- |
641| `name` | The marketplace's name |
642| `source` | `github`, `git`, `url`, `directory`, `file`, or `claudeai` |
643| `repo` | `owner/repo`. `github` sources only |
644| `url` | The clone or fetch URL. `git` and `url` sources only |
645| `path` | The local path. `directory` and `file` sources only |
646| `ref` | The pinned branch or tag. `github` and `git` sources, only when pinned |
647| `installLocation` | Where Claude Code cached the marketplace |
639| Field | Description |
640| :- | :- |
641| `name` | The marketplace's name |
642| `source` | `github`, `git`, `url`, `directory`, `file`, or `claudeai` |
643| `repo` | `owner/repo`. `github` sources only |
644| `url` | The clone or fetch URL. `git` and `url` sources only |
645| `path` | The local path. `directory` and `file` sources only |
646| `ref` | The pinned branch or tag. `github` and `git` sources, only when pinned |
647| `installLocation` | Where Claude Code cached the marketplace |
648648 
649649An added [claude.ai marketplace](/docs/en/plugins/install#add-from-claude-ai) has no local clone, so its entry carries its claude.ai identifiers, `marketplaceId` and `organizationUuid`, in place of `installLocation`. It also carries `scope` when one is recorded, and `status`.
650650 
from line 668
668668 
669669The `<name>` is the marketplace name that `plugin marketplace list` shows, not the source you passed to `add`.
670670 
671| Flag | Description |
672| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
671| Flag | Description |
672| :- | :- |
673673| `--scope <scope>` | Remove the declaration from one settings scope: `user`, `project`, or `local`. Without it, Claude Code removes the declaration from every scope |
674674 
675675Remove a marketplace from every scope:
from line 712
712712 
713713The table below lists every session form. The shell subcommands `init`, `update`, `details`, `prune`, `eval`, and `eval init` have no session form.
714714 
715| Command | Aliases | What it does |
716| :-------------------------------------------------- | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
717| `/plugin` | | Opens the panel on the **Discover** tab. Any unrecognized first word after `/plugin` does the same |
718| `/plugin help` | `/plugin --help`, `/plugin -h` | Shows the usage list of `/plugin` subcommands |
719| `/plugin list [--enabled\|--disabled]` | `ls` | Prints your marketplace-installed plugins inline, with version, scope, and status. A filter flag shows only that state. A plugin whose enable state hasn't been applied yet is marked `— run /reload-plugins to apply`. Requires Claude Code v2.1.163 or later |
720| `/plugin install` | `i` | Opens the **Discover** tab |
721| `/plugin install <plugin>` | `i` | Opens the plugin's details in the **Discover** tab. With `name@marketplace`, opens them in that marketplace's list |
722| `/plugin install <plugin> --marketplace <source>` | `i` | Adds the marketplace at `<source>` when you haven't added it yet, asking you to confirm first, then opens the plugin's details. See [Add a marketplace and install in one command](/docs/en/plugins/install#add-a-marketplace-and-install-in-one-command). Requires Claude Code v2.1.275 or later |
723| `/plugin manage` | | Opens the **Installed** tab |
724| `/plugin stats` | | Opens the **Stats** tab, in sessions where [`/skill-doctor`](/docs/en/skills#find-unused-skills) is available. Anywhere else it opens the panel on the **Discover** tab |
725| `/plugin enable <plugin>` | | Opens the **Installed** tab at the plugin and enables it |
726| `/plugin disable <plugin>` | | Opens the **Installed** tab at the plugin and disables it |
727| `/plugin uninstall <plugin>` | | Opens the **Installed** tab at the plugin and uninstalls it |
728| `/plugin configure <plugin>` | `config` | Opens the plugin's [`userConfig`](/docs/en/plugins/manifest-reference) dialog, or reports that the plugin declares none. Requires Claude Code v2.1.147 or later |
729| `/plugin validate <path>` | | Prints the same report as `claude plugin validate`, inline |
730| `/plugin tag [path] [--push] [--dry-run] [--force]` | | Creates the release tag as `claude plugin tag` does. Accepts `--push`, `--dry-run`, and `--force` or `-f`; with any other flag or an extra argument, Claude Code prints usage instead |
731| `/plugin marketplace` | `market` | Does nothing visible. Pass `add`, `list`, `update`, or `remove` |
732| `/plugin marketplace add [source]` | `market add` | With a source, adds it and reports the result. Without one, opens the **Add marketplace** input |
733| `/plugin marketplace list` | `market list` | Prints your marketplace names inline |
734| `/plugin marketplace update [name]` | `market update` | Opens the **Marketplaces** tab. With a name, refreshes that marketplace there |
735| `/plugin marketplace remove [name]` | `market remove`, `market rm`, `marketplace rm` | Opens the **Marketplaces** tab. With a name, removes that marketplace there |
715| Command | Aliases | What it does |
716| :- | :- | :- |
717| `/plugin` | | Opens the panel on the **Discover** tab. Any unrecognized first word after `/plugin` does the same |
718| `/plugin help` | `/plugin --help`, `/plugin -h` | Shows the usage list of `/plugin` subcommands |
719| `/plugin list [--enabled\|--disabled]` | `ls` | Prints your marketplace-installed plugins inline, with version, scope, and status. A filter flag shows only that state. A plugin whose enable state hasn't been applied yet is marked `— run /reload-plugins to apply`. Requires Claude Code v2.1.163 or later |
720| `/plugin install` | `i` | Opens the **Discover** tab |
721| `/plugin install <plugin>` | `i` | Opens the plugin's details in the **Discover** tab. With `name@marketplace`, opens them in that marketplace's list |
722| `/plugin install <plugin> --marketplace <source>` | `i` | Adds the marketplace at `<source>` when you haven't added it yet, asking you to confirm first, then opens the plugin's details. See [Add a marketplace and install in one command](/docs/en/plugins/install#add-a-marketplace-and-install-in-one-command). Requires Claude Code v2.1.275 or later |
723| `/plugin manage` | | Opens the **Installed** tab |
724| `/plugin stats` | | Opens the **Stats** tab, in sessions where [`/skill-doctor`](/docs/en/skills#find-unused-skills) is available. Anywhere else it opens the panel on the **Discover** tab |
725| `/plugin enable <plugin>` | | Opens the **Installed** tab at the plugin and enables it |
726| `/plugin disable <plugin>` | | Opens the **Installed** tab at the plugin and disables it |
727| `/plugin uninstall <plugin>` | | Opens the **Installed** tab at the plugin and uninstalls it |
728| `/plugin configure <plugin>` | `config` | Opens the plugin's [`userConfig`](/docs/en/plugins/manifest-reference) dialog, or reports that the plugin declares none. Requires Claude Code v2.1.147 or later |
729| `/plugin validate <path>` | | Prints the same report as `claude plugin validate`, inline |
730| `/plugin tag [path] [--push] [--dry-run] [--force]` | | Creates the release tag as `claude plugin tag` does. Accepts `--push`, `--dry-run`, and `--force` or `-f`; with any other flag or an extra argument, Claude Code prints usage instead |
731| `/plugin marketplace` | `market` | Does nothing visible. Pass `add`, `list`, `update`, or `remove` |
732| `/plugin marketplace add [source]` | `market add` | With a source, adds it and reports the result. Without one, opens the **Add marketplace** input |
733| `/plugin marketplace list` | `market list` | Prints your marketplace names inline |
734| `/plugin marketplace update [name]` | `market update` | Opens the **Marketplaces** tab. With a name, refreshes that marketplace there |
735| `/plugin marketplace remove [name]` | `market remove`, `market rm`, `marketplace rm` | Opens the **Marketplaces** tab. With a name, removes that marketplace there |
736736 
737737If you name a plugin that isn't installed in the current project in `/plugin enable`, `disable`, `uninstall`, or `configure`, Claude Code prints `Plugin "<plugin>" is not installed in this project` instead of acting.
738738 
from line 748
748748/reload-plugins [--force]
749749```
750750 
751| Flag | Description |
752| :-------- | :------------------------------------------------------------------------------------------------ |
751| Flag | Description |
752| :- | :- |
753753| `--force` | Apply the reload even when it would invalidate the prompt cache. `force` without dashes works too |
754754 
755755### Reload summary
from line 778
778778 
779779Plugin authors use them to test a plugin before publishing. For the load-edit-reload workflow, see [Develop without a marketplace](/docs/en/plugins/create#develop-without-a-marketplace).
780780 
781| Flag | Description | Example |
782| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |
783| `--plugin-dir <path>` | Load a plugin from a directory or a `.zip` archive of one. A folder of plugins loads each child folder that holds a `.claude-plugin/plugin.json`. Each flag takes one path | `claude --plugin-dir ./my-plugin --plugin-dir ./other.zip` |
784| `--plugin-url <url>` | Fetch a plugin `.zip` archive from a URL. Repeat the flag, or pass several URLs space-separated in one quoted value | `claude --plugin-url "https://example.com/a.zip https://example.com/b.zip"` |
781| Flag | Description | Example |
782| :- | :- | :- |
783| `--plugin-dir <path>` | Load a plugin from a directory or a `.zip` archive of one. A folder of plugins loads each child folder that holds a `.claude-plugin/plugin.json`. Each flag takes one path | `claude --plugin-dir ./my-plugin --plugin-dir ./other.zip` |
784| `--plugin-url <url>` | Fetch a plugin `.zip` archive from a URL. Repeat the flag, or pass several URLs space-separated in one quoted value | `claude --plugin-url "https://example.com/a.zip https://example.com/b.zip"` |
785785 
786786A plugin that either flag loads is a session-only plugin. `claude plugin list` shows it as `<name>@inline` with scope `session`, but only when the same flag precedes the subcommand. For example, run `claude --plugin-dir ./my-plugin plugin list`.
787787 

plugins/code-intelligence Changed · +15 / -15 lines

from line 22
2222 <Step title="Install the language server binary">
2323 Find your language in the table below and install the binary in its row. If your language isn't listed, see [Add a language without an official plugin](#add-a-language-without-an-official-plugin).
2424 
25 | Language | Plugin | Binary |
26 | :------------------------ | :--------------------------------------------------------------------------------------------------------------- | :------------------------------ |
27 | C/C++ | [`clangd-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/clangd-lsp) | `clangd` |
28 | C# | [`csharp-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/csharp-lsp) | `csharp-ls` |
29 | Go | [`gopls-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/gopls-lsp) | `gopls` |
30 | Java | [`jdtls-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/jdtls-lsp) | `jdtls` |
31 | Kotlin | [`kotlin-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/kotlin-lsp) | `kotlin-lsp` |
32 | Liquid | [`liquid-lsp`](https://github.com/Shopify/liquid-skills/tree/main/plugins/liquid-lsp) | `shopify`, from the Shopify CLI |
33 | Lua | [`lua-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/lua-lsp) | `lua-language-server` |
34 | PHP | [`php-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/php-lsp) | `intelephense` |
35 | Python | [`pyright-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/pyright-lsp) | `pyright-langserver` |
36 | Ruby | [`ruby-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ruby-lsp) | `ruby-lsp` |
37 | Rust | [`rust-analyzer-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/rust-analyzer-lsp) | `rust-analyzer` |
38 | Swift | [`swift-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/swift-lsp) | `sourcekit-lsp` |
39 | TypeScript and JavaScript | [`typescript-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/typescript-lsp) | `typescript-language-server` |
25 | Language | Plugin | Binary |
26 | :- | :- | :- |
27 | C/C++ | [`clangd-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/clangd-lsp) | `clangd` |
28 | C# | [`csharp-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/csharp-lsp) | `csharp-ls` |
29 | Go | [`gopls-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/gopls-lsp) | `gopls` |
30 | Java | [`jdtls-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/jdtls-lsp) | `jdtls` |
31 | Kotlin | [`kotlin-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/kotlin-lsp) | `kotlin-lsp` |
32 | Liquid | [`liquid-lsp`](https://github.com/Shopify/liquid-skills/tree/main/plugins/liquid-lsp) | `shopify`, from the Shopify CLI |
33 | Lua | [`lua-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/lua-lsp) | `lua-language-server` |
34 | PHP | [`php-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/php-lsp) | `intelephense` |
35 | Python | [`pyright-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/pyright-lsp) | `pyright-langserver` |
36 | Ruby | [`ruby-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ruby-lsp) | `ruby-lsp` |
37 | Rust | [`rust-analyzer-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/rust-analyzer-lsp) | `rust-analyzer` |
38 | Swift | [`swift-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/swift-lsp) | `sourcekit-lsp` |
39 | TypeScript and JavaScript | [`typescript-lsp`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/typescript-lsp) | `typescript-language-server` |
4040 
4141 Anthropic maintains every plugin in the table except `liquid-lsp`, which Shopify maintains and the official marketplace lists.
4242 

plugins/components Changed · +4 / -4 lines

from line 910
910910 
911911A plugin can include color themes and output styles. Both appear in the same pickers as the user's own. For either one, setting the manifest key replaces the folder scan.
912912 
913| Component | Save as | Format | Appears in | Manifest key |
914| :----------- | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ | :-------------------- |
915| Theme | `themes/<slug>.json` | The [custom theme file](/docs/en/terminal-config#create-a-custom-theme) format users write in `~/.claude/themes/` | `/theme`, under the file's `name` | `experimental.themes` |
916| Output style | `output-styles/<name>.md` | The [custom output style](/docs/en/output-styles#create-a-custom-output-style) format, with `name` and `description` frontmatter | `/output-style`, as `<plugin>:<name>` | `outputStyles` |
913| Component | Save as | Format | Appears in | Manifest key |
914| :- | :- | :- | :- | :- |
915| Theme | `themes/<slug>.json` | The [custom theme file](/docs/en/terminal-config#create-a-custom-theme) format users write in `~/.claude/themes/` | `/theme`, under the file's `name` | `experimental.themes` |
916| Output style | `output-styles/<name>.md` | The [custom output style](/docs/en/output-styles#create-a-custom-output-style) format, with `name` and `description` frontmatter | `/output-style`, as `<plugin>:<name>` | `outputStyles` |
917917 
918918Plugin themes are read-only, so when a user edits one in `/theme`, the edit is saved as a copy in their own themes directory.
919919 

plugins/create Changed · +7 / -7 lines

from line 142
142142 
143143The table lists the directories most plugins start with, and the [full layout](/docs/en/plugins/manifest-reference#standard-layout) lists the rest.
144144 
145| Location | Contents |
146| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
145| Location | Contents |
146| :- | :- |
147147| `.claude-plugin/plugin.json` | The manifest. When you load a plugin with `--plugin-dir` and it has no manifest, Claude Code names the plugin after its directory |
148| `skills/` | One `<name>/SKILL.md` directory per skill |
149| `commands/` | Flat Markdown files, the older form of skills. Use `skills/` for new plugins |
150| `agents/` | One Markdown file per subagent |
151| `hooks/hooks.json` | Hook configuration: a top-level `"hooks"` key whose value has the same shape as `hooks` in a settings file |
152| `.mcp.json` | MCP server definitions |
148| `skills/` | One `<name>/SKILL.md` directory per skill |
149| `commands/` | Flat Markdown files, the older form of skills. Use `skills/` for new plugins |
150| `agents/` | One Markdown file per subagent |
151| `hooks/hooks.json` | Hook configuration: a top-level `"hooks"` key whose value has the same shape as `hooks` in a settings file |
152| `.mcp.json` | MCP server definitions |
153153 
154154<Warning>
155155 Only `plugin.json` goes inside `.claude-plugin/`. Components saved there don't load.

plugins/create-marketplace Changed · +5 / -5 lines

from line 152
152152 
153153Each plugin entry in `marketplace.json` has a `source` that tells Claude Code where to fetch that one plugin. Pick the source by where the plugin's files are stored. The table lists the sources most marketplace owners use.
154154 
155| Source | Use it when | Minimal `source` value |
156| :------------ | :------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------- |
157| Relative path | The plugin's files are inside the marketplace directory itself | `"./plugins/my-first-plugin"` |
158| `github` | The plugin is a GitHub repository of its own | `{ "source": "github", "repo": "your-org/my-first-plugin" }` |
159| `git-subdir` | The plugin is a subdirectory of some other repository, such as a monorepo | `{ "source": "git-subdir", "url": "your-org/monorepo", "path": "tools/my-first-plugin" }` |
155| Source | Use it when | Minimal `source` value |
156| :- | :- | :- |
157| Relative path | The plugin's files are inside the marketplace directory itself | `"./plugins/my-first-plugin"` |
158| `github` | The plugin is a GitHub repository of its own | `{ "source": "github", "repo": "your-org/my-first-plugin" }` |
159| `git-subdir` | The plugin is a subdirectory of some other repository, such as a monorepo | `{ "source": "git-subdir", "url": "your-org/monorepo", "path": "tools/my-first-plugin" }` |
160160 
161161In a `git-subdir` source, `url` takes a git URL or an `owner/repo` GitHub shorthand.
162162 

plugins/dependencies Changed · +10 / -10 lines

from line 41
4141 
4242To set a version constraint, use an object with these fields, each a string:
4343 
44| Field | Description |
45| :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
46| `name` | The dependency's plugin name, as it appears in its marketplace entry. Claude Code looks it up in the same marketplace as the declaring plugin unless you set `marketplace`. Required. |
47| `version` | A [semantic-version range](https://github.com/npm/node-semver#ranges) such as `~2.1.0`, `^2.0`, `>=1.4`, or `=2.1.0`. The dependency installs at the highest git tag that satisfies this range, so the dependency's maintainer must [tag releases](#tag-plugin-releases-for-version-resolution). |
48| `marketplace` | A different marketplace to resolve `name` in. An allowlist controls cross-marketplace dependencies, described in [Depend on a plugin from another marketplace](#depend-on-a-plugin-from-another-marketplace). |
44| Field | Description |
45| :- | :- |
46| `name` | The dependency's plugin name, as it appears in its marketplace entry. Claude Code looks it up in the same marketplace as the declaring plugin unless you set `marketplace`. Required. |
47| `version` | A [semantic-version range](https://github.com/npm/node-semver#ranges) such as `~2.1.0`, `^2.0`, `>=1.4`, or `=2.1.0`. The dependency installs at the highest git tag that satisfies this range, so the dependency's maintainer must [tag releases](#tag-plugin-releases-for-version-resolution). |
48| `marketplace` | A different marketplace to resolve `name` in. An allowlist controls cross-marketplace dependencies, described in [Depend on a plugin from another marketplace](#depend-on-a-plugin-from-another-marketplace). |
4949 
5050A range doesn't match pre-release versions such as `2.0.0-beta.1` unless you opt in with a pre-release suffix such as `^2.0.0-0`.
5151 
from line 201
201201 
202202When several installed plugins constrain the same dependency, the dependency resolves to the highest version that satisfies all of their ranges. Common combinations resolve like this:
203203 
204| Plugin A requires | Plugin B requires | Result |
205| :---------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------ |
206| `^2.0` | `>=2.1` | One install at the highest `2.x` tag at or above `2.1.0`. Both plugins load. |
207| `~2.1` | `~3.0` | Installing plugin B fails with a `has conflicting version requirements` message. Plugin A and the dependency stay as they were. |
208| `=2.1.0` | none | The dependency stays at `2.1.0`. Auto-update skips newer versions while plugin A is installed. |
204| Plugin A requires | Plugin B requires | Result |
205| :- | :- | :- |
206| `^2.0` | `>=2.1` | One install at the highest `2.x` tag at or above `2.1.0`. Both plugins load. |
207| `~2.1` | `~3.0` | Installing plugin B fails with a `has conflicting version requirements` message. Plugin A and the dependency stay as they were. |
208| `=2.1.0` | none | The dependency stays at `2.1.0`. Auto-update skips newer versions while plugin A is installed. |
209209 
210210Auto-update fetches a constrained dependency at the highest git tag that satisfies every installed plugin's range, rather than at the marketplace's latest version. If the installed plugins' ranges don't overlap, auto-update leaves that dependency at its current version, and the `/plugin` **Errors** tab shows an entry naming the constraining plugin. If they overlap but no tag falls in the range, auto-update fetches the marketplace's current copy and skips the update when that copy's `version` falls outside any installed plugin's range.
211211 

plugins/host-marketplace Changed · +19 / -19 lines

from line 19
1919 
2020You can host the marketplace on GitHub, on another git host, as a hosted `marketplace.json` URL, or in a directory on a shared filesystem. Send your users the add command for your host and tell them what they need on their machine:
2121 
22| Host | Users run, in a Claude Code session | What users need |
23| :--------------------------------------------------------------- | :--------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
24| GitHub | `/plugin marketplace add your-org/your-marketplace` | `git`, and for a private repository the access described under [Grant access to a private marketplace](#grant-access-to-a-private-marketplace) |
25| GitLab, Bitbucket, GitHub Enterprise Server, or another git host | `/plugin marketplace add https://gitlab.example.com/team/plugins.git` | `git`, and access to the host from their machine. Send the full URL, because `owner/repo` shorthand always means github.com |
26| A hosted `marketplace.json` URL | `/plugin marketplace add https://plugins.example.com/marketplace.json` | HTTPS access to the URL. Users don't need `git` for the catalog itself |
27| A directory on a shared filesystem | `/plugin marketplace add /Volumes/shared/claude-plugins` | Read access to the path |
22| Host | Users run, in a Claude Code session | What users need |
23| :- | :- | :- |
24| GitHub | `/plugin marketplace add your-org/your-marketplace` | `git`, and for a private repository the access described under [Grant access to a private marketplace](#grant-access-to-a-private-marketplace) |
25| GitLab, Bitbucket, GitHub Enterprise Server, or another git host | `/plugin marketplace add https://gitlab.example.com/team/plugins.git` | `git`, and access to the host from their machine. Send the full URL, because `owner/repo` shorthand always means github.com |
26| A hosted `marketplace.json` URL | `/plugin marketplace add https://plugins.example.com/marketplace.json` | HTTPS access to the URL. Users don't need `git` for the catalog itself |
27| A directory on a shared filesystem | `/plugin marketplace add /Volumes/shared/claude-plugins` | Read access to the path |
2828 
2929To pin a branch or tag of a GitHub or git-URL marketplace, tell users to append `#<ref>`, as in `your-org/your-marketplace#stable`. The [plugin commands reference](/docs/en/plugins/cli-reference#plugin-marketplace-add) lists every form the command accepts.
3030 
from line 132
132132 
133133Rolling a plugin out to a company involves you as the marketplace owner, an administrator who controls managed settings, and each person who uses Claude Code. You can run the rollout without the administrator, in which case each person adds the marketplace and installs the plugin themselves.
134134 
135| Who | What they do | Where it's covered |
136| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
137| You, the marketplace owner | Keep the catalog in a repository only the company can read, send the add command for your host, and say what each person needs on their machine | [Host your marketplace](#host-your-marketplace) and [Grant access to a private marketplace](#grant-access-to-a-private-marketplace) |
138| An administrator | Registers the marketplace and turns its plugins on for everyone with `extraKnownMarketplaces` and `enabledPlugins` in managed settings, and sets `autoUpdate` there | [Require a marketplace and its plugins](/docs/en/plugins/org#require-a-marketplace-and-its-plugins) and [Set update policy](/docs/en/plugins/org#set-update-policy) |
139| Each person | Needs read access to a private git repository, with credentials already stored on their machine. Without an administrator, they also run the add and install commands | [Add a private marketplace](/docs/en/plugins/install#add-a-private-marketplace) |
135| Who | What they do | Where it's covered |
136| :- | :- | :- |
137| You, the marketplace owner | Keep the catalog in a repository only the company can read, send the add command for your host, and say what each person needs on their machine | [Host your marketplace](#host-your-marketplace) and [Grant access to a private marketplace](#grant-access-to-a-private-marketplace) |
138| An administrator | Registers the marketplace and turns its plugins on for everyone with `extraKnownMarketplaces` and `enabledPlugins` in managed settings, and sets `autoUpdate` there | [Require a marketplace and its plugins](/docs/en/plugins/org#require-a-marketplace-and-its-plugins) and [Set update policy](/docs/en/plugins/org#set-update-policy) |
139| Each person | Needs read access to a private git repository, with credentials already stored on their machine. Without an administrator, they also run the add and install commands | [Add a private marketplace](/docs/en/plugins/install#add-a-private-marketplace) |
140140 
141141For people who have no git-host account, these sections each cover one way to reach them:
142142 
from line 284
284284 
285285The place you choose decides which downloads get the headers and when Claude Code runs the command:
286286 
287| Place | Downloads that get the headers | When Claude Code runs a `headersHelper` set there |
288| :----------------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
287| Place | Downloads that get the headers | When Claude Code runs a `headersHelper` set there |
288| :- | :- | :- |
289289| Marketplace `url` source | Archive downloads on the marketplace URL's origin, meaning the same scheme, host, and port | Before each fetch of the marketplace's `marketplace.json` and before each archive download on that origin. Claude Code reuses one run's output for up to 60 seconds |
290| Plugin entry | That entry's download only | Only when a user installs or updates that one plugin by itself and [accepts the command](#how-users-accept-a-headershelper-command) |
290| Plugin entry | That entry's download only | Only when a user installs or updates that one plugin by itself and [accepts the command](#how-users-accept-a-headershelper-command) |
291291 
292292Where both places set a header of the same name, Claude Code sends the entry's value. Within one place, a header the command prints overrides a header of the same name listed in `headers`.
293293 
from line 360
360360 
361361You declare a marketplace `url` source's `headersHelper` in a settings file, such as an [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) entry, rather than in the catalog the marketplace publishes. Claude Code therefore doesn't ask the user to accept it on each install or update. Instead, the settings file that declares it decides when Claude Code runs it:
362362 
363| Settings file | When Claude Code runs the command |
364| :---------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
365| User settings, a `--settings` file, or a managed settings file on the machine | Without asking, including during a background marketplace refresh |
366| A project's `.claude/settings.json` or `.claude/settings.local.json` | Only after the user accepts the [workspace trust dialog](/docs/en/permissions#what-runs-before-you-trust-a-folder) for that folder itself. A `-p` or SDK session doesn't count as accepting it, and neither does trust granted to a parent folder |
367| Server-managed settings | In an interactive session, only after the user approves the delivered settings in the [security approval dialog](/docs/en/server-managed-settings#security-approval-dialogs) |
363| Settings file | When Claude Code runs the command |
364| :- | :- |
365| User settings, a `--settings` file, or a managed settings file on the machine | Without asking, including during a background marketplace refresh |
366| A project's `.claude/settings.json` or `.claude/settings.local.json` | Only after the user accepts the [workspace trust dialog](/docs/en/permissions#what-runs-before-you-trust-a-folder) for that folder itself. A `-p` or SDK session doesn't count as accepting it, and neither does trust granted to a parent folder |
367| Server-managed settings | In an interactive session, only after the user approves the delivered settings in the [security approval dialog](/docs/en/server-managed-settings#security-approval-dialogs) |
368368 
369369For an [inline plugin entry](/docs/en/settings-reference#extraknownmarketplaces) in one of these files, Claude Code requires the same folder trust or settings approval as for a marketplace-level command in that file, and the user also accepts the entry's command on each install or update.
370370 

plugins/install Changed · +10 / -10 lines

from line 198
198198 
199199In a Claude Code session, run `/plugin marketplace add` followed by the marketplace's source: a GitHub repository, a git repository on any host, a local directory or file, or a hosted `marketplace.json`.
200200 
201| Source | What you type | Example |
202| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
203| GitHub repository | `owner/repo`. Add `#ref` to pin a branch or tag. | `/plugin marketplace add anthropics/claude-code`, or `/plugin marketplace add your-org/plugins#v1.2.0` to pin the `v1.2.0` tag |
204| Git repository on any host | The full clone URL. Add `#ref` to pin a branch or tag. | `/plugin marketplace add https://gitlab.example.com/your-group/your-marketplace.git#v1.0.0` |
205| Local directory or file | A relative or absolute path to a directory that holds `.claude-plugin/marketplace.json`, or to the JSON file itself. Start a relative path with `./` or `../`, because Claude Code reads a bare `name/name` as a GitHub repository. | `/plugin marketplace add ./my-marketplace` |
206| Hosted `marketplace.json` | Its `https://` URL | `/plugin marketplace add https://example.com/marketplace.json` |
201| Source | What you type | Example |
202| :- | :- | :- |
203| GitHub repository | `owner/repo`. Add `#ref` to pin a branch or tag. | `/plugin marketplace add anthropics/claude-code`, or `/plugin marketplace add your-org/plugins#v1.2.0` to pin the `v1.2.0` tag |
204| Git repository on any host | The full clone URL. Add `#ref` to pin a branch or tag. | `/plugin marketplace add https://gitlab.example.com/your-group/your-marketplace.git#v1.0.0` |
205| Local directory or file | A relative or absolute path to a directory that holds `.claude-plugin/marketplace.json`, or to the JSON file itself. Start a relative path with `./` or `../`, because Claude Code reads a bare `name/name` as a GitHub repository. | `/plugin marketplace add ./my-marketplace` |
206| Hosted `marketplace.json` | Its `https://` URL | `/plugin marketplace add https://example.com/marketplace.json` |
207207 
208208From your shell, `claude plugin marketplace add` takes the same sources.
209209 
from line 359
359359 
360360You can also list, update, and remove marketplaces with commands, from your shell or inside a session:
361361 
362| Action | In your shell | Inside a session |
363| :----------------------------- | :---------------------------------------- | :---------------------------------- |
364| List marketplaces | `claude plugin marketplace list` | `/plugin marketplace list` |
362| Action | In your shell | Inside a session |
363| :- | :- | :- |
364| List marketplaces | `claude plugin marketplace list` | `/plugin marketplace list` |
365365| Update a marketplace's listing | `claude plugin marketplace update <name>` | `/plugin marketplace update <name>` |
366| Remove a marketplace | `claude plugin marketplace remove <name>` | `/plugin marketplace remove <name>` |
366| Remove a marketplace | `claude plugin marketplace remove <name>` | `/plugin marketplace remove <name>` |
367367 
368368When you remove a marketplace, Claude Code uninstalls every plugin you installed from it and removes their `enabledPlugins` entries from your settings files. The **Marketplaces** tab names those plugins before it asks you to confirm.
369369 

plugins/loading Changed · +39 / -39 lines

from line 42
4242 
4343Every plugin has an id of the form `<name>@<origin>`, which is what you see in settings files and in `claude plugin list --json`. The part after `@` tells you where Claude Code found the plugin:
4444 
45| ID ends in | How the plugin got there | How you turn it on or off |
46| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
47| `@<marketplace>` | You installed it from a marketplace you added | `"<name>@<marketplace>": true` or `false` under `enabledPlugins` in a settings file |
48| `@inline` | You started Claude Code with `--plugin-dir` or `--plugin-url`, set [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/en/env-vars#variables), or an Agent SDK app passed the `plugins` option. It loads for that session only | On for the session unless the manifest sets `defaultEnabled: false` or a settings file sets `"<name>@inline": false` |
49| `@skills-dir` | You saved a plugin directory that has a `.claude-plugin/plugin.json` under `~/.claude/skills/` or the project's `.claude/skills/` | The manifest's `defaultEnabled`, unless a settings file sets `"<name>@skills-dir"` to `true` or `false` |
50| `@synced` | You or your organization turned it on for your claude.ai account, and Claude Code [downloaded it](#synced-plugins) | On unless the manifest sets `defaultEnabled: false` or a settings file sets `"<name>@synced": false`. A plugin your organization marks as required loads regardless |
45| ID ends in | How the plugin got there | How you turn it on or off |
46| :- | :- | :- |
47| `@<marketplace>` | You installed it from a marketplace you added | `"<name>@<marketplace>": true` or `false` under `enabledPlugins` in a settings file |
48| `@inline` | You started Claude Code with `--plugin-dir` or `--plugin-url`, set [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/en/env-vars#variables), or an Agent SDK app passed the `plugins` option. It loads for that session only | On for the session unless the manifest sets `defaultEnabled: false` or a settings file sets `"<name>@inline": false` |
49| `@skills-dir` | You saved a plugin directory that has a `.claude-plugin/plugin.json` under `~/.claude/skills/` or the project's `.claude/skills/` | The manifest's `defaultEnabled`, unless a settings file sets `"<name>@skills-dir"` to `true` or `false` |
50| `@synced` | You or your organization turned it on for your claude.ai account, and Claude Code [downloaded it](#synced-plugins) | On unless the manifest sets `defaultEnabled: false` or a settings file sets `"<name>@synced": false`. A plugin your organization marks as required loads regardless |
5151 
5252For a marketplace plugin, `<name>` is the entry name in `marketplace.json`; for `@inline` and `@skills-dir` it's the `name` in the plugin's manifest.
5353 
from line 119
119119 
120120You can set an `enabledPlugins` entry in any of six sources. The table lists them from lowest precedence to highest, and who each one applies to. For the settings files themselves, see [Settings files and who they affect](/docs/en/settings#where-settings-live).
121121 
122| Source | Where you set it | Reaches |
123| :---------- | :------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------- |
124| `--add-dir` | `.claude/settings.json` or `.claude/settings.local.json` in a directory you pass with `--add-dir` | This session only. Only a `true` value has an effect, and every other source overrides it |
125| `user` | `~/.claude/settings.json` | You, in every project |
126| `project` | `.claude/settings.json` | Everyone who clones the repository |
127| `local` | `.claude/settings.local.json` | You, in this repository only |
128| `flag` | The `--settings` value you pass at launch | This session only |
129| `managed` | [Managed settings](/docs/en/managed-settings) | Every user the policy covers. `true` force-enables and `false` blocks, and no other source overrides them |
122| Source | Where you set it | Reaches |
123| :- | :- | :- |
124| `--add-dir` | `.claude/settings.json` or `.claude/settings.local.json` in a directory you pass with `--add-dir` | This session only. Only a `true` value has an effect, and every other source overrides it |
125| `user` | `~/.claude/settings.json` | You, in every project |
126| `project` | `.claude/settings.json` | Everyone who clones the repository |
127| `local` | `.claude/settings.local.json` | You, in this repository only |
128| `flag` | The `--settings` value you pass at launch | This session only |
129| `managed` | [Managed settings](/docs/en/managed-settings) | Every user the policy covers. `true` force-enables and `false` blocks, and no other source overrides them |
130130 
131131These sources merge key by key. For each plugin id, the value that applies is the one from the highest-precedence source that mentions the id. A source that doesn't mention the id leaves the value from the lower-precedence source in effect.
132132 
from line 153
153153 
154154Claude Code keeps plugin files and state records under one plugins root, which is `~/.claude/plugins` unless you set [`CLAUDE_CODE_PLUGIN_CACHE_DIR`](/docs/en/env-vars). Every path in the table is relative to that root.
155155 
156| Path | What it holds |
157| :----------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
158| `cache/<marketplace>/<plugin>/<version>/` | One directory per installed version of a marketplace plugin. `<plugin>` is the marketplace entry name and `<version>` is the [resolved version](#versions-and-updates). `${CLAUDE_PLUGIN_ROOT}` points at this directory |
159| `data/<plugin-id>/` | The plugin's persistent directory, exposed as `${CLAUDE_PLUGIN_DATA}`. For how `<plugin-id>` is formed, see [Path variables and persistent data](/docs/en/plugins/components#path-variables-and-persistent-data). Claude Code creates it when a plugin component first uses it and keeps it across updates. By default, Claude Code deletes it when you uninstall the plugin from its last scope. For `--keep-data` and the other cases where it stays, see [plugin uninstall](/docs/en/plugins/cli-reference#plugin-uninstall) |
160| `marketplaces/<name>/` | The clone or download of a marketplace added from GitHub, another Git host, or a URL. A marketplace added from a local `file` or `directory` source has no copy here, and its `installLocation` in `known_marketplaces.json` is the path you gave |
161| `synced/` | The plugins Claude Code [synced from your claude.ai account](#synced-plugins) |
162| `.trash/` | Plugins that the claude.ai sync removed, such as after you turn one off on claude.ai or stop syncing |
163| `installed_plugins.json` and `known_marketplaces.json` | The records of what Claude Code has installed and which marketplaces it has fetched, described under [Check which stage a plugin reached](#check-which-stage-a-plugin-reached). A [marketplace hosted on claude.ai](/docs/en/plugins/install#add-from-claude-ai) is recorded in `known_marketplaces_claudeai.json` instead |
164| `flagged-plugins.json` | Plugins Claude Code uninstalled because their marketplace delisted them. They appear in the **Flagged** section of `/plugin`; see [Host a marketplace](/docs/en/plugins/host-marketplace) |
156| Path | What it holds |
157| :- | :- |
158| `cache/<marketplace>/<plugin>/<version>/` | One directory per installed version of a marketplace plugin. `<plugin>` is the marketplace entry name and `<version>` is the [resolved version](#versions-and-updates). `${CLAUDE_PLUGIN_ROOT}` points at this directory |
159| `data/<plugin-id>/` | The plugin's persistent directory, exposed as `${CLAUDE_PLUGIN_DATA}`. For how `<plugin-id>` is formed, see [Path variables and persistent data](/docs/en/plugins/components#path-variables-and-persistent-data). Claude Code creates it when a plugin component first uses it and keeps it across updates. By default, Claude Code deletes it when you uninstall the plugin from its last scope. For `--keep-data` and the other cases where it stays, see [plugin uninstall](/docs/en/plugins/cli-reference#plugin-uninstall) |
160| `marketplaces/<name>/` | The clone or download of a marketplace added from GitHub, another Git host, or a URL. A marketplace added from a local `file` or `directory` source has no copy here, and its `installLocation` in `known_marketplaces.json` is the path you gave |
161| `synced/` | The plugins Claude Code [synced from your claude.ai account](#synced-plugins) |
162| `.trash/` | Plugins that the claude.ai sync removed, such as after you turn one off on claude.ai or stop syncing |
163| `installed_plugins.json` and `known_marketplaces.json` | The records of what Claude Code has installed and which marketplaces it has fetched, described under [Check which stage a plugin reached](#check-which-stage-a-plugin-reached). A [marketplace hosted on claude.ai](/docs/en/plugins/install#add-from-claude-ai) is recorded in `known_marketplaces_claudeai.json` instead |
164| `flagged-plugins.json` | Plugins Claude Code uninstalled because their marketplace delisted them. They appear in the **Flagged** section of `/plugin`; see [Host a marketplace](/docs/en/plugins/host-marketplace) |
165165 
166166Because `${CLAUDE_PLUGIN_ROOT}` points at a version directory, a plugin's root path changes with every version. Keep a plugin's durable files in `${CLAUDE_PLUGIN_DATA}` instead.
167167 
from line 208
208208 
209209The install runs only when the plugin's root directory contains both a `package.json` and a supported lockfile. The lockfile decides which command Claude Code runs:
210210 
211| Lockfile | Command |
212| :------------------------------------------- | :----------------------------------------------- |
213| `bun.lock` or `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |
214| `npm-shrinkwrap.json` or `package-lock.json` | `npm ci --ignore-scripts` |
211| Lockfile | Command |
212| :- | :- |
213| `bun.lock` or `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |
214| `npm-shrinkwrap.json` or `package-lock.json` | `npm ci --ignore-scripts` |
215215 
216216If 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`.
217217 
from line 268
2682682. Then the `version` field in the plugin's marketplace entry
2692693. When neither is set, the version comes from the source type:
270270 
271| Source type | Version when no `version` field is set |
272| :----------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
273| `github`, `url`, or `git-subdir` | The commit SHA of the source, shortened to 12 characters. A `git-subdir` version also carries a hash of the subdirectory path |
274| `archive` | The SHA-256 digest, shortened to 12 characters: the `sha256` pin in the marketplace entry, or the digest of the downloaded file when there is no pin |
275| Relative path inside a Git-hosted marketplace | The commit SHA of the installed directory |
276| Local directory, when neither the plugin directory nor its marketplace is a git repository | `unknown` |
277| `npm` | `unknown` |
271| Source type | Version when no `version` field is set |
272| :- | :- |
273| `github`, `url`, or `git-subdir` | The commit SHA of the source, shortened to 12 characters. A `git-subdir` version also carries a hash of the subdirectory path |
274| `archive` | The SHA-256 digest, shortened to 12 characters: the `sha256` pin in the marketplace entry, or the digest of the downloaded file when there is no pin |
275| Relative path inside a Git-hosted marketplace | The commit SHA of the installed directory |
276| Local directory, when neither the plugin directory nor its marketplace is a git repository | `unknown` |
277| `npm` | `unknown` |
278278 
279279Claude Code doesn't take the version from a repository that encloses the install path, such as a git-managed `~/.claude`.
280280 
from line 286
286286 
287287When you install a plugin, Claude Code looks it up in its local copy of the marketplace catalog. You can run `/plugin install` in a session or `claude plugin install` in your shell, and name the plugin with or without its marketplace. The table shows which of those combinations refresh the local copy.
288288 
289| Plugin name | Command | What Claude Code refreshes |
290| :----------------- | :------------------------------------------- | :--------------------------------------------------------------------------- |
291| `name@marketplace` | `/plugin install` or `claude plugin install` | The named marketplace, before the lookup |
292| `name` alone | `/plugin install` | Only marketplaces that have auto-update on, and only after the lookup misses |
293| `name` alone | `claude plugin install` | Nothing. It reads the cached catalogs without refreshing |
289| Plugin name | Command | What Claude Code refreshes |
290| :- | :- | :- |
291| `name@marketplace` | `/plugin install` or `claude plugin install` | The named marketplace, before the lookup |
292| `name` alone | `/plugin install` | Only marketplaces that have auto-update on, and only after the lookup misses |
293| `name` alone | `claude plugin install` | Nothing. It reads the cached catalogs without refreshing |
294294 
295295The refresh before a `name@marketplace` install doesn't depend on the marketplace's auto-update setting or on `DISABLE_AUTOUPDATER`.
296296 

plugins/manifest-reference Changed · +113 / -113 lines

from line 117
117117 
118118For component keys such as `commands` and `hooks`, [Component path forms](#component-path-forms) shows each accepted shape with an example, and every path follows the [path rules](#path-rules) for the `./` prefix, extensions, and containment.
119119 
120| Field | Type | Description |
121| :----------------------------------- | :------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
122| `$schema` | String | JSON Schema URL for editor autocomplete. Claude Code ignores it at load time |
123| [`name`](#name) | String | Plugin identifier, required. Use kebab-case. Every component is namespaced under it |
124| [`displayName`](#displayname) | String | Name shown in UI in place of `name` |
125| [`version`](#version) | String | Version string. Setting it keeps users on that version until you change it |
126| `description` | String | Short explanation of what the plugin provides |
127| `author` | Object | `name`, which is required, plus optional `email` and `url` |
128| `homepage` | String | Documentation URL. Must parse as a URL, or the plugin fails to load |
129| `repository` | String | Source repository URL. Not validated |
130| `license` | String | SPDX identifier such as `MIT` or `Apache-2.0` |
131| `keywords` | Array of strings | Discovery tags |
132| [`metadata`](#metadata) | Object | Free-form object for your own data. Claude Code doesn't read it |
133| [`defaultEnabled`](#defaultenabled) | Boolean | Whether the plugin starts enabled when the user hasn't set it. Defaults to `true` |
134| [`dependencies`](#dependencies) | Array of strings or objects | Plugins that must be enabled for this one to work |
135| [`settings`](#settings) | Object | Settings Claude Code applies while the plugin is enabled. Only `agent` and `subagentStatusLine` take effect |
136| [`userConfig`](#user-configuration) | Object | Values Claude Code prompts the user for when the plugin is enabled |
137| [`channels`](#channels) | Array of objects | Message channels the plugin provides, each bound to one of its MCP servers |
138| `skills` | Path, or array of paths | Directories to scan for skills, each a directory of `<name>/SKILL.md` folders or one folder holding `SKILL.md` directly. `"."` names the plugin root. Adds to the default `skills/` scan |
139| [`commands`](#commands) | Path, array of paths, or object | Flat `.md` command files, directories of them, or an object map of command name to `source` or `content`. Replaces the default `commands/` scan |
140| `agents` | Path, or array of paths | Agent `.md` files. Directories aren't accepted. Replaces the default `agents/` scan |
141| [`hooks`](#hooks) | Path, object, or array of either | `.json` hook files or inline hook config. Loaded together with `hooks/hooks.json` |
142| [`mcpServers`](#mcpservers) | Path, object, or array of either | `.json` MCP config files, `.mcpb` or `.dxt` bundles, or inline server configs keyed by name. Loaded together with `.mcp.json`; a server name declared later replaces an earlier one |
143| [`lspServers`](#lspservers) | Path, object, or array of either | `.json` LSP config files or inline server configs keyed by name. Loaded together with `.lsp.json` |
144| `outputStyles` | Path, or array of paths | Output style files or directories. Replaces the default `output-styles/` scan |
145| `workflows` | Path, or array of paths | [Workflow](/docs/en/workflows#distribute-a-workflow-in-a-plugin) `.js` files or directories. Replaces the default `workflows/` scan |
146| `experimental` | Object | Container for `themes`, `monitors`, and `evals`, whose manifest shape may still change |
147| `experimental.themes` | Path, or array of paths | Theme files or directories. Replaces the default `themes/` scan. A top-level `themes` key still loads, with a `claude plugin validate` warning |
148| [`experimental.monitors`](#monitors) | Path, or inline array | A `.json` file holding the monitors array, or the array itself. Defaults to `monitors/monitors.json`. A top-level `monitors` key still loads, with a `claude plugin validate` warning. Monitors run only in interactive sessions, and not on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry |
149| `experimental.evals` | Path, or array of paths | Directory that holds the plugin's [eval cases](/docs/en/plugin-evals#use-a-different-eval-directory) when it isn't the default `evals/`. `claude plugin eval --eval-dir` overrides it |
120| Field | Type | Description |
121| :- | :- | :- |
122| `$schema` | String | JSON Schema URL for editor autocomplete. Claude Code ignores it at load time |
123| [`name`](#name) | String | Plugin identifier, required. Use kebab-case. Every component is namespaced under it |
124| [`displayName`](#displayname) | String | Name shown in UI in place of `name` |
125| [`version`](#version) | String | Version string. Setting it keeps users on that version until you change it |
126| `description` | String | Short explanation of what the plugin provides |
127| `author` | Object | `name`, which is required, plus optional `email` and `url` |
128| `homepage` | String | Documentation URL. Must parse as a URL, or the plugin fails to load |
129| `repository` | String | Source repository URL. Not validated |
130| `license` | String | SPDX identifier such as `MIT` or `Apache-2.0` |
131| `keywords` | Array of strings | Discovery tags |
132| [`metadata`](#metadata) | Object | Free-form object for your own data. Claude Code doesn't read it |
133| [`defaultEnabled`](#defaultenabled) | Boolean | Whether the plugin starts enabled when the user hasn't set it. Defaults to `true` |
134| [`dependencies`](#dependencies) | Array of strings or objects | Plugins that must be enabled for this one to work |
135| [`settings`](#settings) | Object | Settings Claude Code applies while the plugin is enabled. Only `agent` and `subagentStatusLine` take effect |
136| [`userConfig`](#user-configuration) | Object | Values Claude Code prompts the user for when the plugin is enabled |
137| [`channels`](#channels) | Array of objects | Message channels the plugin provides, each bound to one of its MCP servers |
138| `skills` | Path, or array of paths | Directories to scan for skills, each a directory of `<name>/SKILL.md` folders or one folder holding `SKILL.md` directly. `"."` names the plugin root. Adds to the default `skills/` scan |
139| [`commands`](#commands) | Path, array of paths, or object | Flat `.md` command files, directories of them, or an object map of command name to `source` or `content`. Replaces the default `commands/` scan |
140| `agents` | Path, or array of paths | Agent `.md` files. Directories aren't accepted. Replaces the default `agents/` scan |
141| [`hooks`](#hooks) | Path, object, or array of either | `.json` hook files or inline hook config. Loaded together with `hooks/hooks.json` |
142| [`mcpServers`](#mcpservers) | Path, object, or array of either | `.json` MCP config files, `.mcpb` or `.dxt` bundles, or inline server configs keyed by name. Loaded together with `.mcp.json`; a server name declared later replaces an earlier one |
143| [`lspServers`](#lspservers) | Path, object, or array of either | `.json` LSP config files or inline server configs keyed by name. Loaded together with `.lsp.json` |
144| `outputStyles` | Path, or array of paths | Output style files or directories. Replaces the default `output-styles/` scan |
145| `workflows` | Path, or array of paths | [Workflow](/docs/en/workflows#distribute-a-workflow-in-a-plugin) `.js` files or directories. Replaces the default `workflows/` scan |
146| `experimental` | Object | Container for `themes`, `monitors`, and `evals`, whose manifest shape may still change |
147| `experimental.themes` | Path, or array of paths | Theme files or directories. Replaces the default `themes/` scan. A top-level `themes` key still loads, with a `claude plugin validate` warning |
148| [`experimental.monitors`](#monitors) | Path, or inline array | A `.json` file holding the monitors array, or the array itself. Defaults to `monitors/monitors.json`. A top-level `monitors` key still loads, with a `claude plugin validate` warning. Monitors run only in interactive sessions, and not on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry |
149| `experimental.evals` | Path, or array of paths | Directory that holds the plugin's [eval cases](/docs/en/plugin-evals#use-a-different-eval-directory) when it isn't the default `evals/`. `claude plugin eval --eval-dir` overrides it |
150150 
151151In the Type column, a path is a string relative to the plugin root, such as `"./custom/commands"`.
152152 
from line 206
206206 
207207Each value sets exactly one of `source` or `content`, and an entry that sets both or neither fails validation. The other fields in this table are optional:
208208 
209| Field | Type | Description |
210| :------------- | :--------------- | :--------------------------------------------------------------- |
211| `source` | string | Path to the command's Markdown file, relative to the plugin root |
212| `content` | string | Inline Markdown for the command body, instead of `source` |
213| `description` | string | Description shown for the command |
214| `argumentHint` | string | Argument hint shown after the command name, such as `[file]` |
215| `model` | string | Default model for the command |
216| `allowedTools` | array of strings | Tools the command may use without prompting |
209| Field | Type | Description |
210| :- | :- | :- |
211| `source` | string | Path to the command's Markdown file, relative to the plugin root |
212| `content` | string | Inline Markdown for the command body, instead of `source` |
213| `description` | string | Description shown for the command |
214| `argumentHint` | string | Argument hint shown after the command name, such as `[file]` |
215| `model` | string | Default model for the command |
216| `allowedTools` | array of strings | Tools the command may use without prompting |
217217 
218218This map declares one command from a file and one from inline content:
219219 
from line 258
258258 
259259An `mcpServers` value takes one of these shapes:
260260 
261| Shape | Example value | What Claude Code does |
262| :---------------- | :------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
263| `.json` file path | `"./mcp/servers.json"` | Reads the file as an `mcpServers` map |
264| MCP bundle path | `"./bundle.mcpb"` | Extracts the `.mcpb` or `.dxt` bundle into `.mcpb-cache/` under the plugin root and reads its server config |
265| MCP bundle URL | `"https://example.com/server.mcpb"` | Downloads the bundle into `.mcpb-cache/`, then reads it |
266| Inline map | `{ "deploy-api": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"] } }` | Uses the map as server configs keyed by name |
261| Shape | Example value | What Claude Code does |
262| :- | :- | :- |
263| `.json` file path | `"./mcp/servers.json"` | Reads the file as an `mcpServers` map |
264| MCP bundle path | `"./bundle.mcpb"` | Extracts the `.mcpb` or `.dxt` bundle into `.mcpb-cache/` under the plugin root and reads its server config |
265| MCP bundle URL | `"https://example.com/server.mcpb"` | Downloads the bundle into `.mcpb-cache/`, then reads it |
266| Inline map | `{ "deploy-api": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"] } }` | Uses the map as server configs keyed by name |
267267 
268268A bundle path or URL must end in `.mcpb` or `.dxt`. Any other extension fails validation.
269269 
from line 275
275275 
276276Each server config is a strict object with these fields. An unknown key fails validation.
277277 
278| Field | Required | Description |
279| :---------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
280| `command` | Yes | Language server binary. No spaces unless the value starts with `/`; put arguments in `args` |
281| `extensionToLanguage` | Yes | Map of file extension to LSP language ID, at least one entry. Keys start with a dot, such as `".go"` |
282| `args` | No | Arguments passed to the server |
283| `transport` | No | Communication transport: `stdio` (default) or `socket`. Claude Code accepts `socket` but runs every server over stdio, so the stdout protocol rules apply to all servers |
284| `env` | No | Environment variables for the server process |
285| `initializationOptions` | No | Options sent in the initialize request |
286| `settings` | No | Settings sent by `workspace/didChangeConfiguration` |
287| `workspaceFolder` | No | Workspace folder path for the server |
288| `startupTimeout` | No | Milliseconds to wait for startup, a positive integer |
289| `shutdownTimeout` | No | Milliseconds to wait for a graceful shutdown, a positive integer. When the timeout elapses, Claude Code terminates the server process. When unset, no timeout applies |
290| `restartOnCrash` | No | Whether to restart the server after it crashes. Defaults to `true`. Set to `false` to leave a crashed server stopped instead of restarting it |
291| `maxRestarts` | No | Restart attempts before giving up, zero or more |
292| `diagnostics` | No | Whether to push diagnostics into context after edits. Defaults to `true` |
278| Field | Required | Description |
279| :- | :- | :- |
280| `command` | Yes | Language server binary. No spaces unless the value starts with `/`; put arguments in `args` |
281| `extensionToLanguage` | Yes | Map of file extension to LSP language ID, at least one entry. Keys start with a dot, such as `".go"` |
282| `args` | No | Arguments passed to the server |
283| `transport` | No | Communication transport: `stdio` (default) or `socket`. Claude Code accepts `socket` but runs every server over stdio, so the stdout protocol rules apply to all servers |
284| `env` | No | Environment variables for the server process |
285| `initializationOptions` | No | Options sent in the initialize request |
286| `settings` | No | Settings sent by `workspace/didChangeConfiguration` |
287| `workspaceFolder` | No | Workspace folder path for the server |
288| `startupTimeout` | No | Milliseconds to wait for startup, a positive integer |
289| `shutdownTimeout` | No | Milliseconds to wait for a graceful shutdown, a positive integer. When the timeout elapses, Claude Code terminates the server process. When unset, no timeout applies |
290| `restartOnCrash` | No | Whether to restart the server after it crashes. Defaults to `true`. Set to `false` to leave a crashed server stopped instead of restarting it |
291| `maxRestarts` | No | Restart attempts before giving up, zero or more |
292| `diagnostics` | No | Whether to push diagnostics into context after edits. Defaults to `true` |
293293 
294294This inline config runs `gopls` for `.go` files:
295295 
from line 313
313313 
314314Each entry is a strict object with these fields.
315315 
316| Field | Required | Description |
317| :------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
318| `name` | Yes | Identifier unique within the plugin |
319| `command` | Yes | Shell command Claude Code runs as a persistent background process in the session working directory |
320| `description` | Yes | Short summary shown in the task panel and notification summaries |
321| `when` | No | With `"always"`, the default, the monitor starts at session start and on plugin reload. With `"on-skill-invoke:<skill>"`, it starts the first time that skill runs |
316| Field | Required | Description |
317| :- | :- | :- |
318| `name` | Yes | Identifier unique within the plugin |
319| `command` | Yes | Shell command Claude Code runs as a persistent background process in the session working directory |
320| `description` | Yes | Short summary shown in the task panel and notification summaries |
321| `when` | No | With `"always"`, the default, the monitor starts at session start and on plugin reload. With `"on-skill-invoke:<skill>"`, it starts the first time that skill runs |
322322 
323323This inline array declares one monitor that starts the first time the `deploy` skill runs:
324324 
from line 375
375375 
376376Each value is a strict object with these fields. An unknown key fails validation.
377377 
378| Field | Required | Description |
379| :------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
380| `type` | Yes | One of `string`, `number`, `boolean`, `directory`, or `file` |
381| `title` | Yes | Label shown in the configuration dialog |
382| `description` | Yes | Help text shown beneath the field |
383| `required` | No | If `true`, the configuration dialog doesn't accept an empty value |
384| `default` | No | Value used when the user provides nothing: a string, number, boolean, or array of strings |
385| `options` | No | For `string`, the values the field accepts, shown as a picker in `/config`. See [Limit a field to fixed options](#limit-a-field-to-fixed-options). Requires Claude Code v2.1.271 or later |
386| `multiple` | No | For `string`, allows an array of strings |
387| `sensitive` | No | If `true`, masks input and stores the value in secure storage instead of `settings.json` |
388| `min` / `max` | No | Bounds for `number` |
378| Field | Required | Description |
379| :- | :- | :- |
380| `type` | Yes | One of `string`, `number`, `boolean`, `directory`, or `file` |
381| `title` | Yes | Label shown in the configuration dialog |
382| `description` | Yes | Help text shown beneath the field |
383| `required` | No | If `true`, the configuration dialog doesn't accept an empty value |
384| `default` | No | Value used when the user provides nothing: a string, number, boolean, or array of strings |
385| `options` | No | For `string`, the values the field accepts, shown as a picker in `/config`. See [Limit a field to fixed options](#limit-a-field-to-fixed-options). Requires Claude Code v2.1.271 or later |
386| `multiple` | No | For `string`, allows an array of strings |
387| `sensitive` | No | If `true`, masks input and stores the value in secure storage instead of `settings.json` |
388| `min` / `max` | No | Bounds for `number` |
389389 
390390Each option of each enabled plugin also appears as a row in the `/config` panel, except `sensitive` options and `multiple` lists. The `/config` rows require Claude Code v2.1.269 or later.
391391 
from line 450
450450 
451451The table shows how the value can reach each of these fields instead.
452452 
453| Field | How the value can reach it |
454| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
455| Shell-form hook commands | Use [exec form](/docs/en/hooks#exec-form-and-shell-form) with `args`, or read `CLAUDE_PLUGIN_OPTION_<KEY>` from the hook's environment |
456| Monitor commands | Not through Claude Code. Monitor processes don't receive `CLAUDE_PLUGIN_OPTION_<KEY>`, so the monitor script has to obtain the value on its own |
457| MCP `headersHelper` | Not through Claude Code. The helper's environment carries `CLAUDE_PLUGIN_ROOT`, `CLAUDE_CODE_MCP_SERVER_NAME`, and `CLAUDE_CODE_MCP_SERVER_URL` but no option values, so the helper script has to obtain the value on its own |
453| Field | How the value can reach it |
454| :- | :- |
455| Shell-form hook commands | Use [exec form](/docs/en/hooks#exec-form-and-shell-form) with `args`, or read `CLAUDE_PLUGIN_OPTION_<KEY>` from the hook's environment |
456| Monitor commands | Not through Claude Code. Monitor processes don't receive `CLAUDE_PLUGIN_OPTION_<KEY>`, so the monitor script has to obtain the value on its own |
457| MCP `headersHelper` | Not through Claude Code. The helper's environment carries `CLAUDE_PLUGIN_ROOT`, `CLAUDE_CODE_MCP_SERVER_NAME`, and `CLAUDE_CODE_MCP_SERVER_URL` but no option values, so the helper script has to obtain the value on its own |
458458 
459459## Channels
460460 
from line 462
462462 
463463Each entry is a strict object bound to one of the plugin's MCP servers, with these fields:
464464 
465| Field | Required | Description |
466| :------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
467| `server` | Yes | Key of the MCP server in this plugin's `mcpServers` that the channel binds to |
468| `displayName` | No | Name shown in the configuration dialog title. Defaults to the server name |
469| `userConfig` | No | Options to prompt for, in the same shape as [top-level `userConfig`](#user-configuration). Saved values substitute into `${user_config.KEY}` references in the server's `env` |
465| Field | Required | Description |
466| :- | :- | :- |
467| `server` | Yes | Key of the MCP server in this plugin's `mcpServers` that the channel binds to |
468| `displayName` | No | Name shown in the configuration dialog title. Defaults to the server name |
469| `userConfig` | No | Options to prompt for, in the same shape as [top-level `userConfig`](#user-configuration). Saved values substitute into `${user_config.KEY}` references in the server's `env` |
470470 
471471This manifest binds a channel to the plugin's `telegram` MCP server and prompts for a bot token that substitutes into the server's `env`:
472472 
from line 500
500500 
501501Claude Code provides three path variables to plugin components. Reference them as `${NAME}` in the fields listed under [Where each variable resolves](#where-each-variable-resolves), and read them as environment variables in the processes that receive them.
502502 
503| Variable | Resolves to | Use it for |
504| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------ |
505| `${CLAUDE_PLUGIN_ROOT}` | Absolute path of the plugin's installed version | Scripts, binaries, and config files bundled with the plugin |
503| Variable | Resolves to | Use it for |
504| :- | :- | :- |
505| `${CLAUDE_PLUGIN_ROOT}` | Absolute path of the plugin's installed version | Scripts, binaries, and config files bundled with the plugin |
506506| `${CLAUDE_PLUGIN_DATA}` | `~/.claude/plugins/data/<id>/`, created on first reference and kept across plugin updates. `<id>` is the plugin identifier with every character other than a letter, digit, `_`, or `-` replaced by `-` | Installed dependencies such as `node_modules`, generated code, and caches |
507| `${CLAUDE_PROJECT_DIR}` | The project root | Project-local scripts and config files |
507| `${CLAUDE_PROJECT_DIR}` | The project root | Project-local scripts and config files |
508508 
509509`${CLAUDE_PLUGIN_ROOT}` changes when the plugin updates, so don't write state there. For where the root moves and when the old directory is cleaned up, see the [loading page](/docs/en/plugins/loading).
510510 
from line 514
514514 
515515In each plugin component, `${...}` references resolve inline in specific fields, and some components also receive the variables in their process environment:
516516 
517| Plugin component | Fields where `${...}` resolves | Exported to the process |
518| :-------------------------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------- |
519| Hook commands | Anywhere in `command` and `args` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PROJECT_DIR`, and `CLAUDE_PLUGIN_OPTION_<KEY>` |
520| Monitor commands | Anywhere in `command` | Not exported |
521| MCP `stdio` servers | `command`, `args`, `env` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA` |
522| MCP `http`, `sse`, `ws` servers | `url`, `headers`, `headersHelper` | Not applicable |
523| LSP servers | `command`, `args`, `env`, `workspaceFolder` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PROJECT_DIR` |
524| Skill, command, and agent content | Anywhere in the Markdown body | Not applicable |
517| Plugin component | Fields where `${...}` resolves | Exported to the process |
518| :- | :- | :- |
519| Hook commands | Anywhere in `command` and `args` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PROJECT_DIR`, and `CLAUDE_PLUGIN_OPTION_<KEY>` |
520| Monitor commands | Anywhere in `command` | Not exported |
521| MCP `stdio` servers | `command`, `args`, `env` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA` |
522| MCP `http`, `sse`, `ws` servers | `url`, `headers`, `headersHelper` | Not applicable |
523| LSP servers | `command`, `args`, `env`, `workspaceFolder` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PROJECT_DIR` |
524| Skill, command, and agent content | Anywhere in the Markdown body | Not applicable |
525525 
526526The variables aren't present in the environment of commands Claude runs through the Bash tool, in the main session or in a subagent. In skill, command, and agent content, write the `${...}` reference in the Markdown body instead, and Claude Code substitutes the path inline when it loads the content.
527527 
from line 559
559559 
560560Each component type has a default location under the plugin root, used when the manifest doesn't point elsewhere.
561561 
562| Component | Default location | Contents |
563| :------------ | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
564| Manifest | `.claude-plugin/plugin.json` | Plugin metadata and configuration. Optional |
565| Skills | `skills/` | One `<name>/SKILL.md` per skill. A plugin with `SKILL.md` at its root, no `skills/`, and no `skills` key loads as a single skill |
566| Commands | `commands/` | Flat Markdown command files. Prefer `skills/` for new plugins |
567| Agents | `agents/` | Agent Markdown files. Subfolders are part of the [agent name](/docs/en/plugins/components#agents) |
568| Hooks | `hooks/hooks.json` | Hook configuration |
569| MCP servers | `.mcp.json` | MCP server definitions |
570| LSP servers | `.lsp.json` | LSP server configurations |
571| Output styles | `output-styles/` | Output style Markdown files |
572| Workflows | `workflows/` | Workflow `.js` files |
573| Themes | `themes/` | Theme JSON files |
574| Monitors | `monitors/monitors.json` | The monitors array |
575| Executables | `bin/` | Files here are on the Bash tool's `PATH` while the plugin is enabled, so Claude runs them as bare commands. claude.ai and Cowork don't install a plugin that has this directory, including one you [distribute through claude.ai organization settings](https://claude.com/docs/plugins/org-sync#keep-executables-out-of-the-top-level-bin-directory) |
576| Settings | `settings.json` | `agent` and `subagentStatusLine` defaults applied while the plugin is enabled |
562| Component | Default location | Contents |
563| :- | :- | :- |
564| Manifest | `.claude-plugin/plugin.json` | Plugin metadata and configuration. Optional |
565| Skills | `skills/` | One `<name>/SKILL.md` per skill. A plugin with `SKILL.md` at its root, no `skills/`, and no `skills` key loads as a single skill |
566| Commands | `commands/` | Flat Markdown command files. Prefer `skills/` for new plugins |
567| Agents | `agents/` | Agent Markdown files. Subfolders are part of the [agent name](/docs/en/plugins/components#agents) |
568| Hooks | `hooks/hooks.json` | Hook configuration |
569| MCP servers | `.mcp.json` | MCP server definitions |
570| LSP servers | `.lsp.json` | LSP server configurations |
571| Output styles | `output-styles/` | Output style Markdown files |
572| Workflows | `workflows/` | Workflow `.js` files |
573| Themes | `themes/` | Theme JSON files |
574| Monitors | `monitors/monitors.json` | The monitors array |
575| Executables | `bin/` | Files here are on the Bash tool's `PATH` while the plugin is enabled, so Claude runs them as bare commands. claude.ai and Cowork don't install a plugin that has this directory, including one you [distribute through claude.ai organization settings](https://claude.com/docs/plugins/org-sync#keep-executables-out-of-the-top-level-bin-directory) |
576| Settings | `settings.json` | `agent` and `subagentStatusLine` defaults applied while the plugin is enabled |
577577 
578578A plugin that uses every default location, plus a `scripts/` folder that its hooks call, is laid out like this:
579579 

plugins/marketplace-reference Changed · +108 / -108 lines

from line 51
5151 
5252The table lists every key Claude Code reads from `marketplace.json`. `name`, `owner`, and `plugins` are required.
5353 
54| Field | Type | Description |
55| :----------------------------------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
56| `name` | string | Marketplace identifier. No spaces, control characters, or bidirectional-formatting characters, no `/` or `\`, no `..`, and not `.`. See [Reserved names](#reserved-names). Users type it after `@` when they install a plugin |
57| `owner` | object | Maintainer information. `name` is required; `email` and `url` are optional |
58| `plugins` | array | [Plugin entries](#plugin-entries). Each entry is validated on its own, so one invalid entry doesn't fail the marketplace |
59| `$schema` | string | JSON Schema URL for editor autocomplete. Ignored at load time |
60| `description` | string | Marketplace description shown to users. `claude plugin validate` warns when it's missing |
61| `version` | string | Marketplace manifest version |
62| `metadata.description`, `metadata.version` | string | Alternate location for `description` and `version` |
63| `metadata.pluginRoot` | string | Directory that bare plugin source names resolve under. See [Relative path plugin source](#relative-path-plugin-source). Requires Claude Code v2.1.239 or later |
64| `forceRemoveDeletedPlugins` | boolean | When `true`, a plugin you remove from `plugins` is uninstalled on users' machines. See [Host and maintain a marketplace](/docs/en/plugins/host-marketplace) |
65| `allowCrossMarketplaceDependenciesOn` | array of strings | Marketplace names whose plugins may be installed as dependencies of this marketplace's plugins. When you install a plugin, only the list in that plugin's own marketplace applies, for its whole dependency chain. See [Plugin dependencies](/docs/en/plugins/dependencies) |
66| `renames` | object | Map from a former plugin `name` to its current name, or to `null` for a plugin you removed. Requires Claude Code v2.1.193 or later. See [Host and maintain a marketplace](/docs/en/plugins/host-marketplace) |
54| Field | Type | Description |
55| :- | :- | :- |
56| `name` | string | Marketplace identifier. No spaces, control characters, or bidirectional-formatting characters, no `/` or `\`, no `..`, and not `.`. See [Reserved names](#reserved-names). Users type it after `@` when they install a plugin |
57| `owner` | object | Maintainer information. `name` is required; `email` and `url` are optional |
58| `plugins` | array | [Plugin entries](#plugin-entries). Each entry is validated on its own, so one invalid entry doesn't fail the marketplace |
59| `$schema` | string | JSON Schema URL for editor autocomplete. Ignored at load time |
60| `description` | string | Marketplace description shown to users. `claude plugin validate` warns when it's missing |
61| `version` | string | Marketplace manifest version |
62| `metadata.description`, `metadata.version` | string | Alternate location for `description` and `version` |
63| `metadata.pluginRoot` | string | Directory that bare plugin source names resolve under. See [Relative path plugin source](#relative-path-plugin-source). Requires Claude Code v2.1.239 or later |
64| `forceRemoveDeletedPlugins` | boolean | When `true`, a plugin you remove from `plugins` is uninstalled on users' machines. See [Host and maintain a marketplace](/docs/en/plugins/host-marketplace) |
65| `allowCrossMarketplaceDependenciesOn` | array of strings | Marketplace names whose plugins may be installed as dependencies of this marketplace's plugins. When you install a plugin, only the list in that plugin's own marketplace applies, for its whole dependency chain. See [Plugin dependencies](/docs/en/plugins/dependencies) |
66| `renames` | object | Map from a former plugin `name` to its current name, or to `null` for a plugin you removed. Requires Claude Code v2.1.193 or later. See [Host and maintain a marketplace](/docs/en/plugins/host-marketplace) |
6767 
6868## Plugin entries
6969 
from line 73
7373 
7474The table lists the entry's own fields and the manifest fields whose meaning changes in an entry.
7575 
76| Field | Type | Description |
77| :--------------- | :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78| `name` | string | Plugin identifier, with no spaces, control characters, or bidirectional-formatting characters. Users type it before `@` when they install, even when the plugin's own `plugin.json` sets a different `name` |
79| `source` | string or object | Where to fetch the plugin. See [Plugin sources](#plugin-sources) |
80| `description` | string | Shown in [`/plugin`](/docs/en/plugins/install) listings and details |
81| `version` | string | Version string for the plugin. When `plugin.json` also sets `version`, `plugin.json` takes precedence and `claude plugin validate` warns. See [Plugin loading reference](/docs/en/plugins/loading) |
82| `category` | string | Free-form category for organizing the catalog |
83| `tags` | array of strings | Free-form tags for search |
84| `strict` | boolean | Default `true`. Whether `plugin.json` is the definitive source for the plugin's components. See [Strict mode](#strict-mode) |
85| `relevance` | object | Signals that tell Claude Code when to suggest the plugin. See [Recommend plugins for your org](/docs/en/plugins/relevance) |
86| `dependencies` | array | Plugins that must be enabled for this one to work. Each item is `"name"`, `"name@marketplace"`, or an object. See [Plugin dependencies](/docs/en/plugins/dependencies) |
87| `defaultEnabled` | boolean | Default `true`. Whether the plugin starts enabled when the user hasn't set it in [`enabledPlugins`](/docs/en/settings-reference#enabledplugins). The entry value takes precedence over `plugin.json` |
88| `displayName` | string | Human-readable name shown in the UI. When neither the entry nor the plugin's `plugin.json` sets one, users see the plugin's `name` |
89| `metadata` | object | Free-form object for your own fields. Claude Code doesn't read it. Requires Claude Code v2.1.222 or later |
90| `headers` | object | HTTP headers Claude Code sends when it downloads this entry's [archive](#archive-plugin-source). A header set here replaces a header of the same name from the marketplace source's [`headers`](#fields-by-type). Requires Claude Code v2.1.238 or later |
91| `headersHelper` | string | Command that prints this entry's archive-download headers as one JSON object, for a credential that expires. The entry must also set [`"strict": false`](#strict-mode). Requires Claude Code v2.1.238 or later. See [Authenticate archive downloads](/docs/en/plugins/host-marketplace#authenticate-archive-downloads) |
76| Field | Type | Description |
77| :- | :- | :- |
78| `name` | string | Plugin identifier, with no spaces, control characters, or bidirectional-formatting characters. Users type it before `@` when they install, even when the plugin's own `plugin.json` sets a different `name` |
79| `source` | string or object | Where to fetch the plugin. See [Plugin sources](#plugin-sources) |
80| `description` | string | Shown in [`/plugin`](/docs/en/plugins/install) listings and details |
81| `version` | string | Version string for the plugin. When `plugin.json` also sets `version`, `plugin.json` takes precedence and `claude plugin validate` warns. See [Plugin loading reference](/docs/en/plugins/loading) |
82| `category` | string | Free-form category for organizing the catalog |
83| `tags` | array of strings | Free-form tags for search |
84| `strict` | boolean | Default `true`. Whether `plugin.json` is the definitive source for the plugin's components. See [Strict mode](#strict-mode) |
85| `relevance` | object | Signals that tell Claude Code when to suggest the plugin. See [Recommend plugins for your org](/docs/en/plugins/relevance) |
86| `dependencies` | array | Plugins that must be enabled for this one to work. Each item is `"name"`, `"name@marketplace"`, or an object. See [Plugin dependencies](/docs/en/plugins/dependencies) |
87| `defaultEnabled` | boolean | Default `true`. Whether the plugin starts enabled when the user hasn't set it in [`enabledPlugins`](/docs/en/settings-reference#enabledplugins). The entry value takes precedence over `plugin.json` |
88| `displayName` | string | Human-readable name shown in the UI. When neither the entry nor the plugin's `plugin.json` sets one, users see the plugin's `name` |
89| `metadata` | object | Free-form object for your own fields. Claude Code doesn't read it. Requires Claude Code v2.1.222 or later |
90| `headers` | object | HTTP headers Claude Code sends when it downloads this entry's [archive](#archive-plugin-source). A header set here replaces a header of the same name from the marketplace source's [`headers`](#fields-by-type). Requires Claude Code v2.1.238 or later |
91| `headersHelper` | string | Command that prints this entry's archive-download headers as one JSON object, for a credential that expires. The entry must also set [`"strict": false`](#strict-mode). Requires Claude Code v2.1.238 or later. See [Authenticate archive downloads](/docs/en/plugins/host-marketplace#authenticate-archive-downloads) |
9292 
9393<h3 id="entry-and-plugin-json">
9494 How an entry combines with plugin.json
from line 116
116116 
117117`strict` decides what happens when the fetched plugin has its own `plugin.json` and the entry also declares any of the [component fields](#entry-and-plugin-json): `commands`, `agents`, `skills`, `hooks`, `outputStyles`, or `themes`. With `strict: true`, the default, Claude Code appends the entry's component fields to `plugin.json`, except `hooks`, whose matchers replace the manifest's per event. With `strict: false`, an entry that declares any component field is a conflict, and the plugin fails to load. The table shows each combination of `strict`, `plugin.json`, and the entry's component fields.
118118 
119| `strict` | `plugin.json` | Entry component fields | Result |
120| :------------------ | :------------ | :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
121| any | absent | any | The entry is the manifest |
122| `true`, the default | present | any | `plugin.json` is the authority. Claude Code appends the entry's component fields to it, except `hooks`, whose matchers [replace the manifest's per event](/docs/en/plugins/manifest-reference#how-entry-fields-combine-with-plugin-json) |
123| `false` | present | none | `plugin.json` is the manifest, as with `true` |
124| `false` | present | one or more | Conflict. The plugin fails to load with `Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components` |
119| `strict` | `plugin.json` | Entry component fields | Result |
120| :- | :- | :- | :- |
121| any | absent | any | The entry is the manifest |
122| `true`, the default | present | any | `plugin.json` is the authority. Claude Code appends the entry's component fields to it, except `hooks`, whose matchers [replace the manifest's per event](/docs/en/plugins/manifest-reference#how-entry-fields-combine-with-plugin-json) |
123| `false` | present | none | `plugin.json` is the manifest, as with `true` |
124| `false` | present | one or more | Conflict. The plugin fails to load with `Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components` |
125125 
126126## Plugin sources
127127 
from line 129
129129 
130130The table lists each plugin source type and its fields.
131131 
132| Type | Fields | Notes |
133| :------------ | :------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
134| Relative path | the string itself | A directory inside the marketplace, resolved from the marketplace root. Must start with `./`, unless you write a [bare name under `metadata.pluginRoot`](#relative-path-plugin-source). `"."` on its own means the root itself |
135| `github` | `repo`, `ref`, `sha` | GitHub repository in `owner/repo` form |
136| `url` | `url`, `ref`, `sha` | Any git repository by URL |
137| `git-subdir` | `url`, `path`, `ref`, `sha` | One subdirectory of a git repository, fetched with a sparse partial clone |
138| `npm` | `package`, `version`, `registry` | npm package, fetched with your npm client and unpacked without running install scripts |
139| `archive` | `url`, `sha256` | Zip archive over HTTPS. Requires Claude Code v2.1.224 or later |
140| `command` | `command`, `timeout`, `mode` | Directory printed by a command Claude Code runs on the user's machine. Requires Claude Code v2.1.229 or later |
132| Type | Fields | Notes |
133| :- | :- | :- |
134| Relative path | the string itself | A directory inside the marketplace, resolved from the marketplace root. Must start with `./`, unless you write a [bare name under `metadata.pluginRoot`](#relative-path-plugin-source). `"."` on its own means the root itself |
135| `github` | `repo`, `ref`, `sha` | GitHub repository in `owner/repo` form |
136| `url` | `url`, `ref`, `sha` | Any git repository by URL |
137| `git-subdir` | `url`, `path`, `ref`, `sha` | One subdirectory of a git repository, fetched with a sparse partial clone |
138| `npm` | `package`, `version`, `registry` | npm package, fetched with your npm client and unpacked without running install scripts |
139| `archive` | `url`, `sha256` | Zip archive over HTTPS. Requires Claude Code v2.1.224 or later |
140| `command` | `command`, `timeout`, `mode` | Directory printed by a command Claude Code runs on the user's machine. Requires Claude Code v2.1.229 or later |
141141 
142142The names `url` and `github` are also [marketplace source](#marketplace-sources) types, where `url` means a direct link to a `marketplace.json` file rather than a git repository. `git` exists only as a marketplace source, and `npm` exists as both. `git-subdir`, `archive`, and `command` exist only as plugin sources.
143143 
from line 329
329329 
330330The type names `url`, `git`, and `github` mean something different in a marketplace source than in a [plugin source](#plugin-sources):
331331 
332| Type name | As a marketplace source | As a plugin source |
333| :-------- | :-------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- |
334| `url` | A direct link to a `marketplace.json` file, with fields `url`, `headers`, and `headersHelper` | A git repository to clone, with fields `url`, `ref`, and `sha` |
335| `git` | A git repository to clone, with fields `url`, `ref`, `path`, and `sparsePaths` | Doesn't exist |
336| `github` | A GitHub repository, with fields `repo`, `ref`, `path`, and `sparsePaths` | A GitHub repository, with fields `repo`, `ref`, and `sha`, and no `path` |
332| Type name | As a marketplace source | As a plugin source |
333| :- | :- | :- |
334| `url` | A direct link to a `marketplace.json` file, with fields `url`, `headers`, and `headersHelper` | A git repository to clone, with fields `url`, `ref`, and `sha` |
335| `git` | A git repository to clone, with fields `url`, `ref`, `path`, and `sparsePaths` | Doesn't exist |
336| `github` | A GitHub repository, with fields `repo`, `ref`, `path`, and `sparsePaths` | A GitHub repository, with fields `repo`, `ref`, and `sha`, and no `path` |
337337 
338338The table lists every marketplace source type with its fields, the `claude plugin marketplace add` input that produces it, and what it does in each of the three settings keys.
339339 
340| Type | Fields | `marketplace add` input | `extraKnownMarketplaces` | `strictKnownMarketplaces` | `blockedMarketplaces` |
341| :------------ | :----------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
342| `url` | `url`, `headers`, `headersHelper` | An `http://` or `https://` URL that doesn't match a git form | Loads | Allows the same URL | Blocks the same URL |
343| `github` | `repo`, `ref`, `path`, `sparsePaths` | `owner/repo`, `owner/repo@ref`, or `owner/repo#ref` | Loads | Allows the same `repo`, `ref`, and `path`. `repo` may be `owner/*` | Blocks the same, and a `git` URL to the same repository |
344| `git` | `url`, `ref`, `path`, `sparsePaths` | A `user@host:path` URL, or an `https://` URL that ends in `.git`, contains `/_git/`, or names a github.com or gitlab.com repository. `#ref` pins a ref | Loads | Allows the same URL, `ref`, and `path` | Blocks the same, and other spellings of the same github.com repository |
345| `npm` | `package` | Not produced | Fails to load: `NPM marketplace sources not yet implemented` | Parses but matches nothing, because nothing registers an `npm` marketplace | Parses but matches nothing |
346| `file` | `path` | A path to a `.json` file | Loads | Allows the same path | Blocks the same path |
347| `directory` | `path` | A path to a directory | Loads | Allows the same path | Blocks the same path |
348| `settings` | `name`, `plugins`, `owner` | Not produced | Loads | Allows an entry with the same `name` and identical `plugins` | Blocks the same `name` |
349| `skills-dir` | none | Not produced | Fails to load: `Unsupported marketplace source type` | Keeps [skills-directory plugins](/docs/en/plugins/org#keep-skills-directory-plugins-loading) loading while an allowlist is set. See [Source values valid only in policy lists](#source-values-valid-only-in-policy-lists) | Stops skills-directory plugins from loading |
350| `hostPattern` | `hostPattern` | Not produced | Fails to load: `Unsupported marketplace source type` | Allows `github`, `git`, and `url` sources whose host matches | Blocks those sources |
351| `pathPattern` | `pathPattern` | Not produced | Fails to load: `Unsupported marketplace source type` | Allows `file` and `directory` sources whose `path` matches | Blocks those sources |
340| Type | Fields | `marketplace add` input | `extraKnownMarketplaces` | `strictKnownMarketplaces` | `blockedMarketplaces` |
341| :- | :- | :- | :- | :- | :- |
342| `url` | `url`, `headers`, `headersHelper` | An `http://` or `https://` URL that doesn't match a git form | Loads | Allows the same URL | Blocks the same URL |
343| `github` | `repo`, `ref`, `path`, `sparsePaths` | `owner/repo`, `owner/repo@ref`, or `owner/repo#ref` | Loads | Allows the same `repo`, `ref`, and `path`. `repo` may be `owner/*` | Blocks the same, and a `git` URL to the same repository |
344| `git` | `url`, `ref`, `path`, `sparsePaths` | A `user@host:path` URL, or an `https://` URL that ends in `.git`, contains `/_git/`, or names a github.com or gitlab.com repository. `#ref` pins a ref | Loads | Allows the same URL, `ref`, and `path` | Blocks the same, and other spellings of the same github.com repository |
345| `npm` | `package` | Not produced | Fails to load: `NPM marketplace sources not yet implemented` | Parses but matches nothing, because nothing registers an `npm` marketplace | Parses but matches nothing |
346| `file` | `path` | A path to a `.json` file | Loads | Allows the same path | Blocks the same path |
347| `directory` | `path` | A path to a directory | Loads | Allows the same path | Blocks the same path |
348| `settings` | `name`, `plugins`, `owner` | Not produced | Loads | Allows an entry with the same `name` and identical `plugins` | Blocks the same `name` |
349| `skills-dir` | none | Not produced | Fails to load: `Unsupported marketplace source type` | Keeps [skills-directory plugins](/docs/en/plugins/org#keep-skills-directory-plugins-loading) loading while an allowlist is set. See [Source values valid only in policy lists](#source-values-valid-only-in-policy-lists) | Stops skills-directory plugins from loading |
350| `hostPattern` | `hostPattern` | Not produced | Fails to load: `Unsupported marketplace source type` | Allows `github`, `git`, and `url` sources whose host matches | Blocks those sources |
351| `pathPattern` | `pathPattern` | Not produced | Fails to load: `Unsupported marketplace source type` | Allows `file` and `directory` sources whose `path` matches | Blocks those sources |
352352 
353353### Fields by type
354354 
355355The table lists each marketplace source field that has a default, a constraint, or a meaning specific to its type.
356356 
357| Field | Types | Description |
358| :-------------- | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
359| `url` | `url` | Link to the `marketplace.json` file. Claude Code downloads only that file, so the marketplace's plugins can't use [relative-path sources](#relative-path-plugin-source) |
360| `url` | `git` | The git repository to clone |
361| `headers` | `url` | Map of HTTP headers Claude Code sends with the fetch, for authenticated hosts |
362| `headersHelper` | `url` | Command that prints headers whose values are too short-lived to list in `headers`. Requires Claude Code v2.1.238 or later. See [Authenticate archive downloads](/docs/en/plugins/host-marketplace#authenticate-archive-downloads) |
363| `repo` | `github` | In `marketplace add` and `extraKnownMarketplaces`, `repo` must name one repository. `marketplace add` rejects `owner/*` as not a valid `owner/repo` shorthand; in `extraKnownMarketplaces` Claude Code takes it literally and the clone fails |
364| `ref` | `github`, `git` | Branch or tag. Defaults to the repository's default branch |
365| `path` | `github`, `git` | The marketplace file's path inside the repository. Defaults to `.claude-plugin/marketplace.json` |
366| `path` | `file` | The marketplace file itself. Claude Code reads it in place and takes the directory two levels up as the marketplace root, so keep the file at `<root>/.claude-plugin/marketplace.json` |
367| `path` | `directory` | The marketplace root, the directory that contains `.claude-plugin/marketplace.json` |
368| `sparsePaths` | `github`, `git` | Array of directories for a sparse checkout, such as `[".claude-plugin", "plugins"]`. `claude plugin marketplace add --sparse` sets it |
369| `skipLfs` | `github`, `git` | Accepted and has no effect. See [Keep plugin files out of Git LFS](/docs/en/plugins/host-marketplace#keep-plugin-files-out-of-git-lfs) |
370| `name` | `settings` | Must equal the `extraKnownMarketplaces` key and can't be a [reserved name](#reserved-names) |
371| `plugins` | `settings` | The inline catalog, with no hosted file. Each item takes `name`, `source`, `description`, `version`, `strict`, `headers`, and `headersHelper`. Write each item's `source` as an object type, because a relative path has no repository to resolve against |
357| Field | Types | Description |
358| :- | :- | :- |
359| `url` | `url` | Link to the `marketplace.json` file. Claude Code downloads only that file, so the marketplace's plugins can't use [relative-path sources](#relative-path-plugin-source) |
360| `url` | `git` | The git repository to clone |
361| `headers` | `url` | Map of HTTP headers Claude Code sends with the fetch, for authenticated hosts |
362| `headersHelper` | `url` | Command that prints headers whose values are too short-lived to list in `headers`. Requires Claude Code v2.1.238 or later. See [Authenticate archive downloads](/docs/en/plugins/host-marketplace#authenticate-archive-downloads) |
363| `repo` | `github` | In `marketplace add` and `extraKnownMarketplaces`, `repo` must name one repository. `marketplace add` rejects `owner/*` as not a valid `owner/repo` shorthand; in `extraKnownMarketplaces` Claude Code takes it literally and the clone fails |
364| `ref` | `github`, `git` | Branch or tag. Defaults to the repository's default branch |
365| `path` | `github`, `git` | The marketplace file's path inside the repository. Defaults to `.claude-plugin/marketplace.json` |
366| `path` | `file` | The marketplace file itself. Claude Code reads it in place and takes the directory two levels up as the marketplace root, so keep the file at `<root>/.claude-plugin/marketplace.json` |
367| `path` | `directory` | The marketplace root, the directory that contains `.claude-plugin/marketplace.json` |
368| `sparsePaths` | `github`, `git` | Array of directories for a sparse checkout, such as `[".claude-plugin", "plugins"]`. `claude plugin marketplace add --sparse` sets it |
369| `skipLfs` | `github`, `git` | Accepted and has no effect. See [Keep plugin files out of Git LFS](/docs/en/plugins/host-marketplace#keep-plugin-files-out-of-git-lfs) |
370| `name` | `settings` | Must equal the `extraKnownMarketplaces` key and can't be a [reserved name](#reserved-names) |
371| `plugins` | `settings` | The inline catalog, with no hosted file. Each item takes `name`, `source`, `description`, `version`, `strict`, `headers`, and `headersHelper`. Write each item's `source` as an object type, because a relative path has no repository to resolve against |
372372 
373373### Source values valid only in policy lists
374374 
from line 421
421421 
422422The table maps marketplace-level messages to the field each is about.
423423 
424| Message | Level | Field |
425| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------- |
426| `Marketplace must have a name` | Error | `name` is empty |
427| `Marketplace name cannot contain spaces. Use kebab-case (e.g., "my-marketplace")` | Error | `name` |
428| `Marketplace name cannot contain path separators (/ or \), ".." sequences, or be "."` | Error | `name` |
429| `Marketplace name impersonates an official Anthropic/Claude marketplace` | Error | `name`. See [Reserved names](#reserved-names) |
430| `Marketplace name cannot contain control or bidirectional-formatting characters` | Error | `name` contains a control character, such as an escape or a newline, or a Unicode bidirectional-formatting character |
431| `Marketplace name "inline" is reserved for --plugin-dir session plugins`, and the `builtin`, `skills-dir`, `synced`, `claude-plugin-test`, `npm`, `pip`, `uv`, `cargo`, `github`, and `gh` variants | Error | `name` |
432| `Author name cannot be empty` | Error | `owner.name` |
433| `Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin")` | Error | `plugins[i].name` |
434| `Plugin name cannot contain control or bidirectional-formatting characters` | Error | `plugins[i].name` |
435| `Duplicate plugin name "x" found in marketplace` | Error | Two entries share a `name` |
436| `plugins.i.source: Invalid input` | Error | The entry's `source` matches no type. See [Invalid input on a source](#invalid-input-on-a-source) |
437| `plugins[i].source: Path contains "..": <path>` | Error | A relative `source` that escapes the marketplace root |
438| `source.source: 'unsupported' is a parse-time placeholder and cannot be authored` | Error | `plugins[i].source` |
439| `Plugin "x" sets headersHelper but is not "strict": false` | Error | `plugins[i].headersHelper`, on an `archive` entry |
440| `chain does not resolve (<reason>) — target must be a name in plugins[], a key in renames, or null` | Error | `renames.<old>` |
441| `target "x" is not a valid plugin name (PluginIdSchema)` | Error | `renames.<old>` |
442| `Unknown field 'x'. Claude Code ignores it at load time.` | Warning | The named key at the top level, under `metadata`, in an entry, or under an entry's `relevance` |
443| `Marketplace has no plugins defined` | Warning | `plugins` is empty |
444| `Plugin "x" sets headers/headersHelper, which only apply to "archive" sources; they have no effect on this entry.` | Warning | `plugins[i].headers` or `plugins[i].headersHelper`, on an entry whose `source` isn't `archive` |
445| `Plugin "x" fetches its archive with a headersHelper but sets no sha256 pin` | Warning | `plugins[i].source.sha256` |
446| `Header "x" is a request-routing/identity header that catalog entries may not set; Claude Code drops it at download time.` | Warning | `plugins[i].headers.<name>` |
447| `Local source "x" is or traverses a symlink, so <path> was not read` | Warning | `plugins[i].source` |
448| `No marketplace description provided. Adding a description helps users understand what this marketplace offers` | Warning | `description` |
449| `Entry declares version "x" but <path>/plugin.json says "y". At install time, plugin.json wins` | Warning | `plugins[i].version`, on a relative-path entry |
450| `'relevance' must be an object containing topic and signals; got <type>. It will be ignored at load time.` | Warning | `plugins[i].relevance` |
451| `'metadata' must be a free-form object; got <type>. It will be ignored at load time.` | Warning | `plugins[i].metadata` |
452| `'experimental' must be an object containing component declarations; got <type>. It will be ignored at load time.` | Warning | `plugins[i].experimental` |
453| `Marketplace name "x" is reserved in Claude Desktop` | Warning | `name` is `org`, `org-provisioned`, or `unknown`. Claude Desktop rejects the marketplace |
454| `Marketplace name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars)` | Warning | `name`. Claude Desktop rejects the marketplace |
455| `Plugin name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars)` | Warning | `plugins[i].name`. Claude Desktop drops the entry |
424| Message | Level | Field |
425| :- | :- | :- |
426| `Marketplace must have a name` | Error | `name` is empty |
427| `Marketplace name cannot contain spaces. Use kebab-case (e.g., "my-marketplace")` | Error | `name` |
428| `Marketplace name cannot contain path separators (/ or \), ".." sequences, or be "."` | Error | `name` |
429| `Marketplace name impersonates an official Anthropic/Claude marketplace` | Error | `name`. See [Reserved names](#reserved-names) |
430| `Marketplace name cannot contain control or bidirectional-formatting characters` | Error | `name` contains a control character, such as an escape or a newline, or a Unicode bidirectional-formatting character |
431| `Marketplace name "inline" is reserved for --plugin-dir session plugins`, and the `builtin`, `skills-dir`, `synced`, `claude-plugin-test`, `npm`, `pip`, `uv`, `cargo`, `github`, and `gh` variants | Error | `name` |
432| `Author name cannot be empty` | Error | `owner.name` |
433| `Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin")` | Error | `plugins[i].name` |
434| `Plugin name cannot contain control or bidirectional-formatting characters` | Error | `plugins[i].name` |
435| `Duplicate plugin name "x" found in marketplace` | Error | Two entries share a `name` |
436| `plugins.i.source: Invalid input` | Error | The entry's `source` matches no type. See [Invalid input on a source](#invalid-input-on-a-source) |
437| `plugins[i].source: Path contains "..": <path>` | Error | A relative `source` that escapes the marketplace root |
438| `source.source: 'unsupported' is a parse-time placeholder and cannot be authored` | Error | `plugins[i].source` |
439| `Plugin "x" sets headersHelper but is not "strict": false` | Error | `plugins[i].headersHelper`, on an `archive` entry |
440| `chain does not resolve (<reason>) — target must be a name in plugins[], a key in renames, or null` | Error | `renames.<old>` |
441| `target "x" is not a valid plugin name (PluginIdSchema)` | Error | `renames.<old>` |
442| `Unknown field 'x'. Claude Code ignores it at load time.` | Warning | The named key at the top level, under `metadata`, in an entry, or under an entry's `relevance` |
443| `Marketplace has no plugins defined` | Warning | `plugins` is empty |
444| `Plugin "x" sets headers/headersHelper, which only apply to "archive" sources; they have no effect on this entry.` | Warning | `plugins[i].headers` or `plugins[i].headersHelper`, on an entry whose `source` isn't `archive` |
445| `Plugin "x" fetches its archive with a headersHelper but sets no sha256 pin` | Warning | `plugins[i].source.sha256` |
446| `Header "x" is a request-routing/identity header that catalog entries may not set; Claude Code drops it at download time.` | Warning | `plugins[i].headers.<name>` |
447| `Local source "x" is or traverses a symlink, so <path> was not read` | Warning | `plugins[i].source` |
448| `No marketplace description provided. Adding a description helps users understand what this marketplace offers` | Warning | `description` |
449| `Entry declares version "x" but <path>/plugin.json says "y". At install time, plugin.json wins` | Warning | `plugins[i].version`, on a relative-path entry |
450| `'relevance' must be an object containing topic and signals; got <type>. It will be ignored at load time.` | Warning | `plugins[i].relevance` |
451| `'metadata' must be a free-form object; got <type>. It will be ignored at load time.` | Warning | `plugins[i].metadata` |
452| `'experimental' must be an object containing component declarations; got <type>. It will be ignored at load time.` | Warning | `plugins[i].experimental` |
453| `Marketplace name "x" is reserved in Claude Desktop` | Warning | `name` is `org`, `org-provisioned`, or `unknown`. Claude Desktop rejects the marketplace |
454| `Marketplace name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars)` | Warning | `name`. Claude Desktop rejects the marketplace |
455| `Plugin name "x" is not accepted by Claude Desktop (letters, digits, ".", "_", "-"; must start alphanumeric; max 128 chars)` | Warning | `plugins[i].name`. Claude Desktop drops the entry |
456456 
457457### Invalid input on a source
458458 

plugins/measure Changed · +12 / -12 lines

from line 127
127127 
128128These OpenTelemetry events and attributes answer each plugin question from your backend:
129129 
130| Question | OpenTelemetry event or attribute |
131| :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
132| Which plugins get installed, and from where | [`claude_code.plugin_installed`](/docs/en/monitoring-usage#plugin-installed-event), one per install |
133| Which plugins are active in how many sessions | [`claude_code.plugin_loaded`](/docs/en/monitoring-usage#plugin-loaded-event), one per enabled plugin at session start |
134| Which skills activate, and which plugin owns them | [`claude_code.skill_activated`](/docs/en/monitoring-usage#skill-activated-event), with `plugin.name` and `marketplace.name` for plugin skills |
135| What a plugin's hooks report | [`claude_code.hook_plugin_metrics`](/docs/en/monitoring-usage#hook-plugin-metrics-event), emitted only for hooks in official-marketplace plugins |
136| What a plugin costs in API spend | `plugin.name` and `marketplace.name` on the [cost counter](/docs/en/monitoring-usage#cost-counter), set when the active skill or subagent belongs to a plugin |
130| Question | OpenTelemetry event or attribute |
131| :- | :- |
132| Which plugins get installed, and from where | [`claude_code.plugin_installed`](/docs/en/monitoring-usage#plugin-installed-event), one per install |
133| Which plugins are active in how many sessions | [`claude_code.plugin_loaded`](/docs/en/monitoring-usage#plugin-loaded-event), one per enabled plugin at session start |
134| Which skills activate, and which plugin owns them | [`claude_code.skill_activated`](/docs/en/monitoring-usage#skill-activated-event), with `plugin.name` and `marketplace.name` for plugin skills |
135| What a plugin's hooks report | [`claude_code.hook_plugin_metrics`](/docs/en/monitoring-usage#hook-plugin-metrics-event), emitted only for hooks in official-marketplace plugins |
136| What a plugin costs in API spend | `plugin.name` and `marketplace.name` on the [cost counter](/docs/en/monitoring-usage#cost-counter), set when the active skill or subagent belongs to a plugin |
137137 
138138### Redacted plugin names in your backend
139139 
from line 141
141141 
142142To get real names on some events, set the [`OTEL_LOG_TOOL_DETAILS`](/docs/en/monitoring-usage#common-configuration-variables) environment variable to `1` on the machines that export telemetry, for example in the `env` block of the same [managed settings](/docs/en/monitoring-usage#administrator-configuration) that configure the exporter:
143143 
144| Event | Default | With `OTEL_LOG_TOOL_DETAILS=1` |
145| :------------------------------------ | :------------------------------------------------------------------------------------------------- | :-------------------------------------------------- |
146| `plugin_loaded` | `plugin.name` and `marketplace.name` are the literal string `third-party` | Real names |
147| `plugin_installed`, `skill_activated` | `plugin.name` and `marketplace.name` omitted; on `skill_activated`, `skill.name` is `custom_skill` | Real names |
148| Cost counter | `plugin.name` is `third-party`; `marketplace.name` absent | Real `plugin.name`; `marketplace.name` still absent |
144| Event | Default | With `OTEL_LOG_TOOL_DETAILS=1` |
145| :- | :- | :- |
146| `plugin_loaded` | `plugin.name` and `marketplace.name` are the literal string `third-party` | Real names |
147| `plugin_installed`, `skill_activated` | `plugin.name` and `marketplace.name` omitted; on `skill_activated`, `skill.name` is `custom_skill` | Real names |
148| Cost counter | `plugin.name` is `third-party`; `marketplace.name` absent | Real `plugin.name`; `marketplace.name` still absent |
149149 
150150On `plugin_loaded`, `plugin_id_hash` still identifies each plugin by default, so you can count distinct third-party plugins.
151151 

plugins/org Changed · +19 / -19 lines

from line 95
9595 
9696The table shows when each kind of Claude Code session applies `extraKnownMarketplaces` and `enabledPlugins`, from managed settings and from a repository's `.claude/settings.json`. For the Desktop app and the IDE extensions, see [Install a plugin](/docs/en/plugins/install#install-a-plugin).
9797 
98| Surface | Managed `extraKnownMarketplaces` and `enabledPlugins` | Repository `.claude/settings.json` |
99| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- |
100| Terminal, interactive | Applied at session start on every machine that receives the settings | `extraKnownMarketplaces` applied after trust; `enabledPlugins` applied at session start |
101| `-p` and CI | Applied at session start, with installs running in the background | `extraKnownMarketplaces` in trusted folders only; `enabledPlugins` applied |
102| Cloud sessions | In an Anthropic-hosted environment, only server-managed settings reach the session, which waits for them before it installs plugins. MDM policies and managed settings files stay on the user's machine. For a self-hosted environment, see [Where and when a policy applies](/docs/en/managed-settings#where-and-when-a-policy-applies) | See the **Cloud session** tab under [Install a plugin](/docs/en/plugins/install#install-a-plugin) |
98| Surface | Managed `extraKnownMarketplaces` and `enabledPlugins` | Repository `.claude/settings.json` |
99| :- | :- | :- |
100| Terminal, interactive | Applied at session start on every machine that receives the settings | `extraKnownMarketplaces` applied after trust; `enabledPlugins` applied at session start |
101| `-p` and CI | Applied at session start, with installs running in the background | `extraKnownMarketplaces` in trusted folders only; `enabledPlugins` applied |
102| Cloud sessions | In an Anthropic-hosted environment, only server-managed settings reach the session, which waits for them before it installs plugins. MDM policies and managed settings files stay on the user's machine. For a self-hosted environment, see [Where and when a policy applies](/docs/en/managed-settings#where-and-when-a-policy-applies) | See the **Cloud session** tab under [Install a plugin](/docs/en/plugins/install#install-a-plugin) |
103103 
104104In a `-p` or CI run, marketplaces and plugins install in the background, so a plugin can be missing from the first turn. Set `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` to make the run wait for the install before its first query.
105105 
from line 174
174174 
175175The table lists each plugin policy key, what it enforces, and what it can't do.
176176 
177| Key | What it enforces | What it can't do |
178| :----------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
179| `strictKnownMarketplaces` | Allowlist of marketplace sources. `[]` blocks every source, including the official marketplace. Alias: `allowedMarketplaces` | Doesn't register a marketplace, restrict entries inside an allowed marketplace, or block `--plugin-dir` |
180| `blockedMarketplaces` | Blocklist of marketplace sources, checked before the allowlist | Doesn't block a marketplace already registered from a source it doesn't match |
181| `syncClaudeAiPlugins` | Set `false` to stop Claude Code downloading and loading the plugins [synced from claude.ai](/docs/en/plugins/loading#synced-plugins) for each user's account. Requires Claude Code v2.1.273 or later | Doesn't turn off one synced plugin. For that, set `"<name>@synced": false` in [`enabledPlugins`](/docs/en/settings-reference#enabledplugins) |
182| `enabledPlugins` | `true` force-enables, `false` blocks at every scope and hides the plugin | Doesn't install a plugin whose marketplace isn't registered or allowed |
183| `disableSideloadFlags` | Rejects `--plugin-dir`, `--plugin-url`, `--agents`, the Agent SDK `plugins` option, and non-SDK `--mcp-config` at startup, and rejects folders named in the [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/en/env-vars#variables) variable the same way | Doesn't restrict `.mcp.json`, `claude mcp add`, or SDK-provided servers. Pair it with [`allowedMcpServers`](/docs/en/managed-mcp) |
184| `disableCommandPluginSources` | Blocks plugins with a `command` source from installing, updating, or loading. A `command` source is one whose plugin directory is produced by running a command on the machine. When unset, it takes the value of `allowManagedHooksOnly` | Doesn't affect other source types |
185| `allowManagedHooksOnly` | Restricts which hooks run. See [`allowManagedHooksOnly`](/docs/en/settings-reference#allowmanagedhooksonly) | Doesn't trust hooks from plugins users enable themselves |
186| `strictPluginOnlyCustomization` | Blocks skills, agents, hooks, and MCP servers that don't come from a plugin, managed settings, or Claude Code's built-ins. Set `true` to cover all four types, or an array of `skills`, `agents`, `hooks`, and `mcp` values such as `["skills", "hooks"]` to cover some | Doesn't restrict which plugins users install. Pair it with `strictKnownMarketplaces` |
187| `pluginSuggestionMarketplaces` | Marketplaces whose plugins may appear as install suggestions. See [Recommend plugins](#recommend-plugins) | Doesn't affect the built-in tips |
188| `pluginTrustMessage` | Appends your text to the trust warning that `/plugin` shows before a plugin installs | Doesn't change the warning's own text |
189| `allowedChannelPlugins` | Replaces the default list of plugins allowed to push channel messages. Requires `channelsEnabled: true` | See [Restrict which channel plugins can run](/docs/en/channels#restrict-which-channel-plugins-can-run) |
190| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/en/env-vars) | Stops interactive terminal sessions from auto-registering the official marketplace | Doesn't remove a marketplace already registered. The allowlist and blocklist gate the same auto-registration without it. A machine that started once with it set doesn't resume auto-registration after you unset it |
177| Key | What it enforces | What it can't do |
178| :- | :- | :- |
179| `strictKnownMarketplaces` | Allowlist of marketplace sources. `[]` blocks every source, including the official marketplace. Alias: `allowedMarketplaces` | Doesn't register a marketplace, restrict entries inside an allowed marketplace, or block `--plugin-dir` |
180| `blockedMarketplaces` | Blocklist of marketplace sources, checked before the allowlist | Doesn't block a marketplace already registered from a source it doesn't match |
181| `syncClaudeAiPlugins` | Set `false` to stop Claude Code downloading and loading the plugins [synced from claude.ai](/docs/en/plugins/loading#synced-plugins) for each user's account. Requires Claude Code v2.1.273 or later | Doesn't turn off one synced plugin. For that, set `"<name>@synced": false` in [`enabledPlugins`](/docs/en/settings-reference#enabledplugins) |
182| `enabledPlugins` | `true` force-enables, `false` blocks at every scope and hides the plugin | Doesn't install a plugin whose marketplace isn't registered or allowed |
183| `disableSideloadFlags` | Rejects `--plugin-dir`, `--plugin-url`, `--agents`, the Agent SDK `plugins` option, and non-SDK `--mcp-config` at startup, and rejects folders named in the [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/en/env-vars#variables) variable the same way | Doesn't restrict `.mcp.json`, `claude mcp add`, or SDK-provided servers. Pair it with [`allowedMcpServers`](/docs/en/managed-mcp) |
184| `disableCommandPluginSources` | Blocks plugins with a `command` source from installing, updating, or loading. A `command` source is one whose plugin directory is produced by running a command on the machine. When unset, it takes the value of `allowManagedHooksOnly` | Doesn't affect other source types |
185| `allowManagedHooksOnly` | Restricts which hooks run. See [`allowManagedHooksOnly`](/docs/en/settings-reference#allowmanagedhooksonly) | Doesn't trust hooks from plugins users enable themselves |
186| `strictPluginOnlyCustomization` | Blocks skills, agents, hooks, and MCP servers that don't come from a plugin, managed settings, or Claude Code's built-ins. Set `true` to cover all four types, or an array of `skills`, `agents`, `hooks`, and `mcp` values such as `["skills", "hooks"]` to cover some | Doesn't restrict which plugins users install. Pair it with `strictKnownMarketplaces` |
187| `pluginSuggestionMarketplaces` | Marketplaces whose plugins may appear as install suggestions. See [Recommend plugins](#recommend-plugins) | Doesn't affect the built-in tips |
188| `pluginTrustMessage` | Appends your text to the trust warning that `/plugin` shows before a plugin installs | Doesn't change the warning's own text |
189| `allowedChannelPlugins` | Replaces the default list of plugins allowed to push channel messages. Requires `channelsEnabled: true` | See [Restrict which channel plugins can run](/docs/en/channels#restrict-which-channel-plugins-can-run) |
190| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/en/env-vars) | Stops interactive terminal sessions from auto-registering the official marketplace | Doesn't remove a marketplace already registered. The allowlist and blocklist gate the same auto-registration without it. A machine that started once with it set doesn't resume auto-registration after you unset it |
191191 
192192Every key in the table is a managed setting, apart from `enabledPlugins`, `syncClaudeAiPlugins`, and `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`:
193193 

plugins/publish Changed · +5 / -5 lines

from line 19
1919 
2020Choose a distribution option based on who needs to install the plugin:
2121 
22| Route | Who can install | What you need | Do users get your updates automatically? |
23| :------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------- |
24| [No marketplace](#share-a-plugin-without-a-marketplace) | The people you send the plugin folder or a `.zip` of it | The plugin's folder | None. They load the copy you sent |
25| [Your own marketplace](#publish-through-your-own-marketplace) | Anyone who can reach the repository, which can be a private one your team can clone | A git repository or other host with a `.claude-plugin/marketplace.json` that lists your plugin | Off |
26| [Anthropic's directory](#submit-to-anthropics-directory) | People who add it on claude.ai or in Cowork. It also loads in their Claude Code sessions through [account sync](/docs/en/plugins/loading#synced-plugins) | A GitHub repository holding the plugin and a paid claude.ai plan to submit from | Yes, after the version you push is published |
22| Route | Who can install | What you need | Do users get your updates automatically? |
23| :- | :- | :- | :- |
24| [No marketplace](#share-a-plugin-without-a-marketplace) | The people you send the plugin folder or a `.zip` of it | The plugin's folder | None. They load the copy you sent |
25| [Your own marketplace](#publish-through-your-own-marketplace) | Anyone who can reach the repository, which can be a private one your team can clone | A git repository or other host with a `.claude-plugin/marketplace.json` that lists your plugin | Off |
26| [Anthropic's directory](#submit-to-anthropics-directory) | People who add it on claude.ai or in Cowork. It also loads in their Claude Code sessions through [account sync](/docs/en/plugins/loading#synced-plugins) | A GitHub repository holding the plugin and a paid claude.ai plan to submit from | Yes, after the version you push is published |
2727 
2828Auto-update is a per-marketplace setting on the user's side that fetches new versions in the background.
2929 

plugins/relevance Changed · +9 / -9 lines

from line 73
7373 
7474### `relevance`
7575 
76| Field | Type | Description |
77| :-------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78| `topic` | string | Optional. The phrase that fills "Working with *topic*?" in the spinner tip. Defaults to the plugin name with each hyphen segment capitalized. Maximum 64 characters. |
76| Field | Type | Description |
77| :- | :- | :- |
78| `topic` | string | Optional. The phrase that fills "Working with *topic*?" in the spinner tip. Defaults to the plugin name with each hyphen segment capitalized. Maximum 64 characters. |
7979| `signals` | object | Matchers that determine when the plugin is relevant. Claude Code suggests the plugin only if at least one signal is set. See [`relevance.signals`](#relevance-signals). |
8080 
8181The `topic` is often the product name, for example `Terraform`. Use a domain such as `design` when the plugin name doesn't sound natural as a topic.
from line 84
8484 
8585The `signals` object accepts the following fields.
8686 
87| Field | Type | Description | Limit |
88| :------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------- |
89| `cwd` | array of strings | Glob patterns matched against the session's working directory. See [working directory matching](#working-directory-matching). | 10 patterns of 256 characters each |
90| `cli` | array of strings | Command names from shell commands Claude has run this session, for example `["terraform"]`. Exact match. See [command name matching](#command-name-matching). | 10 entries of 64 characters each |
91| `hosts` | array of strings | Hostnames seen in `http://` or `https://` URLs in Bash commands this session, for example `["registry.terraform.io"]`. Bare lowercase hostname only: no scheme, port, or path. Exact case-insensitive match. | 20 entries of 128 characters each |
92| `filesRead` | array of strings | Glob patterns matched against the paths of files Claude has read this session, for example `["**/*.tf"]`. Forward-slash normalized and case-insensitive. | 10 patterns of 256 characters each |
87| Field | Type | Description | Limit |
88| :- | :- | :- | :- |
89| `cwd` | array of strings | Glob patterns matched against the session's working directory. See [working directory matching](#working-directory-matching). | 10 patterns of 256 characters each |
90| `cli` | array of strings | Command names from shell commands Claude has run this session, for example `["terraform"]`. Exact match. See [command name matching](#command-name-matching). | 10 entries of 64 characters each |
91| `hosts` | array of strings | Hostnames seen in `http://` or `https://` URLs in Bash commands this session, for example `["registry.terraform.io"]`. Bare lowercase hostname only: no scheme, port, or path. Exact case-insensitive match. | 20 entries of 128 characters each |
92| `filesRead` | array of strings | Glob patterns matched against the paths of files Claude has read this session, for example `["**/*.tf"]`. Forward-slash normalized and case-insensitive. | 10 patterns of 256 characters each |
9393| `manifestDeps` | array of objects | Dependencies declared in package manifests Claude has read this session. Each entry is `{ "file": "...", "pattern": "..." }`, where both values are regular expressions. See [manifest dependency matching](#manifest-dependency-matching). | 10 entries, each value at most 256 characters. Manifest files larger than 512 KB are skipped |
9494 
9595The `filesRead` and `manifestDeps` signals also match against files Claude has written or edited this session and against the project's auto-loaded `CLAUDE.md` memory files.

plugins/security Changed · +5 / -5 lines

from line 45
4545 
4646The table lists which names fall in each tier:
4747 
48| Tier | Which marketplaces |
49| :---------- | :----------------------------------------------------------------------------------------------- |
50| Official | The [official marketplace names](#official-marketplace-names), such as `claude-plugins-official` |
51| Community | `claude-community`, `claude-plugins-community`, and `healthcare` |
52| Third-party | Every other marketplace |
48| Tier | Which marketplaces |
49| :- | :- |
50| Official | The [official marketplace names](#official-marketplace-names), such as `claude-plugins-official` |
51| Community | `claude-community`, `claude-plugins-community`, and `healthcare` |
52| Third-party | Every other marketplace |
5353 
5454Where the `claude-community` catalog pins a plugin to a commit SHA, which it does for nearly every entry, Claude Code refuses to install a different commit.
5555 

plugins/troubleshooting Changed · +38 / -38 lines

from line 89
8989 
9090Several command spellings are in use that Claude Code doesn't have. The table below maps each one to the real command. The [plugin commands reference](/docs/en/plugins/cli-reference) lists every subcommand and flag.
9191 
92| You typed | What Claude Code says | Use instead |
93| :----------------------------------------- | :--------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
94| `claude plugin add <source>` | `error: unknown command 'add'` | `claude plugin marketplace add <source>` to add a marketplace, or `claude plugin install <plugin>@<marketplace>` to install a plugin |
95| `claude plugin install <plugin> --project` | `error: unknown option '--project'` | `claude plugin install <plugin>@<marketplace> --scope project` |
96| `/install <plugin>` | `Unknown command: /install` | `/plugin install <plugin>@<marketplace>` |
97| `/plugin add <source>` | The `/plugin` panel opens on the **Discover** tab | `/plugin marketplace add <source>` |
98| `marketplace.anthropic.com` as a source | `Invalid marketplace source format. Try: owner/repo, https://..., or ./path` | `anthropics/claude-plugins-official` for the official marketplace |
92| You typed | What Claude Code says | Use instead |
93| :- | :- | :- |
94| `claude plugin add <source>` | `error: unknown command 'add'` | `claude plugin marketplace add <source>` to add a marketplace, or `claude plugin install <plugin>@<marketplace>` to install a plugin |
95| `claude plugin install <plugin> --project` | `error: unknown option '--project'` | `claude plugin install <plugin>@<marketplace> --scope project` |
96| `/install <plugin>` | `Unknown command: /install` | `/plugin install <plugin>@<marketplace>` |
97| `/plugin add <source>` | The `/plugin` panel opens on the **Discover** tab | `/plugin marketplace add <source>` |
98| `marketplace.anthropic.com` as a source | `Invalid marketplace source format. Try: owner/repo, https://..., or ./path` | `anthropics/claude-plugins-official` for the official marketplace |
9999 
100100These spellings look wrong but work:
101101 
from line 558
558558 
559559The table lists each message and its fix. To declare dependencies as an author, see [Plugin dependencies](/docs/en/plugins/dependencies).
560560 
561| Message | Meaning | How to resolve |
562| :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
563| `Dependency "<dep>" is not installed` | A declared dependency isn't installed. | Install it in your shell with `claude plugin install <dep>@<marketplace>`, or uninstall the plugin. If the dependency's marketplace isn't registered yet, add it and run `/reload-plugins` in your session, which installs the missing dependencies it can resolve. |
564| `Dependency "<dep>" is disabled` | The dependency is installed but turned off. | Enable the dependency, or uninstall the plugin that needs it. |
565| `Requires "<dep>" <range>, installed <version>` | The installed dependency's version is outside the plugin's declared range. | Update the dependency to a version in the range, or uninstall the plugin. |
566| `<Plugin or Dependency> "<name>" has conflicting version requirements` | No version satisfies every range that pins it. The message lists the ranges. | Uninstall or update one of the conflicting plugins, or ask the upstream author to widen its constraint. |
567| `... has version requirements too complex to intersect` or `has an invalid version requirement` | A range isn't valid semver, or the combined ranges can't be intersected. | Fix the invalid range or simplify long `\|\|` chains. |
568| `... has no git tag satisfying <range>` | The dependency's repository has no `<name>--v*` tag in the range. | Check that the upstream tags releases with that convention, or relax the range. |
569| `Dependency "<dep>" (required by <plugin>) is in <marketplace>, which is not in the allowlist` | The dependency is in a different marketplace, and cross-marketplace resolution is off by default. | Install the dependency yourself at the same scope, in your shell with `claude plugin install <dep>@<marketplace>` plus the `--scope` you're installing the plugin at, then retry. |
561| Message | Meaning | How to resolve |
562| :- | :- | :- |
563| `Dependency "<dep>" is not installed` | A declared dependency isn't installed. | Install it in your shell with `claude plugin install <dep>@<marketplace>`, or uninstall the plugin. If the dependency's marketplace isn't registered yet, add it and run `/reload-plugins` in your session, which installs the missing dependencies it can resolve. |
564| `Dependency "<dep>" is disabled` | The dependency is installed but turned off. | Enable the dependency, or uninstall the plugin that needs it. |
565| `Requires "<dep>" <range>, installed <version>` | The installed dependency's version is outside the plugin's declared range. | Update the dependency to a version in the range, or uninstall the plugin. |
566| `<Plugin or Dependency> "<name>" has conflicting version requirements` | No version satisfies every range that pins it. The message lists the ranges. | Uninstall or update one of the conflicting plugins, or ask the upstream author to widen its constraint. |
567| `... has version requirements too complex to intersect` or `has an invalid version requirement` | A range isn't valid semver, or the combined ranges can't be intersected. | Fix the invalid range or simplify long `\|\|` chains. |
568| `... has no git tag satisfying <range>` | The dependency's repository has no `<name>--v*` tag in the range. | Check that the upstream tags releases with that convention, or relax the range. |
569| `Dependency "<dep>" (required by <plugin>) is in <marketplace>, which is not in the allowlist` | The dependency is in a different marketplace, and cross-marketplace resolution is off by default. | Install the dependency yourself at the same scope, in your shell with `claude plugin install <dep>@<marketplace>` plus the `--scope` you're installing the plugin at, then retry. |
570570 
571571To see these programmatically, run `claude plugin list --json` in your shell. Plugins with problems carry an `errors` field with the messages and an `errorDetails` field with a `type` for each: the first two rows are `dependency-unsatisfied` and the third is `dependency-version-unsatisfied`.
572572 
from line 880
880880 
881881The table covers the messages that stop validation and two warnings, `No frontmatter block found` and `Unknown field '<key>'`, which stop it only when you pass `--strict`. Other warnings, such as a missing description, aren't listed.
882882 
883| Message | Cause | Fix |
884| :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
885| `File not found: <path>` | The path has no manifest, or doesn't exist. | Run the command against the plugin or marketplace root, the directory that contains `.claude-plugin/`. |
886| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | The directory has no `.claude-plugin/` manifest. | Create the manifest, or point at the right directory. |
887| `Invalid JSON syntax: <parse error>` | The manifest, or `hooks/hooks.json`, isn't valid JSON. | Fix the JSON. Until you fix `hooks/hooks.json`, a session loads the plugin without the hooks in that file. |
888| `Path not found: <path>. The runtime loader will report this as a load failure.` | A component path in the manifest doesn't exist. | Fix the path or create the directory. |
889| `Path contains ".." which could be a path traversal attempt: <path>` | A component path escapes the plugin directory. | Use paths inside the plugin root. |
890| `Path is a file; skills entries must be directories containing SKILL.md` | A `skills` entry points at `SKILL.md` instead of its directory. | Point at the parent directory, or `.` for a root-level `SKILL.md`. |
891| `No frontmatter block found` or `YAML frontmatter failed to parse: <error>` | A skill, agent, or command file has missing or invalid YAML frontmatter. | Add or fix the frontmatter between `---` delimiters. Reported when validating a plugin directory. |
892| `Unknown field '<key>'` | The manifest has a field the schema doesn't define. | Remove it, or use the name the message suggests. Claude Code ignores unknown fields at load time. |
883| Message | Cause | Fix |
884| :- | :- | :- |
885| `File not found: <path>` | The path has no manifest, or doesn't exist. | Run the command against the plugin or marketplace root, the directory that contains `.claude-plugin/`. |
886| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | The directory has no `.claude-plugin/` manifest. | Create the manifest, or point at the right directory. |
887| `Invalid JSON syntax: <parse error>` | The manifest, or `hooks/hooks.json`, isn't valid JSON. | Fix the JSON. Until you fix `hooks/hooks.json`, a session loads the plugin without the hooks in that file. |
888| `Path not found: <path>. The runtime loader will report this as a load failure.` | A component path in the manifest doesn't exist. | Fix the path or create the directory. |
889| `Path contains ".." which could be a path traversal attempt: <path>` | A component path escapes the plugin directory. | Use paths inside the plugin root. |
890| `Path is a file; skills entries must be directories containing SKILL.md` | A `skills` entry points at `SKILL.md` instead of its directory. | Point at the parent directory, or `.` for a root-level `SKILL.md`. |
891| `No frontmatter block found` or `YAML frontmatter failed to parse: <error>` | A skill, agent, or command file has missing or invalid YAML frontmatter. | Add or fix the frontmatter between `---` delimiters. Reported when validating a plugin directory. |
892| `Unknown field '<key>'` | The manifest has a field the schema doesn't define. | Remove it, or use the name the message suggests. Claude Code ignores unknown fields at load time. |
893893 
894894Run the command again after each fix until it prints no errors.
895895 
from line 939
939939 
940940The table lists the marketplace-level messages. Entry-level messages are the plugin messages under [`claude plugin validate` reports errors](#claude-plugin-validate-reports-errors), prefixed with `plugins[N] plugin.json →`.
941941 
942| Message | Kind | Fix |
943| :------------------------------------------------------------------------------------------------------------------------ | :------ | :---------------------------------------------------------------------------------------------------------------------------------- |
944| `Duplicate plugin name "<name>" found in marketplace` | Error | Give each plugin a unique `name`. |
945| `Path contains "..": <path>` under `plugins[N].source` | Error | Use paths relative to the marketplace root without `..` segments. |
946| `Marketplace name cannot contain control or bidirectional-formatting characters` | Error | Remove the character from the name, such as an escape or a newline. |
947| `Plugin name cannot contain control or bidirectional-formatting characters` | Error | Remove the character from the plugin `name`. |
948| `Marketplace has no plugins defined` | Warning | Add at least one entry to `plugins`. |
949| `No marketplace description provided` | Warning | Add a top-level `description`. |
950| `Plugin name "<name>" is not kebab-case` under `plugins[N] plugin.json → name` | Warning | Rename to lowercase letters, digits, and hyphens. Claude Code accepts other forms, but the claude.ai marketplace sync rejects them. |
951| `Entry declares version "<a>" but <path>/plugin.json says "<b>"` | Warning | Update the entry to match `plugin.json`, which is authoritative at install time. |
952| `Marketplace name "<name>" is reserved in Claude Desktop` | Warning | Rename the marketplace. Claude Desktop's managed marketplace sync rejects `org`, `org-provisioned`, and `unknown` in any casing. |
953| `Marketplace name "<name>" is not accepted by Claude Desktop` or `Plugin name "<name>" is not accepted by Claude Desktop` | Warning | Rename to at most 128 characters of letters, digits, `.`, `_`, and `-`, starting with a letter or digit. |
942| Message | Kind | Fix |
943| :- | :- | :- |
944| `Duplicate plugin name "<name>" found in marketplace` | Error | Give each plugin a unique `name`. |
945| `Path contains "..": <path>` under `plugins[N].source` | Error | Use paths relative to the marketplace root without `..` segments. |
946| `Marketplace name cannot contain control or bidirectional-formatting characters` | Error | Remove the character from the name, such as an escape or a newline. |
947| `Plugin name cannot contain control or bidirectional-formatting characters` | Error | Remove the character from the plugin `name`. |
948| `Marketplace has no plugins defined` | Warning | Add at least one entry to `plugins`. |
949| `No marketplace description provided` | Warning | Add a top-level `description`. |
950| `Plugin name "<name>" is not kebab-case` under `plugins[N] plugin.json → name` | Warning | Rename to lowercase letters, digits, and hyphens. Claude Code accepts other forms, but the claude.ai marketplace sync rejects them. |
951| `Entry declares version "<a>" but <path>/plugin.json says "<b>"` | Warning | Update the entry to match `plugin.json`, which is authoritative at install time. |
952| `Marketplace name "<name>" is reserved in Claude Desktop` | Warning | Rename the marketplace. Claude Desktop's managed marketplace sync rejects `org`, `org-provisioned`, and `unknown` in any casing. |
953| `Marketplace name "<name>" is not accepted by Claude Desktop` or `Plugin name "<name>" is not accepted by Claude Desktop` | Warning | Rename to at most 128 characters of letters, digits, `.`, `_`, and `-`, starting with a letter or digit. |
954954 
955955Before v2.1.247, a marketplace name containing control or bidirectional-formatting characters was reported only as `Marketplace name impersonates an official Anthropic/Claude marketplace`.
956956 

prompt-caching Changed · +33 / -36 lines

from line 18
1818 
1919To get the most out of prefix matching, Claude Code orders each request so content that rarely changes between turns comes first:
2020 
21| Layer | Content | Changes when |
22| --------------- | ----------------------------------------------- | ----------------------------------------------- |
23| System prompt | Core instructions, tool definitions | The set of loaded tool definitions changes |
24| Project context | CLAUDE.md, auto memory, unscoped rules | Session starts, or after `/clear` or `/compact` |
25| Conversation | Your messages, Claude's responses, tool results | Every turn |
21| Layer | Content | Changes when |
22| - | - | - |
23| System prompt | Core instructions, tool definitions | The set of loaded tool definitions changes |
24| Project context | CLAUDE.md, auto memory, unscoped rules | Session starts, or after `/clear` or `/compact` |
25| Conversation | Your messages, Claude's responses, tool results | Every turn |
2626 
2727A change to the conversation layer leaves the system prompt and project context cached. A change to the system prompt invalidates everything, because all later content now sits behind a different prefix. The third column gives common triggers rather than an exhaustive list, and the sections below cover the full set.
2828 
from line 104
104104 
105105### Connecting or removing an MCP server
106106 
107Tool definitions sit in the system prompt layer, so the cache invalidates when the set of tool definitions in the request changes between turns. Toggling the [advisor tool](/docs/en/advisor) is an exception: its definition sits after the cache breakpoint, so enabling or disabling `/advisor` keeps the cached prefix intact. Whether an [MCP server](/docs/en/mcp) change does this depends on whether its tools are deferred by [tool search](/docs/en/mcp#scale-with-mcp-tool-search) or loaded into the prefix:
107Tool definitions sit in the system prompt layer, so the cache invalidates when the set of tool definitions in the request changes between turns. Toggling the [advisor tool](/docs/en/advisor) is an exception: its definition sits after the cache breakpoint, so enabling or disabling `/advisor` keeps the cached prefix intact. Whether an [MCP server](/docs/en/mcp) change does this depends on whether [tool search](/docs/en/mcp#scale-with-mcp-tool-search) defers the session's MCP tools, the default on supported models:
108108 
109* **Deferred tools**, the default on supported models: a server connecting, disconnecting, or changing its tool list only appends new content and doesn't disturb anything already cached.
110* **Tools loaded into the prefix**: adding a definition invalidates the cache, and so does removing one on purpose. This is the case when [tool search is unavailable or disabled](/docs/en/mcp#configure-tool-search), such as on Google Cloud's Agent Platform models earlier than the Claude 4.5 generation, with a custom `ANTHROPIC_BASE_URL` gateway, or on a Microsoft Foundry [deployment hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) once Claude Code detects that the deployment rejects tool search.
109* **Tools deferred**: Claude Code keeps the tool list from the conversation's first request for the whole conversation, so a server connecting or disconnecting mid-session doesn't disturb anything already cached. A server that finishes connecting after the first request supplies its tools as deferred definitions that Claude loads on demand.
110* **Tools loaded upfront**: adding a definition invalidates the cache, and so does removing one on purpose. This applies when tool search is [below its `auto` threshold, disabled, or unavailable](/docs/en/mcp#configure-tool-search), such as on Google Cloud's Agent Platform models earlier than the Claude 4.5 generation, with a custom `ANTHROPIC_BASE_URL` gateway, or on a Microsoft Foundry [deployment hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) once Claude Code detects that the deployment rejects tool search.
111111 
112112Without tool search, whether a mid-session server change invalidates the cache depends on what changed. For each change, this table gives whether the cache is kept and what happens to the tool definitions in the next request.
113113 
114| Mid-session change | Cache | Tool definitions in the next request |
115| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
116| A server connects, or a [dynamic tool update](/docs/en/mcp#dynamic-tool-updates) adds tools | Invalidated | The new definitions are added |
117| A server drops out with no action on your part, such as a stdio server's process exiting | Kept | The server's definitions stay unchanged. A call to one of its tools returns an error instead of running |
118| A remote server [reconnects automatically](/docs/en/mcp#automatic-reconnection) after its connection drops | Kept, unless a request sent while the server reconnects adds the `WaitForMcpServers` tool, which invalidates the cache once | The server's definitions stay unchanged. A request sent while the server reconnects can add `WaitForMcpServers` when the conversation hasn't listed it yet, and the tool then stays listed for the rest of the conversation |
119| You remove a tool on purpose, such as with a [deny rule](#denying-an-entire-tool) or by disabling its server in `/mcp` | Invalidated | The definition is removed |
114| Mid-session change | Cache | Tool definitions in the next request |
115| - | - | - |
116| A server connects, or a [dynamic tool update](/docs/en/mcp#dynamic-tool-updates) adds tools | Invalidated | The new definitions are added |
117| A server drops out with no action on your part, such as a stdio server's process exiting | Kept | The server's definitions stay unchanged. A call to one of its tools returns an error instead of running |
118| A remote server [reconnects automatically](/docs/en/mcp#automatic-reconnection) after its connection drops | Kept, unless a request sent while the server reconnects adds the `WaitForMcpServers` tool, which invalidates the cache once | The server's definitions stay unchanged. A request sent while the server reconnects can add `WaitForMcpServers` when the conversation hasn't listed it yet, and the tool then stays listed for the rest of the conversation |
119| You remove a tool on purpose, such as with a [deny rule](#denying-an-entire-tool) or by disabling its server in `/mcp` | Invalidated | The definition is removed |
120120 
121121When you resume a conversation whose tools load into the prefix, one of its MCP servers can still be connecting as the first request goes out. If the transcript recorded that server's tool definitions, that request includes them as recorded, so it doesn't change when the server finishes connecting with the same tools.
122122 
from line 132
132132 
133133#### Plugins that provide MCP servers
134134 
135When you enable or disable a plugin that provides [MCP servers](/docs/en/plugins/components#mcp-servers), Claude Code follows the same rules as when you [connect or remove an MCP server](#connecting-or-removing-an-mcp-server):
135When you enable or disable a plugin that provides [MCP servers](/docs/en/plugins/components#mcp-servers), Claude Code follows the same rules as when you [connect or remove an MCP server](#connecting-or-removing-an-mcp-server).
136136 
137* If Claude Code defers the server's tools, it keeps the cache.
138* If Claude Code loads them into the prefix, the next request re-reads the entire conversation.
139 
140137#### Code intelligence plugins
141138 
142139When you enable a [code intelligence plugin](/docs/en/plugins/code-intelligence), Claude gets the [LSP tool](/docs/en/tools-reference#lsp-tool-behavior).
from line 263
266263 
267264Unless you choose a TTL yourself, Claude Code requests the one-hour TTL only on a Claude subscription within your plan's included usage. There it requests the hour for the main conversation, plus a small set of helper requests that Anthropic controls server-side. This table gives each bucket's default TTL under both kinds of billing.
268265 
269| Request bucket | Claude subscription, within plan usage | Usage credits, API key, or cloud provider |
270| ----------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
271| Main conversation | One hour | Five minutes |
272| Everything else | Five minutes, except the server-controlled helper requests, which get one hour | Five minutes |
266| Request bucket | Claude subscription, within plan usage | Usage credits, API key, or cloud provider |
267| - | - | - |
268| Main conversation | One hour | Five minutes |
269| Everything else | Five minutes, except the server-controlled helper requests, which get one hour | Five minutes |
273270 
274271Once you go over your plan's usage limit and Claude Code draws on [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans), you are billed for that usage, so Claude Code drops the main conversation to the cheaper five-minute TTL. To keep the one-hour TTL there, [choose the TTL yourself](#choose-the-ttl-yourself).
275272 
from line 296
299296 
300297## Cache scope
301298 
302In Claude Code, the cache is effectively scoped to one machine and directory. Each conversation carries the working directory, platform, shell, and OS version, and the system prompt names your auto memory paths, so two sessions in different directories build different prefixes and miss each other's cache. That includes worktrees of the same repository, since each worktree has its own working directory.
299In Claude Code, the cache is effectively scoped to one machine and directory. The system prompt embeds your auto memory paths, and the conversation opens with an announcement of the working directory, platform, shell, and OS version. Two sessions in different directories therefore build different prefixes and miss each other's cache.
303300 
304301Sessions you run in parallel in the same directory build matching prefixes and read each other's cache. Sequential sessions share the prefix only when the git status snapshot taken at startup matches, since each conversation also carries the branch and recent commits from that snapshot.
305302 
306The underlying API cache is broader. Caches are isolated between organizations, and on some providers, [between workspaces within an organization](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing). Within those boundaries, any two requests with the same model and prefix read the same cache. For Agent SDK callers running fleets of automated processes, see [improve prompt caching across users and machines](/docs/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) to suppress the per-machine sections of the system prompt and share the cache across machines.
303The underlying API cache is broader. Caches are isolated between organizations, and on some providers, [between workspaces within an organization](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing). Within those boundaries, any two requests with the same model and prefix read the same cache. For Agent SDK callers running fleets of automated processes, see [improve prompt caching across users and machines](/docs/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) to move the auto memory location out of the system prompt and share the system prompt's cache entry across users and machines.
307304 
308305## Check cache performance
309306 
310307Cache performance shows up as two token counts the API reports on every response. The most direct way to watch them live is a [statusline script](/docs/en/statusline) that reads the `current_usage` object:
311308 
312| Field | Meaning |
313| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
314| `cache_creation_input_tokens` | Tokens written to the cache on this turn, billed at the cache write rate |
315| `cache_read_input_tokens` | Tokens served from cache on this turn, billed at the model's [cached token rate](https://platform.claude.com/docs/en/about-claude/pricing), below the standard input rate |
309| Field | Meaning |
310| - | - |
311| `cache_creation_input_tokens` | Tokens written to the cache on this turn, billed at the cache write rate |
312| `cache_read_input_tokens` | Tokens served from cache on this turn, billed at the model's [cached token rate](https://platform.claude.com/docs/en/about-claude/pricing), below the standard input rate |
316313 
317314A high read-to-creation ratio means caching is working well. If creation stays high turn after turn, something is changing in your prefix. The [actions that invalidate the cache](#actions-that-invalidate-the-cache) section lists the usual causes.
318315 
from line 338
341338 
342339Disabling caching is occasionally useful when debugging caching behavior with a specific model or provider. To turn it off, set one of these environment variables to `1`:
343340 
344| Variable | Effect |
345| ------------------------------- | ----------------------------------- |
346| `DISABLE_PROMPT_CACHING` | Disable for all models |
347| `DISABLE_PROMPT_CACHING_HAIKU` | Disable for the default Haiku model |
348| `DISABLE_PROMPT_CACHING_SONNET` | Disable for Sonnet only |
349| `DISABLE_PROMPT_CACHING_OPUS` | Disable for Opus only |
350| `DISABLE_PROMPT_CACHING_FABLE` | Disable for Fable only |
341| Variable | Effect |
342| - | - |
343| `DISABLE_PROMPT_CACHING` | Disable for all models |
344| `DISABLE_PROMPT_CACHING_HAIKU` | Disable for the default Haiku model |
345| `DISABLE_PROMPT_CACHING_SONNET` | Disable for Sonnet only |
346| `DISABLE_PROMPT_CACHING_OPUS` | Disable for Opus only |
347| `DISABLE_PROMPT_CACHING_FABLE` | Disable for Fable only |
351348 
352349`DISABLE_PROMPT_CACHING_HAIKU` applies to the default Haiku model, the model the `haiku` alias resolves to. It disables caching wherever that model runs, including the main conversation when it is your main model. Covering the main conversation requires Claude Code v2.1.283 or later.
353350 

quickstart Changed · +12 / -12 lines

from line 266
266266 
267267**Shell commands**
268268 
269| Command | What it does | Example |
270| ------------------- | ------------------------------------------------------ | ----------------------------------- |
271| `claude` | Start interactive mode | `claude` |
272| `claude "task"` | Start interactive mode with an initial prompt | `claude "fix the build error"` |
273| `claude -p "query"` | Run one-off query, then exit | `claude -p "explain this function"` |
274| `claude -c` | Continue most recent conversation in current directory | `claude -c` |
275| `claude -r` | Resume a previous conversation | `claude -r` |
269| Command | What it does | Example |
270| - | - | - |
271| `claude` | Start interactive mode | `claude` |
272| `claude "task"` | Start interactive mode with an initial prompt | `claude "fix the build error"` |
273| `claude -p "query"` | Run one-off query, then exit | `claude -p "explain this function"` |
274| `claude -c` | Continue most recent conversation in current directory | `claude -c` |
275| `claude -r` | Resume a previous conversation | `claude -r` |
276276 
277277**Session commands**
278278 
279| Command | What it does | Example |
280| ----------------------- | -------------------------- | -------- |
281| `/clear` | Clear conversation history | `/clear` |
282| `/help` | Show available commands | `/help` |
283| `/exit` or Ctrl+D twice | Exit Claude Code | `/exit` |
279| Command | What it does | Example |
280| - | - | - |
281| `/clear` | Clear conversation history | `/clear` |
282| `/help` | Show available commands | `/help` |
283| `/exit` or Ctrl+D twice | Exit Claude Code | `/exit` |
284284 
285285See the [CLI reference](/docs/en/cli-reference) for the complete list of shell commands and the [commands reference](/docs/en/commands) for the complete list of session commands.
286286 

remote-control Changed · +23 / -23 lines

from line 26
2626* **Feature-flag evaluation**: if you set an [environment variable that turns off feature-flag evaluation](/docs/en/env-vars#features-that-need-feature-flag-fetching), whether Remote Control is available depends on which one:
2727 * If you set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or `DISABLE_GROWTHBOOK`, Remote Control is unavailable. Unset the variable wherever it's set, in your shell environment or in the `env` block of a [`settings.json` file](/docs/en/settings-reference#all-settings), to use Remote Control.
2828 * If you set only `DISABLE_TELEMETRY` or `DO_NOT_TRACK`, Remote Control stays available unless your organization requires [Trusted Devices](#trusted-devices). If it does, unset the variable to use Remote Control. Using Remote Control with either variable set requires Claude Code v2.1.283 or later.
29* **Workspace trust**: run `claude` in your project directory at least once to accept the workspace trust dialog. The startup trust dialog never saves trust for your home directory, so start Remote Control from a project directory.
29* **Workspace trust**: in a directory you haven't trusted yet, `claude remote-control` prints what trusting it turns on and asks `Trust <directory>? [y/N]` before it starts. Answering `y` saves the choice, except in your home directory, where trust is never saved and the question returns on every run. When its standard input or output isn't a terminal, the command can't ask and exits with a [`Workspace not trusted`](/docs/en/errors#workspace-not-trusted-when-starting-remote-control) error.
3030 
3131## Start a Remote Control session
3232 
from line 46
4646 
4747 Available flags:
4848 
49 | Flag | Description |
50 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
51 | `--name "My Project"` | Set a custom session title visible in the session list at claude.ai/code. |
52 | `--remote-control-session-name-prefix <prefix>` | Prefix for auto-generated session names when no explicit name is set. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. Set `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` for the same effect. |
53 | `-c`, `--continue` | Bring back the session that the last server in this directory started with, instead of creating a new one. See [Resume sessions after stopping the server](#resume-sessions-after-stopping-the-server). Can't be combined with `--session-id`, `--spawn`, `--capacity`, or `--create-session-in-dir`. Requires Claude Code v2.1.200 or later. |
54 | `--session-id <id>` | Bring back one session by its ID. See [Resume sessions after stopping the server](#resume-sessions-after-stopping-the-server). Can't be combined with `--continue`, `--spawn`, `--capacity`, or `--create-session-in-dir`. Requires Claude Code v2.1.200 or later. |
55 | `--spawn <mode>` | How the server creates sessions.<br />• `same-dir` (default): all sessions share the current working directory, so they can conflict if editing the same files.<br />• `worktree`: each on-demand session gets its own [git worktree](/docs/en/worktrees). Requires a git repository.<br />• `session`: single-session mode. Serves exactly one session and rejects additional connections. Set at startup only.<br />Press `w` at runtime to toggle between `same-dir` and `worktree`. |
56 | `--capacity <N>` | Maximum number of concurrent sessions. Default is 32. Cannot be used with `--spawn=session`. |
57 | `--[no-]create-session-in-dir` | Pre-create one session in the current directory when the server starts, so you have somewhere to type immediately. In `worktree` mode this session stays in the current directory while on-demand sessions get isolated worktrees. On by default. If you pass `--no-create-session-in-dir` to start with none, Claude Code archives the server's sessions when you stop it, so there's nothing to [resume](#resume-sessions-after-stopping-the-server). |
58 | `--permission-mode <mode>` | Set the starting [permission mode](/docs/en/permission-modes) for the server's sessions, such as `acceptEdits`. Accepts `manual` as an alias for `default`; an unrecognized mode stops the server at startup and lists the valid modes. |
59 | `-d`, `--debug[=<filter>]` | Turn on debug logging for the server, optionally filtered by category. Pass a filter only in the `=` form, such as `--debug=api,hooks`. Requires Claude Code v2.1.282 or later; earlier versions reject the flag as an unknown argument. |
60 | `--debug-file <path>` | Write debug logs to the given file. |
61 | `--verbose` | Show detailed connection and session logs. |
62 | `--sandbox` / `--no-sandbox` | Enable or disable [sandboxing](/docs/en/sandboxing) for filesystem and network isolation. Off by default. |
49 | Flag | Description |
50 | - | - |
51 | `--name "My Project"` | Set a custom session title visible in the session list at claude.ai/code. |
52 | `--remote-control-session-name-prefix <prefix>` | Prefix for auto-generated session names when no explicit name is set. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. Set `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` for the same effect. |
53 | `-c`, `--continue` | Bring back the session that the last server in this directory started with, instead of creating a new one. See [Resume sessions after stopping the server](#resume-sessions-after-stopping-the-server). Can't be combined with `--session-id`, `--spawn`, `--capacity`, or `--create-session-in-dir`. Requires Claude Code v2.1.200 or later. |
54 | `--session-id <id>` | Bring back one session by its ID. See [Resume sessions after stopping the server](#resume-sessions-after-stopping-the-server). Can't be combined with `--continue`, `--spawn`, `--capacity`, or `--create-session-in-dir`. Requires Claude Code v2.1.200 or later. |
55 | `--spawn <mode>` | How the server creates sessions.<br />• `same-dir` (default): all sessions share the current working directory, so they can conflict if editing the same files.<br />• `worktree`: each on-demand session gets its own [git worktree](/docs/en/worktrees). Requires a git repository.<br />• `session`: single-session mode. Serves exactly one session and rejects additional connections. Set at startup only.<br />Press `w` at runtime to toggle between `same-dir` and `worktree`. |
56 | `--capacity <N>` | Maximum number of concurrent sessions. Default is 32. Cannot be used with `--spawn=session`. |
57 | `--[no-]create-session-in-dir` | Pre-create one session in the current directory when the server starts, so you have somewhere to type immediately. In `worktree` mode this session stays in the current directory while on-demand sessions get isolated worktrees. On by default. If you pass `--no-create-session-in-dir` to start with none, Claude Code archives the server's sessions when you stop it, so there's nothing to [resume](#resume-sessions-after-stopping-the-server). |
58 | `--permission-mode <mode>` | Set the starting [permission mode](/docs/en/permission-modes) for the server's sessions, such as `acceptEdits`. Accepts `manual` as an alias for `default`; an unrecognized mode stops the server at startup and lists the valid modes. |
59 | `-d`, `--debug[=<filter>]` | Turn on debug logging for the server, optionally filtered by category. Pass a filter only in the `=` form, such as `--debug=api,hooks`. Requires Claude Code v2.1.282 or later; earlier versions reject the flag as an unknown argument. |
60 | `--debug-file <path>` | Write debug logs to the given file. |
61 | `--verbose` | Show detailed connection and session logs. |
62 | `--sandbox` / `--no-sandbox` | Enable or disable [sandboxing](/docs/en/sandboxing) for filesystem and network isolation. Off by default. |
6363 
6464 Give these flags after `remote-control`.
6565 
from line 283
283283 
284284Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.
285285 
286| | Trigger | Claude runs on | Setup | Best for |
287| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
288| [Dispatch](/docs/en/desktop#sessions-from-dispatch) | Message a task from the Claude mobile app | Your machine (Desktop) | [Pair the mobile app with Desktop](https://support.claude.com/en/articles/13947068) | Delegating work while you're away, minimal setup |
289| [Remote Control](/docs/en/remote-control) | Drive a running session from [claude.ai/code](https://claude.ai/code) or the Claude mobile app | Your machine (CLI, Desktop, or VS Code) | Run [`claude remote-control` or `/remote-control`](/docs/en/remote-control#start-a-remote-control-session) | Steering in-progress work from another device |
290| [Channels](/docs/en/channels) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](/docs/en/channels#quickstart) or [build your own](/docs/en/channels-reference) | Reacting to external events like CI failures or chat messages |
291| [Slack](/docs/en/slack) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](/docs/en/slack#setting-up-claude-code-in-slack) with [Claude Code on the web](/docs/en/claude-code-on-the-web) enabled | PRs and reviews from team chat |
292| [Self-hosted environments](/docs/en/self-hosted-environments) | Start a [cloud session](/docs/en/claude-code-on-the-web) and pick your organization's environment | Your organization's infrastructure | [Deploy runners](/docs/en/self-hosted-environments-quickstart), on Team and Enterprise plans | Cloud sessions that must run inside your network |
293| [Scheduled tasks](/docs/en/scheduled-tasks) | Set a schedule | [CLI](/docs/en/scheduled-tasks), [Desktop](/docs/en/desktop-scheduled-tasks), or [cloud](/docs/en/routines) | Pick a frequency | Recurring automation like daily reviews |
286| | Trigger | Claude runs on | Setup | Best for |
287| :- | :- | :- | :- | :- |
288| [Dispatch](/docs/en/desktop#sessions-from-dispatch) | Message a task from the Claude mobile app | Your machine (Desktop) | [Pair the mobile app with Desktop](https://support.claude.com/en/articles/13947068) | Delegating work while you're away, minimal setup |
289| [Remote Control](/docs/en/remote-control) | Drive a running session from [claude.ai/code](https://claude.ai/code) or the Claude mobile app | Your machine (CLI, Desktop, or VS Code) | Run [`claude remote-control` or `/remote-control`](/docs/en/remote-control#start-a-remote-control-session) | Steering in-progress work from another device |
290| [Channels](/docs/en/channels) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](/docs/en/channels#quickstart) or [build your own](/docs/en/channels-reference) | Reacting to external events like CI failures or chat messages |
291| [Slack](/docs/en/slack) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](/docs/en/slack#setting-up-claude-code-in-slack) with [Claude Code on the web](/docs/en/claude-code-on-the-web) enabled | PRs and reviews from team chat |
292| [Self-hosted environments](/docs/en/self-hosted-environments) | Start a [cloud session](/docs/en/claude-code-on-the-web) and pick your organization's environment | Your organization's infrastructure | [Deploy runners](/docs/en/self-hosted-environments-quickstart), on Team and Enterprise plans | Cloud sessions that must run inside your network |
293| [Scheduled tasks](/docs/en/scheduled-tasks) | Set a schedule | [CLI](/docs/en/scheduled-tasks), [Desktop](/docs/en/desktop-scheduled-tasks), or [cloud](/docs/en/routines) | Pick a frequency | Recurring automation like daily reviews |
294294 
295295## Mobile push notifications
296296 
Feedback