Pi
Four tools and a tiny prompt
Prerequisites
- Agentic Coding Basics
What You'll Learn
- Argue the minimal-core thesis and its limits
- Explain context economy: less per turn, cheaper and often better
- Know when batteries-included beats minimalism
Four Tools, Precisely
Pi ships exactly four core tools — read, write, edit, and bash — and a system prompt under a thousand tokens.
Most harnesses treat a big tool catalog as capability. Pi treats it as overhead: every tool schema you ship is context the model re-reads on every turn, and another way for it to pick the wrong instrument. Four primitives cover the whole job:
readInspect any file. The exploration primitive — the agent learns your codebase one read at a time.
writeCreate a file whole. New modules, new tests, new configs — anything that starts from empty.
editSurgical replacement inside an existing file. The precision instrument for the 90% of coding that is changing code, not writing it.
bashEverything else. Search, tests, git, builds, package managers — the escape hatch that makes four enough.
It speaks a unified multi-provider API (Anthropic, OpenAI, Google, local models) with bring-your-own-key.
npm i -g @earendil-works/pi-coding-agentFacts as of August 2026Minimal Core vs Batteries Included
Everything else — skills, subagents, plan mode, permission gates, sandboxing, MCP — is an opt-in, typed TypeScript extension, not a built-in.
That inverts the default. A batteries-included harness ships capability and asks you to disable what you don't want; Pi ships almost nothing and asks you to add what you do. Neither is simply better — they fail differently:
| Minimal core (Pi) | Batteries included | |
|---|---|---|
| Per-turn overhead | Tiny — only what you opted into rides along | Every built-in tool and instruction, every turn |
| Day-one capability | Four tools; you assemble the rest | Subagents, permissions, integrations out of the box |
| Surface to audit | Small enough to read in one sitting | Large; you trust defaults you have not read |
| When it fails | A missing capability you must build or install | Diffuse context bloat and tool-choice confusion |
| Best fit | Cost-sensitive loops, subagent fleets, tinkerers | Teams that want guardrails without assembly |
✓ Reach for minimalism when
- •You run long sessions or many agents — per-turn overhead compounds
- •You need to audit exactly what the model sees each turn
- •You want to swap providers or models freely
✗ Prefer batteries included when
- •A team needs shared guardrails on day one, not after assembly
- •Sandboxing and permission gates must be defaults, not opt-ins
- •Nobody wants to maintain a set of extensions as a side project
Context Economy
The harness prompt is not a one-time cost. It is re-sent on every single turn of the agent loop, so harness overhead multiplies by the length of the session. A core under a thousand tokens makes Pi cheaper per turn by construction — no benchmark required for that part.
One benchmark claim worth citing carefully: a Databricks internal evaluation reportedly measured Pi sending roughly 3× less context per turn than heavier harnesses at a higher pass rate — a single unverified benchmark, not settled fact.
Treat that number as a signal worth watching, not a verdict: one internal evaluation, unreplicated, is exactly one data point. The cost half of the argument, though, needs no benchmark — fewer tokens per turn is arithmetic.
This is the course's core claim landing one last time: the context window is the real cost of agentic coding. If you want to feel that arithmetic instead of reading it, play the Duel — it runs the same economics as a 90-second game.
💡 Pro Tips — and a Course Wrap
- 1.Adopt Pi's ordering even in other harnesses: start minimal and add capabilities when a task proves the need. Overhead you never add is overhead you never pay per turn.
- 2.Audit your current harness like Pi forces you to: list every tool and MCP server in the prompt and remove the ones this project never calls.
- 3.Evaluate any new harness with the four knobs from the basics lesson — loop ownership, context strategy, tool surface, model coupling. dsh, opencode, Kimi Code, and Pi are four different answers to the same four questions.
- 4.That's the course — four harnesses down, 5 to go: Codex CLI, Antigravity CLI, Aider, Amp, Crush are next on the roadmap. Subscribe below to read each one first, free.
The walkthrough, as text
-
1. The Thousand-Token Bet
Pi ships exactly four core tools — read, write, edit, and bash — and a system prompt under a thousand tokens. Watch a bloated harness prompt distill down to that core.
-
2. Why Four Is Enough
Explore, fix, verify: real coding tasks decompose into sequences of the same four primitives, with bash covering everything the other three do not — search, tests, git, builds.
-
3. Everything Else Is an Extension
Everything else — skills, subagents, plan mode, permission gates, sandboxing, MCP — is an opt-in, typed TypeScript extension, not a built-in. You assemble exactly the harness the task needs, and nothing rides along by default.
-
4. Context Economy
The harness prompt is re-sent on every turn, so a smaller core means fewer tokens per turn — cheaper by construction, and per one carefully-cited (and unverified) benchmark, sometimes better too.
-
5. Four Harnesses, Four Answers
Pi closes the course: dsh made the loop a plugin, opencode split client from server, Kimi Code isolated subagent contexts, and Pi shrank the core — four different answers to the four knobs from the basics lesson.
Facts verified against the Pi repository and official docs, as of August 2026.
New lessons, straight to your inbox
5 more harness deep dives are on the roadmap. Subscribers read them first — free.
Check your inbox to confirm.