skills/docs/research/pi-extension-ecosystem-research.md

Pi Coding Agent Extension Ecosystem Research

Date: 2026-01-22 Purpose: Survey the pi-coding-agent extension landscape for ideas to incorporate into dotfiles

Overview

Pi has a vibrant extension ecosystem with ~56 GitHub projects and 52 official examples. Extensions range from practical productivity tools to creative experiments.

Notable Community Extensions

🌟 High-Value Extensions

1. pi-interactive-shell (⭐ 56)

Author: nicobailon Use Case: Run interactive CLIs (vim, psql, htop) in observable overlay

Key Features:

• PTY emulation, no tmux dependency
• User can watch agent work, take over anytime
• Hands-free mode for long-running processes (dev servers)
• Auto-exit on quiet for single-task delegations
• Session management with query/kill

Interesting Patterns:

• interactive_shell({ command: 'vim config.yaml' })
• Token-efficient approach: agent spawns subprocess, user observes
• Rate-limited status queries (60s)
• Timeout mode for TUI apps that don't exit

Steal-worthy:

• Observable subprocess pattern for Nix builds
• Session management with named IDs
• Auto-exit detection for fire-and-forget tasks

---

2. pi-mcp-adapter (⭐ 16)

Author: nicobailon Use Case: Use MCP servers without burning context window

Key Innovation: Solves Mario's critique of MCP verbosity

• Single proxy tool (~200 tokens) instead of hundreds
• On-demand tool discovery: mcp({ search: "screenshot" })
• Then call: mcp({ tool: "...", args: '...' })

Pattern:

mcp({ search: "query" })  // discover tools
mcp({ tool: "name", args: jsonString })  // invoke

Steal-worthy:

• Lazy tool loading pattern
• Search-then-invoke flow
• Token budget consciousness

---

3. shitty-extensions (⭐ 25)

Author: hjanuschka Collection: 10+ extensions + 2 skills

Standout Extensions:

oracle.ts - Second opinions from other models

• Inherits conversation context
• Model picker UI with quick keys
• "Add to context?" after response
• Excludes current model from picker

memory-mode.ts - Save instructions to AGENTS.md

• Location selector: local/project/global
• AI-assisted integration (smart merge)
• Preview before save

plan-mode.ts - Claude Code-style read-only exploration

• Toggle with /plan or Shift+P
• Safe code exploration without mutations

handoff.ts - Transfer context to new sessions

• Generate context-aware prompt for fresh session

usage-bar.ts - AI provider usage statistics

• Multi-provider support (Claude, Copilot, Gemini, Codex, Kiro, z.ai)
• Status polling with outage detection
• Reset countdowns, visual progress bars

speedreading.ts - RSVP speed reader (Spritz-style)

• ORP (Optimal Recognition Point) highlighting
• Adaptive timing for longer words
• Big ASCII art font mode
• Speed control, seek, progress tracking

loop.ts (by mitsuhiko) - Conditional loops

• Loop until breakout condition (tests pass, custom, self-decided)
• Status widget with turn count
• Compaction-safe state preservation

Steal-worthy:

• Multi-model consensus pattern (oracle)
• Smart AGENTS.md integration (memory-mode)
• Provider usage tracking (usage-bar)
• Loop-until-done pattern (loop.ts)

---

4. pi-review-loop (⭐ 11)

Author: nicobailon Use Case: Automated code review loop until clean

Pattern:

/review-start
→ agent reviews, finds bugs, fixes
→ auto-prompt for another review
→ loop until "No issues found"
→ auto-exit

Features:

