Pi Mono: The Minimalist Kernel

What is Pi Mono?

Pi Mono (@mariozechner/pi-coding-agent, version 0.66.1) is a TypeScript-based coding agent CLI created by Mario Zechner (badlogic). It lives in a monorepo with six sibling packages, all at the same version and under the MIT license:

The project is hosted at pi.dev (domain donated by exe.dev) and its logo lives at shittycodingagent.ai — a self-deprecating branding choice that signals the project's no-nonsense attitude.

This philosophical stance makes Pi fundamentally different from Claude Code, OpenHands, and DeerFlow. It is not trying to be an operating system or a framework — it is a focused tool with a clear opinion about what a coding agent should be.

The Four Run Modes

Tool System: JSON Function Calling with TypeBox

Pi uses JSON Schema-based function calling, not XML wrappers or raw CLI parsing. Tools are defined using TypeBox schemas (@sinclair/typebox), providing type-safe parameter validation at runtime. Tool arguments are validated using AJV — if validation fails, the error is returned to the LLM as an isError: true tool result, allowing the model to retry without human intervention.

The core tool set includes 7 tools, split into two groups:

The default tool set is read, bash, edit, write (4 tools). In read-only mode, it switches to read, grep, find, ls.

The Edit Tool: Precision Engineering

Pi's edit tool is one of the most carefully designed components in any coding agent. It does not use unified diff patches or whole-file rewrites. Instead:

Bash Tool: Streaming with Safety

Pi's bash tool has several notable features:

• Pluggable backend: BashOperations interface allows swapping the execution backend. Default uses child_process.spawn() with the user's shell.
• Detached process trees: Commands spawn as detached processes. On abort or timeout, the entire process tree is killed via killProcessTree(), not just the shell.
• Streaming output: Output streams via onUpdate callback for real-time TUI updates.
• Rolling buffer: Keeps recent output in memory (up to DEFAULT_MAX_BYTES * 2), trimming old chunks.
• Temp file fallback: When output exceeds the buffer (10MB each for stdout/stderr), it writes to /tmp/pi-bash-*.log and tells the model where to find the full output.
• ANSI stripping: User-initiated bash (!command) strips ANSI codes and sanitizes binary output.
• Extension hooks: Extensions can intercept commands via BashSpawnHook, modifying the command, cwd, or environment before execution. An optional commandPrefix can be prepended to every command.

Session Management: Tree-Structured JSONL (v3)

Pi's session system is one of its most distinctive features. Sessions are stored as JSONL files with tree structure, enabling branching without file proliferation. The current session format version is v3.

{"type": "message", "id": "abc123", "parentId": null, "role": "user", "content": "..."}
{"type": "message", "id": "def456", "parentId": "abc123", "role": "assistant", ...}
{"type": "toolResult", "id": "ghi789", "parentId": "def456", "toolName": "bash", ...}
{"type": "thinking_level_change", "id": "...", "parentId": "...", "level": "high"}
{"type": "model_change", "id": "...", "parentId": "...", "model": "anthropic/claude-sonnet-4-5"}
{"type": "compaction", "id": "jkl012", "parentId": "abc123", "summary": "...", "firstKeptEntryId": "xyz", "tokensBefore": 120000}
{"type": "branch_summary", "id": "mno345", "parentId": "abc123", ...}
{"type": "label", "id": "...", "parentId": "...", "label": "bookmark-name"}

Each entry has an id and parentId, creating a tree within a single file. Entry types include: message, thinking_level_change, model_change, compaction, branch_summary, custom, custom_message, label, and session_info.

This enables:

• In-place branching: Jump to any point in the conversation and fork without creating new files.
• /tree command: Navigate the session tree with search, fold/unfold, and branch jumping.
• /fork command: Create a new session file from the current branch point.
• Compaction: Auto-triggers when context approaches limits. Uses the LLM to summarize old messages while preserving recent ones. Compaction entries track firstKeptEntryId for tree traversal.
• Labels/bookmarks: Mark important points in the tree for quick navigation.

Sessions auto-save to ~/.pi/agent/sessions/ organized by working directory. Commands like pi -c (continue most recent), pi -r (resume from list), and --session <path> provide flexible session control.

Agent Runtime: Parallel Tool Execution & Steering

The agent runtime in packages/agent/src/ is where the core agentic loop lives. The Agent class wraps agentLoop() and agentLoopContinue() with sophisticated state management:

Model Support: 23 Providers

Pi supports 24 providers via the unified @mariozechner/pi-ai package. The KnownProviders enum lists them all:

Only 10 APIs are actually implemented — the remaining 14 providers reuse compatible API shapes (most use OpenAI-compatible completions, some use Anthropic-compatible).

Model Resolution System

The ModelRegistry manages built-in models (auto-generated in models.generated.ts — 14,278 lines) and custom models. Resolution supports:

• Exact match by ID
• Canonical provider/modelId format
• Fuzzy/partial matching by ID or name
• Glob patterns for scoping (claude-*, gpt-4o)
• Thinking level suffix shorthand (model:high)
• Alias preference over dated versions (e.g., claude-sonnet-4-5 preferred over claude-sonnet-4-5-20250929)
• Ambiguity rejection when the same ID exists on multiple providers
• Custom models via ~/.pi/agent/models.json
• Dynamic providers — extensions can call pi.registerProvider() at runtime

Auth Storage

