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

Ask, answer, and hand off

Inspect and manage work

Analyze, automate, and customize

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