pi-extensions

A pi package that bundles pi extensions. Documentation lives on the docs site, built with VitePress from the docs/ folder.

• codegraph - semantic code index for the agent. The main extension.
• tools - the /tools command to enable and disable tools per session.
• context-cap - --context-window <tokens> caps the session's context window so compaction fires early.
• model-router - recovers a session from a provider usage-limit halt (switch to a fallback or wait for the reset, then resume).
• llama-refresh - self-heals the context window of a session that resolved a local llama.cpp model while it was asleep.
• quota - monitors the OpenAI ChatGPT plan quota: a footer line with the used windows, and a /quota detail view.
• resource-toggle - /resources, /enable, /disable, /inherit: enable and disable extensions, skills, prompt templates, and themes from inside a running session. A state command with no name opens the resource picker in TUI mode (a resource table in the headless modes), and every surface shows the one-line description derived from the resource's source file.
• usage - token and cost reporting across all pi sessions: the /usage TUI view, the usage_report agent tool, and the pi-usage CLI.
• sync - cross-device pi config sync: /sync plus the pi-sync CLI, three-way merge, v1 backend a secret GitHub Gist.
• compress - replaces finished turns in outgoing requests with one short standing-in message; the session file stays intact.
• pruning - two-level context control: prunes large tool outputs out of the request at pi's compaction threshold, and lets the prune gate cancel the compaction when pruning alone frees enough headroom.
• output-limits - bounds the size of a tool result before pi stores it, against a share of the session's headroom, and keeps the whole result in a spill file so the cut is lossless.
• output-starvation - judges each request's output budget against the Effective window: refuses a budget that collapsed to pi's floor, and fits one the window cannot pay for, so the provider answers instead of rejecting.
• edit-assist - corrects and diagnoses built-in edit calls: an oldText that differs from the file only in leading whitespace is corrected before execution, and the success result carries a one-line honesty note naming the line; a no-match failure gets the Nearest region with a unified diff, an ambiguous match gets the occurrence line numbers, a malformed call gets one targeted hint, and the stock error text is always kept. Also injects the standing edit-tool prompt rule while the edit tool is active.
• bash-no-match - returns a no-match search (rg/grep exit 1 with an empty stream) to the agent as a normal result with a "(no matches)" note, instead of an error.
• background-jobs - bash_bg, job_wait, job_status: run long commands in the background and wait on them once, instead of sleep-and-tail loops.
• skill-migrate - deterministic repo-structure migrations with a committed changelog: a status/migrate CLI and a /migrate command. The first step records the adoption, the second migrates the domain docs to the GLOSSARY file layout and rewrites every reference to the old file names.
• skills - a curated skill tree loaded by pi from the package's skills/ directory, with npm run skills:update to three-way-merge upstream changes into the copies. The mattpocock/ skills come from mattpocock/skills and the anti-slop/ skills from miqdadbadjuber/Anti-Slop; both are MIT licensed (the upstream LICENSE ships at skills/mattpocock/LICENSE and skills/anti-slop/LICENSE).

See the pi packages docs and the extensions docs.

Extensions

Extension	Docs
codegraph	user page / internals
tools	docs
context-cap	docs
initial-context	docs
model-router	docs
quota	docs
sync	user page / internals
usage	docs
compress	docs
pruning	docs
output-limits	docs
output-starvation	docs
edit-assist	docs
bash-no-match	docs
background-jobs	docs
skill-command	docs
skill-migrate	README

Skills

The package ships a skill tree under skills/; pi loads it through the skills entry in the pi manifest in package.json when the package is installed (convention directories are not auto-discovered while a pi manifest is present). Layout is the manifest:

• skills/mattpocock/<bucket>/<name> - skills tracked against the upstream mattpocock/skills repo, mirroring its skills/<bucket>/<name> layout.
• skills/anti-slop/<name> - the antislop suite tracked against the upstream miqdadbadjuber/Anti-Slop repo, mirroring its flat skills/<name> layout.
• skills/local/<name> - local-only skills. Sync never reads, merges, or reports them.

Tweaking a skill is editing the file in this repo: a skill sync merges against the tweak, so an upstream change to a tweaked region comes back as a conflict, never as a silent overwrite. skills-manifest.json holds one entry per skill source: repo URL, local root, the upstream root it mirrors, and the Source pin (the upstream commit the whole tree last agreed on).

npm run skills:update                # fetch upstream, three-way-merge tracked skills
npm run skills:add -- <slug>/<path>  # adopt a new upstream skill, e.g. anti-slop/antislop-ui

