pi-package-manager

Installed packages manager for pi — a blueprint-style web dashboard for browsing, installing, and removing pi packages from your agent.

Preview

The dashboard lists every installed package and lets you install, uninstall, or copy the install command with one click. When a package isn't on the machine yet, the action button flips to a neutral Install state; when it is, it switches to a brand-green Uninstall state — and you can mix the two in the same view.

The preflight paste box above the grid calls your configured pi LLM to assess any package before you install it. Fit label, reasoning, concerns, and up to 3 better alternatives — all without leaving the dashboard.

| Dashboard (13 installed + manager card) | LLM preflight result | |---|---| | | |

What it does

Adds two slash commands to your pi agent:

• /packages — opens the local dashboard at http://127.0.0.1:7878/ showing your installed packages with one-click install/uninstall
• /packages-stop — stops the dashboard server (the agent also stops it on session end)

The dashboard is a self-contained HTML page that lists your installed extensions and lets you install or remove any npm-published pi package directly from the browser. No terminal round-trips, no copy-paste.

Paste-a-command preflight

Above the package grid, the dashboard has a single paste box. Drop in npm:some-package (or pi install npm:some-package, or just the bare name) and click Run preflight — the server assembles a fact sheet about the package (npm metadata, your installed stack, your environment) and sends it to your configured pi LLM. The LLM returns a fit label and reasoning.

Fit labels: Essential · Recommended · Good · Caution · Low

The result panel shows the label, the reasoning, any concerns the LLM flagged, and up to 3 better alternatives from pi.dev/packages. From there you can install with one click, ignore the recommendation, or (if the LLM was unavailable) open a typed-confirm dialog to force-install anyway. Every force-install is audit-logged to ~/.pi/agent/pi-packages-audit.log.

Prebuilt package setup

The dashboard ships with 12 proven pi packages already listed, plus a 13th card for pi-package-manager itself (marked MGR — the card host, no action button). Fresh pi agent users don't need to search for good extensions — they're all one click away:

| Package | What it does | |---------|-------------| | pi-lean-ctx | Token-saves bash/read/grep/find/ls via lean-ctx compression | | pi-btw | Parallel side conversations with /btw | | pi-intercom | 1:1 messaging between pi sessions on the same machine | | pi-goal | Persistent autonomous goals via /goal | | pi-web-access | Web search, URL fetch, GitHub clone, YouTube understanding | | pi-hermes-memory | Persistent memory + session search + procedural skills | | pi-subagents | Delegate tasks to subagents with chains and parallel execution | | @gonrocca/zero-pi | Spec-driven development workflow (explore → plan → build) | | pi-mcp-adapter | MCP (Model Context Protocol) adapter | | pi-paster | Paste image paths as first-class attachments | | pi-markdown-preview | Markdown/LaTeX preview → PDF, HTML, or PNG | | @llblab/pi-telegram | Telegram DM as a session-local operator console |

If you already have a package installed, the button shows Uninstall instead of Install — so you can see at a glance which of the recommended extensions you're still missing.

Install

pi install npm:pi-package-manager

That's it — restart the agent and /packages is registered.

Requirements

• Node.js ≥ 18
• pi CLI on your PATH (you have this if pi is installed)
• A modern browser to view the dashboard

Usage

Inside the pi agent

/packages

Spawns the bridge server in the background and opens the dashboard. Subsequent invocations are instant (the server is reused).

From a terminal (no agent)

# Server + open browser
npx pi-package-manager

# Server only
npx pi-package-manager --no-open

# Custom port
npx pi-package-manager --port 9000

How it works

1. The /packages slash command resolves the bundled src/server.mjs path and spawns node against it
2. The server binds 127.0.0.1:7878 (or whatever PI_PACKAGES_PORT is set to) and serves the dashboard HTML
3. The dashboard probes /api/state to read the recipient's installed packages from ~/.pi/agent/settings.json
4. Clicking Install or Uninstall POSTs to /api/install or /api/uninstall, which shells out to the real pi install / pi remove commands
5. On session_shutdown, the extension kills the server process

HTML resolution

The server picks the dashboard HTML in this order:

1. $PI_PACKAGES_HTML env var (explicit override)
2. ~/.pi/agent/pi-packages.html — your personal copy (if it exists)
3. src/pi-packages.html — the bundled copy that ships with the package

This means the personal regen flow (update_pi_packages.py) still works: the dashboard always shows your latest local catalog, even if you installed the package long ago.

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | / | GET | Serves the dashboard HTML | | /api/state | GET | Returns installed packages from settings.json | | /api/health | GET | Server health check | | /api/install | POST | Install a package ({ "source": "npm:<name>" }) | | /api/uninstall | POST | Uninstall a package ({ "source": "npm:<name>" }) | | /api/preflight | POST | LLM preflight ({ "source": "npm:<name>" } → { ok, label, reasoning, alternatives, concerns, ... }) | | /api/force-install | POST | Force-install after typed-confirm ({ "source": "npm:<name>", "phrase": "I understand the risks" }); audit-logged |

Security

• Bound to 127.0.0.1 only — never reachable from the network
• Source strings validated against a strict regex before reaching the shell: /^npm:@?[a-z0-9][\w.-]*(\/[a-z0-9][\w.-]*)?$/i
• 180-second timeout on install/uninstall operations
• CORS headers allow the page to be opened as file:// for offline use

Structure

pi-package-manager/
├── extensions/
│   └── index.ts          # Pi extension entry point — /packages command
├── src/
│   ├── server.mjs        # Bridge server (zero external deps; uses @earendil-works/pi-ai for preflight)
│   └── pi-packages.html  # Dashboard UI
├── bin/
│   ├── pi-package-manager.mjs  # CLI entry point (npx / global)
│   └── pi-preflight.mjs        # LLM preflight shim (throwaway; moves upstream when pi gains a preflight subcommand)
├── package.json
├── LICENSE
├── tsconfig.json
└── README.md

License

MIT