# pi-ext

Make Pi fit the way you work: choose tools, working modes, review flows, and session helpers.
Use only the extensions you need; each README shows when it helps and how to start using it in Pi.

## Install

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, restart Pi to load the updated packages.

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.

## Extensions

| Extension slug | Short explanation | Config | README |
| --- | --- | --- | --- |
| `angel` | Tool-using investigative advisor backed by a configured model. | settings | [README](extensions/angel/README.md) |
| `ask` | Answer Pi's clarifying questions with structured choices. | none | [README](extensions/ask/README.md) |
| `bak` | Back up and restore Pi sessions across machines. | settings, env | [README](extensions/bak/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) |
| `gratis` | Native `grts/auto` virtual routing across explicitly free chat models. | none | [README](extensions/gratis/README.md) |
| `handoff` | Transfers the current conversation into a new focused session via an editable prompt. | none | [README](extensions/handoff/README.md) |
| `horst` | Shared config with per-host environment facts and tool deltas. | settings | [README](extensions/horst/README.md) |
| `intellij` | Automatically registers native IntelliJ MCP for `.idea` projects. | 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` | Run Nushell commands directly from Pi's input. | settings, env | [README](extensions/nu-bang/README.md) |
| `nushell` | Let Pi work with structured shell data and persistent shell state. | settings, env, `--nushell` | [README](extensions/nushell/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` | Keep Pi's Python dependency work on `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) |