Credentials are stored at ~/.pi/agent/auth.json with 0o600 permissions (owner read/write only). The file uses proper-lockfile with retry logic for multi-instance safety — if you run two pi instances simultaneously, they won't corrupt each other's auth state.

Extension System: Build Everything Else

Pi's extension system is where the real power lies. Extensions are loaded at runtime using jiti (TypeScript runtime executor — a custom fork @mariozechner/jiti with virtualModules support for compiled Bun binaries), and they can hook into virtually every aspect of the agent.

// Example extension: Permission gate for dangerous commands
export default function(pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
      if (!ok) return { block: true, reason: "Blocked by user" };
    }
  });
}

The ExtensionAPI provides:

• pi.on(event, handler) — Subscribe to 20+ lifecycle events
• pi.registerTool(tool) — Register LLM-callable tools with TypeBox schemas
• pi.registerCommand(name, options) — Register slash commands
• pi.registerShortcut(keyId, options) — Register keyboard shortcuts
• pi.registerFlag(name, options) — Register CLI flags
• pi.registerMessageRenderer(type, renderer) — Custom message rendering
• pi.exec(command, args, options) — Execute shell commands
• pi.registerProvider(name, config) — Register custom LLM providers
• pi.events — EventBus for custom event patterns
• Custom editors, widgets, status lines, headers, footers

Extension Discovery Order

1. Project-local: cwd/.pi/extensions/
2. Global: ~/.pi/agent/extensions/
3. Explicitly configured: Via settings or -e flag
4. Pi Packages: Discovered from installed packages

No recursion beyond one level — extensions are intentionally flat and discoverable.

Event Categories

Pi Packages (Pip): Shareable Bundles

One of Pi's most distinctive features is its package system. Pi Packages (sometimes called "Pip") are shareable bundles installable via npm or git:

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo

Packages declare their contents via a pi key in package.json. They can contain:

• Extensions — TypeScript modules that hook into the agent
• Skills — Markdown-based tool definitions
• Prompts — Pre-built prompt templates
• Themes — TUI visual customization

Auto-discovery scans extensions/, skills/, prompts/, and themes/ directories within installed packages. This creates a genuine ecosystem — you don't need to write code to extend Pi, you can just install a package.

Skills: Markdown-Based Tool Definitions

Pi supports Agent Skills — markdown files following the Agent Skills standard at agentskills.io. Skills are essentially self-contained tool definitions with instructions that the agent can discover and use.

Instead of MCP servers, Pi expects you to build CLI tools with READMEs (or Skills) and extensions. The philosophy is that the overhead of MCP is unnecessary when a well-structured CLI tool plus its documentation provides the same capability.

Context Files: Auto-Loaded Project Knowledge

Pi automatically loads AGENTS.md and CLAUDE.md files from the current working directory up through parent directories, plus a global location. This means the agent picks up project-specific conventions, coding standards, and instructions without any explicit configuration.

TUI: Differential Rendering

The terminal UI in packages/tui/ is not just another blessed/inquirer wrapper. It implements a custom differential rendering engine:

• Tracks previousLines and previousWidth/previousHeight
• Only writes changed lines to the terminal — not full redraws
• Minimum render interval of 16ms (~60fps throttle)
• Overlay stack with focus management, percentage/absolute positioning, anchors
• Hardware cursor support via APC escape sequence for IME positioning
• Kitty graphics protocol for terminal image rendering
• Component-based architecture (Component interface with render(), handleInput(), invalidate())
• Input listener chain with consume/transform support
• Optional koffi (FFI) dependency for clipboard integration

Web UI: Lit Components, Artifacts, and JS REPL

The @mariozechner/pi-web-ui package (built with Lit and @mariozechner/mini-lit) provides a complete web-based agent interface:

Components

• ChatPanel — Main chat interface
• AgentInterface — Full agent interface
• MessageList, MessageEditor, Input
• Message types: UserMessage, AssistantMessage, ToolMessage, AbortedMessage, ArtifactMessage

Artifact System

Pi has a full artifact rendering system with types for:

• HtmlArtifact — Rendered HTML in sandboxed iframe
• ImageArtifact — Image display
• SvgArtifact — SVG display
• MarkdownArtifact — Rendered Markdown
• TextArtifact — Plain text
• ArtifactElement / ArtifactPill — UI components

Sandboxed Runtime

SandboxedIframe with runtime providers:

• ArtifactsRuntimeProvider — Read-only and read-write modes
• ConsoleRuntimeProvider — Console.log capture
• AttachmentsRuntimeProvider — File attachment handling
• FileDownloadRuntimeProvider — Downloadable files

JavaScript REPL

Pi includes a javascriptReplTool that renders an interactive JavaScript REPL in the web UI for tool results. This is unique among coding agents — most just show text output.

Document Extraction

The extractDocumentTool handles PDFs, DOCX, and XLSX files via pdfjs-dist, docx-preview, and xlsx — allowing the agent to read complex document formats.

Storage

IndexedDB backend with stores for sessions, settings, custom providers, and provider keys.

Sibling Packages: Mom and Pods

Error Handling and Recovery

Pi's error handling is multi-layered:

How Pi Compares to Other Agents

Strengths and Weaknesses

Key Files to Read

Updates in This Iteration

Pi Mono received significant updates with ~22,697 insertions and ~5,517 deletions:

Final Verdict