# Pi Mono Pi is a minimal, extensible [[AI Agent Harness]] created by [[Mario Zechner]]. It's written in TypeScript and MIT licensed. The 1.0 README describes it as "a minimal, extensible agent harness that you can make your own". The idea is simple: ship a small core, then let you adapt it with extensions, skills, prompt templates and themes instead of waiting for someone to add the feature you need. It started as a minimal CLI coding agent in the `badlogic/pi-mono` repo. With 1.0 (2026), the project moved to the `earendil-works/pi` GitHub org and the `@earendil-works/pi-coding-agent` npm package. It now has its own site (pi.dev) and installer: `curl -fsSL https://pi.dev/install.sh | sh`, then `pi update` for updates. ## Philosophy The guiding rule is "If I don't need it, it won't be built". Missing features are meant to come from extensions or packages ("ask Pi to build what you want, or install a package that does it your way"). In practice: - A minimal system prompt: under 1000 tokens at launch, vs ~10k for [[Claude Code]] - A small set of core tools: read, write, edit and bash - Full context observability. Nothing gets injected behind your back - Stable, documented system prompts, so new releases don't break your workflows - YOLO by default: tools run with the OS permissions of the Pi process. Since 1.0, Pi resolves project trust before loading a project's settings and resources ## How it works The agent loop sends a request to the model, streams back the response and its tool calls, executes the tools, then starts the next turn. It keeps going until there's no more work. Sessions are stored as JSONL trees. Every entry points to its parent, so continuing from an earlier message creates a branch in the same file. Forking and cloning copy the history into a new session. Compaction inserts a summary entry, but the original entries stay in the tree (nothing is thrown away). What goes into the context: the base instructions, the context files Pi discovers (`AGENTS.md`, `CLAUDE.md`), the tool definitions and the skill descriptions. Full skill instructions only load when they're needed. You can drive Pi through an interactive TUI, print mode (`-p`), JSON mode (events as JSONL), RPC mode (JSONL commands on stdin) or a TypeScript SDK. All of them share the same agent and session mechanisms. ## Extensibility (1.0) - **Extensions**: TypeScript modules loaded in the Pi process. They register tools, slash commands, shortcuts, providers, event handlers, renderers and TUI elements - **Skills**: Pi implements the Agent Skills specification (`SKILL.md` directories; see [[AI Agent Skills]]). Same format as Claude Code skills - **Prompt templates**: reusable markdown messages that you use as custom slash commands - **Pi packages**: bundles of extensions, skills, prompt templates and themes, shared via npm or git (`pi install <source>`, `pi list`, `pi remove`) - **MCP**: native [[Model Context Protocol (MCP)]] client since 1.0 (stdio and streamable HTTP, OAuth servers, `pi mcp add/list`, per-project overrides in `.pi/mcp.json`). That reverses the original "no MCP" stance - **Virtual models**: an extension registers a selectable model that picks a physical model for each request (e.g., quick questions go to a small model, hard ones to a large one) - **Codemode**: an optional tool where the model writes a JavaScript script (in a QuickJS sandbox) that calls Pi's tools in parallel and filters the results. Only the script's output reaches the context - **Classifier models**: built-in support for [[Jev]] by [[TypeSafe AI]] (via TypeSafe, [[OpenRouter]] or Cloudflare Workers AI) and Cloudflare's Clef models, called from codemode with `models.classify()`. Cheap decisions (routing, gating, verification) become a first-class primitive; see [[Decision Models (DMs)]] ## Models and providers - Many providers, via API key or `/login` (OAuth/device flow): Anthropic, OpenAI, Google, GitHub Copilot, Mistral, Groq, Cerebras, xAI, DeepSeek, [[OpenRouter]], Vercel AI Gateway, and more. Local models work through [[llama.cpp]] and OpenAI-compatible servers - You can switch models mid-session, cycle through a scoped set of models, and track costs and tokens in full A warning about Claude subscriptions. Pi can technically sign in with a Claude Pro/Max account, but Anthropic forbids using these subscriptions in third-party harnesses. Server-side blocks started on 2026-01-09, and since 2026-04-04 that usage is billed per token as "extra usage" instead of counting against the plan. On top of that, you put your account at risk. So, in practice, Claude in Pi means an Anthropic API key. ## Packages in the monorepo - **pi-ai**: unified LLM API across providers - **pi-agent-core**: the agent loop runtime (tool execution, state management, event streaming) - **pi-coding-agent**: the CLI itself - **pi-tui**: terminal UI framework with differential rendering - **pi-web-ui**: web chat interface components - **pi-mom**: Slack integration that routes messages to the coding agent - **pi-pods**: deployment utility for vLLM on GPU infrastructure ## What Pi still leaves out Per the 1.0 README, there are still NO sub-agents and NO plan mode. If you need those, use external sessions, RPC, files (`PLAN.md`) or a package. Originally, Pi also had no background bash (use tmux) and no built-in to-dos (use `TODO.md`). ## Why it matters To me, Pi is the clearest example of the "build your own harness" approach to [[Harness Engineering]]. You get a small, observable loop, and routing, gating and verification live in your own code rather than in a vendor's built-in rules. [[OpenClaw]] is built on it. ## References - Source code (1.0+): https://github.com/earendil-works/pi - Original repo: https://github.com/badlogic/pi-mono - Website: https://pi.dev - Author's writeup: https://mariozechner.at/posts/2025-11-30-pi-coding-agent/ - Armin Ronacher's review: https://lucumr.pocoo.org/2026/1/31/pi - Pi + Jev harness tutorial: https://academy.dair.ai/resources/jev-decisions-in-a-pi-sdk-harness - Anthropic subscription ban: https://alternativeto.net/news/2026/2/anthropic-officially-bans-using-subscription-authentication-for-third-party-claude-use - April 4 billing enforcement: https://github.com/thedotmack/claude-mem/issues/1826 ## Related - [[AI Agents]] - [[AI Agent Harness]] - [[Harness Engineering]] - [[AI Agent Skills]] - [[Model Context Protocol (MCP)]] - [[Jev]] - [[Decision Models (DMs)]] - [[Claude Code]] - [[Vibe Coding]] - [[OpenClaw]]