Pi Coding Agent

Imagine a coding agent that fits in your pocket. Not literally, but philosophically. A tool with a system prompt under a thousand tokens, just four tools, and no MCP, no plan mode, no background bash, no sub-agents, and no built-in to-do lists. That's Pi.

Pi is an open-source, minimalist AI coding agent created by Mario Zechner (also known as badlogic). It runs in your terminal and gives an LLM exactly four tools to work with your codebase: read, write, edit, and bash. That's it. And yet, despite this radical simplicity, Pi has become quietly foundational as the agent harness that OpenClaw is built on top of.

What makes Pi genuinely interesting is not what it has, but what it deliberately leaves out. Mario built Pi because he was frustrated with how Claude Code had turned into what he calls "a spaceship with 80% of functionality I have no use for." Every release changed the system prompt, broke his workflows, and altered model behavior. Pi is his answer: a stable, predictable, deeply understandable agent that does one thing well and gets out of your way.

Pi lives on pi.dev and is published on npm as a collection of packages under the @earendil-works scope. It's MIT licensed and written in TypeScript with a focus on clean architecture, minimal dependencies, and developer experience.

Mario Zechner had been using LLMs for assisted coding for about three years before he built Pi. Like many developers, he went through the evolution: copying and pasting into ChatGPT, trying Copilot (which never clicked), moving to Cursor, and eventually settling on Claude Code as his daily driver.

But over time, Claude Code changed. Features were added rapidly. The system prompt and tools shifted on every release. Workflows broke. Model behavior became unpredictable. Mario, who describes himself as "a simple boy who likes simple, predictable tools," had had enough. So he built his own.

Mario named the project "Pi" precisely because it would be hard to search for. As he put it, he wanted "a name that's entirely un-Googleable, so there will never be any users." The joke, of course, is that Pi became popular anyway.

Pi's story is intertwined with OpenClaw. Peter Steinberger, the creator of OpenClaw, had gotten Mario and Armin Ronacher (creator of Flask) hooked on the idea of agents that write and run code. As OpenClaw exploded in popularity, people discovered that under the hood, its agent loop was built on Pi's packages. Armin Ronacher wrote a widely-read blog post titled "Pi: The Minimal Agent Within OpenClaw" that brought Pi to a much wider audience.

Pi was featured on the Pragmatic Engineer Podcast in April 2026, where Mario and Armin discussed the philosophy behind the tool, the risks of automation bias, and why human judgment still matters in an AI-driven world.

Pi is not a monolith. It's a collection of four npm packages that layer on top of each other, each handling a specific concern. This modular design is what makes Pi both flexible and stable.

Package	npm Scope	What It Does
pi-ai	@earendil-works/pi-ai	Unified multi-provider LLM API with streaming, tool calling, thinking, abort support, cost tracking, and cross-provider context handoff
pi-agent-core	@earendil-works/pi-agent-core	Agent loop with tool execution, validation, event streaming, state management, and transport abstraction
pi-tui	@earendil-works/pi-tui	Minimal terminal UI framework with differential rendering, flicker-free updates, markdown rendering, and autocomplete editors
pi-coding-agent	@earendil-works/pi-coding-agent	The actual CLI: wires agent with session management, custom tools, themes, project context files, and extension loading

A fifth package, pi-chat, exists for Slack and chat-based automation workflows.

pi-ai: The Unified LLM API

At the bottom of the stack is pi-ai, a carefully designed abstraction over the four major LLM APIs: OpenAI's Completions API, OpenAI's Responses API, Anthropic's Messages API, and Google's Generative AI API. It supports streaming, tool calling with TypeBox schema validation, thinking traces, abort signals throughout the entire pipeline, and token and cost tracking on a best-effort basis.

The really clever part is cross-provider context handoff. pi-ai was designed from day one to let you switch models mid-session. You can start a conversation with Claude, ask a follow-up with GPT, and hand it off to Gemini, all while preserving context. Thinking traces from Anthropic get converted to <thinking> tagged text when passed to OpenAI.

pi-agent-core and pi-tui

On top of pi-ai sits the agent runtime, providing an agent loop that handles the full orchestration. The loop emits events for everything, making it easy to build reactive UIs on top. pi-tui uses a retained-mode UI model with differential rendering, which means it only redraws what changed. The result is a terminal UI that barely flickers, a stark contrast to tools like Claude Code.

Pi ships with exactly four built-in tools. That's by design. Mario believes that if you give an LLM more tools than these, you're solving the wrong problem.

Tool	What It Does
Read	Read files from the filesystem. The agent can inspect any file in the project.
Write	Write new files or overwrite existing ones.
Edit	Targeted edits to existing files. Search-and-replace style modifications.
Bash	Run shell commands. Execute code, install packages, run tests, anything a terminal can do.

No browser tool, no MCP connector, no sub-agent spawner, no file search, no git integration as a built-in. If the agent needs to do something beyond these four actions, it can write a script and run it with bash. Or it can build an extension.

Pi's design is rooted in the YAGNI principle: "You Aren't Gonna Need It." Every feature has to justify its existence.

What Pi Deliberately Omits

• No MCP support - The Model Context Protocol is intentionally absent.
• No plan mode - No "first I'll plan, then I'll execute" workflow.
• No sub-agents - No delegation to child agents.
• No background bash - Commands run in the foreground.
• No built-in to-do lists - No task tracking baked into the agent.
• No built-in permission system - Pi runs with whatever permissions the launching user has.