• Smart exit detection (won't be fooled by "Fixed 3 issues. No further issues found.")
• Auto-trigger on phrases like "implement the plan"
• Configurable max iterations (default 7)
• Prompt templates: /double-check, /double-check-plan

Steal-worthy:

• "Keep going until clean" automation
• Smart multi-pass detection (catches different issues each time)
• Pre/post implementation workflow

---

5. pi-powerline-footer (⭐ 7)

Author: nicobailon Inspiration: oh-my-pi

Features:

• Welcome overlay with gradient logo
• Rounded box design in editor border
• Live thinking level indicator (rainbow shimmer for high/xhigh)
• Git integration with async fetching, 1s cache TTL
• Context awareness (color warnings at 70%/90%)
• Token intelligence (1.2k, 45M formatting)
• Nerd Font auto-detection with ASCII fallback

Presets: default, minimal, compact, full, nerd, ascii

Segments: model, thinking, path, git, subagents, tokens, cost, context, time, session, hostname, cache

Steal-worthy:

• Nerd Font detection pattern
• Async git status caching
• Preset system for different contexts
• Thinking level visualization

---

6. pi-model-switch (⭐ 6)

Author: nicobailon Use Case: Agent can switch models autonomously

Features:

• Alias configuration: { "cheap": "google/gemini-2.5-flash", "coding": "anthropic/claude-opus-4-5" }
• Fallback chains: "budget": ["openai/gpt-5-mini", "google/gemini-2.5-flash"]
• Natural language: "switch to a cheaper model", "use Claude for this"
• Tool: switch_model({ action: "list|search|switch", search: "term" })

Steal-worthy:

• Alias system for model shortcuts
• Fallback chain pattern
• Agent-driven model selection

---

7. piception (⭐ 1)

Author: otahontas Inspiration: Claudeception

Use Case: Meta-learning - save debugging discoveries as skills

Workflow:

1. Debug something complex
2. Say "save this as a skill"
3. Interactive wizard (edit name, description, content, location)
4. Skill loads automatically next time based on semantic matching

Triggers:

• Keywords: "save this as a skill", "extract a skill"
• Session end offer if significant debugging happened

Steal-worthy:

• Meta-learning loop pattern
• Skill extraction from conversation
• Semantic matching for auto-loading

---

Official Examples (52 total)

Practical Examples

git-checkpoint.ts - Git stash checkpoints at each turn

• /fork can restore code state
• Offers to restore on fork
• Tracks entry ID → stash ref mapping

protected-paths.ts - Block writes to sensitive files

• Intercepts write and edit tools
• Configurable protected path list
• Shows notification on block

tools.ts - Enable/disable tools interactively

• /tools command with UI selector
• Persists across reloads
• Respects branch navigation
• Settings list with enabled/disabled toggle

modal-editor.ts - Vim-like modal editing

• Normal/insert mode toggle
• hjkl navigation, vim keybindings
• Mode indicator in border

auto-commit-on-exit.ts - Auto-commit on session end

dirty-repo-guard.ts - Warn if starting with uncommitted changes

file-trigger.ts - Trigger actions on file events

input-transform.ts - Transform user input before sending

trigger-compact.ts - Auto-compact at thresholds

custom-compaction.ts - Custom compaction strategies

confirm-destructive.ts - Require confirmation for dangerous ops

permission-gate.ts - Permission system for tools

tool-override.ts - Override tool implementations

truncated-tool.ts - Truncate tool outputs

UI/UX Examples

custom-header.ts - Custom header component

custom-footer.ts - Custom footer component

status-line.ts - Status line widget

widget-placement.ts - Control widget positioning

rainbow-editor.ts - Rainbow syntax theme

mac-system-theme.ts - Follow macOS light/dark mode

Interactive Examples

doom-overlay/ - Full Doom game in overlay (!)

• WAD file finder
• Doom engine
• Custom keybindings

snake.ts - Snake game

qna.ts - Q&A framework

questionnaire.ts - Multi-question forms

question.ts - Single question prompts

overlay-test.ts - Overlay testing

Communication Examples

notify.ts - System notifications

ssh.ts - SSH connection management

send-user-message.ts - Programmatic user messages

shutdown-command.ts - Shutdown handlers

Development Examples

chalk-logger.ts - Colored logging

model-status.ts - Model availability status

preset.ts - Configuration presets

summarize.ts - Conversation summarization

handoff.ts - Context transfer

pirate.ts - Pirate speak translator (fun example)

timed-confirm.ts - Confirmation with timeout

todo.ts - TODO tracking

claude-rules.ts - Claude-specific rules integration

---

Patterns Worth Stealing

1. Multi-Model Consensus

• oracle.ts: second opinions without switching contexts
• Model picker UI with inheritance
• "Add to context?" after response

2. Meta-Learning Loop

• piception: save discoveries as skills
• Semantic matching for auto-loading
• Interactive extraction wizard

3. Token Budget Consciousness

• pi-mcp-adapter: lazy tool discovery
• Search-then-invoke pattern
• Proxy tools instead of full schemas

4. Observable Subprocess Control

• pi-interactive-shell: watch agent work
• Session management (query/kill)
• Auto-exit on quiet

5. Smart Persistence

• tools.ts: branch-aware state
• git-checkpoint.ts: stash per turn
• Compaction-safe storage

6. Review Loops

• pi-review-loop: keep going until clean
• Smart exit detection
• Multi-pass catching different issues

7. Adaptive UI

• powerline-footer: Nerd Font detection
• Preset system for contexts
• Thinking level visualization
• Async git caching

8. Safety Guards

• protected-paths.ts: block dangerous writes
• dirty-repo-guard.ts: warn on uncommitted changes
• confirm-destructive.ts: require confirmation

9. Model Management

• pi-model-switch: agent-driven switching
• Alias system with fallbacks
• Natural language selection

10. Memory/Instruction Management

• memory-mode.ts: AI-assisted AGENTS.md merge
• Location selector (local/project/global)
• Preview before save

---

Ideas for Dotfiles Integration

High Priority

1. Multi-agent consensus - /orch equivalent as extension

   • Already have orch CLI, could wrap as tool
   • Modal picker UI for model selection
   • "Add to context?" option

2. Nix build observer - Interactive-shell pattern

   • Watch long Nix builds in overlay
   • Take over if needed
   • Auto-exit on completion

3. Review loop integration - Work with nix-review skill

   • /nix-review-loop command
   • Keep reviewing until no issues
   • Multi-lens passes

4. Protected paths for NixOS - Prevent accidental mutations

   • Block writes to /secrets/*.yaml (use sops edit)
   • Block direct writes to /nix/store
   • Warn on /etc/nixos (use modules/)

5. Git checkpoint auto-restore - Already have good git hygiene

   • Track changes per turn
   • Offer restore on fork
   • Persist with session

Medium Priority

6. Beads integration - Native issue tracking

   • /beads command for issue operations
   • Tool registration for agent-created issues
   • Smart linking to commits/files

7. Model switcher with aliases

   • cheap: gemini-2.5-flash
   • expensive: claude-opus-4-5
   • nix: claude-sonnet-4-5 (good at Nix)
   • Agent decides based on task

8. Usage tracking - Anthropic, OpenAI, Gemini quotas

   • Footer widget with remaining tokens
   • Warning at 80% usage
   • Cost tracking per session

9. Sops secret guard - Prevent accidental leaks

   • Intercept tool calls with secret patterns
   • Require confirmation for copying secrets
   • Never write secrets to non-sops files

10. Skill extraction - Piception pattern

    • Save debugging sessions as skills
    • Auto-populate ~/.pi/agent/skills/
    • Semantic matching for future loads

Low Priority

11. Niri window capture integration - Already have skill

    • Tool registration for agent use
    • Screenshot before/after comparisons
    • Visual regression testing

12. Powerline footer - NixOS-specific widgets

    • Flake lock status (outdated inputs)
    • Rebuild needed indicator
    • System generation count

13. Speed reader - For long outputs

    • Nix build logs
    • Test results
    • Documentation

14. Plan mode - Safe exploration

    • Read-only for large refactors
    • Preview changes before applying
    • "/plan" toggle

---

Architecture Notes

Extension Hooks (from examples)

Lifecycle:

• session_start - initialization
• session_end - cleanup
• agent_start - before agent turn
• agent_end - after agent turn
• turn_start - before turn processing
• turn_end - after turn completion

Interaction:

• tool_call - intercept before execution (can block)
• tool_result - after execution (can modify)
• user_message - intercept user input
• ai_message - intercept AI output

Session:

• session_before_fork - before creating fork
• session_fork - after fork created
• session_tree - on tree navigation
• session_compact - during compaction

UI:

• ctx.ui.notify() - system notifications
• ctx.ui.select() - picker UI
• ctx.ui.confirm() - yes/no prompts
• ctx.ui.custom() - full custom components
• ctx.ui.setEditorComponent() - replace editor

State:

• pi.appendEntry<T>(type, data) - persist to session
• ctx.sessionManager.getBranch() - get current branch
• ctx.sessionManager.getLeafEntry() - get current entry

Tools:

• pi.registerTool() - add new tools
• pi.setActiveTools() - filter available tools
• pi.getAllTools() - list all tools
• pi.getActiveTools() - list active tools

Commands:

• pi.registerCommand(name, { description, handler }) - add /command

Execution:

• pi.exec(cmd, args) - run subprocess

---

Next Steps

1. Review dotfiles' current extension setup (if any)
2. Prioritize extensions to implement
3. Start with git-checkpoint (simple, high value)
4. Add protected-paths for secrets
5. Build beads tool integration
6. Consider multi-agent consensus wrapper

---

References

• pi-mono GitHub
• Pi extensions docs
• shitty-extensions
• nicobailon's extensions
• Mario's "What if you don't need MCP"