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
nvidia-nim	Command	Nvidia NIM auth & config	✅ 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]

Extensions

Sessions

Quick session picker for the pi coding agent. Provides a compact /sessions selector (default 5 visible rows) with arrow navigation, Enter to switch, and Esc to cancel.

Usage:

/sessions       # Show last 5 sessions
/sessions 10    # Show last 10 sessions

Features:

• Lists sessions from the current project only
• Displays absolute timestamps (YYYY-MM-DD HH:mm)
• Filter by typing (prefix match on session name or cwd)
• In non-UI mode (pi -p or JSON/RPC), sessions are printed to stdout

See docs/extensions/sessions.md for details.

Ask User

The LLM can call the ask_user tool to gather user input with structured questions and options.

Status: ⚙️ Beta (v0.1.0) - Core features working, enhanced UI coming soon

Example:

ask_user({
  questions: [{
    question: "Which database should we use?",
    header: "Database Selection",
    options: [
      { label: "PostgreSQL (Recommended)", description: "Battle-tested relational DB" },
      { label: "SQLite", description: "Lightweight, file-based" },
      { label: "MongoDB", description: "Document store" }
    ]
  }]
})

Features:

• ✅ Text input questions
• ✅ Option selection with descriptions
• ✅ "Other" option always available
• ✅ Print mode (pending file workflow)
• ✅ Session persistence
• ⏸️ Custom TUI components (using built-in helpers for now)
• ⏸️ Tabbed multi-question UI (sequential currently)

See extensions/ask-user/README.md and docs/extensions/ask-user.md for details.

Handoff

Transfer context to a new focused session. Unlike /compact which summarizes everything, /handoff extracts only what's relevant to your next goal.

Usage:

/handoff <goal>

Examples:

/handoff implement team-level handoff with proper tests
/handoff fix the authentication bug in login flow
/handoff add unit tests for the parser module

Features:

• Goal-driven context extraction (files, commands, decisions, open questions)
• Structured JSON extraction with LLM
• Skill inheritance (preserves last /skill: used)
• Git metadata (branch, dirty state)
• Session metadata (model, tools, thinking level)
• Interactive editor to review/edit before creating new session
• Configurable via .pi/settings.json

What gets extracted:

• Relevant files with reasons
• Commands that were run
• Key context and decisions
• Open questions/risks

See docs/extensions/handoff.md for full documentation.

Whimsical

A personality engine for Pi that makes waiting fun.

Usage:

/whimsy         # Check status
/whimsy chaos   # Enable chaos mode (Bollywood + Geek + Tips)
/exit           # Graceful whimsical exit

Features:

• Context-Aware: Messages change based on time of day (Morning/Night) and wait duration.
• Personality Modes:
  • chaos: The full experience (50% Bollywood, 30% Tips, 20% Geek).
  • bollywood: 100% Bollywood dialogues & Hinglish memes.
  • geek: Sci-Fi & Dev humor ("Reticulating splines...").
• Smart Exit: /exit and /bye commands that ensure a clean terminal shutdown with a funny goodbye message.

See extensions/whimsical/README.md for details.

BTW

Ask quick "by the way" side questions without polluting your conversation history. Inspired by Claude Code's /btw command.

Usage:

/btw what's the syntax for useEffect cleanup?
/btw which files did we modify just now?
/btw why did you choose Zustand over Redux?

Features:

• ✅ Full conversation context visibility
• ✅ No tool access (lightweight, read-only)
• ✅ Ephemeral overlay — nothing enters session history
• ✅ Zero context cost — no tokens wasted
• ✅ Scrollable answer (↑↓/j/k, PgUp/PgDn)
• ✅ Uses your currently selected model
• ✅ Non-UI fallback (prints to stdout)

When to use /btw vs normal prompts:

Use /btw	Use normal prompts
Quick syntax checks	Requests needing tool access
Confirming earlier decisions	Changes you want tracked
Recalling context details	Complex multi-step tasks
"One and done" lookups	Follow-up conversations

Productivity Tools

Files (/files) Unified file explorer with git integration. Adapted from agent-stuff.

• /files - Open file browser
• Ctrl+Shift+F - Open file picker

Todos (/todos) File-based todo list management (stores in .pi/todos/).

• /todos - List and manage todos
• Tool: todo (create, update, claim, close tasks)

Notify Allows the agent to send desktop notifications (via terminal OSC 777).

• Tool: notify

Review Interactive code review system. The agent can request a review, and you can approve/reject/comment on specific files.

• Tool: request_review

Loop Iterative execution loop for complex tasks.

• Tool: run_loop

Control RPC-based session control. Allows sessions to talk to each other (e.g., a "manager" session spawning and controlling "worker" sessions).

• Flag: --session-control
• Tool: send_to_session

Nvidia NIM (/nvidia-nim-auth) Authenticate and configure Nvidia NIM as an LLM provider.

• Commands: /nvidia-nim-auth (alias: /nvidia-auth), /nvidia-nim-models
• Saves provider config to ~/.pi/nvidia-nim.json
• Adds configured models to ~/.pi/agent/settings.json enabledModels for scoped /model + Ctrl+P cycling
• Model IDs must be org/model (exactly one /), e.g. moonshotai/kimi-k2.5 (not nvidia/moonshotai/kimi-k2.5)

Powerline Footer Custom powerline-style footer replacing the default pi footer with richer information.

• Git branch + working tree status (staged/unstaged/untracked/ahead/behind)
• Model name + context usage with color-coded percentage
• Estimated session cost from model pricing
• Session duration timer
• Python virtualenv / conda environment detection
• Extension statuses + session name
• Auto-refreshes every 10 seconds via async git commands

Session Breakdown (/session-breakdown) Interactive analytics dashboard for your pi sessions.

• Analyzes all sessions in ~/.pi/agent/sessions/
• Shows sessions/day, messages/day, tokens/day, cost/day
• Model breakdown with per-model usage stats
• Filterable by 7/30/90 day windows

Development

npm install
npm test

License

MIT