mise run //:build-all

mise run //:build-ext ultra

mise run //:settings-entries

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

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

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

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

npm run lint
npm test
npm run typecheck

npm run fmt

vX.Y.Z

# 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:

```bash
mise run //:build-all
```

Build one:

```bash
mise run //:build-ext ultra
```

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

```bash
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:

```json
{
  "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](extensions/SETTINGS.md) 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](extensions/DEBUG.md) for OS log locations, timing spans, investigation, and code generation.

## Extensions

| Extension slug | Short explanation | Config | README |
| --- | --- | --- | --- |
| `angel` | Tool-using investigative advisor backed by a configured model. | settings | [README](extensions/angel/README.md) |
| `ask` | Structured single- and multiple-choice questions for humans. | none | [README](extensions/ask/README.md) |
| `chrome-cdp` | Raw CDP commands, captures, and traces against extension-owned Chrome. | settings, `--chrome` | [README](extensions/chrome-cdp/README.md) |
| `context-size` | Context-window usage telemetry. | settings, env | [README](extensions/context-size/README.md) |
| `continuity` | Continues unfinished work after context compaction. | none | [README](extensions/continuity/README.md) |
| `cost` | Token and spend telemetry. | none | [README](extensions/cost/README.md) |
| `decay` | Recency-weighted structured context compaction. | settings | [README](extensions/decay/README.md) |
| `fast` | OpenAI Codex priority service tier. | settings | [README](extensions/fast/README.md) |
| `footer` | Shared stable footer renderer. | none | [README](extensions/footer/README.md) |
| `git-safe` | Hardened Git operations and clone tooling. | settings, env | [README](extensions/git-safe/README.md) |
| `good-job` | Learns from pass-through `gj` praise and `wtf` complaints. | settings | [README](extensions/good-job/README.md) |
| `horst` | Shared config with per-host environment facts and tool deltas. | settings | [README](extensions/horst/README.md) |
| `intellij` | Connects to IntelliJ's MCP server on demand. | settings | [README](extensions/intellij/README.md) |
| `klaus` | Runs Claude models through the Claude Agent SDK. | none | [README](extensions/klaus/README.md) |
| `masks` | Switches model and thinking level together. | settings | [README](extensions/masks/README.md) |
| `model-info` | Executor, transport, and advisor telemetry. | none | [README](extensions/model-info/README.md) |
| `mockup` | Browser-based review of generated HTML mockups. | settings, env | [README](extensions/mockup/README.md) |
| `notes` | Session-backed pending prompt notes. | settings, env | [README](extensions/notes/README.md) |
| `nu-bang` | Routes bang commands through Nushell. | settings, env | [README](extensions/nu-bang/README.md) |
| `open` | Opens mentioned files in an editor beside Pi. | none | [README](extensions/open/README.md) |
| `os-notifier` | Native notifications when interactive work completes or blocks. | none | [README](extensions/os-notifier/README.md) |
| `pfui` | Pain-Free User Interface fallback identity and Pi context discovery. | none | [README](extensions/pfui/README.md) |
| `prompt-autopsy` | Writes and groups Pi's generated system prompt for inspection. | none | [README](extensions/prompt-autopsy/README.md) |
| `quota` | Subscription quota dashboard for supported providers. | settings, env | [README](extensions/quota/README.md) |
| `rtk` | Rewrites eligible Bash tool calls through RTK. | settings, env | [README](extensions/rtk/README.md) |
| `runtime` | Runtime detection telemetry for footer and status. | settings, env | [README](extensions/runtime/README.md) |
| `session-rename` | Generates short session names from branch activity. | settings, env | [README](extensions/session-rename/README.md) |
| `strata` | Browser review of Git changes organized into cohorts and layers. | settings, env | [README](extensions/strata/README.md) |
| `the-system` | Project governance through one `/system` command. | none | [README](extensions/the-system/README.md) |
| `tps` | Tokens-per-second footer telemetry. | none | [README](extensions/tps/README.md) |
| `ultra` | Declarative multi-agent workflow orchestration. | settings | [README](extensions/ultra/README.md) |
| `usage` | Local usage statistics dashboard. | none | [README](extensions/usage/README.md) |
| `uv` | Routes Python package tooling through `uv`. | none | [README](extensions/uv/README.md) |
| `vcs-status` | Git and Jujutsu workspace telemetry. | settings, env | [README](extensions/vcs-status/README.md) |
| `web` | Web fetch, search, and site-map discovery. | settings, env | [README](extensions/web/README.md) |

## 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.

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

## Development

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

```bash
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`:

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

Checks:

```bash
npm run lint
npm test
npm run typecheck
```

Formatting:

```bash
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:

```text
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.