pi-book: source-backed architecture notes on the pi agent loop

What pi-book actually is, and who should open it

pi-book is not the pi agent. It is a workspace holding a Chinese architecture book whose subject is the packages/agent directory of the pi repository, described in the README as "一个 agent 循环，被做成一个库" (an agent loop made into a library). The book explains how @earendil-works/pi-agent-core is assembled: what it promises, what it refuses to do, and where its load-bearing points are.

The intended reader is stated plainly. You need to read TypeScript, and you need to know the basic vocabulary of LLM APIs: messages, tool calls, streaming. You do not need prior knowledge of the pi repository. That combination is narrower than it sounds. Someone who wants to run an agent will find nothing here about configuration or deployment. Someone who wants to know why the loop was shaped a certain way, and is willing to read the source alongside the prose, is the actual audience.

The workspace has a second audience: people writing about code. Every claim in the book is tied to a file and line number, with the quoted lines printed next to the claim, so a reader can verify an argument without opening an editor. That convention is the most transferable part of the project.

The citation contract: file:line plus the quote, pinned to commit cd20a8d2e

The mechanism that distinguishes this book from a blog series is its citation rule. References are written as file:line, and each reference carries its quotation in place. The stated goal is that a reader can check any assertion in the book without leaving the page.

Pinning matters here. The entire book corresponds to commit cd20a8d2e on the main branch of the pi repository. That is a deliberate constraint: line numbers are only meaningful against a fixed revision, so the book trades currency for verifiability. If pi's main branch has moved since that commit, the quoted lines still describe the code as it was at cd20a8d2e, and a reader comparing against a newer checkout may find the line numbers shifted. The README does not describe a process for re-pinning the book to a later commit, so treat the pin as a boundary of the work rather than a detail.

The book also defines three card components for its own prose: 插叙 (digression), 岔路 (fork in the road), and 为什么不去 (why not go there). The rules for quotations, these cards, and what falls outside the book's scope are documented in the 体例 section of agent/README.md. The card vocabulary is worth noting because it tells you the book intends to record rejected designs, not only the design that shipped.

Structure: whole, then parts, then cross-cutting concerns

The book is organized in three parts, and the ordering is dependency ordering. Each chapter in the middle part depends only on chapters before it, which is why the README can promise that a reader who finishes the first part should be able to draw the system from memory.

Part one, the whole, establishes a correct mental model without touching implementation detail. Two chapters are published as of the README. Part two, the parts, expands component by component in dependency order. Part three, cross-cutting, handles questions that do not belong to any single component.

One consequence of writing in dependency order is that the table of contents only lists published chapters, with later chapters added as they are written. A reader arriving now gets an incomplete book whose published portion is internally consistent. That is an honest arrangement, but it means you cannot plan a reading schedule around a finished arc. The README does not state how many chapters the remaining parts will contain.

Running the reader locally

The web reader is a Vite + Vue application under web/. It renders the Chinese manuscripts and the translations; it does not store any body text itself. The README gives one command sequence for starting it, run from the repository root:

cd web && npm install && npm run dev

After npm install finishes and the dev server starts, Vite prints a local URL, typically on port 5173. Opening it gives you the reader, with language switching in the top right corner between Chinese, English and Spanish.

The published reader is also available at books.antinomie.org/pi if you would rather not run anything. The README lists a second reading path for people who want to work with an AI assistant: the Markdown manuscripts under agent/, agent/en/ and agent/es/ can be downloaded and read locally, for example alongside Claude or Cursor, so you can ask questions while comparing against the pi source. No install command is given for that path, because it is just files.

Where the book stops: it is not an adoption guide for pi

The clearest limitation is scope. pi-book documents the architecture of packages/agent in the pi repository. It does not tell you how to install pi, how to configure it, how to deploy an agent built on it, or how to evaluate whether pi suits your workload. The reader assumptions in the README confirm this: TypeScript literacy and familiarity with LLM API concepts are prerequisites, not outcomes.

There is a second constraint that follows from the citation model. Because every argument is anchored to a specific commit, the book ages the moment pi's main branch changes. A reader who wants current behavior has to reconcile the book's quoted lines with the code in front of them. The README does not document a maintenance or re-pinning procedure, and it does not document rollback of any kind, so the book's own freshness policy is simply not stated.

Finally, the content source is the Chinese manuscript. The English and Spanish versions are translations of agent/, and the README calls the Chinese directory the only content source. If a translation lags or diverges, the Chinese text is the authority. A reader who needs the newest material should check the Chinese directory first.

How it compares to reading the source or a generic architecture post

The obvious alternative is reading pi's source directly. That gives you the current code with no translation layer and no pin, but it gives you no argument about why the code is shaped that way, and no map of which parts depend on which. pi-book's value is the map plus the reasoning, at the cost of being tied to one commit.

The second alternative is the class of architecture write-ups that describe a system from memory, with code excerpts that may or may not match the repository. The difference is mechanical rather than stylistic: pi-book requires a file:line reference and prints the quoted lines beside the claim, so a reader can falsify an assertion on the spot. That rule is also the book's main cost, since it makes every chapter expensive to write and to update.

A third comparison is the reading environment. The Markdown manuscripts are plain files, which means they work with whatever editor or assistant you already use. The web reader adds syntax-highlighted code quotations and language switching, and it is the only place where the three language versions are presented together. Neither path changes the content; the choice is about how you want to read it.

Maintenance, licensing and what the repository does not say

The repository is not archived, and the last push was on 2026-08-24. The README does not describe a release process, and no releases were retrieved, so there is no versioned artifact to upgrade against. Updating means pulling the repository and, for the reader, re-running the web install if dependencies changed.

Upgrade cost is dominated by the commit pin. If pi's packages/agent changes, the book's quoted lines and line numbers describe the old revision until someone re-pins the book and re-checks the quotations. The README does not state who does that or how often.

On licensing, the repository does not declare a license in the repository files available here. The README also does not state the license of the pi repository it quotes, and it does not state the license of the translations. If you intend to redistribute the manuscripts or the reader, or to reuse the quoted code excerpts, treat the licensing position as unresolved and check the repository files directly rather than assuming a default.

Editorial conclusion

Read pi-book if you already write TypeScript and want to understand how pi's agent loop is put together before you depend on it, or if you want a model for how to cite source code in technical writing. Do not read it as pi's user manual: the README states the reader must know TypeScript and LLM basics, and the book covers packages/agent rather than installation or deployment. Before relying on any chapter, open the cited file at commit cd20a8d2e and check the quoted lines yourself, because the book pins that commit and the main branch moves on.

Frequently asked questions

Official sources

1. antinomie-lab/pi-book on GitHub
2. Issues
3. Project website
4. README