#202 — Pi: The minimal agent harness

Pi is a deliberately minimalist, four-tool coding agent and toolkit that gives you full control over what enters the context window, across many LLM providers and runtimes.§

Why Pi exists

Mario Zechner built Pi after Claude Code’s system prompt, tools, and behavior kept changing under him, breaking workflows without warning. He wanted a small, layered core—under 1,000 tokens of prompt—that could run as a terminal coding CLI or sit underneath products you build, without hidden context injection or undocumented session formats.§

Pi targets a specific problem: most harnesses and unified LLM SDKs quietly inject instructions, mishandle tool calling on non-frontier models, and obscure what actually enters the context window. Pi reverses that: controlling context is the design goal, not a side-effect.§

The four core packages

Pi ships as a small toolkit of packages you can use together or embed separately.§

• pi-ai — unified API for Anthropic, OpenAI, Google, xAI, Groq, Cerebras, OpenRouter, and other OpenAI-compatible endpoints, handling streaming, TypeBox/AJV-validated tool calls, reasoning traces, cross-provider context handoff, and cost tracking.
• pi-agent-core — the agent loop: tool execution, validation, event streaming, state management, message queuing, attachments, and a transport layer that runs directly or behind a proxy.
• pi-tui — a terminal UI framework Zechner wrote from scratch, with differential rendering that only redraws changed lines instead of repainting the entire screen.
• pi-coding-agent — the CLI harness that wires sessions, tools, themes, and project context files onto the three layers below.

Zechner’s rule is explicit: if he doesn’t need a feature, Pi won’t ship it.§

What pi-ai normalizes

Under the hood, pi-ai collapses different provider APIs into four shapes: OpenAI Completions, OpenAI Responses, Anthropic Messages, and Google Generative AI. It patches over inconsistencies—fields like store being rejected by some providers, max_tokens vs max_completion_tokens, and differing reasoning-trace fields—so you can switch models mid-session without rewriting payloads.§

Anthropic thinking traces become tagged text blocks when you move to OpenAI, and full contexts can serialize to JSON for later resume on a different model. Tool results can split into a text portion for the model and a structured portion for UI rendering, including images as native attachments, with arguments checked via TypeBox and AJV. AbortController propagates through the pipeline, so canceling mid-stream still leaves a usable partial result, and pi-ai works around limitations like Google’s lack of streaming tool calls.§

CLI capabilities

The Pi CLI runs on Windows, Linux, and macOS. It supports multiple providers with mid-session switching, session resume and branching, and automatic loading of an AGENTS.md file from parent directories upward.§

You get slash commands with arguments, OAuth for Claude Pro/Max, JSON-configured custom providers, live-reloading themes, fuzzy file search and drag-and-drop in the editor, message queuing while the agent runs, vision support, HTML export, and headless operation via JSON streaming or RPC.§

System prompt and tools

Pi’s system prompt is intentionally small: a few short paragraphs describing four tools, plus your AGENTS.md appended at the bottom—and nothing else. Prompt plus tool definitions stay under 1,000 tokens, vs 10,000+ in many other harnesses.§

The built-in tools:§

• read — reads text and images with a default 2,000-line limit and offset/limit controls.
• write — creates or overwrites files, creating parent directories as needed.
• edit — performs exact-match text replacement.
• bash — runs commands synchronously with optional timeouts.

Read-only helpers like grep, find, and ls exist but are off by default, keeping the tool surface small.§

Full access, security posture, and isolation

Pi runs with full filesystem and command access by default and does not prompt for confirmation. Zechner’s argument is that once an agent can write and execute code, permission popups don’t meaningfully mitigate the risk; the only strong mitigation is cutting network access, which neuters most useful workflows.§

He points to Simon Willison’s “dual LLM” pattern as evidence that a trifecta of read access, code execution, and network access remains exploitable even with elaborate safeguards. Pi doesn’t ship a default web-search tool, but tools like curl and file reads already let a malicious file inject instructions.§

If that trade-off is uncomfortable, the docs outline three containerized patterns:§

Pattern	What’s isolated	Best for
Gondolin extension	Built-in tools and ! commands routed into a local micro-VM	Local isolation with host-side authentication
Plain Docker	Entire pi process inside a container	Simple local boundary; credentials enter container
OpenShell	Pi inside a policy-controlled sandbox (filesystem, network, credential rules)	Managed local or remote isolation via a gateway

“Project trust” only gates whether project-local settings and extensions load before you review them; it does not restrict what the model can do once running.§

What Pi leaves out

Pi deliberately omits several common agent features and explains why.§

Instead of	Pi suggests	Reasoning
MCP servers	Write a CLI tool with a README, or ship/install a Pi extension	Large MCP bundles consume thousands of prompt tokens before any useful work, shrinking the context window.
Sub-agents	Spawn another Pi instance via tmux, or orchestrate via extensions	Sub-agents hide checks and failures inside another black box, reducing visibility.
Permission popups	Run Pi in a container, or build your own confirmation flow in an extension	Confirmation dialogs don’t help once shell access exists.
Plan mode	Write plans to PLAN.md	Same output, but readable, editable, and versioned like normal code, instead of opaque in-model state.
Built-in to-dos	Use a TODO.md file with checkboxes	Files are easier to inspect and diff than to-do state embedded in a model’s memory.
Background bash	Use tmux	tmux already handles background processes reliably.

