Pi Plugins

@nklisch/pi-plugins is a filesystem-first marketplace and plugin manager for Pi. It installs compatible Claude Code and Codex plugin bundles, discovers their skills, runs their simple command hooks, and supplies their MCP declarations to Pi.

Install

pi install npm:@nklisch/pi-plugins

Run /plugins with no arguments to open the keyboard-first manager. It provides Installed, Discover, Marketplaces, and Issues views; search and plugin details; and explicit multi-select batches. Ctrl+F focuses search, Space selects rows, a selects all filtered rows, Enter opens details, r checks marketplaces, and the footer shows the contextual action keys. A theme-native frame separates the manager from the transcript; Page Up/Down scrolls long views while arrow-key navigation keeps the selected row visible.

The manager opens from local files. Marketplace checks run asynchronously with bounded concurrency and timeouts, remain cancellable, and never hide the installed copies when a source is offline. Runtime changes are applied sequentially and trigger one Pi reload when the manager closes.

The direct command surface remains available for scripts and focused actions:

/plugins list
/plugins marketplace add nklisch/skills
/plugins marketplace list
/plugins marketplace refresh nklisch-skills
/plugins browse nklisch-skills
/plugins install workbench@nklisch-skills --yes
/plugins update workbench@nklisch-skills --yes
/plugins enable workbench@nklisch-skills --yes
/plugins disable workbench@nklisch-skills
/plugins remove workbench@nklisch-skills --yes
/plugins update-marked

Direct installation, update, enablement, or removal of executable plugin content requires confirmation; pass --yes for headless use. Each direct runtime mutation reloads Pi after it succeeds.

Automatic updates

An installed plugin can be marked for automatic updates from its detail view. The .auto-update marker is both the selection and the standing authorization to replace that plugin's executable content.

Before plugin activation, Pi refreshes each affected marketplace once with a bounded timeout. A marked plugin updates only when the candidate bundle version differs from its installed version. Native manifests supply versions even when the marketplace omits them; catalog entries and installed receipts are fallbacks, not replacements for a bundle’s own version. Remote candidates are checked with bounded acquisition and installed from that same copy when needed. Missing versions, offline sources, and item failures leave the installed copy unchanged and do not block startup.

/plugins update-marked is the explicit escape path. It refreshes affected marketplaces, force-updates every marked plugin—including unversioned entries— reports mixed results, and reloads once if any update succeeds. There is no scheduler or periodic background updater.

Filesystem truth

The host stores no database or lifecycle ledger. Its durable layout is:

<agent-dir>/plugin-host/
├── .check-on-open?
├── marketplaces/<name>/{source.json,checkout}
├── plugins/<marketplace>/<plugin>/{.pi-plugin.json,.disabled?,.auto-update?,...bundle}
└── data/<marketplace>/<plugin>/

A plugin directory is installed; .disabled means disabled. The receipt is descriptive only. .check-on-open stores the manager's optional refresh preference; cursor, selection, progress, results, and errors are never stored. Refresh and install/update stage a sibling directory and rename it into place, restoring the prior copy if the final rename fails. Persistent plugin data is not replaced by an update and is retained by removal unless --delete-data is supplied.

Marketplaces accept GitHub shorthand, Git URLs, and local repository paths. The host reads .agents/plugins/marketplace.json and .claude-plugin/marketplace.json, merges valid siblings, and supports local plugin declarations such as { "source": "local", "path": "./plugins/demo" } and ordinary relative string paths. Catalog paths must remain within the marketplace checkout. Symlinks are rejected anywhere in a copied plugin tree, so catalog-controlled content cannot expose arbitrary host files.

Runtime compatibility

At extension load, enabled bundles are scanned for:

• SKILL.md at the bundle root and skills beneath skills/;
• command hooks in hooks/hooks.json or a simple manifest-declared hook path;
• MCP servers in .mcp.json or a simple manifest-declared MCP path/object.

Supported Claude hook events include SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact, PostCompact, and Stop. Hook processes receive JSON on stdin, the plugin root/data variables, CLAUDE_PROJECT_DIR, a bounded timeout, and cancellation. Hook failures are reported for that plugin and do not disable unrelated bundles. hookSpecificOutput.additionalContext is delivered on the same turn as a model-visible, transcript-backed context message; this preserves per-turn UserPromptSubmit digests instead of treating them as lasting system instructions.

MCP declarations are recursively expanded for the plugin root, persistent data root, and project root, then passed as an in-memory { mcpServers } overlay to @nklisch/pi-mcp-adapter. The adapter merges that overlay with the user's normal file-discovered MCP configuration. Duplicate plugin server names are qualified by plugin identity.

Development

npm run typecheck
npm run test:unit
npm run build
npm run test:package

Pi 0.82 or newer and Node.js 22.19 or newer are required. The package keeps the bundled @nklisch/pi-subagents Pi resource available through a direct, best-effort loader; failure of that optional resource does not prevent plugin discovery.

License

MIT © 2026 Nathan Klisch