# pi-crtr-extensions

crtr's engine-side [pi](https://pi.dev) package — the extensions and prompt
templates every pi engine (including crouter's brokers) loads. This directory,
inside the crouter tree, is the canonical and only copy; it ships in crouter's
`dist/builtin-pi-packages/pi-crtr-extensions` and `crtr sys setup` wires that
path into the `packages` array of `~/.pi/agent/settings.json` (alongside the
bundled `pi-mode-switch`) — there is nothing to clone or install separately.

The package is excluded from crouter's tsc compile unit; pi loads the `.ts`
sources directly with its own loader. Imports may reach from here into
crouter's compiled core (e.g. `lib/subscription-state.ts` imports the model
ladder from `../../../types.js`), never the other direction.

**Does the OAuth plugin ship with pi? No.** `pi-claude-oauth-adapter` is a
third-party npm package ([minzique/dotfiles-agents](https://github.com/minzique/dotfiles-agents/tree/main/packages/pi-claude-oauth-adapter)) —
"Anthropic OAuth / Claude Code compatibility adapter for Pi." pi installs it
from npm because of the `npm:` prefix; it lands in `~/.pi/agent/npm/node_modules/`.
If you want Claude-subscription auth, you add this line yourself — it is not bundled.
(Separately, *this* package's `provider-rotation.ts` extension does its own
OAuth login/refresh via `@earendil-works/pi-ai/oauth` to rotate across
subscription credentials — that's a different mechanism, built in here.)

`@earendil-works/pi-coding-agent` is a peer dependency provided by pi at runtime —
do not install it locally. The one runtime dep (`yaml`) is vendored under this
directory's `node_modules/`.

## Contents

### Extensions (`extensions/`)

| Extension | What it does |
|-----------|--------------|
| `claude-plugin-commands.ts` | Surfaces commands and skills from `~/.claude`, the cwd, every project in the selected crouter profile, and installed plugins as pi slash commands with arg/shell-block execution. Writes shims to `~/.pi/agent/.plugin-command-shims/`. Skips any name pi already serves natively from `~/.pi/agent/prompts/` (e.g. crtr exports a slash command to both `~/.claude/commands` and `~/.pi/agent/prompts`), so the shim never collides with the native prompt. |
| `crouter-help.ts` | Help integration for the `crtr` CLI. |
| `provider-rotation.ts` | Subscription credential rotation across Anthropic / OpenAI-Codex: does its own OAuth login/refresh, rotates on rate-limits, falls back across the model ladder. Registers `/provider-sub <provider> <list\|add\|select\|rm>`. |
| `crtr-commands/` | Auto-generates a slash command per `crtr` CLI node. The tree is derived in-process from crtr's own `buildRoot()` (no subprocesses, no cache on disk); `filters.json` controls which nodes are exposed. |
| `sysprompt-window.ts` | Registers `/sysprompt`, which runs `crtr sys sysprompt --window` without injecting the prompt into context. |
| `frontmatter-rules/` | Injects `.pi/rules/*.md` whose `when:` frontmatter matches a read markdown file. `.claude/rules` are migrated into substrate docs with `applies-to` via `crtr sys sync project-guidance`. Needs the `yaml` dep. See the `pi-frontmatter-rules` skill. |
| `statusline.ts` | Custom status line. |
| `strip-skills-docs.ts` | Trims skill docs from context. |

(`/plan` and `/spec` mode commands live in the separate `pi-mode-switch` package, not here.)

## Notes

- Reload after editing any extension: `/reload` in pi.