pi-ext

Personal Pi extension pack: tools, telemetry, shell bridges, workflow hacks, small demons.

Install

Use pi install. Never pi ext install. That corpse stays buried.

The repository root is a development workspace, not a Pi package. Every extension builds into its own self-contained package under dist/<extension>, and Pi loads those packages.

Build the packages:

mise run //:build-all

Build one:

mise run //:build-ext ultra

Print the explicit package list for ~/.pi/agent/settings.json:

mise run //:settings-entries

Each entry is one local package path, e.g. ~/Workspace/pi-ext/dist/ultra. After a rebuild, run /reload in Pi.

Published npm and Git packages of the generated output are planned; until then, install from a local build.

Filtering

A generated package exposes exactly one extension entry plus its declared skills. Load a subset by listing only the wanted dist/<extension> packages. Resource filters still apply per package:

{
  "packages": [
    {
      "source": "~/Workspace/pi-ext/dist/web",
      "skills": []
    }
  ]
}

Filter rules:

• extensions selects package extension entrypoints.
• skills independently selects extension-owned skills; [] loads none.
• prompts and themes work the same way; [] loads none.
• Omit a key to load every resource of that type exported by the package.
• Values are package-root paths or globs.
• !pattern excludes.
• +path and -path force exact inclusion or exclusion.
• Filters only narrow package exports. They do not resurrect unexported junk.

Settings

Extension settings live under the extension slug in Pi's settings.json, for example { "nushell": { "enable": true } }. Each value resolves in this order: CLI flag, environment variable, trusted project .pi/settings.json, user ~/.pi/agent/settings.json, built-in default. Untrusted project settings are ignored, and an invalid value warns instead of falling back to a lower source. The Config column below shows which sources each extension accepts; its README lists the keys. See settings contract for naming, validation, and code generation.

Debug

Set "pi-ext": { "debug": true } in user ~/.pi/agent/settings.json to enable bounded, private JSONL diagnostics for all extensions. A slug or list of slugs selects only those extensions; PI_<EXTENSION>_DEBUG=1|0 overrides selection for one extension. See debug contract for OS log locations, timing spans, investigation, and code generation.

Extensions

Resources

The root package exports extension entrypoints and extension-owned resources only. Enabled extensions may contribute their own skills or prompts at runtime. Unrelated personal skills, prompts, and themes live in global Pi config. PFUI means Pain-Free User Interface and must remain the first explicit root manifest extension entry. The footer follows it explicitly so footer producers discover the shared footer before publishing their initial state. The extension glob supplies all remaining entrypoints and Pi deduplicates its repeated PFUI and footer matches.

{
  "extensions": [
    "extensions/pfui/index.ts",
    "extensions/footer/index.ts",
    "extensions/*/index.ts"
  ]
}

Development

Clone locally, install dependencies, then point Pi at the checkout:

git clone https://github.com/bugabinga/pi-ext.git
cd pi-ext
npm install
pi install /home/me/Workspace/pi-ext

Or add the checkout to ~/.pi/agent/settings.json:

{
  "packages": [
    {
      "source": "/home/me/Workspace/pi-ext"
    }
  ]
}

Checks:

npm run lint
npm test
npm run typecheck

Formatting:

npm run fmt

Git installs run npm install --omit=dev. For local development, run npm install inside the repository first.

Release model

Single repo version.

Tag format:

vX.Y.Z

Per-extension package versions are intentionally absent. One repo, one version. Less accounting. Fewer tiny coffins.

Tiny demons purr.
Pi feeds them your bloated prompts.
They eat the light whole.