Pi Agent Harness: Mario Zechner's Minimal Coding Agent You Can Own (2026)
Pi (pi.dev) is a minimal terminal agent harness by Mario Zechner — extensible via TypeScript extensions, skills, and packages, with tree sessions and four runtime modes. How it maps to agent harness design and when to use it.
Pi opens with a line that cuts through the 2026 agent-tool noise: there are many agent harnesses, but this one is yours.
That is not marketing fluff — it is an architectural statement. Pi is a minimal terminal coding harness from Mario Zechner (badlogic, creator of libGDX and a long line of developer tools), now documented at pi.dev under Earendil Inc. The npm package is @earendil-works/pi-coding-agent. Pi ships powerful defaults — multi-provider auth, tree-structured sessions, compaction, skills — but deliberately skips features other agents bake in: MCP, sub-agents, plan mode, permission popups, built-in todos, background bash.
If you have read our What Is an Agent Harness? guide, Pi is easiest to understand as a reference implementation of the harness layer — task intake, context management, tool execution, loop control — with maximum extension surface and minimum product opinion. The model still reasons; Pi still runs the loop. What changes is who owns the scaffolding.
Pi implements 1–4 and 6 out of the box with unusual clarity. Verification (5) is intentionally yours — write a test loop, an extension that runs CI, or a skill that defines done. That matches harness engineering as Boris Cherny describes it: the harness shapes reliability; the model does not self-certify.
Where Pi stands out is context / memory (2). Most productized agents hide context assembly behind a black box. Pi's minimal system prompt and extension hooks are built for actual context engineering — the same discipline our harness guide argues separates benchmark wins from model swaps (Terminal-Bench harness story).
# npm (recommended flags per official docs)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# macOS / Linux installer
curl -fsSL https://pi.dev/install.sh | sh
Then in a project directory:
bash
pi
Authenticate with /login for subscription OAuth providers, or export keys such as ANTHROPIC_API_KEY before launch. Pi documents 15+ providers — Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi For Coding, MiniMax, OpenRouter, Ollama, and more. Switch mid-session with /model or Ctrl+L; cycle favorites with Ctrl+P. Custom entries go in models.json or provider extensions. For GLM-5.2 specifically — Z.AI Coding Plan provider, model ids, and reasoning effort — see How to Run GLM 5.2 with Pi and Other Harnesses.
Four modes: interactive to embedded
Pi is not only a TUI. Four modes map to different harness deployment patterns:
Embed in apps — OpenClaw is pi.dev's cited real-world example
The SDK path matters for platform builders. Peter Steinberger's OpenClaw ecosystem — covered in our OpenClaw safety and subscription analysis — sits on top of harness code, not raw API calls. Pi gives you the same separation our harness guide recommends: product on harness, harness on model.
For loop engineering, print/JSON and RPC modes are how you wrap Pi inside cron jobs, verification gates, and /loop-style schedules without fighting a GUI.
Pi's context stack is the feature set most aligned with explainx.ai skills and loops philosophy — progressive disclosure instead of prompt bloat.
AGENTS.md and SYSTEM.md
AGENTS.md — project instructions loaded at startup from ~/.pi/agent/, parent directories, and the current working directory. Same pattern as Claude Code's project memory and the community AGENTS.md standard discussed in memory.md persistence.
SYSTEM.md — replace or append to Pi's default system prompt per project. This is harness-level prompt control without forking the binary.
Compaction
When context fills, Pi auto-summarizes older messages. Extensions can replace the default: topic-based compaction, code-aware summaries, or a cheaper summarization model — exactly the context manager responsibilities in our harness component breakdown.
Skills and prompt templates
Skills — capability packages (instructions + tools), loaded on demand so the prompt cache stays hot. Browse analogous patterns on explainx.ai/skills.
Prompt templates — Markdown files expanded with /name. Same mental model as slash commands on explainx.ai.
Dynamic context via extensions
TypeScript extensions can inject messages before each turn, filter history, wire RAG, or implement long-term memory — the extension point where Pi stops being "minimal" and becomes your harness.
Tree-structured sessions: harness state as a DAG
Most agents store linear chat logs. Pi stores trees.
/tree — navigate to any prior point and continue from there; all branches live in one session file
For harness designers, this is first-class loop state. Failed tool path? Branch, retry with a different skill, merge learnings — without losing the original trajectory. That pairs naturally with agent loops on explainx.ai where verification failures trigger retries rather than new chats.
Steer vs follow-up: human-in-the-loop without stopping the run
Pi supports messages while the agent works:
Enter — steering message: delivered after the current tool finishes; interrupts remaining tools in the batch
Alt+Enter — follow-up: queued until the agent completes the current run
This is harness-level human gate design — lighter than approving every tool call (which Pi intentionally omits), heavier than waiting for a full stop. Teams building loop engineering workflows can treat steering as mid-loop spec correction without tearing down context.
Primitives, not features: what Pi did not build
Pi's "What we didn't build" section is the clearest statement of its philosophy — and the best contrast with sealed products:
Omitted feature
Pi's answer
Harness-guide mapping
No MCP
Skills + CLI READMEs, or MCP via extension
Tool layer is pluggable
No sub-agents
tmux, extension, or pi install package
Multi-agent is opt-in
No permission popups
Containerize, or custom confirm extension
Failure / safety handler is yours
No plan mode
Plans as files, extension, or package
Task definition stays explicit
No built-in todos
TODO.md or extension
Memory schema is yours
No background bash
tmux — full observability
Tool execution stays visible
Pi's blog post argument: aggressive extensibility beats baked-in workflow. That is the same tradeoff our harness guide draws between custom harness (maximum flexibility) and agent platform (minutes to first run) — Pi sits in the customizable platform quadrant, closer to framework than to Claude Code's sealed UX.
Extensions are TypeScript modules with access to tools, slash commands, keyboard shortcuts, events, and the full TUI. Pi ships 50+ examples. Community packages install like:
bash
pi install npm:@foo/pi-tools
pi install git:github.com/badlogic/pi-doom
Yes — pi-doom is real. If an agent harness can run DOOM, your verification loop can run npm test.
Pi can modify Pi: /reload and shareable packages
Pi is self-hosting as a development surface. Need a command, provider, workflow, or UI tweak? Ask Pi to build it, edit extensions in place, hit /reload, continue. Bundle extensions, skills, prompts, and themes as Pi packages; publish to npm or git.
That pattern rhymes with self-harness research — with the same caution Matt Pocock raised about unsupervised self-modification of agent instructions: fine for tools and themes; review anything that rewrites default system behavior before you share it team-wide.
Pi vs forks and neighbors
oh-my-pi (omp)
oh-my-pi is the best-known Pi fork — hashline edits, LSP, DAP debugging, 40+ providers, built-in subagent orchestration. Choose upstream Pi when you want the minimal harness and will assemble pieces yourself; choose omp when you want Pi's loop with production editing and debugging baked in.
Claude Code and Cursor
Claude Code and Cursor optimize time-to-first-success inside an IDE. Pi optimizes ownership of the harness. Use Claude Code for daily flow; prototype custom verification loops in Pi when stock products do not expose the hook you need.
OpenClaw
OpenClaw embeds Pi via the SDK — messaging, scheduling, and skills at product layer; Pi at harness layer. Read our OpenClaw coverage for subscription and safety context before routing production OAuth through third-party harnesses.
When Pi is the right harness choice
Choose Pi when:
You need context engineering control (AGENTS.md, SYSTEM.md, custom compaction)
You want one harness across 15+ providers including local Ollama
You are embedding an agent in your product (SDK / RPC)
You will implement your own MCP, sub-agents, or plan mode — or install a package that matches your security model
You care about branching session history for audit and retry
Choose something else when:
You want zero setup sub-agents and IDE-native UX → Claude Code / Cursor
You want LSP + DAP + hashline edits without building extensions → oh-my-pi
You want copy-ready agent loops without writing harness code → explainx.ai loop library + Claude Code /loop
Mapping Pi to your first custom harness
If our agent harness guide sequence is: define success → write verification → simplest loop → hard exit → context → failures → instrument — Pi gives you steps 3–6 as infrastructure on day one. You still supply step 1–2 (task + verification).
A practical Pi onboarding path:
pi in a repo with AGENTS.md defining done (tests pass, lint clean)
Install a skill or prompt template for your stack from explainx.ai/skills
Add an extension only when print mode lacks a hook you need
/share session trees when debugging harness behavior with teammates
Security and sandboxing
Pi documents project trust, sandbox boundaries, and containerization (Gondolin, Docker, OpenShell) because the core harness does not ship permission popups. That is intentional: confirmation flows belong in your extension, aligned with your threat model — the same design choice our agent harness guide describes for custom failure handlers.
Running Pi in a container gives you deterministic tool boundaries while keeping the steer / follow-up UX in the TUI. For teams comparing Pi to Claude Code's built-in sandbox, the tradeoff is setup cost vs default safety rails.
Summary
Pi at pi.dev is Mario Zechner's answer to harness fatigue: a minimal terminal coding agent you extend instead of adapt to. It implements the agent harness layer — loop, tools, context, sessions — while leaving MCP, sub-agents, permissions, and plan mode as primitives you or the community supply. Tree sessions, four runtime modes (interactive, print/JSON, RPC, SDK), 15+ providers, skills, and pi install packages make it a serious base for context engineering and embedded agents (OpenClaw being the flagship SDK example).
Start with our harness explainer to learn what belongs in the scaffolding; use Pi when you are ready to own that scaffolding instead of renting it from a sealed product.
