File Deleted
View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Plugins reference
6
7> Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications.
8
9<Tip>
10 Looking to install plugins? See [Discover and install plugins](/docs/en/discover-plugins). For creating plugins, see [Plugins](/docs/en/plugins). For distributing plugins, see [Plugin marketplaces](/docs/en/plugin-marketplaces).
11</Tip>
12
13A **plugin** is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, LSP servers, and monitors.
14
15## Plugin components reference
16
17### Skills
18
19Plugins add skills to Claude Code, creating `/name` shortcuts that you or Claude can invoke.
20
21**Location**: `skills/` or `commands/` directory in plugin root, or a single `SKILL.md` file at the plugin root
22
23**File format**: Skills are directories with `SKILL.md`; commands are simple markdown files
24
25**Skill structure**:
26
27```text theme={null}
28skills/
29├── pdf-processor/
30│ ├── SKILL.md
31│ ├── reference.md (optional)
32│ └── scripts/ (optional)
33└── code-reviewer/
34 └── SKILL.md
35```
36
37Skills and commands are automatically discovered when the plugin is installed.
38
39If a plugin has no `skills/` directory and no `skills` manifest field, a `SKILL.md` at the plugin root is loaded as a single skill. Set the frontmatter `name` field to control the skill's invocation name. Without it, Claude Code falls back to the install directory name. For a plugin [copied into the cache](#plugin-caching-and-file-resolution), that name is a version string that changes on every update. For plugins that ship more than one skill, use the `skills/` directory layout shown above.
40
41In plugin skills and commands, Boolean frontmatter fields such as `disable-model-invocation` accept `yes`, `no`, `on`, `off`, `1`, and `0` in any letter case, in addition to `true` and `false`. Before v2.1.218, Claude Code recognized only `true` and `false`.
42
43For complete details, see [Skills](/docs/en/skills).
44
45### Agents
46
47Plugins can provide specialized subagents for specific tasks that Claude can invoke automatically when appropriate.
48
49**Location**: `agents/` directory in plugin root
50
51**File format**: Markdown files describing agent capabilities
52
53**Agent structure**:
54
55```markdown theme={null}
56name: agent-name
57description: What this agent specializes in and when Claude should invoke it
58model: sonnet
59effort: medium
60maxTurns: 20
61disallowedTools: Write, Edit
62
63Detailed system prompt for the agent describing its role, expertise, and behavior.
64```
65
66#### Plugin agent frontmatter
67
68A plugin agent file uses the same [frontmatter fields as a subagent file](/docs/en/sub-agents#supported-frontmatter-fields), except that Claude Code honors only some of them when the agent comes from a plugin:
69
70* **Supported**: `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, `omitClaudeMd`, `isolation`, `color`, and `experimental`. The only valid `isolation` value is `"worktree"`.
71* **Not supported, for security reasons**: `hooks`, `mcpServers`, and `permissionMode`. Claude Code ignores these when loading an agent from a plugin. To use them, copy the agent file into `.claude/agents/` or `~/.claude/agents/`.
72* **Not supported**: `initialPrompt`.
73
74You can put plugin agent files in subfolders of `agents/`. Claude Code [loads them recursively](/docs/en/sub-agents#choose-the-subagent-scope) and joins the plugin name, each subfolder name, and the file name with colons to form the agent's scoped name. For example, `agents/review/security.md` in a plugin named `my-plugin` loads as `my-plugin:review:security`. Two settings change that name:
75
76* Frontmatter `name`: it replaces only the file name, so `name: audit` in `agents/review/security.md` loads as `my-plugin:review:audit`
77* Manifest [`agents`](#component-path-fields) field: a file you list there loads without subfolder names, so `"agents": "./custom/review/security.md"` loads as `my-plugin:security`
78
79Claude Code loads a plugin agent even when its frontmatter has no `name` or doesn't parse:
80
81* No `name`: Claude Code names the agent after the file, so `agents/reviewer.md` in a plugin named `my-plugin` loads as `my-plugin:reviewer`
82* Frontmatter that doesn't parse: Claude Code names the agent after the file, uses `Agent from my-plugin plugin` as its description, and ignores every field in the file
83
84By contrast, Claude Code skips a project, user, or managed agent file whose frontmatter has no `name` or doesn't parse.
85
86To find files in a plugin's default `agents/` directory whose frontmatter doesn't parse, run `claude plugin validate`. The path you pass depends on whether the plugin has a manifest, and both examples use `./my-plugin` as the plugin directory:
87
88* A plugin with a manifest: `claude plugin validate ./my-plugin`
89* A plugin without a manifest: `claude plugin validate ./my-plugin/agents`. Requires Claude Code v2.1.233 or later.
90
91Agents appear in the [@-mention typeahead](/docs/en/sub-agents#invoke-subagents-explicitly) under their scoped name, such as `my-plugin:code-reviewer`, once the plugin is enabled.
92
93For complete details, see [Subagents](/docs/en/sub-agents).
94
95### Hooks
96
97Plugins can provide event handlers that respond to Claude Code events automatically.
98
99**Location**: `hooks/hooks.json` in plugin root, or inline in plugin.json
100
101**Format**: JSON configuration with event matchers and actions
102
103`hooks/hooks.json` can carry a top-level `$schema` key that names a JSON Schema URL for editor autocomplete and validation. Claude Code ignores the key at load time.
104
105**Hook configuration**:
106
107```json theme={null}
108{
109 "hooks": {
110 "PostToolUse": [
111 {
112 "matcher": "Write|Edit",
113 "hooks": [
114 {
115 "type": "command",
116 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
117 }
118 ]
119 }
120 ]
121 }
122}
123```
124
125Plugin hooks respond to the same lifecycle events as [user-defined hooks](/docs/en/hooks):
126
127| Event | When it fires |
128| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
129| `SessionStart` | When a session begins or resumes |
130| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |
131| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |
132| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |
133| `PreToolUse` | Before a tool call executes. Can block it |
134| `PermissionRequest` | When a tool call needs a permission decision |
135| `PermissionDenied` | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry the denied tool call. Claude Code ignores `retry` when the classifier produced no verdict |
136| `PostToolUse` | After a tool call succeeds |
137| `PostToolUseFailure` | After a tool call fails |
138| `PostToolBatch` | After a full batch of parallel tool calls resolves, before the next model call |
139| `Notification` | When Claude Code sends a notification |
140| `MessageDisplay` | While assistant message text is displayed |
141| `SubagentStart` | When a subagent is spawned |
142| `SubagentStop` | When a subagent finishes |
143| `TaskCreated` | When a task is being created via `TaskCreate` |
144| `TaskCompleted` | When a task is being marked as completed |
145| `Stop` | When Claude finishes responding |
146| `StopFailure` | When the turn ends due to an API error |
147| `TeammateIdle` | When an [agent team](/docs/en/agent-teams) teammate is about to go idle |
148| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |
149| `ConfigChange` | When a configuration file changes during a session |
150| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |
151| `DirectoryAdded` | When a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request |
152| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |
153| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |
154| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |
155| `PreCompact` | Before context compaction |
156| `PostCompact` | After context compaction completes |
157| `PreModelSwitch` | Before Claude Code applies a model switch that you or a client requested. Can block the switch |
158| `PostModelSwitch` | After the session's model changes, including changes Claude Code makes on its own, such as restoring the model when you resume a session |
159| `Elicitation` | When an MCP server requests user input during a tool call |
160| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |
161| `SessionEnd` | When a session terminates |
162
163**Hook types**:
164
165* `command`: execute shell commands or scripts
166* `http`: send the event JSON as a POST request to a URL
167* `mcp_tool`: call a tool on a configured [MCP server](/docs/en/mcp)
168* `prompt`: evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context)
169* `agent`: run an agentic verifier with tools for complex verification tasks
170
171Hooks that target the plugin's own [bundled MCP server](#mcp-servers) must use its scoped names. Tool matchers and `if` fields take the scoped tool name `mcp__plugin_<plugin-name>_<server-name>__<tool>`, and an `mcp_tool` hook's `server` field takes `plugin:<plugin-name>:<server-name>`. A matcher written against the bare server key never fires. See [Match MCP tools](/docs/en/hooks#match-mcp-tools) and [Plugin-provided MCP servers](/docs/en/mcp#plugin-provided-mcp-servers).
172
173### MCP servers
174
175Plugins can bundle Model Context Protocol (MCP) servers to connect Claude Code with external tools and services.
176
177**Location**: `.mcp.json` in plugin root, or inline in plugin.json
178
179**Format**: Standard MCP server configuration
180
181**MCP server configuration**:
182
183```json theme={null}
184{
185 "mcpServers": {
186 "plugin-database": {
187 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
188 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
189 "env": {
190 "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
191 }
192 },
193 "plugin-api-client": {
194 "command": "npx",
195 "args": ["@company/mcp-server", "--plugin-mode"]
196 }
197 }
198}
199```
200
201**Integration behavior**:
202
203* Plugin MCP servers start automatically when the plugin is enabled
204* Servers appear as standard MCP tools in Claude's toolkit
205* Plugin servers can be configured independently of user MCP servers
206* If you run [`/reload-plugins`](/docs/en/discover-plugins#apply-plugin-changes-without-restarting) mid-session, Claude Code keeps the live connections of servers whose configuration is unchanged
207
208### LSP servers
209
210<Tip>
211 Looking to use LSP plugins? Install them from the official marketplace: search for "lsp" in the `/plugin` Discover tab. This section documents how to create LSP plugins for languages not covered by the official marketplace.
212</Tip>
213
214Plugins can provide [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers to give Claude [real-time code intelligence](/docs/en/discover-plugins#code-intelligence) while working on your codebase.
215
216**Location**: `.lsp.json` in plugin root, or inline in `plugin.json`
217
218**Format**: JSON configuration mapping language server names to their configurations
219
220**`.lsp.json` file format**:
221
222```json theme={null}
223{
224 "go": {
225 "command": "gopls",
226 "args": ["serve"],
227 "extensionToLanguage": {
228 ".go": "go"
229 }
230 }
231}
232```
233
234**Inline in `plugin.json`**:
235
236```json theme={null}
237{
238 "name": "my-plugin",
239 "lspServers": {
240 "go": {
241 "command": "gopls",
242 "args": ["serve"],
243 "extensionToLanguage": {
244 ".go": "go"
245 }
246 }
247 }
248}
249```
250
251**Required fields:**
252
253| Field | Description |
254| :-------------------- | :------------------------------------------- |
255| `command` | The LSP binary to execute (must be in PATH) |
256| `extensionToLanguage` | Maps file extensions to language identifiers |
257
258**Optional fields:**
259
260| Field | Description |
261| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
262| `args` | Command-line arguments for the LSP server |
263| `transport` | 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 |
264| `env` | Environment variables to set when starting the server |
265| `initializationOptions` | Options passed to the server during initialization |
266| `settings` | Settings passed via `workspace/didChangeConfiguration` |
267| `workspaceFolder` | Workspace folder path for the server |
268| `startupTimeout` | Max time to wait for server startup (milliseconds) |
269| `shutdownTimeout` | Max time to wait for graceful shutdown (milliseconds). When the timeout elapses, Claude Code terminates the server process. When unset, no timeout applies |
270| `restartOnCrash` | Whether to restart the server after it crashes. Defaults to `true`. Set to `false` to leave a crashed server stopped instead of restarting it |
271| `maxRestarts` | Maximum number of restart attempts before giving up |
272| `diagnostics` | Whether to push diagnostics into Claude's context after edits (default `true`). Set to `false` to keep code navigation but suppress automatic diagnostic injection. |
273
274`restartOnCrash` and `shutdownTimeout` require Claude Code v2.1.205 or later. Before v2.1.205, the config schema accepted both options but setting either one caused Claude Code to skip that LSP server entirely at startup, with the reason visible only in `claude --debug` output.
275
276**Multiple servers for the same extension**: when more than one enabled LSP server declares the same file extension in `extensionToLanguage`, whether the servers come from one plugin or from different plugins, the first server registered handles files with that extension and the others never start. The `/plugin` interface shows a warning naming the plugin whose server is active.
277
278**Servers that fail to initialize**: Claude Code skips a server whose configuration is invalid, for example one missing `command` or `extensionToLanguage`, and the other configured servers still start. Run `claude --debug` to see why a server was skipped.
279
280A skipped server doesn't claim its file extensions, so another valid server that declares the same extension, from the same or a different plugin, still handles those files.
281
282**Send log output to stderr, not stdout**: Claude Code reads a server's stdout as protocol messages only, and accepts message headers up to 64 KiB and a message body up to 32 MiB. Claude Code disconnects a server that exceeds either limit or writes non-protocol output to stdout, and counts the disconnect as a crash for `restartOnCrash` and `maxRestarts`. When you run with `--debug`, Claude Code writes an error naming the cause to the debug log.
283
284<Warning>
285 **You must install the language server binary separately.** LSP plugins configure how Claude Code connects to a language server, but they don't include the server itself. If you see `Executable not found in $PATH` in the `/plugin` Errors tab, install the required binary for your language.
286</Warning>
287
288**Available LSP plugins:**
289
290| Plugin | Language server | Install command |
291| :------------------ | :------------------------- | :----------------------------------------------------------------------------------------- |
292| `pyright-lsp` | Pyright (Python) | `pip install pyright` or `npm install -g pyright` |
293| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |
294| `rust-analyzer-lsp` | rust-analyzer | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) |
295
296Install the language server first, then install the plugin from the marketplace.
297
298### Monitors
299
300Plugins can declare background monitors that Claude Code starts automatically when the plugin is active. Each monitor runs a shell command for the lifetime of the session and delivers every stdout line to Claude as a notification, so Claude can react to log entries, status changes, or polled events without being asked to start the watch itself.
301
302Plugin monitors use the same mechanism as the [Monitor tool](/docs/en/tools-reference#monitor-tool) and share its availability constraints. They run only in interactive CLI sessions, run unsandboxed at the same trust level as [hooks](#hooks), and are skipped on hosts where the Monitor tool is unavailable.
303
304**Location**: `monitors/monitors.json` in the plugin root, or inline in `plugin.json`
305
306**Format**: JSON array of monitor entries
307
308The following `monitors/monitors.json` watches a deployment status endpoint and a local error log:
309
310```json theme={null}
311[
312 {
313 "name": "deploy-status",
314 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
315 "description": "Deployment status changes"
316 },
317 {
318 "name": "error-log",
319 "command": "tail -F ./logs/error.log",
320 "description": "Application error log",
321 "when": "on-skill-invoke:debug"
322 }
323]
324```
325
326To declare monitors inline, set `experimental.monitors` in `plugin.json` to the same array. To load from a non-default path, set `experimental.monitors` to a relative path string such as `"./config/monitors.json"`. Monitors are an [experimental component](#experimental-components).
327
328**Required fields:**
329
330| Field | Description |
331| :------------ | :-------------------------------------------------------------------------------------------------------------------- |
332| `name` | Identifier unique within the plugin. Prevents duplicate processes when the plugin reloads or a skill is invoked again |
333| `command` | Shell command run as a persistent background process in the session working directory |
334| `description` | Short summary of what is being watched. Shown in the task panel and in notification summaries |
335
336**Optional fields:**
337
338| Field | Description |
339| :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
340| `when` | Controls when the monitor starts. `"always"` starts it at session start and on plugin reload, and is the default. `"on-skill-invoke:<skill-name>"` starts it the first time the named skill in this plugin is dispatched |
341
342The `command` value supports the [path substitutions](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, and `${CLAUDE_PROJECT_DIR}`, plus any `${ENV_VAR}` from the environment. Prefix the command with `cd "${CLAUDE_PLUGIN_ROOT}" && ` if the script needs to run from the plugin's own directory.
343
344A monitor `command` can't reference [`${user_config.*}`](#user-configuration) values. The command runs through a shell, so Claude Code rejects the monitor with an [error](/docs/en/errors#plugin-command-references-user-config) instead of substituting the value. Monitor processes don't receive `CLAUDE_PLUGIN_OPTION_<KEY>` environment variables, so have the monitor script read the value from a config file it owns.
345
346If you disable a plugin mid-session, Claude Code doesn't stop monitors that are already running; they stop when the session ends.
347
348### Themes
349
350Plugins can ship color themes that appear in `/theme` alongside the built-in presets and the user's local themes. A theme is a JSON file in `themes/` with a `base` preset and a sparse `overrides` map of color tokens. Themes are an [experimental component](#experimental-components).
351
352```json theme={null}
353{
354 "name": "Dracula",
355 "base": "dark",
356 "overrides": {
357 "claude": "#bd93f9",
358 "error": "#ff5555",
359 "success": "#50fa7b"
360 }
361}
362```
363
364When a user selects a plugin theme, Claude Code saves `custom:<plugin-name>:<slug>` in their config. Plugin themes are read-only: when a user presses `Ctrl+E` on one in `/theme`, Claude Code copies it into `~/.claude/themes/` so they can edit the copy.
365
366***
367
368## Plugin installation scopes
369
370When you install a plugin, you choose a **scope** that determines where the plugin is available and who else can use it:
371
372| Scope | Settings file | Use case |
373| :-------- | :--------------------------------------- | :-------------------------------------------------------------------------- |
374| `user` | `~/.claude/settings.json` | Personal plugins available across all projects (default) |
375| `project` | `.claude/settings.json` | Team plugins shared via version control |
376| `local` | `.claude/settings.local.json` | Project-specific plugins, gitignored when Claude Code saves a setting to it |
377| `managed` | [Managed settings](/docs/en/managed-settings) | Managed plugins (read-only, update only) |
378
379Plugins use the same scope system as other Claude Code configurations. For installation instructions and scope flags, see [Install plugins](/docs/en/discover-plugins#install-plugins). For a complete explanation of scopes, see [Configuration scopes](/docs/en/settings#where-settings-live).
380
381***
382
383## Skills-directory plugins
384
385Any folder under a skills directory that contains a `.claude-plugin/plugin.json` manifest is loaded as a plugin named `<name>@skills-dir` on the next session, with no marketplace and no install step. Scaffold one with [`plugin init`](#plugin-init). Unlike a copied marketplace install, the plugin is discovered in place rather than copied into the plugin cache.
386
387A skills directory tree supports three distinct things:
388
389| What you have | What it is |
390| :-------------------------------------------- | :---------------------------------------------------------------------------------- |
391| `<skills-dir>/foo/SKILL.md` with no manifest | A plain [skill](/docs/en/skills) named `foo` |
392| `<skills-dir>/foo/.claude-plugin/plugin.json` | A plugin `foo@skills-dir`, which can bundle its own skills, agents, hooks, and more |
393| `<plugin>/skills/bar/SKILL.md` | A skill `bar` packaged inside a plugin |
394
395### Choose where the plugin loads from
396
397| Skills directory | Scope | Loads |
398| :---------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------- |
399| `~/.claude/skills/` | personal | In every project, since the location is yours alone |
400| `<cwd>/.claude/skills/` | project | Only after you accept the workspace [trust dialog](/docs/en/permissions#what-runs-before-you-trust-a-folder) for that folder |
401
402A project-scope plugin is checked into the repository and reaches every collaborator who clones it. Because that content comes from the repository rather than from you, it loads only after the same trust gate that governs project allow rules in `.claude/settings.json`, so trusting a parent folder or running with `-p` isn't enough, and components that run code are restricted further:
403
404* MCP servers it declares go through the [same per-server approval](/docs/en/mcp) as a project `.mcp.json`
405* LSP servers start only after you trust the workspace
406* [Background monitors](#monitors) do not load
407
408Personal-scope plugins have none of these restrictions.
409
410<Warning>
411 Project-scope `@skills-dir` plugins load only from the `.claude/skills/` of the session's [primary working directory](/docs/en/permissions#working-directories). They don't [walk up to the repository root](/docs/en/skills#discovery-from-parent-and-nested-directories) the way plain skills and commands do, so launching from a subdirectory misses a plugin that lives at the repo root. Launch from the repository root, or [move the session there with `/cd`](/docs/en/permissions#move-the-session-to-another-directory) on v2.1.246 or later.
412</Warning>
413
414### Edit, reload, and disable a skills-directory plugin
415
416Changes you make to a skill's `SKILL.md` take effect immediately in the current session. Changes to the plugin's other components, such as `hooks/`, `.mcp.json`, `agents/`, and `output-styles/`, do not. Run `/reload-plugins` or restart Claude Code to pick those up. See [Live change detection](/docs/en/skills#live-change-detection).
417
418To stop loading a skills-directory plugin, delete its folder or disable it by name. There is no `uninstall` step because nothing was installed from a marketplace.
419
420```bash theme={null}
421claude plugin disable my-tool@skills-dir
422```
423
424***
425
426<h2 id="synced-plugins">
427 Plugins synced from claude.ai
428</h2>
429
430Claude Code loads the plugins enabled for your claude.ai account, including plugins your organization turns on for its members, alongside the plugins you install from marketplaces. It downloads each one into `~/.claude/plugins/synced/` and loads it as `<name>@synced`, with no marketplace and no install record. A synced plugin runs with the same trust as a marketplace plugin you installed: its skills, agents, hooks, MCP servers, and LSP servers all load.
431
432Where Claude Code syncs these plugins depends on the session:
433
434* In [Cowork](https://claude.com/product/cowork) and [cloud sessions](/docs/en/cloud-environments#what-carries-over-from-your-setup), Claude Code downloads them into the session's own environment when the session starts. Before v2.1.239, Claude Code loaded these plugins as `<name>@inline`, the identity that `--plugin-dir` plugins use.
435* In terminal sessions where you sign in with your claude.ai account, Claude Code checks your account once each time it starts, then downloads new and updated plugins and removes the ones that you or your organization turned off, all in the background. Syncing in terminal sessions requires Claude Code v2.1.273 or later.
436
437The launch check runs in the background, so it can finish after your session has started. When it adds, updates, or removes a synced plugin in an interactive session, Claude Code shows `Plugins changed. Run /reload-plugins to activate.` Run [`/reload-plugins`](/docs/en/discover-plugins#apply-plugin-changes-without-restarting) to load the change in that session, or leave it for the next time you start Claude Code. If you enable a plugin on claude.ai while a session is running, Claude Code downloads it the next time it starts.
438
439Plugin sync in terminal sessions runs under the same sign-in conditions as [skills synced from claude.ai](/docs/en/skills#where-synced-skills-load). It also needs a sign-in that grants Claude Code access to your account's plugins.
440
441A sign-in from an earlier version of Claude Code picks up plugin access the next time Claude Code renews that sign-in in the background, within a few hours, or right away if you run `/login` again. Plugin sync starts the next time you start Claude Code after that.
442
443`claude plugin list` shows synced plugins under a `Synced from claude.ai` heading, and the `/plugin` **Installed** tab lists them with `synced` as their source. Manage a synced plugin by the `<name>@synced` ID that `claude plugin list` prints:
444
445* **Turn one off**: run `claude plugin disable <name>@synced`, or disable it from the `/plugin` **Installed** tab. Claude Code saves the choice as `"<name>@synced": false` in your user-level [`enabledPlugins`](/docs/en/settings-reference#enabledplugins). To turn the plugin back on, run `claude plugin enable <name>@synced`.
446* **Keep one out everywhere**: [turn the plugin off for your claude.ai account](/docs/en/desktop#extend-claude-code). To keep it out of one project in every environment, set `"<name>@synced": false` under `enabledPlugins` in that project's committed `.claude/settings.json`.
447* **Manage the plugin itself on claude.ai**: `claude plugin install`, `update`, and `uninstall` don't apply to a synced plugin. Claude Code downloads a plugin's updates at the next sync. To remove one, turn the plugin off for your claude.ai account, and Claude Code removes it at the next sync.
448* **Stop syncing on a machine**: set [`syncClaudeAiPlugins`](/docs/en/settings-reference#syncclaudeaiplugins) to `false` in your user settings. Claude Code stops downloading, and the next time it starts it moves the plugins it already synced to `~/.claude/plugins/.trash/` and no longer loads them. Your organization can set the same key in [managed settings](/docs/en/managed-settings), or turn off Skills on claude.ai, which stops plugins from syncing too.
449
450You can't turn off a plugin that your organization marks as required on claude.ai. Claude Code loads it even if you disabled it earlier, and `claude plugin disable` refuses with `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.` In `claude plugin list`, these plugins are marked `required by your org`.
451
452When an enabled plugin from any other source matches a synced plugin's name, Claude Code loads that plugin and reports the synced copy as not loaded. Other sources include marketplace installs, [skills-directory plugins](#skills-directory-plugins), `--plugin-dir` plugins, and plugins built into Claude Code. To use the claude.ai copy instead, disable your own copy. Before v2.1.239, Claude Code loaded the synced copy instead of a same-named marketplace install.
453
454***
455
456## Plugin manifest schema
457
458The `.claude-plugin/plugin.json` file defines your plugin's metadata and configuration.
459
460The manifest is optional. If omitted, Claude Code auto-discovers components in [default locations](#file-locations-reference) and derives the plugin name from the directory name. Use a manifest when you need to provide metadata or custom component paths.
461
462### Complete schema
463
464```json theme={null}
465{
466 "name": "plugin-name",
467 "displayName": "Plugin Name",
468 "version": "1.2.0",
469 "description": "Brief plugin description",
470 "author": {
471 "name": "Author Name",
472 "email": "author@example.com",
473 "url": "https://github.com/author"
474 },
475 "homepage": "https://docs.example.com/plugin",
476 "repository": "https://github.com/author/plugin",
477 "license": "MIT",
478 "keywords": ["keyword1", "keyword2"],
479 "metadata": { "catalogId": "cat-123", "tier": "pro" },
480 "skills": "./custom/skills/",
481 "commands": ["./custom/commands/special.md"],
482 "agents": ["./custom/agents/reviewer.md"],
483 "hooks": "./config/hooks.json",
484 "mcpServers": "./mcp-config.json",
485 "outputStyles": "./styles/",
486 "lspServers": "./.lsp.json",
487 "experimental": {
488 "themes": "./themes/",
489 "monitors": "./monitors.json",
490 "evals": "quality/evals"
491 },
492 "dependencies": [
493 "helper-lib",
494 { "name": "secrets-vault", "version": "~2.1.0" }
495 ]
496}
497```
498
499### Required fields
500
501If you include a manifest, `name` is the only required field.
502
503| Field | Type | Description | Example |
504| :----- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
505| `name` | string | Unique identifier in kebab-case, with no spaces, control characters, or bidirectional-formatting characters. When a [marketplace entry](/docs/en/plugin-marketplaces#plugin-entries) lists the plugin under a different name, the marketplace entry name is what `enabledPlugins` keys and `/plugin` use | `"deployment-tools"` |
506
507This name is used for namespacing components. For example, in the UI, the
508agent `agent-creator` for the plugin with name `plugin-dev` will appear as
509`plugin-dev:agent-creator`.
510
511### Unrecognized fields
512
513Claude Code ignores top-level fields it does not recognize. You can keep
514metadata from another ecosystem in `plugin.json` and the plugin still loads.
515This makes it practical to maintain one manifest that doubles as a VS Code or
516Cursor extension manifest, an npm `package.json`, or an MCPB/DXT bundle
517manifest.
518
519`claude plugin validate` reports unrecognized fields as warnings, not errors.
520If a field is one or two characters off from a recognized one, the warning
521suggests the likely intended name. A plugin with only unrecognized-field
522warnings still passes validation and loads at runtime.
523
524How Claude Code handles a recognized field whose value has the wrong type depends on the field:
525
526* **Most fields**: the plugin fails to load. For example, a `keywords` value that is a string instead of an array is a load error, and `claude plugin validate` reports it as one.
527* **`experimental` and `metadata`**: Claude Code ignores a non-object value, and `claude plugin validate` reports a warning.
528
529Pass `--strict` to treat warnings as errors. Use it in CI to catch a misspelled
530field name or a field left over from another tool's manifest before publishing,
531even though the plugin would load at runtime.
532
533```bash theme={null}
534claude plugin validate ./my-plugin --strict
535```
536
537### Metadata fields
538
539| Field | Type | Description | Example |
540| :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
541| `$schema` | string | JSON Schema URL for editor autocomplete and validation. Claude Code ignores this field at load time. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
542| `displayName` | string | Human-readable name shown in the `/plugin` picker and other UI surfaces. For a marketplace-installed plugin, a `displayName` on the [marketplace entry](/docs/en/plugin-marketplaces#optional-plugin-fields) takes precedence over this value. When no display name is set in either place, users see `name`. Unlike `name`, may contain spaces and any casing. Not used for namespacing or lookup. | `"Deployment Tools"` |
543| `version` | string | Optional. Semantic version. Setting this pins the plugin to that version string, so users only receive updates when you bump it, except for a [`command` source](/docs/en/plugin-marketplaces#command-sources) or a plugin [loaded in place](#plugin-caching-and-file-resolution); see [Version management](#version-management). If also set in the marketplace entry, `plugin.json` wins. If omitted, the version comes from the next source in [Version management](#version-management). | `"2.1.0"` |
544| `description` | string | Brief explanation of plugin purpose | `"Deployment automation tools"` |
545| `author` | object | Author information | `{"name": "Dev Team", "email": "dev@company.com"}` |
546| `homepage` | string | Documentation URL | `"https://docs.example.com"` |
547| `repository` | string | Source code URL | `"https://github.com/user/plugin"` |
548| `license` | string | License identifier | `"MIT"`, `"Apache-2.0"` |
549| `keywords` | array | Discovery tags | `["deployment", "ci-cd"]` |
550| `metadata` | object | Free-form object for your own data, such as entitlement or catalog fields. Claude Code doesn't read it, so the values never affect plugin behavior. Claude Code ignores a non-object value, and `claude plugin validate` reports it as a warning. Before v2.1.222, Claude Code treated the key as an [unrecognized field](#unrecognized-fields). | `{"catalogId": "cat-123"}` |
551| `defaultEnabled` | boolean | Whether the plugin starts in an enabled state when the user has not set one. Defaults to `true`. See [Default enablement](#default-enablement). | `false` |
552
553### Default enablement
554
555Set `defaultEnabled: false` in `plugin.json` to ship a plugin that installs disabled. The user turns it on with `claude plugin enable <plugin>` or the `/plugin` interface. Use this for plugins that add cost or scope a user should opt into, such as one that connects to an external service.
556
557`defaultEnabled` is the fallback when nothing else has decided the plugin's state. The user's setting and a dependency requirement take precedence over it:
558
559* **The user's setting**: an entry for the plugin in `enabledPlugins` at any settings scope. Once written, it persists across plugin updates and reinstalls, so changing `defaultEnabled` in a later release does not flip an existing user.
560* **A dependency requirement**: when a plugin is required by another one that is active, Claude Code writes `true` for it at install or enable time. That gives it an explicit setting, so its own default no longer applies. See [Enable or disable a plugin with dependencies](/docs/en/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).
561
562The same field can appear in a plugin's marketplace entry, where it takes precedence over the value in `plugin.json`. See [Optional plugin fields](/docs/en/plugin-marketplaces#optional-plugin-fields).
563
564### Component path fields
565
566| Field | Type | Description | Example |
567| :---------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------- |
568| `skills` | string\|array | Custom skill directories containing `<name>/SKILL.md`. Adds to the default `skills/` scan. See [Path behavior rules](#path-behavior-rules) for the marketplace-root exception | `"./custom/skills/"` |
569| `commands` | string\|array | Custom flat `.md` skill files or directories (replaces default `commands/`) | `"./custom/cmd.md"` or `["./cmd1.md"]` |
570| `agents` | string\|array | Custom agent files (replaces default `agents/`) | `"./custom/agents/reviewer.md"` |
571| `workflows` | string\|array | Custom [workflow](/docs/en/workflows) script files or directories (replaces default `workflows/`) | `"./custom/workflows/"` |
572| `hooks` | string\|array\|object | Hook config paths or inline config | `"./my-extra-hooks.json"` |
573| `mcpServers` | string\|array\|object | MCP config paths or inline config | `"./my-extra-mcp-config.json"` |
574| `outputStyles` | string\|array | Custom output style files/directories (replaces default `output-styles/`) | `"./styles/"` |
575| `lspServers` | string\|array\|object | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) configs for code intelligence (go to definition, find references, etc.) | `"./.lsp.json"` |
576| `experimental.themes` | string\|array | Color theme files/directories (replaces default `themes/`). See [Themes](#themes) | `"./themes/"` |
577| `experimental.monitors` | string\|array | Background [Monitor](/docs/en/tools-reference#monitor-tool) configurations that start automatically when the plugin is active. See [Monitors](#monitors) | `"./monitors.json"` |
578| `experimental.evals` | string\|array | Directory below the plugin root 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 | `"quality/evals"` |
579| `userConfig` | object | User-configurable values prompted at enable time. See [User configuration](#user-configuration) | |
580| `channels` | array | Channel declarations for message injection (Telegram, Slack, Discord style). See [Channels](#channels) | |
581| `dependencies` | array | Other plugins this plugin requires, optionally with semver version constraints. See [Constrain plugin dependency versions](/docs/en/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |
582
583### Experimental components
584
585Components under the `experimental` key, `themes` and `monitors`, have a manifest schema that may change between releases while they stabilize. Where you declare them is a separate migration: the top level still works, `claude plugin validate` warns, and a future release will require `experimental.*`.
586
587### User configuration
588
589The `userConfig` field declares values that Claude Code prompts the user for when the plugin is enabled. Use this instead of requiring users to hand-edit `settings.json`.
590
591```json theme={null}
592{
593 "userConfig": {
594 "api_endpoint": {
595 "type": "string",
596 "title": "API endpoint",
597 "description": "Your team's API endpoint"
598 },
599 "api_token": {
600 "type": "string",
601 "title": "API token",
602 "description": "API authentication token",
603 "sensitive": true
604 }
605 }
606}
607```
608
609Keys must be valid identifiers. Each option supports these fields:
610
611| Field | Required | Description |
612| :------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
613| `type` | Yes | One of `string`, `number`, `boolean`, `directory`, or `file` |
614| `title` | Yes | Label shown in the configuration dialog |
615| `description` | Yes | Help text shown beneath the field |
616| `sensitive` | No | If `true`, masks input and stores the value in secure storage instead of `settings.json` |
617| `required` | No | If `true`, validation fails when the field is empty |
618| `default` | No | Value used when the user provides nothing |
619| `options` | No | For `string` type, the values the field accepts, shown in `/config` as a picker over them. See [Limit a field to fixed options](#limit-a-field-to-fixed-options). Requires Claude Code v2.1.271 or later |
620| `multiple` | No | For `string` type, allow an array of strings |
621| `min` / `max` | No | Bounds for `number` type |
622
623Except `sensitive` fields and `multiple` lists, each field of each enabled plugin also appears as a row in the `/config` panel. The rows require Claude Code v2.1.269 or later.
624
625Each value is available for substitution as `${user_config.KEY}` in MCP and LSP server configs and hook commands. Non-sensitive values can also be substituted in skill and agent content. All values are exported to hook processes as `CLAUDE_PLUGIN_OPTION_<KEY>` environment variables, where `<KEY>` is the option key uppercased.
626
627Fields that run in a shell reject `${user_config.*}`: substituting a configured value into a shell command would let the shell run whatever that value contains, so the component fails with an [error](/docs/en/errors#plugin-command-references-user-config) instead. Each rejected field has an alternative way to pass the value:
628
629| Rejected field | How to pass the value |
630| :--------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
631| 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 |
632| [Monitor](#monitors) commands | Read the value from a config file in the script |
633| MCP [`headersHelper`](/docs/en/mcp#use-dynamic-headers-for-custom-authentication) | Read the value from a config file in the script |
634
635Before v2.1.207, these fields substituted `${user_config.KEY}` values; update plugins that relied on this.
636
637Non-sensitive values are stored under the [`pluginConfigs`](/docs/en/settings-reference#pluginconfigs) key in your user `settings.json` as `pluginConfigs[<plugin-id>].options`.
638
639On macOS, Claude Code stores sensitive values in the macOS Keychain, falling back to `~/.claude/.credentials.json` when the Keychain rejects the write. On platforms without a supported keychain, it stores them in `~/.claude/.credentials.json`. Keychain storage is shared with OAuth tokens and has an approximately 2 KB total limit, so keep sensitive values small.
640
641Claude Code reads all `pluginConfigs` values from only three settings sources:
642
643* **User settings**: `~/.claude/settings.json`, the file the enable-time prompt writes to
644* **`--settings`**: the CLI flag or SDK inline settings
645* **Managed settings**: [organization-controlled policy](/docs/en/permissions#managed-settings)
646
647When more than one source sets the same key, managed settings take precedence, then `--settings`, then user settings. The only source you can remove from this list is user settings: pass [`--setting-sources`](/docs/en/cli-reference#cli-flags) without `user` and Claude Code skips them. Managed settings and `--settings` stay whatever you pass. The SDK's [`settingSources`](/docs/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) option sets the same list.
648
649Entries in a project's `.claude/settings.json` or `.claude/settings.local.json` are ignored. Both files live in the workspace, so a cloned repository could supply values there, and those values would flow into plugin hook commands, MCP server configs, LSP commands, and monitor commands. Before v2.1.207, these entries were read. The restriction is specific to `pluginConfigs`: [`enabledPlugins`](/docs/en/settings-reference#enabledplugins) still honors project and local settings.
650
651#### Limit a field to fixed options
652
653Set `options` on a `userConfig` field to make users pick its value from a fixed list.
654
655To limit a `tone` field to three options, list them in `options` and set `default` to one of them:
656
657```json theme={null}
658{
659 "userConfig": {
660 "tone": {
661 "type": "string",
662 "title": "Tone",
663 "description": "Voice for generated replies",
664 "options": ["neutral", "warm", "formal"],
665 "default": "neutral"
666 }
667 }
668}
669```
670
671If you declare `options` on any field, users on Claude Code versions before v2.1.271 can't load the plugin.
672
673When you set `options` on a field, follow these rules:
674
675* Set `type` to `string`
676* Don't set `multiple` or `sensitive` to `true`
677* Set `default` to one of the options
678* If you leave `default` unset, set `required` to `true`
679* List at least one option, each 1 to 64 characters long
680* Don't start or end an option with a space
681* Don't use control characters, invisible characters, characters that change text direction, or spaces other than a regular space in an option
682* Don't list the same option twice, even in a different letter case
683
684If you break any of these rules, the plugin fails to load. Run `claude plugin validate` to see which field breaks which rule.
685
686### Channels
687
688The `channels` field lets a plugin declare one or more message channels that inject content into the conversation. Each channel binds to an MCP server that the plugin provides.
689
690```json theme={null}
691{
692 "channels": [
693 {
694 "server": "telegram",
695 "userConfig": {
696 "bot_token": {
697 "type": "string",
698 "title": "Bot token",
699 "description": "Telegram bot token",
700 "sensitive": true
701 },
702 "owner_id": {
703 "type": "string",
704 "title": "Owner ID",
705 "description": "Your Telegram user ID"
706 }
707 }
708 }
709 ]
710}
711```
712
713The `server` field is required and must match a key in the plugin's `mcpServers`. The optional per-channel `userConfig` uses the same schema as the top-level field, letting the plugin prompt for bot tokens or owner IDs when the plugin is enabled.
714
715### Path behavior rules
716
717Whether a custom path replaces or extends the plugin's default directory depends on the field:
718
719* **Replaces the default**: `commands`, `agents`, `workflows`, `outputStyles`, `experimental.themes`, `experimental.monitors`. For example, when the manifest specifies `commands`, the default `commands/` directory is not scanned. To keep the default and add more, list it explicitly: `"commands": ["./commands/", "./extras/"]`
720* **Adds to the default**: `skills`. The default `skills/` directory is always scanned, and directories listed in `skills` are loaded alongside it. Exception: for a [marketplace entry whose `source` resolves to the marketplace root](/docs/en/plugin-marketplaces#advanced-plugin-entries), declaring specific subdirectories replaces the default `skills/` scan
721* **Own merge rules**: [hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers). See each section for how multiple sources combine
722
723When a plugin has both a default folder and the matching manifest key, Claude Code warns about the ignored folder in `claude plugin list` and the `/plugin` detail view. The plugin still loads using the manifest paths. Claude Code doesn't warn when the manifest key points into the default folder, for example `"commands": ["./commands/deploy.md"]`, because that path names the folder explicitly.
724
725For all path fields:
726
727* All paths must be relative to the plugin root and start with `./`, except that the `skills` field also accepts `"."`
728 * Both `"."` and `"./"` denote the plugin root itself
729 * Before v2.1.221, `"."` failed manifest validation and the plugin didn't load, so use `"./"` to support earlier versions
730* Components from custom paths use the same naming and namespacing rules, except agent files. See [Agents](#agents) for how agent names work
731* Multiple paths can be specified as arrays
732* A skill path can point to a directory that contains a `SKILL.md` directly, for example `"skills": ["."]` for the plugin root
733 * Claude Code takes the skill's invocation name from the frontmatter `name` field in `SKILL.md`, so the name stays stable whatever the install directory is named
734 * If `name` isn't set in the frontmatter, Claude Code falls back to the directory basename
735
736A plugin that has a `SKILL.md` at its root, no `skills/` subdirectory, and no `skills` manifest field is automatically loaded as a single-skill plugin. You do not need to set `"skills": ["./"]` in `plugin.json` for this layout.
737
738**Path examples**:
739
740```json theme={null}
741{
742 "commands": [
743 "./specialized/deploy.md",
744 "./utilities/batch-process.md"
745 ],
746 "agents": [
747 "./custom-agents/reviewer.md",
748 "./custom-agents/tester.md"
749 ]
750}
751```
752
753### Environment variables
754
755Claude Code provides three variables for referencing paths:
756
757| Variable | Resolves to | Use it for |
758| :---------------------- | :---------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
759| `${CLAUDE_PLUGIN_ROOT}` | Absolute path to the plugin's installation directory | Scripts, binaries, and config files bundled with the plugin |
760| `${CLAUDE_PLUGIN_DATA}` | [Persistent directory](#persistent-data-directory) that survives plugin updates, created on first reference | Installed dependencies such as `node_modules` or Python virtual environments, generated code, and caches |
761| `${CLAUDE_PROJECT_DIR}` | The project root | Project-local scripts and config files |
762
763All three are exported as environment variables to hook processes and to MCP and LSP server subprocesses. They aren't present in the environment of commands Claude runs through the Bash tool, in the main session or in a subagent. In plugin content, write the placeholder instead, and Claude Code substitutes the path inline when it loads the content. Which fields substitute them inline depends on the plugin component:
764
765| Plugin component | Fields where placeholders resolve |
766| :------------------------------ | :------------------------------------------ |
767| Skill and agent content | Anywhere the placeholder appears |
768| Hook and monitor commands | Anywhere the placeholder appears |
769| MCP `stdio` servers | `command`, `args`, `env` |
770| MCP `http`, `sse`, `ws` servers | `url`, `headers`, `headersHelper` |
771| LSP servers | `command`, `args`, `env`, `workspaceFolder` |
772
773In hook commands, use [exec form](/docs/en/hooks#exec-form-and-shell-form) with `args` so each path is passed as one argument with no quoting. In shell-form hooks and monitor commands, wrap the variables in double quotes, as in `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`. This shell-form hook runs a script bundled with a plugin:
774
775```json theme={null}
776{
777 "hooks": {
778 "PostToolUse": [
779 {
780 "hooks": [
781 {
782 "type": "command",
783 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
784 }
785 ]
786 }
787 ]
788 }
789}
790```
791
792For a copied plugin, `${CLAUDE_PLUGIN_ROOT}` changes when the plugin updates. The previous version's directory remains on disk for a grace period after an update, but treat it as ephemeral and don't write state there. For a plugin loaded in place from a local-directory marketplace, the variable points at the stable source directory. See [plugin caching](#plugin-caching-and-file-resolution) for which plugins are copied and for cleanup semantics.
793
794When a copied plugin updates mid-session, hook commands, monitors, MCP servers, and LSP servers keep using the previous version's path. Run `/reload-plugins` to switch hooks, MCP servers, and LSP servers to the new path; monitors require a session restart. In a session without an interactive terminal, the reload leaves plugin MCP servers on the old path until the next session.
795
796For a plugin with a `command` source, Claude Code [can reload the plugin itself](/docs/en/plugin-marketplaces#when-claude-code-re-runs-the-command).
797
798MCP servers can also call the `roots/list` request to read the session's working directories at runtime. See [what `roots/list` returns and when Claude Code notifies the server of changes](/docs/en/mcp#option-3-add-a-local-stdio-server).
799
800#### Persistent data directory
801
802The `${CLAUDE_PLUGIN_DATA}` directory resolves to `~/.claude/plugins/data/{id}/`, where `{id}` is the plugin identifier with characters outside `a-z`, `A-Z`, `0-9`, `_`, and `-` replaced by `-`. For a plugin installed as `formatter@my-marketplace`, the directory is `~/.claude/plugins/data/formatter-my-marketplace/`.
803
804A common use is installing language dependencies once and reusing them across sessions and plugin updates. Use it for Python dependencies, dependencies locked with Yarn or pnpm, and packages whose lifecycle scripts must run. For a marketplace-installed plugin, you may not need it at all: Claude Code installs eligible [Node.js package dependencies](#node-js-package-dependencies) automatically when it caches the plugin.
805
806Because the data directory outlives any single plugin version, a check for directory existence alone cannot detect when an update changes the plugin's dependency manifest. The recommended pattern compares the bundled manifest against a copy in the data directory and reinstalls when they differ.
807
808This `SessionStart` hook installs `node_modules` on the first run and again whenever a plugin update includes a changed `package.json`:
809
810```json theme={null}
811{
812 "hooks": {
813 "SessionStart": [
814 {
815 "hooks": [
816 {
817 "type": "command",
818 "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
819 }
820 ]
821 }
822 ]
823 }
824}
825```
826
827The `diff` exits nonzero when the stored copy is missing or differs from the bundled one, covering both first run and dependency-changing updates. If `npm install` fails, the trailing `rm` removes the copied manifest so the next session retries.
828
829Scripts bundled in `${CLAUDE_PLUGIN_ROOT}` can then run against the persisted `node_modules`:
830
831```json theme={null}
832{
833 "mcpServers": {
834 "routines": {
835 "command": "node",
836 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
837 "env": {
838 "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
839 }
840 }
841 }
842}
843```
844
845The data directory is deleted automatically when you uninstall the plugin from the last scope where it is installed. The `/plugin` interface shows the directory size and prompts before deleting. The CLI deletes by default; pass [`--keep-data`](#plugin-uninstall) to preserve it.
846
847***
848
849## Plugin caching and file resolution
850
851Plugins are specified in one of three ways:
852
853* Through `claude --plugin-dir` or `claude --plugin-url`, for the duration of a session.
854* Through a marketplace, installed for future sessions.
855* Through your claude.ai account, [synced](#synced-plugins) into `~/.claude/plugins/synced/`.
856
857For security and verification purposes, Claude Code copies *marketplace* plugins to the user's local **plugin cache** (`~/.claude/plugins/cache`), unless the plugin loads in place. A [`command` source in link mode](/docs/en/plugin-marketplaces#copy-mode-and-link-mode) loads in place through links in the cache entry. A [relative path source](/docs/en/plugin-marketplaces#relative-paths) in a marketplace added from a local directory loads in place from the marketplace folder.
858
859For a plugin loaded in place from a local-directory marketplace, your edits to the source directory take effect at the next session start or `/reload-plugins`. You don't need a version bump. The plugin's hook processes and MCP and LSP servers receive a `CLAUDE_PLUGIN_ROOT` that points at the source directory. Claude Code doesn't install the plugin's [Node.js package dependencies](#node-js-package-dependencies) into the source directory. Install them there yourself, or from a hook into the [persistent data directory](#persistent-data-directory).
860
861For copied plugins, each installed version is a separate directory in the cache, grouped by marketplace and plugin and named for the resolved version, with its own copy of the plugin's files and [Node.js package dependencies](#node-js-package-dependencies). A dependency resolved from a [release tag](/docs/en/plugin-dependencies#tag-plugin-releases-for-version-resolution) gets a directory name with a commit-SHA suffix.
862
863When you update or uninstall a plugin, Claude Code marks the previous version directory as orphaned and removes it in a background sweep roughly 14 days later. The grace period lets concurrent Claude Code sessions that already loaded the old version keep running without errors. Claude Code runs the sweep only while at least one plugin is installed; after you uninstall your last plugin, orphaned directories stay on disk until you install a plugin again.
864
865Claude Code removes a plugin or marketplace folder from the cache only when it no longer contains any directory or symlink. If you symlink a development checkout into the cache as a plugin's version entry, Claude Code never marks the link as orphaned and never removes it or the folders that hold it. Claude Code also never writes its version-tracking files inside the linked checkout.
866
867Claude's Glob and Grep tools skip orphaned version directories during searches, so file results don't include outdated plugin code.
868
869### Node.js package dependencies
870
871When Claude Code copies a plugin into the cache, it also installs the plugin's Node.js package dependencies there, so the plugin's hooks and MCP servers can load them. This section covers the npm and Bun packages a plugin declares in its own `package.json`. For plugins that depend on other plugins, see [plugin dependency versions](/docs/en/plugin-dependencies).
872
873Claude Code runs the install inside the copied version directory each time it creates one: when you install a plugin, when Claude Code updates a plugin to a new version, and at session start when an enabled plugin isn't cached yet, such as on a new machine. The install runs only when the plugin's root directory contains both a `package.json` and a supported lockfile:
874
875| Lockfile | Command |
876| :------------------------------------------- | :----------------------------------------------- |
877| `bun.lock` or `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |
878| `npm-shrinkwrap.json` or `package-lock.json` | `npm ci --ignore-scripts` |
879
880If 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`.
881
882Claude Code skips the install in two cases, each with its own fix:
883
884* If your plugin ships only a `yarn.lock` or `pnpm-lock.yaml`, replace it with an npm lockfile.
885* If a `bunfig.toml` sits beside the bun lockfile, remove the `bunfig.toml`, or replace the bun lockfile with an npm lockfile.
886
887Ship an npm lockfile for the widest reach. Claude Code runs the matched lockfile's package manager from the user's PATH and doesn't fall back to the other lockfile if it's missing. For a plugin distributed through an npm source, use `npm-shrinkwrap.json`; npm excludes `package-lock.json` from published packages.
888
889Claude Code constrains this dependency install so that no code from the plugin or its packages executes during it, and bounds how long it can run:
890
891* **Frozen resolution:** Bun and npm install exactly what the lockfile pins, and fail rather than re-resolve versions when `package.json` and the lockfile disagree.
892* **No lifecycle scripts:** `--ignore-scripts` keeps `preinstall`, `install`, and `postinstall` scripts from running, so dependencies that build native modules in those scripts download but don't compile during this install.
893* **60-second timeout:** Claude Code stops an install that runs longer and treats it as failed.
894
895Claude Code fetches an npm-source plugin before this dependency install, and none of the package's own install scripts run during the fetch. See [npm packages](/docs/en/plugin-marketplaces#npm-packages).
896
897A failed or skipped install never blocks the plugin. When the install fails, or Claude Code skips it because of a yarn or pnpm lockfile or a `bunfig.toml`, it records the reason as a warning in [debug output](#debugging-commands). A plugin with a `package.json` and no lockfile is skipped without a log entry. A timed-out install can leave a partial `node_modules` tree in the cached copy.
898
899You can't turn the automatic install off; no setting or environment variable disables it. In restricted networks, see the [network access requirements](/docs/en/network-config#network-access-requirements) for the hosts to allow.
900
901For dependencies the automatic install can't provide, such as packages that need their lifecycle scripts to build, Python dependencies, or a plugin locked with Yarn or pnpm, install them from a hook into the [persistent data directory](#persistent-data-directory).
902
903### Path traversal limitations
904
905Claude Code doesn't let a plugin reference files outside its own directory. It rejects a component path that resolves outside the plugin root, whether the path is declared in `plugin.json` or in a [marketplace entry](/docs/en/plugin-marketplaces#plugin-entries). That covers a path that points outside the plugin as written, such as `../shared-utils`, and a symlink that leads outside the plugin, other than [links within one marketplace](#share-files-within-a-marketplace-with-symlinks).
906
907On macOS and Linux, Claude Code also rejects a component path that contains a backslash anywhere in it, even when the path stays inside the plugin. Components declared with backslash paths therefore load on Windows only. Write component paths with forward slashes, such as `./commands/deploy.md`.
908
909When Claude Code rejects a path, it reports a [`path escapes plugin directory`](/docs/en/errors#path-escapes-plugin-directory) error and loads the plugin without that component.
910
911Claude Code also doesn't copy files outside the plugin directory into the cache when it installs the plugin, so when a script inside a copied plugin reads a path above the plugin root, it doesn't find those files either.
912
913### Share files within a marketplace with symlinks
914
915If your plugin needs to share files with other parts of the same marketplace, you can create symbolic links inside your plugin directory. How a symlink is handled when the plugin is copied into the cache depends on where its target resolves:
916
917* **Within the plugin's own directory:** the symlink is preserved as a relative symlink in the cache, so it keeps resolving to the copied target at runtime.
918* **Elsewhere within the same marketplace:** the symlink is dereferenced. The target's content is copied into the cache in its place. This lets a meta-plugin's `skills/` directory link to skills defined by other plugins in the marketplace.
919* **Outside the marketplace:** the symlink is skipped for security. This prevents plugins from pulling arbitrary host files such as system paths into the cache.
920
921For plugins installed with `--plugin-dir`, from a local path, or from a [`command` source](/docs/en/plugin-marketplaces#copy-mode-and-link-mode) in copy mode, only symlinks that resolve within the plugin's own directory are preserved. All others are skipped.
922
923The following command creates a link from inside a marketplace plugin to a shared skill defined by a sibling plugin. On Windows, use `mklink /D` from an elevated Command Prompt or enable Developer Mode:
924
925```bash theme={null}
926ln -s ../../shared-plugin/skills/foo ./skills/foo
927```
928
929***
930
931## Plugin directory structure
932
933### Standard plugin layout
934
935A complete plugin follows this structure:
936
937```text theme={null}
938enterprise-plugin/
939├── .claude-plugin/ # Metadata directory (optional)
940│ └── plugin.json # plugin manifest
941├── skills/ # Skills
942│ ├── code-reviewer/
943│ │ └── SKILL.md
944│ └── pdf-processor/
945│ ├── SKILL.md
946│ └── scripts/
947├── commands/ # Skills as flat .md files
948│ ├── status.md
949│ └── logs.md
950├── agents/ # Subagent definitions
951│ ├── security-reviewer.md
952│ ├── performance-tester.md
953│ ├── compliance-checker.md
954│ └── review/ # Agents here load as enterprise-plugin:review:<name>
955│ └── accessibility.md
956├── workflows/ # Workflow scripts
957│ └── release-audit.js
958├── output-styles/ # Output style definitions
959│ └── terse.md
960├── themes/ # Color theme definitions
961│ └── dracula.json
962├── monitors/ # Background monitor configurations
963│ └── monitors.json
964├── hooks/ # Hook configurations
965│ ├── hooks.json # Main hook config
966│ └── security-hooks.json # Additional hooks
967├── bin/ # Plugin executables added to PATH
968│ └── my-tool # Invokable as bare command in Bash tool
969├── settings.json # Default settings for the plugin
970├── .mcp.json # MCP server definitions
971├── .lsp.json # LSP server configurations
972├── scripts/ # Hook and utility scripts
973│ ├── security-scan.sh
974│ ├── format-code.py
975│ └── deploy.js
976├── LICENSE # License file
977└── CHANGELOG.md # Version history
978```
979
980<Warning>
981 The `.claude-plugin/` directory contains the `plugin.json` file. All other directories (commands/, agents/, skills/, workflows/, output-styles/, themes/, monitors/, hooks/) must be at the plugin root, not inside `.claude-plugin/`.
982</Warning>
983
984A `CLAUDE.md` file at the plugin root is not loaded as project context. Plugins contribute context through skills, agents, and hooks rather than CLAUDE.md. To ship instructions that load into Claude's context, put them in a [skill](#skills).
985
986### File locations reference
987
988| Component | Default Location | Purpose |
989| :---------------- | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
990| **Manifest** | `.claude-plugin/plugin.json` | Plugin metadata and configuration (optional) |
991| **Skills** | `skills/` | Skills with `<name>/SKILL.md` structure |
992| **Commands** | `commands/` | Skills as flat Markdown files. Use `skills/` for new plugins |
993| **Agents** | `agents/` | Subagent Markdown files. Subfolders are part of the [agent name](#agents) |
994| **Workflows** | `workflows/` | [Workflow](/docs/en/workflows) script files |
995| **Output styles** | `output-styles/` | Output style definitions |
996| **Themes** | `themes/` | Color theme definitions |
997| **Hooks** | `hooks/hooks.json` | Hook configuration |
998| **MCP servers** | `.mcp.json` | MCP server definitions |
999| **LSP servers** | `.lsp.json` | Language server configurations |
1000| **Monitors** | `monitors/monitors.json` | Background monitor configurations |
1001| **Executables** | `bin/` | Executables added to the Bash tool's `PATH` and invokable as bare commands while the plugin is enabled. You can't include this directory in a plugin you [distribute through claude.ai organization settings](/docs/en/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory) |
1002| **Settings** | `settings.json` | Default configuration applied when the plugin is enabled. Only the [`agent`](/docs/en/sub-agents) and [`subagentStatusLine`](/docs/en/statusline#subagent-status-lines) keys are supported |
1003
1004***
1005
1006## CLI commands reference
1007
1008Claude Code provides CLI commands for non-interactive plugin management, useful for scripting and automation.
1009
1010### plugin init
1011
1012Scaffold a new plugin at `~/.claude/skills/<name>/`. On the next Claude Code session it loads automatically as `<name>@skills-dir` and appears in `/plugin` and `claude plugin list` with no install step.
1013
1014See [Skills-directory plugins](#skills-directory-plugins) for scope and trust requirements.
1015
1016```bash theme={null}
1017claude plugin init <name> [options]
1018```
1019
1020The command takes these arguments:
1021
1022* `<name>`: Plugin name. Becomes the skill namespace and the directory name under `~/.claude/skills/`, so it cannot contain spaces or path separators.
1023
1024The command accepts these options:
1025
1026| Option | Description | Default |
1027| :----------------------- | :------------------------------------------------------------------------------------------------------------------ | :---------------------- |
1028| `--description <text>` | Manifest description | |
1029| `--author <name>` | Author name | `git config user.name` |
1030| `--author-email <email>` | Author email | `git config user.email` |
1031| `--with <components...>` | Also scaffold component folders. Valid values: `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, `channel` | |
1032| `-f, --force` | Overwrite an existing `.claude-plugin/` at the target | |
1033| `-h, --help` | Display help for command | |
1034
1035`claude plugin new` is an alias for this command.
1036
1037Each `--with` value adds a starter file for that component, ready to edit:
1038
1039| Component | What it scaffolds |
1040| :------------- | :-------------------------------------------------------------------------------------------------------- |
1041| `skills` | An extra namespaced `<name>:example` skill alongside the default one |
1042| `agents` | An `agents/` subagent definition |
1043| `hooks` | A `hooks/hooks.json` with a sample event handler |
1044| `mcp` | A `.mcp.json` with HTTP and stdio server examples |
1045| `lsp` | A `.lsp.json` language-server example |
1046| `output-style` | An `output-styles/<name>.md` that applies automatically while the plugin is enabled |
1047| `channel` | An MCP-based [channel](/docs/en/channels): a stdio server (`server.ts`), its `.mcp.json`, and a `package.json` |
1048
1049The scaffolded plugin uses the `@skills-dir` source rather than a marketplace. Admins can block this source with `strictKnownMarketplaces` or by adding `{"source": "skills-dir"}` to `blockedMarketplaces` in [managed settings](/docs/en/plugin-marketplaces#managed-marketplace-restrictions). When blocked, `plugin init` fails before writing.
1050
1051These examples show common invocations:
1052
1053```bash theme={null}
1054# Scaffold a minimal plugin
1055claude plugin init my-helper
1056
1057# Scaffold with skill and hook folders
1058claude plugin init my-helper --with skills hooks
1059
1060# Overwrite an existing scaffold
1061claude plugin init my-helper --force
1062```
1063
1064### plugin install
1065
1066Install a plugin from available marketplaces.
1067
1068```bash theme={null}
1069claude plugin install <plugin> [options]
1070```
1071
1072The command takes these arguments:
1073
1074* `<plugin>`: Plugin name or `plugin-name@marketplace-name` for a specific marketplace
1075
1076The command accepts these options:
1077
1078| Option | Description | Default |
1079| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
1080| `-s, --scope <scope>` | Installation scope: `user`, `project`, or `local` | `user` |
1081| `--config <key=value>` | Set a [`userConfig`](#user-configuration) option declared in the plugin's manifest. Repeat the flag to set multiple options | |
1082| `-y, --yes` | Accept a command the plugin's marketplace declares, without the confirmation prompt: the command that produces a plugin with a [`command` source](/docs/en/plugin-marketplaces#command-sources), or the [`headersHelper`](/docs/en/plugin-marketplaces#authenticate-archive-downloads) that authenticates an archive download. Accepting a `headersHelper` requires Claude Code v2.1.238 or later. Claude Code still prints the command first. Required when stdin or stdout isn't a TTY, unless you pass `--accept-command`. Has no effect inside a Claude Code session, so run the command from your own terminal | |
1083| `--accept-command <sha256>` | Accept the marketplace-declared command whose `sha256` a previous [`--json` run](#plugin-json-result) reported in `shownCommand`, in place of `-y`. The acceptance counts for exactly that command, plugin, and marketplace catalog. If any of them changed since the command was displayed, including through the run's own marketplace refresh, Claude Code doesn't accept the digest and shows the command again. Can't be combined with `-y`. Has no effect inside a Claude Code session, so run the command from your own terminal. Requires Claude Code v2.1.271 or later | |
1084| `--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 | |
1085| `-h, --help` | Display help for command | |
1086
1087Scope determines which settings file the installed plugin is added to. For example, `--scope project` writes to `enabledPlugins` in .claude/settings.json, making the plugin available to everyone who clones the project repository.
1088
1089<span id="plugin-json-result" />With `--json`, the last line of stdout is one JSON object. Parse only that line, because Claude Code prints any command the marketplace declares ahead of it. Three fields are always present:
1090
1091* `command`: the subcommand that ran, such as `install`
1092* `outcome`: `ok` or `failed`
1093* `message`: a human-readable description of the result
1094
1095Other fields, such as `pluginId`, `scope`, and `failureCode`, appear only when they apply. The `--json` option on `plugin uninstall`, `plugin update`, `plugin enable`, and `plugin disable` prints the same object with that subcommand's own fields. A usage error, such as an invalid `--scope`, prints no result line and exits 1 with the reason on stderr.
1096
1097When a run displays a marketplace-declared command and doesn't run it, the `failed` result also carries a `shownCommand` object whose fields include the command as displayed, the plugin it belongs to, and the command's `sha256`. To accept exactly that command, re-run with that `sha256` as `--accept-command`. Requires Claude Code v2.1.271 or later.
1098
1099If `shownCommand.acceptCommandMatched` is `false`, the digest you passed doesn't match the command now displayed. Show that command to a person before passing its `sha256`.
1100
1101These examples show common invocations:
1102
1103```bash theme={null}
1104# Install to user scope (default)
1105claude plugin install formatter@my-marketplace
1106
1107# Install to project scope (shared with team)
1108claude plugin install formatter@my-marketplace --scope project
1109
1110# Install to local scope (not shared with team)
1111claude plugin install formatter@my-marketplace --scope local
1112```
1113
1114### plugin uninstall
1115
1116Remove an installed plugin.
1117
1118```bash theme={null}
1119claude plugin uninstall <plugin> [options]
1120```
1121
1122The command takes these arguments:
1123
1124* `<plugin>`: Plugin name or `plugin-name@marketplace-name`
1125
1126The command accepts these options:
1127
1128| Option | Description | Default |
1129| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
1130| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local` | `user` |
1131| `--keep-data` | Preserve the plugin's [persistent data directory](#persistent-data-directory) | |
1132| `--prune` | Also remove auto-installed dependencies that no other plugin requires. See [plugin prune](#plugin-prune) | |
1133| `-y, --yes` | Skip the `--prune` confirmation prompt. Required when stdin or stdout is not a TTY | |
1134| `--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 | |
1135| `-h, --help` | Display help for command | |
1136
1137`claude plugin remove` and `claude plugin rm` are aliases for this command.
1138
1139By default, uninstalling from the last remaining scope also deletes the plugin's `${CLAUDE_PLUGIN_DATA}` directory. Use `--keep-data` to preserve it, for example when reinstalling after testing a new version.
1140
1141<Note>
1142 When installed plugins from different marketplaces share a name, the `plugin-name@marketplace-name` form uninstalls only the plugin from the named marketplace. Before v2.1.212, the qualified form could match and uninstall the same-named plugin from a different marketplace.
1143</Note>
1144
1145### plugin prune
1146
1147Remove auto-installed plugin dependencies that are no longer required by any installed plugin. Dependencies that Claude Code pulled in to satisfy another plugin's [`dependencies`](/docs/en/plugin-dependencies) field are removed; plugins you installed directly are never touched.
1148
1149```bash theme={null}
1150claude plugin prune [options]
1151```
1152
1153The command accepts these options:
1154
1155| Option | Description | Default |
1156| :-------------------- | :----------------------------------------------------------------------- | :------ |
1157| `-s, --scope <scope>` | Prune at scope: `user`, `project`, or `local` | `user` |
1158| `--dry-run` | List what would be removed without removing anything | |
1159| `-y, --yes` | Skip the confirmation prompt. Required when stdin or stdout is not a TTY | |
1160| `-h, --help` | Display help for command | |
1161
1162`claude plugin autoremove` is an alias for this command.
1163
1164The command lists orphaned dependencies and asks for confirmation before removing them. To remove a plugin and clean up its dependencies in one step, run `claude plugin uninstall <plugin> --prune`.
1165
1166### plugin enable
1167
1168Enable a disabled plugin. When the target is installed from a marketplace and declares [dependencies](/docs/en/plugin-dependencies), Claude Code enables them transitively at the same scope. The command fails under the conditions that [Enable or disable a plugin with dependencies](/docs/en/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) lists.
1169
1170```bash theme={null}
1171claude plugin enable <plugin> [options]
1172```
1173
1174The command takes these arguments:
1175
1176* `<plugin>`: Plugin name, `plugin-name@marketplace-name`, or `plugin-name@synced` for a [plugin synced from claude.ai](#synced-plugins)
1177
1178The command accepts these options:
1179
1180| Option | Description | Default |
1181| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |
1182| `-s, --scope <scope>` | Scope to enable: `user`, `project`, or `local`. When omitted, Claude Code detects the scope where the plugin is installed | Auto-detect |
1183| `--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 | |
1184| `-h, --help` | Display help for command | |
1185
1186### plugin disable
1187
1188Disable a plugin without uninstalling it.
1189
1190When the target is installed from a marketplace, the command fails if another enabled plugin [depends on](/docs/en/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) it. The error message includes a chained command that disables every dependent first.
1191
1192For a [synced plugin](#synced-plugins) that your organization requires, the command fails and saves nothing.
1193
1194```bash theme={null}
1195claude plugin disable [plugin] [options]
1196```
1197
1198The command takes these arguments:
1199
1200* `[plugin]`: Plugin name, `plugin-name@marketplace-name`, or `plugin-name@synced` for a [plugin synced from claude.ai](#synced-plugins). Optional when using `--all`
1201
1202The command accepts these options:
1203
1204| Option | Description | Default |
1205| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |
1206| `-a, --all` | Disable all enabled plugins. Can't be combined with `--scope` | |
1207| `-s, --scope <scope>` | Scope to disable: `user`, `project`, or `local`. When omitted, Claude Code detects the scope where the plugin is installed | Auto-detect |
1208| `--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 | |
1209| `-h, --help` | Display help for command | |
1210
1211### plugin update
1212
1213Update a plugin to the latest version.
1214
1215```bash theme={null}
1216claude plugin update <plugin> [options]
1217```
1218
1219The command takes these arguments:
1220
1221* `<plugin>`: Plugin name or `plugin-name@marketplace-name`
1222
1223The command accepts these options:
1224
1225| Option | Description | Default |
1226| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
1227| `-s, --scope <scope>` | Scope to update: `user`, `project`, `local`, or `managed` | `user` |
1228| `-y, --yes` | Accept a command the plugin's marketplace declares, without the confirmation prompt: the command that produces a plugin with a [`command` source](/docs/en/plugin-marketplaces#command-sources), or the [`headersHelper`](/docs/en/plugin-marketplaces#authenticate-archive-downloads) that authenticates an archive download. Accepting a `headersHelper` requires Claude Code v2.1.238 or later. Claude Code still prints the command first. Required when stdin or stdout isn't a TTY, unless you pass `--accept-command`. Has no effect inside a Claude Code session, so run the command from your own terminal | |
1229| `--accept-command <sha256>` | Accept the marketplace-declared command whose `sha256` a previous [`--json` run](#plugin-json-result) reported in `shownCommand`, in place of `-y`. The acceptance counts for exactly that command, plugin, and marketplace catalog. If any of them changed since the command was displayed, including through the run's own marketplace refresh, Claude Code doesn't accept the digest and shows the command again. Can't be combined with `-y`. Has no effect inside a Claude Code session, so run the command from your own terminal. Requires Claude Code v2.1.271 or later | |
1230| `--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 | |
1231| `-h, --help` | Display help for command | |
1232
1233<Note>
1234 Claude Code resolves a bare plugin name against your installed plugins. When installed plugins from different marketplaces share the name, Claude Code refuses the update and lists the qualified `plugin-name@marketplace-name` commands to run instead. Before v2.1.246, Claude Code accepted only the qualified form and rejected a bare name as not found.
1235</Note>
1236
1237***
1238
1239### plugin list
1240
1241List installed plugins with their version, source marketplace, and enable status.
1242
1243```bash theme={null}
1244claude plugin list [options]
1245```
1246
1247The command accepts these options:
1248
1249| Option | Description | Default |
1250| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
1251| `--json` | Output as JSON. A plugin row with load problems or authoring warnings carries `errors` or `notes` string arrays. On Claude Code v2.1.268 or later, parallel `errorDetails` and `noteDetails` arrays give each entry's diagnostic `type` and the names it refers to, such as the plugin, marketplace, server, or file | |
1252| `--available` | Include available plugins from marketplaces. Requires `--json` | |
1253| `-h, --help` | Display help for command | |
1254
1255Within an interactive session, `/plugin list` prints a similar listing inline, but it covers marketplace-installed plugins only:
1256
1257* Plugins loaded from skills directories appear in the `/plugin` interface and in `claude plugin list`, but not in the inline `/plugin list` output.
1258* [Plugins synced from claude.ai](#synced-plugins) appear in `claude plugin list` on Claude Code v2.1.239 or later and in the `/plugin` interface, but not in the inline `/plugin list` output.
1259* Plugins loaded for the session with `--plugin-dir` or `--plugin-url` appear in the `/plugin` interface, and in `claude plugin list` only when the same flag precedes the subcommand, as in `claude --plugin-dir <dir> plugin list`. Only the flag names their location, so a bare `claude plugin list` can't find them, unlike synced plugins and skills-directory plugins, whose fixed directories Claude Code scans.
1260
1261The interactive form accepts `--enabled` or `--disabled` to show only plugins in that state, and `ls` as a shorthand for `list`.
1262
1263### plugin details
1264
1265Show a plugin's component inventory and projected token cost. The output lists all components the plugin contributes, grouped as Skills, Agents, Hooks, MCP servers, and LSP servers, along with an estimate of how many tokens it adds to each session. The Skills group includes both `skills/` and `commands/` entries.
1266
1267```bash theme={null}
1268claude plugin details <name>
1269```
1270
1271The command takes these arguments:
1272
1273* `<name>`: Plugin name or `plugin-name@marketplace-name`
1274
1275The command accepts these options:
1276
1277| Option | Description | Default |
1278| :----------- | :----------------------- | :------ |
1279| `-h, --help` | Display help for command | |
1280
1281The output shows two cost figures for each component:
1282
1283* **Always-on:** tokens added to every session by the plugin's listing text, such as skill descriptions, agent descriptions, and command names, regardless of whether any component fires.
1284* **On-invoke:** tokens a component costs when it fires. Shown per component, not as a plugin total, because a typical session invokes only a subset of components.
1285
1286This example shows what the output looks like for a plugin with two skills:
1287
1288```
1289dependency-guard 1.2.0
1290 Dependency analysis for Claude Code sessions
1291 Source: dependency-guard@example-marketplace
1292
1293Component inventory
1294 Skills (2) scan-dependencies, review-changes
1295 Agents (0)
1296 Hooks (1) SessionStart (harness-only — no model context cost)
1297 MCP servers (0)
1298 LSP servers (0)
1299
1300Projected token cost
1301 Always-on: ~180 tok added to every session
1302
1303Per-component (rounded)
1304 component always-on on-invoke
1305 scan-dependencies ~100 ~2400
1306 review-changes ~80 ~1800
1307
1308 On-invoke cost is paid each time a skill or agent fires.
1309 Token counts are estimates and may differ from actual usage.
1310```
1311
1312The always-on total is computed via the `count_tokens` API for your active model. Per-component numbers are proportionally scaled from that total. If the API is unreachable, the command falls back to a character-based estimate.
1313
1314### plugin validate
1315
1316Check a plugin or a marketplace for syntax and schema errors before publishing.
1317
1318The command exits 0 when validation passes, 1 when it fails, and 2 when the validation run itself fails, such as when the path you pass is unreadable.
1319
1320```bash theme={null}
1321claude plugin validate <path> [options]
1322```
1323
1324The command takes these arguments:
1325
1326* `<path>`: Path to a plugin directory or a marketplace directory. See [Validate a plugin or a directory without a manifest](/docs/en/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) for which files a plugin run covers.
1327
1328The command accepts these options:
1329
1330| Option | Description | Default |
1331| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |
1332| `--strict` | Treat warnings as errors and exit 1 on them. Use in CI to catch issues the runtime tolerates, such as [unrecognized fields](#unrecognized-fields) | |
1333| `--json` | Output the validation report as one JSON object with the same exit codes. Requires Claude Code v2.1.259 or later | |
1334| `-h, --help` | Display help for command | |
1335
1336With `--json`, Claude Code writes the report to stdout as one JSON object with these top-level fields:
1337
1338* `success`: the same verdict the exit code gives
1339* `strict`: whether the run treated warnings as errors
1340* `target`: the resolved path Claude Code validated
1341* `manifest`: the manifest's own result, or `null` for a [run without a manifest](/docs/en/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)
1342* `contents`: per-file results, each naming its `file` and carrying `errors`, `warnings`, and `notes` arrays
1343
1344On exit 2, the command writes nothing to stdout; the error message goes to stderr.
1345
1346Within an interactive session, `/plugin validate <path>` runs the same checks inline.
1347
1348### plugin eval
1349
1350Run a plugin's [eval cases](/docs/en/plugin-evals) and report scored results. Requires Claude Code v2.1.269 or later. Each case is a prompt plus graders; Claude Code runs it several times in an isolated session with only the target plugin loaded, and by default also without the plugin so the report shows the difference. See [Test plugins with evals](/docs/en/plugin-evals) for the case format, graders, results, and CI usage.
1351
1352```bash theme={null}
1353claude plugin eval [target] [options]
1354```
1355
1356The optional `target` is a plugin directory, a single `prompt.md` or `case.yaml` file, an installed plugin as `name` or `name@marketplace`, or `name@skills-dir`, and defaults to the current directory. Put it before `--tag`, `--allow-tools`, and `--json`.
1357
1358This 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`.
1359
1360| Option | Description | Default |
1361| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
1362| `--runs <n>` | Runs per case per arm | Each case's `runs`, else 3 |
1363| `-j, --concurrency <n>` | Agent sessions to run at once, 1 to 8. They share your rate limit | `1` |
1364| `--model <model>` | Model for the agent under test | Each case's `model`, else `ANTHROPIC_MODEL` if set, else Claude Code's default |
1365| `--judge-model <model>` | Model for `llm` and `baseline` graders | A small fast model |
1366| `--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` |
1367| `--threshold <0..1>` | Exit 1 if any case scores below this | `1.0` |
1368| `--max-cost-usd <usd>` | Stop before the next run once spend reaches this, exit 2, and report partial results | No ceiling |
1369| `--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) | |
1370| `--scaffold` | Run each case's [`scaffold_script`](/docs/en/plugin-evals#add-setup-or-history-with-case-yaml) | Off |
1371| `--trust-plugin` | Skip the first-run trust prompt, for CI. See [What a run can access](/docs/en/plugin-evals#security) | Off |
1372| `--mocks <mode>` | `record` or `off`. See [Mock MCP servers](/docs/en/plugin-evals#mock-mcp-servers) | `record` |
1373| `--eval-dir <dir>` | Directory below the plugin that holds the cases | The manifest's `experimental.evals`, else `evals` |
1374| `--json [path]` | Print the [result document](/docs/en/plugin-evals#json-result) to stdout, or write it to a `.json` path | |
1375| `--no-publish` | Keep the HTML report local | |
1376| `-h, --help` | Display help for command | |
1377
1378The command exits 0 when every case meets the threshold, 1 on a failing case, a load error, or an untrusted plugin directory, 2 on a partial run, 130 when interrupted, and 143 when terminated. See [Run evals in CI](/docs/en/plugin-evals#run-evals-in-ci).
1379
1380### plugin eval init
1381
1382Create an eval suite for the plugin in the current directory. Requires Claude Code v2.1.269 or later. In a terminal this starts an authoring interview that reads the plugin, proposes cases and graders, pilots them, and writes the files. With `--bare`, or without a terminal, it writes a blank single-case template instead. Run from inside an interactive Claude Code session, it prints the interview instructions for that session to follow rather than writing a template. See [Create your first eval suite](/docs/en/plugin-evals#create-your-first-eval-suite).
1383
1384```bash theme={null}
1385claude plugin eval init [name] [options]
1386```
1387
1388The optional `name` is a case name: the interview doesn't need one, while `--bare` and the no-terminal template path require it. It accepts these options:
1389
1390| Option | Description | Default |
1391| :------------------ | :------------------------------------------------------------------------------------------------ | :------------------------------------------------ |
1392| `--bare` | Write a blank `prompt.md` and `graders/criteria.md` for `<name>` instead of running the interview | |
1393| `-i, --interactive` | Require the interview. Fails without a terminal instead of writing a template | |
1394| `--eval-dir <dir>` | Directory below the current directory to write cases into | The manifest's `experimental.evals`, else `evals` |
1395| `-h, --help` | Display help for command | |
1396
1397### plugin tag
1398
1399Create a release git tag for a plugin. By default the command tags the plugin in the current directory; pass a path to tag a plugin elsewhere. See [Tag plugin releases](/docs/en/plugin-dependencies#tag-plugin-releases-for-version-resolution).
1400
1401```bash theme={null}
1402claude plugin tag [path] [options]
1403```
1404
1405The command takes these arguments:
1406
1407* `[path]`: Path to the plugin directory. Defaults to the current directory.
1408
1409The command accepts these options:
1410
1411| Option | Description | Default |
1412| :-------------------- | :------------------------------------------------------------------------- | :------- |
1413| `--push` | Push the tag to the remote after creating it | |
1414| `--dry-run` | Print what would be tagged without creating the tag | |
1415| `-f, --force` | Create the tag even if the working tree is dirty or the tag already exists | |
1416| `-m, --message <msg>` | Tag annotation message. Use `%s` as a placeholder for the version | |
1417| `--remote <name>` | Remote to push to with `--push` | `origin` |
1418| `-h, --help` | Display help for command | |
1419
1420***
1421
1422## Debugging and development tools
1423
1424### Debugging commands
1425
1426Use `claude --debug` to see plugin loading details:
1427
1428This shows:
1429
1430* Which plugins are being loaded
1431* Any errors in plugin manifests
1432* Skill, agent, and hook registration
1433* MCP server initialization
1434
1435### Common issues
1436
1437| Issue | Cause | Solution |
1438| :---------------------------------- | :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1439| Plugin not loading | Invalid `plugin.json` | Run `claude plugin validate ./my-plugin` or `/plugin validate ./my-plugin`, where `./my-plugin` is your plugin directory, to check `plugin.json`, `hooks/hooks.json`, and the frontmatter of the skills, agents, and commands in the plugin's default directories for syntax and schema errors. See [Validate a plugin or a directory without a manifest](/docs/en/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) for what a run covers |
1440| Skills not appearing | Wrong directory structure | Ensure `skills/` or `commands/` is at the plugin root, not inside `.claude-plugin/` |
1441| Hooks not firing | Script not executable | Run `chmod +x script.sh` |
1442| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |
1443| Path errors | Absolute paths used | Make paths relative, starting with `./`; see [Path behavior rules](#path-behavior-rules), which cover the `skills` field's `"."` exception |
1444| LSP `Executable not found in $PATH` | Language server not installed | Install the binary (for example, `npm install -g typescript-language-server typescript`) |
1445
1446### Example error messages
1447
1448**Manifest validation errors**:
1449
1450* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: check for missing commas, extra commas, or unquoted strings
1451* `Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined`: a required field is missing
1452* `Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`: JSON syntax error. Before v2.1.246, Claude Code also produced this error for a `plugin.json` saved as UTF-8 with a leading byte-order mark (BOM), even when the JSON was otherwise valid.
1453
1454**Plugin loading errors**:
1455
1456* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: command path exists but contains no valid command files
1457* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: the `source` path in marketplace.json points to a non-existent directory
1458* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: remove duplicate component definitions or remove `strict: false` in marketplace entry
1459
1460### Hook troubleshooting
1461
1462**Hook script not executing**:
1463
14641. Check the script is executable: `chmod +x ./scripts/your-script.sh`
14652. Verify the shebang line: First line should be `#!/bin/bash` or `#!/usr/bin/env bash`
14663. Check the path uses `${CLAUDE_PLUGIN_ROOT}`: `"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`
14674. Test the script manually: `./scripts/your-script.sh`
1468
1469**Hook not triggering on expected events**:
1470
14711. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse`
14722. Check the matcher pattern matches your tools: `"matcher": "Write|Edit"` for file operations
14733. Confirm the hook type is valid: `command`, `http`, `mcp_tool`, `prompt`, or `agent`
1474
1475### MCP server troubleshooting
1476
1477**Server not starting**:
1478
14791. Check the command exists and is executable
14802. Verify all paths use `${CLAUDE_PLUGIN_ROOT}` variable
14813. Check the MCP server logs: `claude --debug` shows initialization errors
14824. Test the server manually outside of Claude Code
1483
1484**Server tools not appearing**:
1485
14861. Ensure the server is properly configured in `.mcp.json` or `plugin.json`
14872. Verify the server implements the MCP protocol correctly
14883. Check for connection timeouts in debug output
1489
1490### Directory structure mistakes
1491
1492**Symptoms**: Plugin loads but components (skills, agents, hooks) are missing.
1493
1494**Correct structure**: Components must be at the plugin root, not inside `.claude-plugin/`. Only `plugin.json` belongs in `.claude-plugin/`.
1495
1496**Debug checklist**:
1497
14981. Run `claude --debug` and look for "loading plugin" messages
14992. Check that each component directory is listed in the debug output
15003. Verify file permissions allow reading the plugin files
1501
1502***
1503
1504## Distribution and versioning reference
1505
1506### Version management
1507
1508Claude Code uses the plugin's version as the cache key that determines whether an update is available. When you run `/plugin update` or auto-update fires, Claude Code computes the current version and skips the update if it matches what's already installed. A plugin [loaded in place](#plugin-caching-and-file-resolution) from a local-directory marketplace loads its current source files at every session start, whatever its version string says.
1509
1510For every source type except `command`, Claude Code resolves the version from the first of these that is set:
1511
15121. The `version` field in the plugin's `plugin.json`
15132. The `version` field in the plugin's marketplace entry in `marketplace.json`
15143. The git commit SHA of the plugin's source, for `github`, `url`, `git-subdir`, and relative-path sources in a git-hosted marketplace
15154. The SHA-256 digest, for [`archive` sources](/docs/en/plugin-marketplaces#zip-archives): the `sha256` pin in the marketplace entry, or the digest of the downloaded file when you set no pin. Claude Code shortens it to the first 12 characters
15165. `unknown`, for `npm` sources, or for local directories when neither the plugin directory nor its marketplace is a git repository. Claude Code doesn't take the version from a repository that encloses the install path, such as a git-managed `~/.claude`
1517
1518For a [`command` source](/docs/en/plugin-marketplaces#command-sources), Claude Code always derives the version from what the command produced: a 12-character content hash on its own, or appended to the `plugin.json` version as `<version>-<hash>` when one is set. Claude Code ignores the marketplace entry's `version` field for command sources. A command whose hashed output changes therefore produces a new version, even when the authored version string stays the same. In [link mode](/docs/en/plugin-marketplaces#copy-mode-and-link-mode), the hash covers the printed directory's real path and its top-level entries rather than the file contents.
1519
1520For those source types, this gives you three ways to version a plugin:
1521
1522| Approach | How | Update behavior | Best for |
1523| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- |
1524| **Explicit version** | Set `"version": "2.1.0"` in `plugin.json` | Users get updates only when you bump this field. Pushing new commits without bumping it has no effect, and `/plugin update` reports "already at the latest version". For a plugin [loaded in place](#plugin-caching-and-file-resolution), the new content loads anyway. | Published plugins with stable release cycles |
1525| **Commit-SHA version** | Omit `version` from both `plugin.json` and the marketplace entry | Users get updates whenever the source's resolved commit changes | Internal or team plugins under active development |
1526| **Digest version** | Use an [`archive` source](/docs/en/plugin-marketplaces#zip-archives) and omit `version` from both `plugin.json` and the marketplace entry | With a `sha256` pin, users get updates when you change the pin. Without one, users get updates whenever the hosted zip file's bytes change | Plugins published as zip files to a static server or artifact repository |
1527
1528If you use explicit versions, follow [semantic versioning](https://semver.org) (`MAJOR.MINOR.PATCH`): bump MAJOR for breaking changes, MINOR for new features, PATCH for bug fixes. Document changes in a `CHANGELOG.md`.
1529
1530***
1531
1532## See also
1533
1534* [Plugins](/docs/en/plugins) - Tutorials and practical usage
1535* [Plugin marketplaces](/docs/en/plugin-marketplaces) - Creating and managing marketplaces
1536* [Skills](/docs/en/skills) - Skill development details
1537* [Subagents](/docs/en/sub-agents) - Agent configuration and capabilities
1538* [Hooks](/docs/en/hooks) - Event handling and automation
1539* [MCP](/docs/en/mcp) - External tool integration
1540* [Settings](/docs/en/settings) - Configuration options for plugins
