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 (planned)

The Atlas-owned packages are prepared for individual public npm releases but are not published yet. Once the npm publishing walkthrough is complete, installation will be:

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

Until then, use the local or Git installation method.

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

npm publishing for the Atlas-owned packages is intentionally deferred. Before their first release, walk through npm ownership, package naming, provenance, release tags, and CI publishing together; do not publish them from this repository ad hoc. Pi Atelier retains the standalone release workflow documented in its package contract.