Loads installed marketplace plugins. Source: extensions/internal/plugins.ts.
- Reads the plugin cache at
~/.claude/plugins/cache, active perenabledPluginsin user settings (the user file and the--settingsflag; a--setting-sourceslist withoutuserdrops the user file's entries) and pi's ownpiCode.enabledPluginsoverride 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.jsonrecords (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/reloadwithoutclaude 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 aliasedmcp__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
enabledPluginsentry (force-enables or blocks), the--settingsflag'senabledPlugins, pi'spiCode.enabledPlugins, theenabledPluginsof the Claude user settings file, then the manifest'sdefaultEnabled(defaulttrue: 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.enabledPluginsin pi's own~/.pi/agent/settings.json. It takes the same keys as Claude's (name@marketplaceor the bare name) and ranks below managed settings and the--settingsflag, 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-pluginslists 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--settingsflag decide is listed read-only, since apiCode.enabledPluginsentry would not change it. Installing and removing plugins stays with Claude Code.- Substitutes
${CLAUDE_PLUGIN_ROOT},${CLAUDE_PLUGIN_DATA}, and${user_config.KEY}(frompluginConfigs[id].optionsin user settings or the--settingsflag). A shell-form hook command and an MCPheadersHelperreject${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:deployform 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'sskills/directory is always scanned alongside any directories the manifest'sskillsdeclares. 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.mdat the plugin root) remains unsupported; the scan expects<dir>/<name>/SKILL.md.