LUNAROPS · OPERATIONAL UPLINK 100% UPTIME 1,247d POSTS 893 JEFF.MOON@LUNAROPS.DEV UTC --:--:--

Pi: The Agentic Coding Harness That Refuses to Have Opinions

12 min read AI & Machine Learning
piagentic-codingai-agentsdeveloper-toolsllmcli
Contents

The dominant agentic coding tools of 2026 — Claude Code, Cursor, Codex — are products in the strong sense: they arrive with a worldview baked in, a large system prompt, an opinion about how you should plan, sub-agents, plan modes, and an ever-growing feature surface that you adapt yourself to. Pi, an open-source harness from the earendil-works team (the project of Mario Zechner, better known as badlogic), is the deliberate inverse. Its thesis is that a coding agent should be plumbing, not a personality: a small, inspectable core of four tools and a unified model API, with everything else — planning, sub-agents, MCP, your house style — left to extensions you install or write. The bet underneath is specific and worth taking seriously: in an agentic loop, the scarcest resource is the context window, and the value lives in your repository, your docs, and your plans — not in the harness’s own prompt. Pi is built to keep the harness’s footprint small so that budget stays yours. Whether that is liberating or just homework is the real question, and the answer depends entirely on who you are.

What Pi Actually Is

Pi is not a single binary but a small monorepo of layers, each usable on its own, published under the MIT license. Understanding the split is the fastest way to understand the project’s intent.

Package Role
@earendil-works/pi-ai Unified multi-provider LLM API (Anthropic, OpenAI, Google, and 30+ others)
@earendil-works/pi-agent-core The agent runtime: the tool-calling loop and state management
@earendil-works/pi-coding-agent The interactive coding-agent CLI most people mean by “pi”
@earendil-works/pi-tui A terminal UI library with differential rendering

That layering is the architecture as politics. Because the LLM API, the agent loop, and the TUI are separate packages, you can embed the runtime in your own application without the CLI, or drive the CLI from a script without touching its internals. Most “harnesses” fuse these concerns; Pi keeps them apart on purpose so that none of them gets to dictate the others. Installation is a single global npm install or a shell script:

1
2
3
4
5
6
7
8

# Recommended: install the CLI globally, skipping lifecycle scripts
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# Or the one-liner
curl -fsSL https://pi.dev/install.sh | sh

# Then, from any repo
pi

This sits in the same broad category as the terminal-first agents covered in the AI-in-the-terminal post and the workflow discussion in AI-assisted coding, but Pi’s distinguishing move is what it leaves out, not what it adds.

The Four-Tool Core

By default, Pi hands the model exactly four tools: read, write, edit, and bash. A few read-only helpers like grep, find, and ls round out navigation, and you can narrow or widen the set with --tools and --exclude-tools. That is the entire surface the model acts through. There is no built-in web tool, no MCP client, no sub-agent spawner, no plan mode in the core — those are explicitly out of scope, to be added by extension if you want them.

The minimalism is the point. The more tools and scaffolding a harness injects, the more of every request is consumed by the harness describing itself to the model before your problem even enters the picture. Pi’s design keeps the system prompt and tool definitions lean so that the overwhelming majority of the context budget is your code, your AGENTS.md, and your plans. The agent loop itself is the same shape every agentic tool uses, just with less standing between the model and the filesystem:

        ┌──────────────────────────────────────────────┐
        │  user prompt + AGENTS.md + repo context       │
        └───────────────────────┬──────────────────────┘
                                 v
                        ┌─────────────────┐
              ┌────────>│   LLM (BYO key) │────────┐
              │         └─────────────────┘        │
              │                                     v
              │                          tool call: read/write/edit/bash
              │                                     │
              │                                     v
        ┌─────┴───────┐                   ┌──────────────────┐
        │ tool result │<──────────────────│  execute on host │
        │ into context│                   │  (your perms)    │
        └─────────────┘                   └──────────────────┘
              │
              └── loop until the model stops calling tools ──> final answer

Compared to the heavier orchestration in building AI agents that work, Pi is conspicuously bare: the loop is small, every prompt and tool call is visible, and there is nowhere for hidden behavior to hide. That transparency is a genuine feature for anyone who has tried to debug why a more opinionated agent did something surprising.

