pi-agent-extensions

A collection of extensions for the pi coding agent.

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 these excellent production-ready extensions:

• notify.ts - Desktop notifications via OSC 777
• context.ts - Context breakdown dashboard
• files.ts - Unified file browser with git integration
• review.ts - Code review system
• loop.ts - Iterative execution loop

Original repository: https://github.com/mitsuhiko/agent-stuff

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 | Tool | Desktop notifications via OSC 777 | ✅ Stable | | context | UI | Context breakdown dashboard | ✅ 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 |

Install

From npm (Recommended)

pi install npm:pi-agent-extensions

All extensions will be available immediately after installation.

From Source (For Development)

# Clone the repository
git clone https://github.com/jayshah5696/pi-agent-extensions.git
cd pi-agent-extensions

# Install globally
pi install .

# Or install to specific project
cd ~/your-project
pi install -l /path/to/pi-agent-extensions

Quick Test Without Installing

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

Verify Installation

After installing, start pi and look for the startup message:

Extensions: sessions, ask_user, handoff

Test sessions:

pi
/sessions

Test ask_user:

pi
> Ask me which database I prefer: PostgreSQL or SQLite

The LLM should call the ask_user tool and show you options to select.

Test handoff:

pi
# Have a conversation first, then:
/handoff implement the next feature with proper tests

You'll see a loader while context is extracted, then an editor to review the handoff prompt.

Changelog

See CHANGELOG.md for release history.

Update

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

# Or update all packages
pi --update-packages

Uninstall

pi remove 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 16 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

License

MIT