# pi-book analyses one commit of someone else's agent loop, and pins nothing else > antinomie-lab/pi-book is a workspace for a Chinese architecture book about the agent loop in the pi repository, written as inline file:line citations against a single upstream commit. The manuscript is the only source of truth for two translations, two top-level directories go unexplained, and the repository carries no licence file at all. **antinomie-lab/pi-book** — Source-backed architecture notes on building an agent - Repository: https://github.com/antinomie-lab/pi-book - Website: https://books.antinomie.org/pi - Stars: 425 · Forks: 15 - Language: Vue - License: not declared - Published: 2026-09-17 · Updated: 2026-09-17 · Language: en - Canonical page: https://hysenlabs.com/projects/antinomie-lab-pi-book ## Every claim is a file:line citation against one upstream commit The subject is narrow. The book covers the `packages/agent` directory of the pi repository and the `@earendil-works/pi-agent-core` package built from it, on the theme of an agent loop turned into a library. What it sets out to explain is what that package promises, what it refuses, and where its pivots are. The method is what separates it from a blog post. Code references are written as `file:line`, and every reference carries its quoted text inline, so a reader can check any claim in the book without opening an editor. That is a real commitment and it is unusual. It also has an expiry date written into it. The whole book corresponds to commit `cd20a8d2e` on the pi repository's main branch. The pin is a bare eight-character hash with no date, no link and no note about what changed upstream afterwards, so the verification promise holds for exactly one snapshot. When pi moves, the line numbers drift and nothing in the repository says by how much. ## The directory is packages/agent, the import is @earendil-works/pi-agent-core Two names for one thing, and neither README spells out the mapping. The code lives in `packages/agent` inside the pi repository, and the package you would install carries the scoped name `@earendil-works/pi-agent-core`. A reader trying to line up a citation with a checkout has to work that out from the two names, because the directory and the distribution name share no words. The scope of coverage is equally bounded. One package of one repository gets the treatment, and the reader is told upfront that the book is not an introduction: it assumes you read TypeScript and that you know messages, tool calls and streaming, while explicitly not requiring prior knowledge of the pi repository. That is a reasonable contract for an architecture book and a bad fit for a first look at agent loops. The structure follows the dependency order. The book runs whole, then part, then cross-cutting: part one builds a correct picture of the system without touching implementation detail, part two opens components in dependency order where each chapter leans only on the ones before it, and part three takes the questions that belong to no single component. Part one has two published chapters so far, and the table of contents lists only what is published, so the book's size is not what the outline implies. ## Two of the five top-level directories are named nowhere in the README The workspace layout section explains two directories. `agent/` holds the manuscript in Chinese and is named as the single source of content, with `agent/en/` and `agent/es/` for the translations and `agent/README.md` and `agent/TRANSLATION.md` visible as entry points. `web/` is the reader. The top level actually holds `.gitignore`, three README files, `agent/`, `docs/`, `gateway/` and `web/`. That leaves `docs/` and `gateway/` with no description at all. Neither appears in the layout section, and nothing in the 160-word README explains what either is for. `gateway/` is the more interesting gap, because a gateway implies serving the book from somewhere, and the README points readers to a hosted site at books.antinomie.org/pi without saying whether that site is a build of `web/`, an output of `gateway/`, or something else. A contributor who needs to know where the published version comes from has to read the source. The style rules are split the same way. Citation conventions and the three card types used in the text, a digression, a detour, and a why-not, are all defined in the 体例 section of `agent/README.md`, outside the file most readers arrive at. ## The reader stores no prose, which makes the hosted site a build artifact The web reader is a Vite and Vue application that renders the manuscript and its translations out of `agent/`, and it explicitly does not store body content. That is the right shape for a book that lives in Markdown: the prose has one home, the site is a view of it, and a fork changes text without touching the renderer. Running it locally takes the one command the README gives: ```bash cd web && npm install && npm run dev ``` Three things are left unstated. No Node version is given, although the reader needs a modern one for Vite. No package manager is named, so npm is the only editor-completed path and the lockfile convention is unknown. And the command has to be run from the `web/` subdirectory, so a reader who only wants the text never needs it: the Markdown under `agent/`, `agent/en/` and `agent/es/` is meant to be read locally, alongside an AI tool, with the source open next to it. The same decision has a consequence at the hosted end. If the reader holds no prose, then what appears at books.antinomie.org/pi is a function of the commit that was deployed, and nothing in the repository records which commit that was. ## The Chinese manuscript is the source, so every translation lags by construction Three languages, one origin. The Chinese original in `agent/` is described as the only content source, and the English and Spanish texts sit downstream in `agent/en/` and `agent/es/`. The README itself is triplicated the same way, with `README.md`, `README.en.md` and `README.es.md` linked at the top. The process is written down in `agent/TRANSLATION.md`. That arrangement is honest about direction of travel, and it has a cost that is easy to miss. Every English or Spanish page is behind the Chinese page by definition, so a reader working in a translation is reading a snapshot of the manuscript as it stood when the translator reached that chapter, not the current text. Adding a language is a translation task rather than a code change, which is a fair trade for a book of this kind. What the README does not say is what the reader shows when a chapter exists in Chinese and not in a translation. The web version can switch between zh, EN and ES, so the three sets of files must already differ in coverage somewhere, and the behaviour of the switch in that case is left to the implementation. ## No licence file, so the terms for reusing the text are unstated The repository listing contains no LICENSE, and no licence is named in the README or in the workspace description. That is the whole of it: there is no permissive grant to point at and no explicit restriction either, so nothing in the repository says what a reader may do with the manuscript, the two translations, or the Vue reader. It is worth being precise about what that does and does not mean. It does not make the book unusable, and reading the hosted version or the Markdown locally is unaffected. It does mean that a team intending to mirror the book, fork the workspace, publish the translations under another imprint, or hand the text to a tool that keeps a copy has no statement in the repository to point at, and no grant to fall back on. The mismatch with the project's own use is mild but real. The recommended way to read the book is to pull the Markdown down and work through it with an AI assistant beside the source, which is a workflow built on copying text out of the repository. What the repository offers in return is a viewer for reading, not a licence for redistributing. ## Where reading the pi source at the same commit beats reading about it The obvious alternative is not another book. It is the pi repository itself, at commit `cd20a8d2e`, opened in an editor next to the manuscript. The two routes differ in what they add. The source is authoritative and free of interpretation, but it arrives in dependency order with no argument attached, so a reader has to reconstruct the shape of the system themselves. That reconstruction is exactly what part one of this book offers, along with a claim about what the package promises and refuses, and the file:line apparatus that lets a reader check the interpreter instead of trusting it. The cost of that layer is staleness and a second source to maintain. An interpretation of a moving codebase has to be re-checked, and this one is pinned to a single commit with no date, so the reader has no way to judge how far behind it has fallen. The right use is as a map drawn at a known point: read it for the shape, then confirm each claim against the commit it names before relying on it. ## Conclusion Read this book if you already write TypeScript against LLM APIs and want someone else's reading of how one agent loop is put together, with every claim checkable at the commit it was written against. Do not adopt it as a maintained reference, because the analysis stops at cd20a8d2e with no date, part one has two published chapters, and no licence file states what you may do with the text. First check whether the pi repository at that commit still matches your own version of packages/agent, then read the workspace layout section and notice which two directories it leaves out. ## FAQ ### What does the antinomie-lab/pi-book repository contain? A workspace for a Chinese architecture book about the agent loop in the pi repository, specifically its packages/agent directory and the @earendil-works/pi-agent-core package. The manuscript lives in agent/, translations in agent/en/ and agent/es/, and a Vite plus Vue reader in web/ renders them without storing body content. ### Which version of pi does the pi book describe? The whole book corresponds to commit cd20a8d2e on the pi repository's main branch, and code references are written as file:line with the quoted text inline. The commit is given as a bare short hash with no date attached. ### Can I read the pi book without installing anything? Yes. The hosted reader is at books.antinomie.org/pi with citation highlighting and a switch between Chinese, English and Spanish, and the Markdown originals are in the repository at agent/, agent/en/ and agent/es/. Only the local reader needs an install. ### How do I run the pi book web reader locally? From the web/ directory, run cd web && npm install && npm run dev. The README gives no Node version and names no package manager, and the reader is a Vite plus Vue application, so a Node toolchain has to be present before the command works. ### What licence is the pi book released under? The repository listing has no LICENSE file and the README names no licence, so the repository states nothing about reuse of the manuscript, the translations or the reader. Reading the hosted version and the Markdown locally is unaffected by that absence. ## Sources - [antinomie-lab/pi-book on GitHub](https://github.com/antinomie-lab/pi-book) - [Issues](https://github.com/antinomie-lab/pi-book/issues) - [Project website](https://books.antinomie.org/pi) - [README](https://github.com/antinomie-lab/pi-book/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/antinomie-lab-pi-book