The book explains the code; this appendix gets you reading the code yourself and then building your own. Work through B.1 alongside the chapters, attempt one project from B.2 per part, and use B.3 when a topic deserves a full course.
B.1 A reading path through the source
Read in this order. Each step is small enough for one sitting and builds on the one before. Paths are relative to packages/.
| Step | Files | What to look for | Chapter |
|---|---|---|---|
| 1 | ai/src/types.ts | The message, content and event unions every other package speaks. | 1, 3 |
| 2 | ai/src/utils/event-stream.ts, ai/src/utils/json-parse.ts | The async event queue; parsing tool arguments while they stream. | 3 |
| 3 | ai/src/api/anthropic-messages.ts, ai/src/api/openai-completions.ts | Two adapters side by side: same output events, very different wire formats. | 4 |
| 4 | ai/src/utils/retry.ts, ai/src/utils/overflow.ts | Which errors are retryable, and how a full context window is recognised. | 4 |
| 5 | ai/src/providers/faux.ts, ai/src/api/constrained-sampling.ts | A scripted provider for tests; schema and grammar constraints. | 5 |
| 6 | agent/src/agent-loop.ts, then agent/src/agent.ts | The pure loop, then the stateful wrapper around it. | 6 |
| 7 | coding-agent/src/core/agent-session.ts | Prompt pipeline, retries, compaction triggers. Read it with Chapter 7 open. | 7 |
| 8 | coding-agent/src/modes/json-event.ts, coding-agent/src/modes/rpc/ | The machine-facing modes and their framing. | 7 |
| 9 | coding-agent/src/core/tools/edit.ts, edit-diff.ts, file-mutation-queue.ts, bash.ts | Exact and fuzzy edits, per-file locking, process trees. | 8 |
| 10 | coding-agent/src/core/session-manager.ts, core/compaction/ | The session tree, context reconstruction, compaction and branch summaries. | 9 |
| 11 | coding-agent/src/core/skills.ts, prompt-templates.ts, core/extensions/ | Resources and the extension runtime. | 10 |
| 12 | coding-agent/src/modes/interactive/interactive-mode.ts | The event switch that drives the app. | 11 |
| 13 | tui/src/tui.ts, stdin-buffer.ts, utils.ts, undo-stack.ts, kill-ring.ts | Differential rendering, input parsing, width measurement, editing. | 12 |
| 14 | durable/docs/spec.md, then durable/src/session/session.ts and transaction.ts | The rules first, then the commit path that enforces them. | 13, 14 |
| 15 | durable/src/storage/memory.ts, then storage/sqlite/ and storage/jsonl/ | The reference semantics, then two real backends. | 14 |
| 16 | durable/src/harness/scheduler.ts, tool.ts, generation.ts | Tasks, replay policies, model turns. | 15 |
| 17 | durable/src/env/index.ts, env/node-watch.ts, env/docs/protocol.md | The environment contract, the watcher, the remote wire protocol. | 16 |
| 18 | chord/src/delta/README.md, chord/docs/spec.md, chord/src/context/index.ts | Ownership rules, the object runtime, explicit context. | 17 |
| 19 | codemode/src/runtime/vm.ts, mcp/src/client.ts, telemetry/src/noop.ts, evals/src/plan.ts | Determinism, JSON-RPC, null objects, experimental design. | 18 |
A tip that applies everywhere in this repository: read the doc comment at the top of a file before its code. The authors put the reasoning there ("Problem: … Solution: …"), and the code then reads as an implementation of a stated design. Read the tests next: test/ folders show how each module is meant to be used, and the conformance suites state the contracts in executable form.
B.2 Projects
Each project rebuilds a piece of Pi from scratch, small enough to finish and large enough to teach. Compare your design with Pi's only after yours works.
| # | Project | You will practise | After |
|---|---|---|---|
| 1 | A 200-line agent. One provider over raw fetch and SSE, a read and a bash tool, the ReAct loop, abort with Ctrl-C. | Streaming parsing, tool calling, cooperative cancellation. | Part III |
| 2 | A provider-neutral event stream. Add a second provider behind the same event union, plus a faux provider for tests. | Adapter pattern, discriminated unions, deterministic tests. | Part II |
| 3 | Branching sessions. Store your agent's history as JSONL with parent ids; add /fork, /tree and a compaction that summarises the oldest turns. | Event sourcing, trees, LCA, crash-safe appends. | Part IV |
| 4 | A safe edit tool. Exact match first, then a normalised fuzzy match; refuse ambiguous matches; serialise edits per file. | String algorithms, lost updates, locking. | Ch. 8 |
| 5 | A differential terminal renderer. Components that render lines for a width; redraw only changed lines inside synchronised output. | Terminal protocols, diffing, grapheme width. | Part V |
| 6 | A durable to-do agent. Every model turn and tool call is committed to SQLite before it is shown; kill the process at random and prove it resumes. | WAL, idempotency, the effect sandwich, replay. | Part VI |
| 7 | A JSON delta tracker. Proxy drafts that emit set, delete, append and splice ops; a replica that replays them; property tests that both always agree. | Persistent data, proxies, property-based testing. | Ch. 17 |
| 8 | A tiny remote environment. A daemon that answers length-prefixed frames on stdin/stdout with read, write and exec, plus heartbeats and cancellation. | Framing, multiplexing, liveness, process groups. | Ch. 16 |
| 9 | An MCP client. JSON-RPC over stdio against a real MCP server: initialise, list tools, call one, cancel one, renew a timeout with progress. | Protocol design, correlation, timeouts. | Ch. 18 |
| 10 | An eval harness. Two prompt variants, paired cases, counterbalanced order, three repetitions; report lift with blocked pairs withheld. | Experimental design, statistics, isolation. | Ch. 18 |
For each project, write a one-page design note before coding: the invariants you will keep, the failure you fear most, and how a test will catch it. That habit is the most transferable thing this codebase teaches.
B.3 Further reading
Grouped by the parts of the book they deepen. Classic texts are named without links; standards and stable pages are linked.
Agents and LLM systems (Parts I–IV)
- Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models (2022) — the loop of Chapter 1. arXiv
- The Model Context Protocol specification — Chapters 10 and 18. modelcontextprotocol.io
- Robertson and Zaragoza, The Probabilistic Relevance Framework: BM25 and Beyond (2009) — the ranking of Chapter 16.
Protocols and security (Parts II, VI, VII)
- RFC 6749 OAuth 2.0; RFC 7636 PKCE; RFC 8628 device grant; RFC 8414 authorization server metadata; RFC 7591 dynamic client registration — Chapters 5 and 18.
- JSON-RPC 2.0 specification — Chapter 18.
- The WHATWG HTML Standard's section on server-sent events — Chapter 4.
- Mark S. Miller, Robust Composition (PhD thesis, 2006) — object capabilities, Chapters 10 and 18.
Terminals (Part V)
- ECMA-48, Control Functions for Coded Character Sets — the escape sequences of Chapter 12.
- Unicode UAX #29, Text Segmentation — grapheme clusters.
- The kitty keyboard protocol — unambiguous key events.
- Björn Ottosson, A perceptual color space for image processing — OKLab.
Durability and distributed systems (Parts VI–VII)
- Martin Kleppmann, Designing Data-Intensive Applications — logs, replication, transactions; the best single companion to Part VI.
- Mohan et al., ARIES (1992) — write-ahead logging and recovery, the theory behind Chapter 14.
- SQLite, Write-Ahead Logging — the mode Durable uses.
- Nathaniel J. Smith, Notes on structured concurrency — Chapter 15's task tree.
- Go Concurrency Patterns: Context — the model for Chord's
Context, Chapter 17. - Lamport, Time, Clocks, and the Ordering of Events in a Distributed System (1978) — logical clocks, Chapters 17 and 18.
- The FoundationDB team's talks and writing on deterministic simulation testing — Chapter 18's determinism.
Algorithms (Chapter 17)
- Myers, An O(ND) Difference Algorithm and Its Variations (1986) and Hunt and Szymanski (1977) — diff.
- Seidel and Aragon, Randomized Search Trees (1996) — treaps.
- Marsaglia, Xorshift RNGs (2003).
- Cormen, Leiserson, Rivest and Stein, Introduction to Algorithms — dynamic programming, LIS, search trees.