skills:update merges every tracked file with git merge-file (base = the pin, theirs = the fetched commit, ours = the local copy). Clean merges apply automatically. A file both sides changed comes back with git conflict markers; resolve it in place, and the pin advances on the next clean sync. Upstream deletes of a skill are reported as orphans and kept in place. New upstream skills are listed as offers and adopted only by skills:add. The Source pin advances only when a sync completes with no conflict and no orphan. The tool never commits, pushes, deletes, or renames.

The vendored antislop core is edited once for a tracked tree (ADR-0034): the install wizard and update sections are cut, and an unresolved usage mode resolves to during with the notice antislop active: during (package default). instead of a question, so an unattended session never stalls on it. An operator who wants after pins it the upstream way: npx antislop-ai --mode after for the machine, or say so for one session. The suite ships available, not active: no prompt template or initial-context injection turns it on.

The tree also stays compatible with npx skills@latest add SeriousJul/pi-extensions.

The Skill tree page on the docs site documents the sources, their licenses, and the local-tweak policy.

Layout

.
├── package.json      # pi manifest under the "pi" key, pi-package keyword
├── tsconfig.json     # type checking only. pi loads .ts via jiti, no build step
├── extensions/       # every .ts file (or subdirectory with index.ts) is an extension
│   ├── tools.ts
│   ├── context-cap/  # multi-file extension, entry point at context-cap/index.ts
│   ├── model-router/ # multi-file extension, entry point at model-router/index.ts
│   ├── quota/        # multi-file extension, entry point at quota/index.ts
│   ├── resource-toggle/  # multi-file extension, entry point at resource-toggle/index.ts
│   ├── usage/        # multi-file extension, entry point at usage/index.ts, plus the pi-usage CLI
│   ├── sync/         # multi-file extension, entry point at sync/index.ts, plus the pi-sync CLI
│   ├── skill-migrate/  # multi-file extension, entry point at skill-migrate/index.ts, plus the CLI
│   ├── codegraph/    # multi-file extension, entry point at codegraph/index.ts
│   ├── compress/     # multi-file extension, entry point at compress/index.ts
│   └── pruning/      # multi-file extension, entry point at pruning/index.ts
├── docs/             # VitePress site root, canonical source for all documentation
│   ├── .vitepress/   # site config; its own package.json + lockfile for site tooling
│   ├── adr/          # architecture decision records
│   └── agents/       # agent skill files (excluded from the site navigation)
├── GLOSSARY.md        # the domain glossary, single source (published on the site)
├── scripts/          # postinstall patch for the embedded codegraph library
│   └── skills/       # skill sync (skills:update) and adopt (skills:add) tools
├── skills/           # the skill tree pi loads from the package (mattpocock/ + anti-slop/ + local/)
├── skills-manifest.json  # one entry per skill source: repo, upstream root, local root, Source pin
└── tests/            # vitest suite

extensions/ is a convention directory: every .ts file in it is loaded as an extension. Multi-file extensions go in a subdirectory with an index.ts entry point. You can also add skills/, prompts/, and themes/ directories and list them in the pi manifest in package.json.

Install

Install from the git repository into user settings (default):

pi install https://github.com/SeriousJul/pi-extensions

Or into project settings, shared with the team:

pi install -l https://github.com/SeriousJul/pi-extensions

pi clones the repository to ~/.pi/agent/git/github.com/SeriousJul/pi-extensions (.pi/git/github.com/SeriousJul/pi-extensions for project settings) and runs npm install for you. The postinstall step (scripts/patch-codegraph.mjs) prepares the pinned @colbymchenry/codegraph package for the runtime pi embeds. See the codegraph internals page for what the patch does and why.

Update with pi update --extensions. Remove with pi remove https://github.com/SeriousJul/pi-extensions, list with pi list.

To develop from a local checkout instead, see Develop.

Develop

Work from a local checkout. Install its dependencies once; the postinstall step applies the codegraph patch. The patch is idempotent and uses absolute paths, so re-run npm install if you move the checkout.

npm install

Test the package or a single extension in a pi session without installing:

pi -e /absolute/path/to/pi-extensions
pi -e /absolute/path/to/pi-extensions/extensions/tools.ts

Or install the checkout into settings. pi does not copy local paths, so the checkout stays in use where it is:

pi install /absolute/path/to/pi-extensions      # user settings
pi install -l /absolute/path/to/pi-extensions   # project settings

npm run typecheck
npm test

The full developer walkthrough (minimal example, multi-file layout, local install, test commands) is on the develop page.

Docs site

The site is built from docs/ with VitePress and deployed to the gh-pages branch on every push to main (.github/workflows/deploy-docs.yml). Site tooling lives in docs/package.json with its own lockfile; the root manifest only delegates npm run docs:dev and npm run docs:build, so the site build tools never enter the package that pi install users install.

npm run docs:dev    # local dev server
npm run docs:build  # production build (also run by CI on every PR)