pi-agent-extensions

pi-agent-extensions

A single install for 17 extensions and four themes for the Pi coding agent: session tools, structured questions, handoffs, multi-agent workflows, review utilities, analytics, UI enhancements, and more.

Install

pi install npm:pi-agent-extensions

The npm package is unscoped: use npm:pi-agent-extensions, with no @scope/ prefix. Requires Pi 0.80.10 or newer and Node.js 22.19.0 or newer.

See it in action

Every screenshot below comes from a real Pi session using an isolated installation of npm:pi-agent-extensions. The UI is not mocked: the gallery uses seeded sessions, todos, and a disposable Git project so the extensions have realistic data to display.

Plan and navigate

Workflow setup /workflow setup configures profiles, model routes, concurrency, and approval.

Sessions /sessions searches project sessions with a live conversation preview.

Ask, answer, and hand off

Structured questions The ask_user tool presents validated choices and always supports a free-text answer.	Batch answers /answer collects answers to multiple questions in one focused editor.
Side questions /btw answers an ephemeral question without adding it to session history.	Session handoff /handoff <goal> extracts and opens a reviewable transfer prompt.

Inspect and manage work

Files /files combines fuzzy navigation, Git status, diffs, and prompt context.	Review /review selects a review scope and drives an interactive code-review flow.
Todos /todos manages file-backed tasks that agents can claim and update.	Context /context-simple explains token allocation, loaded resources, and session cost.

Analyze, automate, and customize

Session analytics /session-breakdown charts sessions, messages, tokens, cost, and model usage.	Execution loops /loop configures test-driven, condition-driven, or self-driven iteration.
Session control /control-sessions lists controllable Pi sessions for inter-session work.	Whimsical UI /whimsy tunes themed loading messages, spinners, and exits.

Learn the workflow surface

The gallery also shows the powerline footer on every screen and its live Git branch, dirty-file counts, model, context, cost, and timer. CWD history runs in the background and keeps the displayed working directory synchronized. Notify runs after agent turns and sends an OSC 777 desktop notification, so it has no persistent in-terminal panel to photograph.

Extensions

Extension	Type	Description	Status
sessions	Command	Quick session picker with /sessions	Stable
ask_user	Tool	LLM can ask structured questions	Beta
handoff	Command	Goal-driven context transfer /handoff	Stable
whimsical	UI	Context-aware loading messages & exit	Stable
files	Tool	Unified file browser & git integration	Stable
notify	Automatic	OSC 777 desktop notification after agent turns	Stable
context	Command	Context breakdown dashboard with /context-simple	Stable
review	Tool	Interactive code review system	Stable
loop	Tool	Iterative execution loop	Stable
todos	Tool	File-based todo list management	Stable
control	RPC	Inter-session communication & control	Beta
answer	Tool	Structured Q&A for complex queries	Beta
cwd_history	Tracker	Tracks directory changes in context	Stable
btw	Command	Quick side questions without history	Stable
powerline-footer	UI	Custom powerline-style footer bar	Stable
session-breakdown	Command	Session analytics dashboard	Stable
workflow	Tool / Command	Model-routed dynamic workflows with /workflow	Beta

Verify Installation

Confirm that Pi registered the package:

pi list
# User packages:
#   npm:pi-agent-extensions

Start Pi and press Ctrl+O to expand the startup resources. The [Extensions] section should contain all 17 pi-agent-extensions:* entries shown above.

Useful smoke tests:

pi
/sessions
/workflow help

/sessions opens the session picker. /workflow help renders the workflow guide without making a model call.

Development Installation

git clone https://github.com/jayshah5696/pi-agent-extensions.git
cd pi-agent-extensions

# Install globally from this checkout
pi install .

# Or install only for the current project
pi install /path/to/pi-agent-extensions -l --approve

--approve trusts project-local code. Use it only after reviewing the checkout you are installing.

Load individual extensions without installing the package:

pi -e /path/to/pi-agent-extensions/extensions/sessions/index.ts \
   -e /path/to/pi-agent-extensions/extensions/ask-user/index.ts \
   -e /path/to/pi-agent-extensions/extensions/handoff/index.ts

Changelog

See CHANGELOG.md for release history.

Update

# Update to latest version
pi update npm:pi-agent-extensions

# Or update all packages
pi update --extensions

Uninstall

pi remove npm:pi-agent-extensions

Troubleshooting

Extensions not showing after install

If you installed via npm install or npm update, the package won't be registered with Pi. You must use Pi's package manager:

# Wrong (npm only - won't register with Pi)
npm install pi-agent-extensions

# Correct (registers with Pi)
pi install npm:pi-agent-extensions

Verify installation

Check that the package appears in your settings:

cat ~/.pi/agent/settings.json | grep pi-agent-extensions

You should see:

"packages": [
  "npm:pi-agent-extensions",
  ...
]

Local development vs npm

When running Pi from the pi-agent-extensions directory, it loads local extensions (your development copy), not the npm-installed version. This is useful for development but can cause confusion.

To test the npm version, run Pi from a different directory:

cd ~/some-other-project
pi
# Check: should show npm:pi-agent-extensions in [Extensions]

Documentation & Extensions Reference

For in-depth explanations, options, and commands for all 17 extensions, refer to the Extensions Reference.

For installation, manual testing, and setup guides, see the Documentation Index.

Development

This repository uses just as a command runner for local testing and package releases.

# Install package dependencies
npm install

# Run the full test suite
just test

# Show local vs. published npm version
just versions

# Inspect package files packed in npm bundle
just pack-dry-run

# Check release validity (fails if version is not bumped)
just release-check

# Bump version, tag, commit, push, and publish to npm
just release patch

If you do not have just installed, you can use the equivalent npm wrapper scripts:

npm test
npm run release:check
npm run release:publish -- patch

Acknowledgments

This project includes extensions adapted from mitsuhiko/agent-stuff (Apache 2.0 / MIT License).

Special thanks to Armin Ronacher (@mitsuhiko) for creating and open-sourcing the original notification, context, file-browser, review, and loop extensions.

License

MIT