Four Run Modes

A harness that wants to be plumbing has to be drivable from other programs, and Pi exposes the same agent through four modes:

Mode Invocation Use
Interactive pi The default TUI — editor, slash commands, live output
Print / JSON pi -p "..." / --mode json One-shot non-interactive output, or structured event stream
RPC stdin/stdout JSONL Embed the agent in another process via strict LF-delimited JSONL framing
SDK createAgentSession() Programmatic embedding inside a Node.js application

This is the part most “products” do not offer cleanly. Print mode makes Pi scriptable in a shell pipeline; JSON mode gives you a machine-readable event stream for tooling; RPC mode lets a long-lived parent process talk to the agent over a stable framed protocol; and the SDK lets you build your own app on top of the runtime entirely. A CI job, an editor plugin, and a Slack bot can all sit on the same agent core. The trade-off, predictably, is that you are now the integrator — there is no hosted dashboard waiting for you.

Extensibility Instead of Features

Where another tool ships a feature, Pi ships an extension point. There are four layers, escalating in power:

  • Prompt templates — reusable Markdown prompts in ~/.pi/agent/prompts/, invoked as /name. The lightest way to encode a repeated instruction.
  • Skills — files following the Agent Skills standard (.md) in ~/.pi/agent/skills/ or a project’s .agents/skills/, letting the agent load specialized procedures on demand.
  • Extensions — TypeScript modules that register entirely new tools, slash commands, and UI components. This is where MCP, web search, or a sub-agent system would live if you wanted them.
  • Themes — dark and light built in, hot-reloadable.

The unit of distribution is the package, shared over npm or git and discoverable by the pi-package keyword:

1
2
3

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi install https://github.com/user/repo

The philosophy is stated bluntly by the maintainers: “Pi is aggressively extensible so it doesn’t have to dictate your workflow.” If you want plan mode, you install or build plan mode. If you want sub-agents, same. This is the cleanest expression of the project’s whole worldview — and also the clearest statement of its cost, which is that an empty harness does less on day one than a batteries-included one.

Bring Your Own Model

Pi is provider-agnostic by design, supporting 30+ providers including Anthropic, OpenAI, Google, DeepSeek, Groq, and xAI. You authenticate either through a subscription login (/login) or an API key, pick a model with /model (or Ctrl+L), and the harness maintains per-provider lists of tool-capable models updated every release. Custom or self-hosted providers go in ~/.pi/agent/models.json or an extension, which means the same agent loop can run against a frontier API one minute and a local model the next.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// ~/.pi/agent/models.json — point pi at a local or custom endpoint
{
  "providers": {
    "local": {
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "ollama",
      "models": [{ "id": "qwen3-coder", "toolCall": true }]
    }
  }
}

This decoupling is the same principle behind a routing proxy like the one in the LiteLLM model-routing post, pushed down into the agent itself: you are not married to one lab’s models or subscription. For anyone running models locally, it slots directly into the workflow from the local LLM coding guide — though with the honest caveat that smaller local models drive agentic tool loops far less reliably than frontier ones, and Pi’s minimal scaffolding gives them less help, not more.

Sessions as Trees, Not Logs

Most agents treat a conversation as a linear append-only log. Pi stores sessions as JSONL where every entry carries an id and a parentId, which turns the conversation into a tree you can branch in place. The /tree command navigates branches, /fork starts a new session from a chosen point, and /clone duplicates the active branch. In practice this means you can take a session to the moment before the agent went down a bad path, fork, and try a different instruction without losing the good prefix — the agentic equivalent of git branch for your conversation. It is a small idea with outsized value once you have lost a good context to one bad turn.

The project also leans hard into transparency as a community good: the maintainers publish their own real work sessions as open datasets and encourage users to share OSS sessions, on the argument that real-world tool use, failures, and fixes improve agents more than toy benchmarks.

The Honest Trade-offs

A harness this minimal makes a very particular set of bargains, and they are not all in your favor.

