Pi Coding Agent Review: The Minimal Terminal Harness

Originally published on andrew.ooo — visit the original for any updates, code snippets that aged out, or follow-up posts.

TL;DR

Pi is a minimal, open-source terminal coding agent — a "harness" — that ships with exactly four tools (read, write, edit, bash) and expects you to extend it rather than configure it. It comes from Mario Zechner (creator of libGDX) and Armin Ronacher (creator of Flask and Jinja), published under MIT by Earendil. It's crossed 80,000 GitHub stars and does over 1.3 million npm downloads a week while deliberately doing less than Claude Code, Cursor, or Codex out of the box. Highlights:

• Radical minimalism — four built-in tools, no sub-agents, no plan mode, no bundled MCP. If you want more, you extend it.
• TypeScript extensions — add custom tools, sub-agents, plan mode, permission gates, git checkpointing, MCP, or even Doom, as first-class code you write or install.
• 30+ providers — Anthropic, OpenAI/Codex, Gemini, GitHub Copilot, DeepSeek, Groq, Cerebras, xAI, OpenRouter, local llama.cpp, and more, behind one unified API.
• Session tree with branching — sessions are JSONL trees; /tree, /fork, and /clone let you rewind and explore alternate paths without losing history.
• Four run modes — interactive TUI, print/JSON headless, RPC for process integration, and an SDK for embedding in your own apps.
• Skills + prompt templates + themes, all sharable as npm/git "Pi Packages."
• MIT licensed, built on Bun, and blunt about the fact that it has no built-in permission system — you sandbox it yourself.

If you want a hackable agent you own end-to-end, Pi is one of the most interesting things in the space right now. If you want batteries-included safety rails, that's a different tool. This review covers what Pi actually does, how it's built, the honest limitations, and how it stacks up against Claude Code.

Quick Reference

Repository	github.com/earendil-works/pi
License	MIT
Language	TypeScript (runs on Bun)
npm package	@earendil-works/pi-coding-agent
Authors	Mario Zechner (libGDX), Armin Ronacher (Flask/Jinja)
Stars	~80,000+
Weekly downloads	~1.3 million
Website	pi.dev

