Skip to content

Latest commit

 

History

History
12 lines (10 loc) · 4.39 KB

plugins.md

File metadata and controls

12 lines (10 loc) · 4.39 KB

Claude plugins

Loads installed marketplace plugins. Source: extensions/internal/plugins.ts.

  • Reads the plugin cache at ~/.claude/plugins/cache, active per enabledPlugins in user settings (the user file and the --settings flag; a --setting-sources list without user drops the user file's entries) and pi's own piCode.enabledPlugins override below: a checked-out repo cannot flip which code-bearing plugins run, so project settings never toggle them. The version that loads is the one ~/.claude/plugins/installed_plugins.json records (a user-scope install first); with no usable record, the newest version directory not marked .orphaned_at. Cache directories can be named by commit sha, so the name alone does not say which is newest. A plugin from a local marketplace (claude plugin marketplace add <directory or marketplace.json>) whose entry is a relative ./ path loads from that path inside the marketplace, as in Claude Code, so source edits apply after /reload without claude plugin update; the plugin must still be installed (a live cached version), and when the marketplace is gone, no longer lists the plugin, or the entry leaves its directory, the plugin does not load rather than falling back to the cached copy.
  • Contributes commands as /plugin:name, agents, hooks, MCP servers (tools aliased mcp__plugin_<plugin>_<server>__<tool>), and output styles.
  • Enablement is decided by the first of these that has an entry for the plugin: a managed-settings enabledPlugins entry (force-enables or blocks), the --settings flag's enabledPlugins, pi's piCode.enabledPlugins, the enabledPlugins of the Claude user settings file, then the manifest's defaultEnabled (default true: an installed plugin with no entry runs). The flag ranks above the pi key as it ranks above every settings file in Claude, so a one-off --settings '{"enabledPlugins":{"name@marketplace":true}}' wins over a saved pi override for that session.
  • To turn a plugin on or off in pi only, set piCode.enabledPlugins in pi's own ~/.pi/agent/settings.json. It takes the same keys as Claude's (name@marketplace or the bare name) and ranks below managed settings and the --settings flag, above the Claude user settings file. Claude Code never reads it. This is for plugins that also ship a native pi package: { "piCode": { "enabledPlugins": { "ponytail@ponytail": false } } }.
  • /claude-plugins lists the installed plugins in a settings list showing each one's state and the setting that decided it. Enter or Space toggles a plugin and saves it through that key, like /settings; the change applies after /reload, which pi-code leaves to you because a reload aborts running subagents. The key only gets an entry when pi should differ from Claude's settings or from a bare-name entry, which stays because it may cover same-named plugins from other marketplaces. A plugin whose state managed settings or the --settings flag decide is listed read-only, since a piCode.enabledPlugins entry would not change it. Installing and removing plugins stays with Claude Code.
  • Substitutes ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, and ${user_config.KEY} (from pluginConfigs[id].options in user settings or the --settings flag). A shell-form hook command and an MCP headersHelper reject ${user_config.KEY}, as Claude does: a hook carrying one is dropped, and a server whose helper carries one is skipped. A plugin command body substitutes it like the rest of its content, ! spans included.
  • Plugin skills register as /plugin:name, for example /kit:deploy; personal and project skills keep /skill:name. Deprecated: the bare /skill:deploy form still runs a plugin skill when exactly one enabled plugin ships that name and no personal or project skill has it, with a one-time notice naming /kit:deploy. It will be removed in the next major version, so update invocations to /kit:deploy. When several plugins ship the name, the bare form runs nothing and lists the qualified names. The plugin's skills/ directory is always scanned alongside any directories the manifest's skills declares. Plugin commands retain their established names when a skill has the same name. For duplicate plugin skill names, the first discovered definition wins and a warning names both files.
  • Claude's single-skill layout (SKILL.md at the plugin root) remains unsupported; the scan expects <dir>/<name>/SKILL.md.