No built-in permission system. This is the most important caveat. Pi ships with no sandbox: by default it runs with the full permissions of the user and process that launched it, and bash means bash. There is no per-action approval gate of the kind some other agents default to. The maintainers are upfront about this and document three containment patterns — a “Gondolin” extension that routes tools and ! commands into a local micro-VM while keeping auth on the host, plain Docker around the whole process, and a policy-controlled OpenShell sandbox. If you run Pi against untrusted code or let it execute freely, you should containerize it first. The general guardrails argument in guardrails for production LLM applications applies with extra force here, because Pi deliberately does not provide the rails itself.

You assemble the workflow. The flip side of “no opinions” is “no defaults for the hard parts.” Plan mode, sub-agents, MCP, web access — all are absent until you install or build them. For a tinkerer this is the whole appeal; for someone who wants to open a tool and have it just plan-and-execute a refactor, a more mature all-in-one product will be the faster path, and the maintainers say as much.

Ecosystem maturity. Pi is young and its package ecosystem is small relative to the incumbents. You are early, with the upside (you can shape it) and downside (fewer ready-made pieces) that implies. The cost-comparison framing in AI coding tools cost comparison matters too: bring-your-own-key means you pay raw API costs directly, which can be cheaper or far more expensive than a flat subscription depending on how hard you drive it.

Supply-chain seriousness as a counterweight. On the positive side, Pi treats dependency changes as reviewed code: exact-pinned direct dependencies, a min-release-age guard against same-day releases, shrinkwrapped transitive deps for CLI users, --ignore-scripts installs, and scheduled npm audit runs. For a tool that executes code on your machine with your permissions, that hardening is not decoration — it is the right instinct, and more than some better-funded competitors bother with.

Where Pi Fits Against the Incumbents

It helps to be concrete about what choosing Pi actually changes relative to the tools most engineers already reach for. The differences are not cosmetic; they are a different distribution of responsibility.

Against Claude Code, the contrast is sharpest. Claude Code is tied to Anthropic’s models and ships a large, capable default behavior set — plan mode, sub-agents, a permission prompt, an MCP client — that does a great deal before you configure anything. Pi is model-agnostic and ships almost none of that, trading day-one capability for inspectability and control. If you value a single vendor owning the end-to-end experience and tuning the prompt against their own models, Claude Code’s integration is an advantage Pi structurally cannot match. If you resent being unable to see or change what the harness injects, Pi is the answer to a frustration Claude Code’s design creates.

Against Cursor, the axis is environment: Cursor is an editor-first, GUI experience with the agent woven into an IDE, while Pi is terminal-native and composes with whatever editor you already use. Against Codex and other hosted offerings, the axis is ownership: those are services with billing, dashboards, and managed infrastructure; Pi is a local process you run, key you bring, and machine you secure.

The honest summary is that Pi is not competing on the same dimension as these tools at all. They compete on capability out of the box; Pi competes on control and composability, and explicitly concedes the first to win the second. That makes “which is better” the wrong question. The right one is whether you are the kind of engineer who will actually spend the time to assemble and maintain a workflow — because that labor is the price of admission, and for the right person it buys a tool that finally bends to them instead of the reverse.

Verdict

Pi is the most interesting agentic coding tool of the year precisely because it declines to be a product. It is a clean, MIT-licensed, transparent harness that gives the model four tools and otherwise gets out of the way, and its bets — keep the core small, let the user own the context window, make the agent provider-agnostic, store sessions as branchable trees, and treat extensibility as the feature — are the right bets for a specific kind of engineer: the one who wants to understand and reshape their tools rather than adopt someone else’s workflow wholesale. That same minimalism is its honest cost. There is no sandbox by default, no plan mode, no sub-agents, no MCP until you add them, a younger ecosystem, and raw API billing — which together mean Pi asks more of you upfront than Claude Code or Cursor do. The clean recommendation: if you are an engineer who reads your tools’ source, runs local or multi-provider models, and resents context wasted on a harness’s self-description, install Pi, containerize it, and start building your own packages — you will likely never go back to an opinionated harness. If you want to open a tool and have it confidently drive a complex task on day one with guardrails already in place, reach for a mature all-in-one and keep an eye on Pi as the project that is quietly arguing the whole category got the defaults backwards.

Sources

Comments