# 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**:
```typescript
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](https://github.com/badlogic/pi-mono)
- [Pi extensions docs](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md)
- [shitty-extensions](https://github.com/hjanuschka/shitty-extensions)
- [nicobailon's extensions](https://github.com/nicobailon?tab=repositories&q=pi-)
- [Mario's "What if you don't need MCP"](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/)