The Million-Token System Prompt Problem

Mario observed that many coding agents suffer from system prompt bloat. Every feature, every tool, every integration adds tokens. Over time, these prompts grow to tens of thousands of tokens, silently consuming context window and changing model behavior. Pi's system prompt is under a thousand tokens. Every word has been carefully considered.

Stability Over Velocity

Mario deliberately avoids adding features because every new feature is a potential source of bugs and behavioral changes. The result is a tool that behaves the same way today as it did six months ago.

Pi's extension system is where the seemingly minimal core reveals its hidden depth. Despite having only four tools, Pi is deeply extensible, but in a way that celebrates code writing code rather than downloading plugins.

Extensions in Pi are TypeScript modules that can add new tools, modify existing behavior, and persist state across sessions. An extension can save data to disk and reload it when the agent starts a new session, enabling long-running workflows and learned behaviors. The extension system has built-in hot reloading: the agent can write extension code, reload it without restarting, test it, and iterate in a loop.

Session Trees

One of Pi's most unique features is that sessions are trees, not linear logs. You can branch a session to go on a side-quest, then rewind back to the main branch with a summary of what happened. This is incredibly powerful for maintaining context efficiency.

Pi's most fascinating aspect is its relationship with self-modifying software. Because Pi is written in TypeScript and its extensions are TypeScript modules loaded at runtime, the agent can modify its own source code and extensions to change its behavior.

The practical implication is that Pi can adapt to tasks without waiting for a developer to add a feature. Need a tool that fetches data from a specific API? The agent can write an extension that calls that API. Need a custom workflow? The agent can write the code for it. This is different from "tool use" - the agent isn't just calling a function, it's creating the function. Mario believes this is a preview of how software will work in the future: malleable, self-modifying programs that adapt to their users.

Pi was designed in a multi-model world. The pi-ai package supports Anthropic, OpenAI, Google, xAI, Groq, Cerebras, OpenRouter, and any OpenAI-compatible endpoint. It handles provider-specific quirks like Cerebras not supporting the store field, Mistral using max_tokens instead of max_completion_tokens, and Google not supporting tool call streaming.

pi-ai has an extensive test suite that runs across all supported providers and popular models, covering image inputs, reasoning traces, and tool calling.

Structured Tool Results

One of pi-ai's most thoughtful features is its structured split tool results. Each tool execution can return two separate outputs: one for the LLM (text or JSON that the model reads) and one for the UI (structured data for display). This means you're not forced to cram UI-relevant information into the model's context.

The most prominent project built on Pi is OpenClaw, the viral personal AI assistant framework. OpenClaw uses Pi's packages as its agent core, layering on its own gateway daemon, multi-channel messaging, skill system, and security model.

Mario regularly publishes his own Pi work sessions on Hugging Face under pi-mono. These are real-world coding sessions that anyone can inspect. The project also has pi-share-hf that lets anyone publish their Pi sessions to Hugging Face.

Pi has an active community on Discord where users share extensions for web search, URL fetching, GitHub repo cloning, PDF extraction, YouTube video understanding, and more. These are all implemented as extensions on top of the four core tools.

Aspect	Pi	Claude Code	OpenCode
System prompt size	Under 1K tokens	Large	Moderate
Built-in tools	4 (read, write, edit, bash)	Many (MCP, sub-agents, plan mode)	Many (build/plan agents, toolsets)
Provider support	Multi-provider, cross-session handoff	Anthropic-only	Multi-provider via Zen
Extension system	TypeScript hot-reload extensions	MCP-based	Plugin system
Session model	Tree branches	Linear	Linear
Self-modifying	Yes, writes its own extensions	No	No
TUI quality	Flicker-free differential rendering	Flickering	Modern TUI

Key differentiators: smallest system prompt, only four tools, cross-provider sessions, session trees, self-modifying architecture, and flicker-free TUI.

Quick Install (no global install):

npx @earendil-works/pi-coding-agent

Global Install:

npm install -g @earendil-works/pi-coding-agent
pi

Requirements: Node.js 20+ and an API key for your preferred LLM provider.

Key Commands

• pi - Start an interactive coding session
• pi --model anthropic/claude-sonnet-4 - Start with a specific model
• pi --session NAME - Resume a named session
• pi update --self - Update Pi to the latest version

Containerization

Pi doesn't include built-in permission controls. For safety, three containerization patterns are available: Gondolin extension (local micro-VM), plain Docker (simple isolation), and OpenShell (policy-controlled sandbox).

Pi's minimalist design is not laziness or lack of ambition. It's a carefully considered philosophy about how AI agents should work.

• Context Engineering Is Paramount - Exactly controlling what goes into the model's context yields better outputs. Pi gives you full visibility into what the model sees.
• Inspect Everything - Pi sessions are stored in a clean, documented format that you can post-process with any tool. The agent emits events for everything.
• No Black Boxes - The codebase is clean, modular, and well-documented. If something behaves unexpectedly, you can read the source and understand why.
• You Are the Pilot - Human judgment still matters. Automation bias is one of the biggest risks in agentic coding. Pi is designed to be a tool in your hands, not a replacement for your judgment.