What Pi Is (and Isn't)

Most coding agents compete on features. Claude Code has sub-agents, plan mode, hooks, and MCP baked in. Cursor bundles an editor. Codex ships an opinionated workflow. Pi goes the other way: it is a minimal harness. By default the model gets four tools — read, write, edit, and bash — and that's it.

The philosophy is stated plainly in the docs: adapt Pi to your workflow, not the other way around, without forking Pi internals. If you want something Pi doesn't do, you either ask Pi to build it for you, or you install a third-party Pi Package that adds it. Sub-agents, plan mode, custom compaction, permission gates, git auto-commit — none of it is core, all of it is available as extensions.

That sounds like it would make Pi harder to use than a batteries-included tool. In practice it makes the core small enough to understand completely, which is the whole point. You can read the agent loop, know exactly what the model can and can't do, and add capabilities as reviewed TypeScript code instead of opaque config flags.

It helps that the people behind it have credibility. Mario Zechner built libGDX; Armin Ronacher created Flask and Jinja. This is not a weekend vibe-coded wrapper — it's a harness built by people who have maintained foundational OSS for over a decade.

Installation

Pi installs as a global npm package or via a one-line script:

# npm (note the --ignore-scripts flag — Pi doesn't need install scripts)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# or the installer
curl -fsSL https://pi.dev/install.sh | sh

Authenticate with an API key or an existing subscription:

# API key
export ANTHROPIC_API_KEY=sk-ant-...
pi

# or use a subscription (Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot)
pi
/login   # then pick your provider

Then you just talk to it. The --ignore-scripts detail is deliberate: Pi treats npm dependency lifecycle scripts as an attack surface and pins direct dependencies to exact versions with a two-day minimum release age, so a compromised same-day dependency release can't slip into a build. That level of supply-chain paranoia is unusual for a coding agent and, frankly, welcome.

The Extension Model

The heart of Pi is its extension API. Extensions are TypeScript modules that hook into the agent at runtime:

export default function (pi: ExtensionAPI) {
  // Add a custom tool the model can call
  pi.registerTool({ name: "deploy", /* ... */ });

  // Add a slash command
  pi.registerCommand("stats", { /* ... */ });

  // React to events in the agent loop
  pi.on("tool_call", async (event, ctx) => {
    // e.g. gate dangerous commands, log, checkpoint git
  });
}

From that single API, the community has built the things other agents hard-code:

• Sub-agents and plan mode — the features Pi deliberately omits from core
• Permission gates and path protection — since Pi has no built-in permission system
• Custom compaction and summarization strategies
• Git checkpointing and auto-commit so every agent turn is recoverable
• SSH and sandbox execution, MCP server integration
• Custom editors, status lines, headers, footers, overlays
• "Make Pi look like Claude Code" — a real extension, for people who want the familiar UI on top of the minimal core
• Games while you wait — yes, Doom runs inside the TUI

You bundle extensions, skills, prompt templates, and themes into Pi Packages and share them over npm or git. That turns "my agent setup" into something you can version, publish, and npm install on a new machine — instead of a pile of dotfiles.

Skills, Prompts, and Context Files

Pi speaks the emerging conventions rather than inventing its own:

• Skills follow the Agent Skills standard (SKILL.md files). Invoke them with /skill:name or let the agent auto-load them.
• Prompt templates are Markdown files you expand with /name, with {{variable}} interpolation.
• Context files are AGENTS.md or CLAUDE.md, loaded from the global config, parent directories, and the current folder — the same convention Claude Code and Codex use. You can override or append to the system prompt with .pi/SYSTEM.md and APPEND_SYSTEM.md.

The practical upside: if you already have an AGENTS.md and a .agents/skills/ directory from another tool, Pi picks them up with zero migration.

Sessions Are a Tree, Not a Line

This is Pi's most underrated feature. Sessions are stored as JSONL files where each entry has an id and a parentId, forming a tree. That unlocks in-place branching:

• /tree — navigate the whole session tree, jump to any earlier point, and continue from there. Search, fold branches, bookmark entries, all in one file.
• /fork — start a new session from a previous user message, with that prompt pre-loaded in the editor for editing.
• /clone — duplicate the current branch into a fresh session at the current position.
• --fork <id> — fork any past session straight from the CLI.

Most agents give you a linear transcript and a "clear" button. Pi lets you treat a coding session like a git history you can branch and rewind — which matches how real debugging actually goes when the model heads down a wrong path.

Long sessions are handled by compaction: it summarizes older messages while keeping recent ones, triggers automatically on context overflow (recovers and retries) or proactively near the limit, and is itself customizable via extensions. The full history stays in the JSONL, so /tree can always revisit what compaction summarized away.

Providers: One API, 30+ Backends

Under the hood, @earendil-works/pi-ai is a unified multi-provider LLM API — and it's genuinely broad. Subscriptions include Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro (Codex), and GitHub Copilot. API-key providers span Anthropic, OpenAI, Azure OpenAI, Google Gemini and Vertex, Amazon Bedrock, DeepSeek, Mistral, Groq, Cerebras, xAI, OpenRouter, Vercel AI Gateway, Fireworks, Together, Kimi, MiniMax, Hugging Face, and more. Local inference works through a llama.cpp router — /login llama.cpp, /llama to manage model downloads, /model to select.

You switch models mid-session with /model (or Ctrl+L), and /scoped-models lets you set a shortlist you cycle through with Ctrl+P. For a lot of people, that unified provider layer is worth installing Pi for on its own — it's usable as a standalone library (@earendil-works/pi-ai) even if you never touch the agent.

Community Reactions

Pi has become a reference point in the "minimal vs. maximal agent" debate. A few recurring themes from reviews and discussion:

• "When minimal beats maximal." Multiple writeups frame Pi as the counter-argument to feature-stuffed agents — you get a core small enough to fully understand, and you add only what you need.
• "The only real Claude Code competitor." Several engineers describe running Claude Code and Pi together: Claude Code for its polish and defaults, Pi for full control of the agentic stack when they need to script or customize it.
• Token efficiency. Pi is frequently praised as one of the more token-efficient harnesses, partly because the minimal default toolset means less system-prompt and tool-schema overhead per turn.
• Trust in the maintainers. "It's from the libGDX and Flask guys" comes up a lot — the pedigree buys credibility that a nameless wrapper wouldn't get.

The critical takes are consistent too: Pi asks more of you up front, and its safety story is deliberately your responsibility, not the tool's.

Honest Limitations

Pi is opinionated, and the opinions cut both ways.

• No built-in permission system. This is the big one, and Pi says so directly: it "does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it." There are no per-command approval prompts in core. You're expected to sandbox it — Pi documents three containerization patterns (a Linux micro-VM extension, plain Docker, or a policy-controlled sandbox). If you're used to Claude Code asking before every rm, Pi's defaults will feel alarming.
• Minimalism has a learning curve. No sub-agents or plan mode out of the box means you either accept the plain loop or go install/build extensions. That's power for advanced users and friction for beginners.
• Extensions are code you run. Sub-agents, permission gates, and git checkpointing being extensions means third-party TypeScript executing in your agent. Pi's project-trust flow (/trust, defaultProjectTrust) mitigates this, but it's a real responsibility.
• The ecosystem is young. Conventions like Pi Packages are great, but the catalog of high-quality third-party packages is still growing compared to more established tools.
• Contribution friction. New-contributor issues and PRs are auto-closed by default (maintainers review them daily). It keeps the repo sane at 80K stars, but it surprises first-time contributors.

None of these are dealbreakers — they're the honest cost of a tool that hands you full control instead of guardrails.

Pi vs. Claude Code

	Pi	Claude Code
License	✅ MIT, open source	❌ Proprietary
Default tools	4 (read, write, edit, bash)	Many, built-in
Sub-agents / plan mode	⚠️ Via extensions	✅ Built-in
Providers	✅ 30+ (Claude, GPT, Gemini, local, …)	Anthropic only
Permission system	❌ None in core — you sandbox	✅ Approval prompts
Extensibility	✅ TypeScript extensions + packages	⚠️ Hooks + MCP
Session branching	✅ Tree with /tree, /fork, /clone	⚠️ Linear + resume
Context files	AGENTS.md / CLAUDE.md	CLAUDE.md

The honest summary: Claude Code is the safer, more polished default — approval prompts, sub-agents, and plan mode with zero setup. Pi is the tool you reach for when you want to own the stack — provider-agnostic, MIT-licensed, and extensible down to the agent loop. Plenty of engineers run both, and Pi's own docs even ship a "make Pi look like Claude Code" extension for people who want the familiar surface on the open core.

FAQ

Is Pi free and open source?
Yes. Pi is MIT-licensed and published on npm as @earendil-works/pi-coding-agent. You pay only for whatever LLM provider you point it at (Claude, GPT, Gemini, or a free local model via llama.cpp).

Who makes Pi?
It's built by Mario Zechner (badlogic, creator of libGDX) and Armin Ronacher (mitsuhiko, creator of Flask and Jinja), published under the Earendil org. That maintainer pedigree is a big part of why it's trusted at 80K+ stars.

How is Pi different from Claude Code?
Pi is open source, provider-agnostic (30+ backends including local models), and radically minimal — four built-in tools with everything else as TypeScript extensions. Claude Code is proprietary, Anthropic-only, and ships sub-agents, plan mode, and permission prompts built in. Many engineers use both.

Is Pi safe to run?
Pi has no built-in permission system — by default it runs with your user's full permissions and won't prompt before file edits or shell commands. That makes sandboxing your responsibility. Pi documents three containerization patterns (a Linux micro-VM extension, plain Docker, or a policy-controlled sandbox); use one for anything sensitive.

Can Pi use local models?
Yes. Pi integrates a llama.cpp router — /login llama.cpp to enable it, /llama to download and load models, and /model to select a loaded model. Alongside that it supports 30+ cloud providers behind one unified API.

What are Pi extensions and packages?
Extensions are TypeScript modules that add tools, commands, sub-agents, permission gates, git checkpointing, MCP integration, and UI to Pi. You bundle extensions, skills, prompt templates, and themes into "Pi Packages" and share them via npm or git — so your entire agent setup becomes installable.

Verdict

Pi is one of the most interesting coding agents of 2026 precisely because it refuses to compete on feature count. Four tools, a tiny core you can actually read, and a TypeScript extension model that lets you build up to sub-agents, plan mode, and permission gates only if and when you want them. Add a genuinely broad multi-provider layer (including local models) and a session tree you can branch and rewind, and you have a harness that senior engineers can bend to almost any workflow.

The cost is real: no safety rails by default, a steeper on-ramp than batteries-included tools, and the responsibility of sandboxing it yourself. If you want an agent that holds your hand, run Claude Code. If you want an agent you fully own — open, hackable, and provider-agnostic — Pi has earned its 80,000 stars. The best answer for a lot of people is to run both.

Sources

• Pi on GitHub — README, package overview, containerization docs, supply-chain policy
• pi-coding-agent README — full CLI reference, extensions, skills, sessions, providers
• @earendil-works/pi-coding-agent on npm — package, version, weekly downloads
• pi.dev — project website, demos, and documentation
• Community reviews (Context Studios, Standard Compute, DEV Community, Agentic Engineer) — minimal-vs-maximal framing and Claude Code comparisons