An interactive, principle-by-principle field guide to one of the most thoughtful coding-agent harnesses ever shipped.
→ Read it live · Pi on GitHub · Mario's launch post
"if I don't need it, it won't be built." — Mario Zechner, the one-line philosophy that runs every file in pi
A long-form interactive site that distills the Pi coding agent framework into 42 design principles, 9 architecture diagrams, and ~10 code patterns you can steal for your own framework.
It pairs:
- The "why" — the philosophical thesis, drawn from Mario's launch post
- The "how" — the implementation, pulled directly from the source tree, with every claim hyperlinked to the exact file on GitHub
Built for engineers who don't just want to use an agent framework — they want to understand what a thoughtful one looks like, and steal ideas for their own.
Three years ago the bottleneck in software was "can I write this code?" Today, with frontier models, it's "can the agent see what I see, do what I want, and tell me the truth about what it did?"
That shift created a new product category — the harness — the wrapper around the model that decides which tools it has, what's in its system prompt, how its decisions get persisted, and what you can and can't see.
The harness is the product. Most users never realize this.
Pi is the harness that defines itself by what it refuses to ship. No MCP. No plan mode. No sub-agents. No permission popups. No built-in to-dos. What's left is a tiny, transparent kernel with hooks for everything you might want to add.
| Typical harness | Pi | |
|---|---|---|
| System prompt | ~5K tokens, compiled in | ~750 tokens, on disk |
| Tools | 10+ baked in, more via MCP | 4 core: read, write, edit, bash |
| Plan/sub-agents | Hidden modes | A file you can edit |
| Session storage | Opaque DB | JSONL you can grep |
| Permission model | Per-call popups | None — sandbox at the container |
| Extension surface | File an issue | Hooks: SystemPrompt, Tools, Context, UI |
- §0 Intro — thesis, problem, before/after, what pi proposes
- §1 Foundations — the 13 concepts you need before pi's choices make sense
- §2 Problem space — the 5 grievances pi is the answer to
- §3 The 42 principles — organized A–F by abstraction level
- §4 Architecture — the 4 packages and how they fit
- §5 Diagrams — 9 detailed Mermaid diagrams (system map, request lifecycle, agent loop state, streaming pipeline, tool execution, session tree, TUI rendering, startup, data model)
- §6 Cross-cutting patterns — errors-as-values, hook-driven extensibility, etc.
- §7 Traction — why this gained momentum so fast
- §8 Lessons — the question to carry forward into your own work
- §9 Code patterns to steal — copyable snippets for your own framework
Every principle links to the exact file (and often line range) in earendil-works/pi.
Mario's launch post is brilliant but compressed — it gestures at principles across thousands of lines of code without naming them. I wanted to:
- Force myself to understand the project deeply by reading every file and articulating one principle at a time
- Make those principles legible to anyone, not just people willing to spelunk through a monorepo
- Treat each principle as a portable design decision you could re-apply in a totally different codebase
- Practice the same restraint pi practices — the site has no chat panel, no marketing animations, no newsletter signup. Just the content.
A few decisions worth calling out, since the site itself is a small exercise in the same principles pi advocates:
| Decision | Why |
|---|---|
| Zero npm dependencies in the server | Node 22 has native fetch; everything is node server.js. Matches pi's minimum-kernel ethos. |
| Static deploy on Vercel | The site doesn't need a server — the chat panel is the only dynamic surface, and it's currently disabled. outputDirectory: public ships only static assets. |
| Inter + Source Serif 4 + JetBrains Mono | Inter for UI clarity, serif italics for the editorial voice, mono for code and labels — three families, deliberately. |
| 720px content width | ~70 characters per line is the readability sweet spot. The page felt cramped at 860px. |
| Lead-in bolds + drop caps + numbered complaint lists | Skimmers should be able to absorb the thesis from the bolds alone, then dive into the prose only where they want depth. |
| Mermaid via CDN, dark theme | One <script type="module"> and a themeVariables block — no build step. |
You need Node 22 or newer (for native fetch and --watch).
git clone https://github.com/seyonv/pi-deep-dive
cd pi-deep-dive
npm start # http://localhost:3000
# or, with hot reload:
npm run devThat's it. No npm install required — zero dependencies.
If you want to re-enable the chat panel later, the server proxies to the Anthropic Messages API and streams SSE back:
export ANTHROPIC_API_KEY=sk-ant-...
npm startpi_deep_dive_site/
├── public/
│ ├── index.html # the site — ~4,400 lines of structured content
│ ├── styles.css # dark editorial theme + readability primitives
│ └── app.js # vanilla JS — TOC, progress bar, (optional) chat client
├── server.js # zero-dep Node static server + (disabled) Anthropic proxy
├── synthesis.md # the full deep-dive as a system prompt (for the chat agent)
├── vercel.json # static deploy config
└── README.md
- Frontend — vanilla HTML/CSS/JS. No build step, no framework.
- Diagrams — Mermaid 11 via CDN, custom dark theme.
- Server (local only) — Node 22
http+fetch, zero npm deps. - Deploy — Vercel as a pure static site (
outputDirectory: public). - Fonts — Inter (UI), Source Serif 4 (editorial italics), JetBrains Mono (code), via Google Fonts.
vercel link --project <your-name>
vercel deploy --prodvercel.json already has the right config (no build command, public/ as
output, immutable caching on assets).
- Pi — earendil-works/pi, by Mario Zechner (badlogic).
- Launch post — Pi: a thoughtful coding agent harness, the source of half the quotes on this site.
- This deep dive is an independent study. It is not affiliated with Mario or the pi maintainers.
The site code in this repo is MIT-licensed. The textual content (synthesis, principle write-ups) is CC-BY-4.0 — share, adapt, just credit.
Made because the best way to learn a thoughtful framework is to articulate its decisions one by one.