pipro

A TUI for managing per-project pi coding agent configs — like create-next-app, but for your pi setup.

Why

pi supports global config (~/.pi/agent/) and per-project config (.pi/ in a project). Global config bleeds into every project; per-project config means remembering package names and hand-editing JSON. pipro gives you a curated collection of your extensions, packages, MCP servers, and harvested project files — with categories, descriptions, and favourites — plus presets, so setting up a project is a checkbox flow instead of an act of memory.

Install

npm install -g @skmr/pipro                            # from npm (needs Node >= 20 and pi >= 0.80)
npm install -g github:s2cube/pi-projects-tui    # or straight from GitHub

On first run pipro offers to import your current global pi packages and MCP servers into your collection, with auto-guessed categories you can edit.

Commands

Command	What it does
pipro	Set up (or update) the current directory's .pi/ config
pipro <dir>	Same, targeting <dir> instead of the current directory (created if missing)
pipro migrate	Empty your global pi config into your reusable collection — packages, MCP servers, and every loose extension/skill/prompt/theme (everything defaults to moving; backup taken first)
pipro undo	Restore the latest migration backup, non-interactively

A flow, start to finish

Running pipro in a fresh project walks a single sequence of steps. The ┌ pipro · <step> header renders once at the top of the screen; each step you've answered collapses to a ◇ line pinned underneath it, so by the time you reach review you see the whole run in one frame:

┌  pipro · review
◇  import  · imported 4 items
◇  picks  · 2 selected
◇  defaults  · keep global
│  + install pi-subagents
│  + add-mcp wigolo
◆  Apply these changes?  yes no  ·  y apply · s save as preset · n cancel

Applying hands off to the receipt, which renders on its own (no history lines — it's the very last thing on screen):

┌  pipro · receipt
✓ install pi-subagents
✓ add-mcp wigolo
my-app ready — run `pi` inside it.

In the picker, type / to filter by name, and use f to toggle a favourite, e to edit a name/description, or d to remove an entry from your collection, right from the list. On later runs in the same project, pipro pre-checks whatever's already installed — tick to add, untick to remove.

If you have saved presets, pipro offers to start from one before opening the picker; pipro asks after each successful setup whether to save the combo as a preset (e.g. coding, office); s on the review screen does the same, and presets are deleted from the preset list.

How it works

• Packages are installed/removed by delegating to the real pi CLI (pi install -l -a, pi remove -l -a) — pipro never re-implements pi's package handling.
• MCP servers are written to the project's .pi/mcp.json (pi project override; key = collection entry id).
• Assets (harvested files) are copied from ~/.pi/pipro/library/ into the project's .pi/; a manifest (.pi/.pipro.json) tracks exactly which files pipro owns, so removal is precise and your own files are never touched.
• Settings (default provider/model/thinking level) merge into .pi/settings.json, preserving anything else in the file.
• Anything in a project pipro doesn't recognize is shown as unmanaged and never removed.

pipro's own files

~/.pi/pipro/
├── catalog.json      # your collection: {id, type: package|mcp|asset, name, description, categories, favourite, …}
├── templates.json    # named presets: entry ids + optional model defaults
├── library/          # harvested asset files
└── backups/          # taken automatically before every migration

Both JSON files are human-editable; pipro validates on load and tells you exactly which field is wrong instead of crashing.

Safety

• Every flow ends in a review screen showing the exact commands and file writes before anything happens.
• pipro migrate backs up settings.json + mcp.json first; pipro undo restores the latest backup.
• Package installs pass --approve scoped to that single pi command (you asked for the install, after all). Review third-party package code before installing — pi packages run with full system access.

Development

npm install
npm test        # vitest: core + TUI + e2e (uses a fake pi shim; never touches your real ~/.pi)
npm run build   # tsc → dist/
npm run dev     # tsx src/bin.ts

Architecture: src/core/ is a headless library (catalog, plan computation, apply engine, harvest, migration) with zero TUI imports — a future web UI mounts the same core. src/tui/ is Ink 5 + React.