pi extensions

Custom extensions for Pi, the terminal-based coding agent.

This monorepo is the source of truth for Ed's Pi extensions. Each package lives under packages/, while the root package can install the Atlas collection from Git or through the local development workflow. The working tree also contains the standalone pi-atelier package, which is not registered by the root Pi manifest.

Package	Description
pi-atelier	Standalone responsive status rail and live activity sidebar; not installed by the root collection
pi-better-ask-user	Interactive better_ask_user decision UI with searchable choices, freeform input, JSON workflow previews, and optional Herdr lifecycle metadata
pi-better-btw	Temporary in-memory side conversation in a native /btw overlay

Install

Local development

Requirements: Pi, Node.js/npm, GNU Stow, and just.

git clone git@github.com:edheltzel/pi-extensions.git ~/Developer/Atlas/PiExtensions
cd ~/Developer/Atlas/PiExtensions
just install-local

The local workflow installs workspace dependencies, stows a stable package view at ~/.pi/agent/local-packages/pi-extensions, and registers that local package with Pi. Source edits remain live through symlinks.

Useful commands:

just status
just test
just check
just uninstall-local

Run /reload after installing or changing extension resources.

Git

Install the complete collection directly from GitHub:

pi install git:github.com/edheltzel/pi-extensions

npm packages

The two child packages are independently publishable npm packages. After the package has been released, install the package you need:

pi install npm:@edheltzel/pi-better-ask-user
pi install npm:@edheltzel/pi-better-btw

Use pi update npm:<package> to update one package. The authoritative clean- home smoke test and release status are documented in docs/npm-release.md. The first public publication is still a separate captain decision; until it is authorized, use the local or Git installation method and validate local tarballs with npm run verify:pi-install.

Development

npm install
just test
just check

Extensions are TypeScript modules loaded directly by Pi through jiti; there is no build step. Package-specific behavior and verification commands live in each package README and AGENTS.md.

Preview a Better Ask User workflow

You can exercise a sequence of better_ask_user questions in the real Pi UI without installing the collection or using an agent turn:

pi --no-extensions -e ./packages/pi-better-ask-user/index.ts

In that temporary Pi session, run:

/better-ask-preview ./packages/pi-better-ask-user/examples/preview-questions.json

The fixture is a non-empty JSON array of normal better_ask_user parameter objects. Questions run sequentially through the production interaction path and stop if one is cancelled or fails. Copy or edit the bundled fixture to preview another workflow. See the package preview documentation for the fixture format and behavior.

Repository structure

packages/
  pi-atelier/          # standalone; excluded from the root Pi manifest
  pi-better-ask-user/
  pi-better-btw/

Each package owns its Pi manifest, source, tests, README, and license. The root pi manifest bundles the Atlas-owned Better Ask User and Better BTW resources for collection-level local or Git installation.

Publishing

Independent npm release tags, package allowlists, trusted-publisher setup, provenance, rollback, and troubleshooting are defined in docs/npm-release.md. The root collection remains private and is never published; Pi Atelier retains its standalone release workflow documented in its package contract.