Anything missing from Pi’s core can be built as an extension, or pulled from the example extensions and third-party packages.§

pi-tui: terminal UI from scratch

Zechner evaluated two terminal UI patterns: full-screen “pixel buffer” UIs that take over the terminal and lose native scrollback/search, and UIs that write into normal scrollback and redraw only changed lines. Pi’s TUI uses the second approach.§

Components cache rendered output and only re-render when something changes. On first render or width changes, Pi redraws everything; otherwise it finds the first changed line and redraws from there, using synchronized-output sequences to avoid flicker.§

Providers and auth

Pi supports many providers via API key or subscription login.§

• Direct APIs: Anthropic, OpenAI, Google, xAI, Groq, Cerebras, OpenRouter, Mistral, and more via custom endpoints.
• Subscriptions: Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, xAI, OpenRouter, Radius.
• Enterprise: Azure OpenAI, Amazon Bedrock, Cloudflare AI Gateway and Workers AI, Google Vertex AI.

Credentials resolve in a fixed order: CLI flags, then auth.json, then environment variables, then models.json. In auth.json, a key can be a literal string, an environment variable reference, or a shell command, which lets you pull from system credential stores.§

Sessions, compaction, and branching

Pi stores sessions as JSONL trees under ~/.pi/agent/sessions/, with each entry carrying id and parentId to model branches.§

• /tree jumps to any earlier point within a session file.
• /fork starts a new file from a past message.
• /clone copies the current branch into a new file.

Auto-compaction kicks in when context size passes contextWindow minus a 16,384-token reserve. It summarizes everything older than a ~20k-token recent window into a structured summary—Goal, Constraints & Preferences, Progress, Key Decisions, Next Steps, Critical Context—without ever cutting through the middle of a tool call.§

When /tree navigates away from a branch, Pi finds the common ancestor and offers to summarize the abandoned path before you leave it; extensions can intercept both compaction and summarization to hand them to different models.§

Settings

Global settings live under ~/.pi/agent/settings.json; project overrides live under .pi/settings.json, and they merge instead of replacing each other.§

Settings cover model and “thinking” defaults, custom thinking budgets, UI behavior, retry tuning, message transport mode, and glob-based resource paths for extensions, skills, prompts, and themes. The docs explicitly warn that raising provider-level retries can hide usage-limit errors.§

Extensions

Extensions are TypeScript modules with access to tools, commands, keybindings, events, and the TUI. Hooks include:§

• project_trust, session_start, before_agent_start to inject messages or rewrite the system prompt.
• tool_call to modify arguments or block execution.
• context to edit the message list before each LLM call.
• before_provider_request and after_provider_response to rewrite raw API payloads.
• model_select to control model choice.

Features like permission gates, git checkpointing, and path protection are all built as extensions; none of them are hard-coded into Pi itself.§

Skills

A skill is a directory with a SKILL.md file following the open Agent Skills standard: name, description, and optional allowed-tools. Only the name and description sit in context until you actually call the skill.§

Pi relaxes the rule that the folder name must match the declared skill name so the same skill directory can work across Pi, Claude Code, and Codex without duplicates.§

Embedding Pi via the SDK

The SDK’s createAgentSession() returns a session object with methods like prompt(), steer(), followUp(), subscribe(), setModel() and cycleModel(), navigateTree(), and compact(). Starting, resuming, forking, or cloning sessions happens on a separate AgentSessionRuntime object.§

Events emit granular lifecycle updates—tool_execution_start, tool_execution_update, tool_execution_end, turn_start, turn_end, queue_update, compaction_start, compaction_end—so you can show live tool status instead of a single filling chat bubble. You can disable all built-in tools with noTools: "all" and provide your own with defineTool() when you’re not building a coding agent.§

Model resolution follows the same credential order as the CLI, and scopedModels lets you present a curated model list instead of one fixed option. System prompts, skills, and slash commands go through a swappable ResourceLoader, and SettingsManager.inMemory() plus SessionManager.inMemory() bypass disk for multi-tenant products or tests.§

Three main run modes sit on top:§

• InteractiveMode — full terminal UI.
• runPrintMode — single prompt-in, answer-out from scripts or APIs.
• runRpcMode — JSON over stdin/stdout for integrating from other languages.

System prompt size and benchmarks

Zechner benchmarked Pi’s small prompt against heavier harnesses and found that frontier models don’t need 10,000+ tokens of instruction to perform standard coding-agent tasks. He cites Amp as an example: it reuses parts of Claude Code’s prompt but runs fine on a much smaller one, which he takes as evidence that prompt size and agent capability are less tightly coupled than most harnesses assume.§

The recurring design pattern

Across Pi, the same pattern repeats: sessions are files, plans are files, to-dos are files, skills are portable folders, and extensions run through typed hooks instead of hidden logic. That’s deliberate: it keeps Pi transparent and composable enough to serve both as a personal terminal coding tool and as the engine inside products you build.§

Would you like this adapted into a more “launch blog” voice or kept as a factual, docs-style overview?§