Pi Coding Agent Handbook¶
I've been through the cycle — Cursor, Claude Code, Amp, OpenCode, Codex. I still use most of them. But when I found pi, something clicked. It's the agent that finally made me stop reaching for Claude Code. Not because pi does everything, but because it does so little and gets out of the way.
This handbook is what I wish existed when I started with pi. It covers the philosophy, the architecture, the extension system, the tradeoffs, and the honest gaps. It's opinionated because pi is opinionated, and that's the point.
I don't claim to be an expert. I'm just a builder who got hooked and wanted to write things down. If something here is wrong, outdated, or could be said better — please fix it. This is your handbook too.
What's inside¶
The core argument for pi, the four-tool architecture, how extensions replace features other agents bake in, the no-MCP stance (and why MCP 2.0 might change the calculus), community packages like oracle and handoff, a fair comparison with Claude Code / Amp / OpenCode / Aider, and a quick start that gets you running on macOS, Linux, or Android via Termux.
12 chapters. Code snippets. Every claim sourced.
Get involved¶
This handbook lives or dies by contributions. A typo fix, a better code example, a one-paragraph tip, a whole new chapter — it all counts. The Limitations page is full of gaps waiting to be filled. Every one of them is an open invitation.
If you've built something with pi — an extension, a workflow, a workaround — write it up. Someone out there is stuck on the exact problem you solved last week.
Disclaimer
This is an unofficial community handbook. It is not affiliated with or endorsed by Mario Zechner or the pi project. All quotes are attributed to their original authors and linked to their sources. Pi is MIT licensed.
Chapters¶
| Chapter | What you'll learn | |
|---|---|---|
| 1 | Core Philosophy | Why pi exists, what it deliberately omits |
| 2 | Architecture | The minimal core: read, write, edit, bash |
| 3 | Extension System | TypeScript extensions, skills, packages |
| 4 | Session Management | Tree-structured branching, compaction |
| 5 | Multi-Model Freedom | 15+ providers, mid-session switching |
| 6 | No MCP | The CLI-first philosophy and its tradeoffs |
| 7 | Community Extensions | Oracle, handoff, sub-agents, and more |
| 8 | Comparison | Pi vs Claude Code vs Amp vs others |
| 9 | Limitations | Honest assessment of current gaps |
| 10 | Quick Start | Installation, config, daily workflows |
| Code Snippets | Concrete extension and config examples | |
| References | Official docs, community links, articles |
Key references¶
| Resource | Link |
|---|---|
| Website | shittycodingagent.ai |
| GitHub | badlogic/pi-mono |
| npm | @mariozechner/pi-coding-agent |
| Mario's blog | What I learned building a minimal coding agent |
| MCP vs CLI benchmark | MCP vs CLI: Benchmarking Tools |
| Armin Ronacher | Pi: The Minimal Agent Within OpenClaw |