<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->

# Pi Agent Review for aidevops Inspiration

**Task**: t103
**Date**: 2026-02-05
**Status**: Complete

## Overview

[Pi](https://github.com/badlogic/pi-mono/) (7.1k stars, MIT license) is a minimal coding agent toolkit by Mario Zechner. Blogged about by [Armin Ronacher](https://lucumr.pocoo.org/2026/1/31/pi/) (creator of Flask/Rye/uv). Pi powers [OpenClaw](https://openclaw.ai/) (the viral messaging-platform AI agent).

**Tech Stack**: TypeScript monorepo (npm workspaces), Node.js
**Packages**: coding-agent CLI, unified LLM API, TUI library, web UI, Slack bot, vLLM pods
**Contributors**: 112 | **Releases**: 144 (v0.52.2 as of 2026-02-05)

## Key Design Principles

### 1. Minimal Core (4 Tools Only)

Pi has the shortest system prompt of any known coding agent. Only four tools: **Read, Write, Edit, Bash**.

**aidevops comparison**: aidevops also uses these four core tools but layers many MCP tools on top. Pi's philosophy is that additional capabilities come from extensions and skills the agent builds itself, not from pre-loaded tool definitions.

**Takeaway**: Validates aidevops's on-demand MCP loading pattern (t067). Pre-loading many tools wastes context. Pi proves a minimal tool set is sufficient when the agent can use Bash to access anything.

### 2. Extension System with Persistent State

Extensions can:
- Register new tools for the LLM
- Add slash commands
- Render custom TUI components (spinners, progress bars, file pickers, data tables)
- Persist state across sessions via custom messages in session files
- Hot-reload (agent writes code, reloads, tests in a loop)

**aidevops comparison**: aidevops uses subagents (markdown files) + helper scripts (bash). Pi uses TypeScript extensions with runtime hot-reload. Both achieve extensibility but through different mechanisms.

**Takeaway**: Hot-reload for agent-built tools is powerful. aidevops's `/add-skill` system (t066) is the closest equivalent but skills are static markdown, not executable code. Consider whether aidevops should support executable extensions (TypeScript/Python scripts that register as tools).

### 3. No MCP (Deliberate Omission)

Pi deliberately excludes MCP. Instead:
- Uses [mcporter](https://github.com/steipete/mcporter) CLI bridge when MCP is needed
- Encourages the agent to build its own tools via extensions
- Philosophy: "You don't download an extension, you ask the agent to extend itself"

**aidevops comparison**: aidevops heavily invests in MCP (mcp-index-helper.sh, on-demand loading, per-subagent frontmatter). Pi's approach is philosophically opposite.

**Takeaway**: Both approaches are valid for different audiences. aidevops serves teams needing reproducible, shareable configurations. Pi serves individual power users who want maximum flexibility. No action needed -- aidevops's MCP approach is correct for its multi-tool, multi-user target.

### 4. Session Trees (Branching & Rewinding)

Sessions in Pi are trees, not linear histories. Users can:
- Branch into a side-quest (e.g., fix a broken tool) without polluting the main context
- Rewind to an earlier point after the side-quest
- Pi summarizes what happened on the other branch

**aidevops comparison**: aidevops has no session branching. Context management relies on fresh sessions (Ralph loop), memory system (/remember, /recall), and worktrees for code isolation.

**Takeaway**: Session trees could significantly improve context management. When debugging a tool mid-task, the current approach is to either waste context in the main session or start a new session and lose context. **Recommendation**: Document this as a future consideration for aidevops's session management. Not implementable without agent-level support (would need Claude Code/OpenCode to add session tree features).

### 5. Skills as Agent-Generated Code

Armin Ronacher's approach: skills are hand-crafted by the agent, not downloaded from repositories. He replaced all browser automation MCPs with a single [CDP-based skill](https://github.com/mitsuhiko/agent-stuff/blob/main/skills/web-browser/SKILL.md) the agent built.

Notable skills from mitsuhiko/agent-stuff (912 stars):
- `/commit` - Git commits with Conventional Commits style
- `/web-browser` - Puppeteer-based browsing (replaces MCP)
- `/github` - GitHub CLI interactions
- `/tmux` - Terminal multiplexer control
- `/sentry` - Sentry issue reading
- `/ghidra` - Reverse engineering
- `/uv` - Python dependency management (intercepts pip calls)

**aidevops comparison**: aidevops's `/add-skill` imports external skills. Pi's approach is "point agent at an example, have it build a custom version."

**Takeaway**: The "remix" pattern is interesting -- point the agent at an existing skill and say "build me something like this but with these changes." aidevops could document this as a workflow pattern in build-agent.md: "When a community skill doesn't quite fit, use it as a reference for the agent to build a custom version."

### 6. Notable Pi Extensions (from mitsuhiko/agent-stuff)

| Extension | Purpose | aidevops Equivalent |
|-----------|---------|---------------------|
| `/answer` | Extract questions from agent response into input box | No equivalent (useful UX pattern) |
| `/todos` | File-backed todo manager with TUI | TODO.md + beads |
| `/review` | Branch-based code review (like Codex) | `/pr review` workflow |
| `/files` | Session file browser with diff/reveal | No equivalent |
| `/loop` | Rapid iterative coding loop | Ralph loop |
| `/control` | Send prompts between Pi agents | Mail system (mail-helper.sh) |
| `/notify` | Desktop notifications on completion | No equivalent |

### 7. Multi-Provider Session Portability

Pi's AI SDK allows sessions to contain messages from different model providers. It avoids leaning into provider-specific features that can't transfer.

**aidevops comparison**: aidevops is model-agnostic at the instruction level (AGENTS.md works with any provider) but doesn't manage sessions directly.

**Takeaway**: Validates aidevops's approach of keeping instructions provider-agnostic. No action needed.

## Comparison Matrix

| Aspect | Pi | aidevops | Winner |
|--------|-----|----------|--------|
| Core simplicity | 4 tools, tiny prompt | ~50-100 instructions, many MCPs | Pi (simpler) |
| Extensibility | TypeScript hot-reload extensions | Markdown subagents + bash scripts | Pi (more dynamic) |
| Multi-tool support | Pi-only | Claude Code, OpenCode, Cursor, etc. | aidevops (broader) |
| Team/sharing | Individual-focused | Multi-user, reproducible configs | aidevops (better for teams) |
| Session management | Tree-based branching | Linear + fresh sessions (Ralph loop) | Pi (more sophisticated) |
| MCP support | None (deliberate) | Extensive, on-demand | aidevops (more integrations) |
| Task management | Simple /todos extension | TODO.md + PLANS.md + Beads + TOON | aidevops (more comprehensive) |
| Memory | Extension state in sessions | SQLite FTS5 cross-session memory | aidevops (more persistent) |
| Code quality | Excellent (per Ronacher) | SonarCloud A-grade, ShellCheck | Both strong |
| Community | 7.1k stars, 112 contributors | Growing | Pi (larger community) |

## Actionable Recommendations

### Adopt (high confidence)

1. **Document "remix" skill pattern** in build-agent.md: When a community skill doesn't fit, use it as a reference for the agent to build a custom version rather than forking. (~10m)

2. **Add desktop notification pattern**: Document how to add terminal notifications (OSC 777) when long-running tasks complete. Useful for Ralph loop and full-loop. (~15m, new task)

### Consider (medium confidence)

3. **Executable extensions**: Evaluate whether aidevops should support TypeScript/Python scripts that register as agent tools at runtime (beyond static markdown skills). This would enable hot-reload patterns. Significant architectural change -- park for future evaluation.

4. **Session branching advocacy**: When Claude Code or OpenCode add session tree features, aidevops should be ready to leverage them. Document the concept in session-manager.md as a "future capability."

### Skip (low value for aidevops)

5. **Remove MCP in favor of Pi's approach**: Not appropriate. aidevops's multi-tool, multi-user audience needs reproducible MCP configurations. Pi's "agent builds its own tools" approach works for individual power users but doesn't scale to teams.

6. **Rewrite in TypeScript**: Pi's TypeScript monorepo is elegant but aidevops's bash+markdown approach is more portable and doesn't require a runtime. Different design goals.

## Key Insight

Pi and aidevops represent two valid philosophies for agent frameworks:

- **Pi**: Minimal core, maximum agent autonomy, individual power users, "software building software"
- **aidevops**: Comprehensive framework, reproducible configurations, multi-tool teams, "DevOps automation"

They are complementary, not competing. A user could run Pi as their coding agent while using aidevops's infrastructure (memory, task management, deployment workflows, SEO tools) via skills or bash.

## References

- Blog post: https://lucumr.pocoo.org/2026/1/31/pi/
- Pi monorepo: https://github.com/badlogic/pi-mono/ (7.1k stars, MIT)
- Armin's agent-stuff: https://github.com/mitsuhiko/agent-stuff (912 stars, Apache-2.0)
- OpenClaw: https://openclaw.ai/
- mcporter (MCP CLI bridge): https://github.com/steipete/mcporter
