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.

Read the story

I wrote about building this setup in Stop Renting Your Workflow: Building a Custom AI Coding Agent with Pi, including why I chose Pi, how I use extensions, and what I value about controlling my coding workflow.

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