This book teaches how a modern AI coding agent works, from the bytes on the wire to the design of a crash-proof runtime, by reading one real codebase end to end: the earendil-works/pi monorepo, including its durable runtime pi-durable. Every claim is checked against the source, and source quotes name the file they come from. Along the way it teaches the computer science underneath, because almost every hard problem in an agent is an old problem in a new setting.
What Pi is
Pi is a family of TypeScript packages. Two complete agent runtimes share one model layer:
- The coding agent (
pi-coding-agent) is the interactive program you run in a terminal. It streams model output to the screen, runs tools on your machine and keeps sessions as files. - Pi Durable (
pi-durable) is a server-side harness in which every model turn, tool call and piece of state is committed to storage before anyone sees it, so a crash loses at most a moment of work.
Both stand on pi-ai, a provider-neutral streaming layer for dozens of model APIs. Around them sit smaller libraries: a terminal UI toolkit, a replicated-state and hot-reload runtime (Chord), a sandbox for model-written scripts, an MCP client, a remote execution daemon, telemetry contracts and an eval harness.
the Pi packages by layer · chapters and internal dependencies
Each package depends only on packages in lower rows, and six of them depend on no other Pi package at all. pi-ai is the one both runtimes share.
How the book is organised
| Part | Chapters | Question it answers |
|---|---|---|
| I. Foundations | 1–2 | What is an agent, and how is this repository built? |
| II. pi-ai | 3–5 | How do many incompatible model APIs become one event stream, and how are models and credentials managed? |
| III. Agent core | 6–7 | How does the loop run tools, take steering, cancel, retry, and serve terminals, scripts and other programs? |
| IV. Coding agent | 8–11 | How do the tools, sessions, extensions and the interactive app work? |
| V. pi-tui | 12 | How do you draw a fast, correct UI with escape sequences? |
| VI. pi-durable | 13–16 | How do you make an agent survive crashes, and run its tools on other machines? |
| VII. Supporting libraries | 17–18 | How do replicated state, hot reload, sandboxes, MCP, telemetry and evals work? |
| Appendices | A–B | Every CS concept by field; a reading path, projects and further reading. |
How to read it
Every chapter has the same shape:
- Learning goals: what you should be able to do afterwards.
- The text, with verbatim source quotes. Simplified pseudocode is labelled as such; everything else is real code.
- Diagrams where a structure is easier to see than to read.
- Concepts in this chapter: each CS idea named and explained from first principles.
- Exercises, from "read this file and explain" to "build your own".
Read Parts I–III in order: everything later depends on them. After that the parts are largely independent. Read Part V if you care about terminals, or jump from Part III straight to Part VI if you care about servers. Keep a clone of the repository open: the book points at files, and the files reward reading. Appendix B.1 gives a file-by-file reading path to follow alongside the chapters.
Prerequisites
You need working knowledge of one programming language and basic command-line use. Familiarity with JavaScript or TypeScript helps, but Chapter 1 introduces the TypeScript features the book relies on: union types, generics, async/await and runtime schemas. No prior knowledge of language models, databases, networking or terminals is assumed. Each is introduced when it first matters, and Appendix A collects them by field.
The source changes quickly. Line numbers and small details will drift; the designs described here are the stable part, and the doc comments at the top of each file remain the best guide to the current version.