动手学 Pi: a 15-checkpoint TypeScript course that builds a coding agent from a Git history
《动手学 Pi》：沿 15 个真实 checkpoint 从零构建 Pi-style Agent
At a glance
- What is it?
- The textbook walks one agent execution chain from message protocol to evaluation, with each chapter pairing prose, a real commit, focused tests and a failure experiment. The design is unusually concrete for an agent tutorial, but it is a course about a specific upstream architecture, not a general framework introduction.
- Who is it for?
- Adopt it if you already write TypeScript and want to understand how a coding agent's message protocol, event stream, tool loop, session tree and context compaction fit together, and you are willing to clone the course branch of hahhforest/pi and run npm run checkpoint -w @pi/course -- 05 to see how a chapter is pinned.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 55 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap this course fills: agent internals taught as a runnable chain
Most agent material explains the idea of a loop and leaves the wiring to the reader. This project takes the opposite route. The README describes 15 checkpoints that advance along a single execution chain: TypeScript protocol, streaming model, provider, tools, agent loop, session tree, context compaction, extensions, evaluation. Each chapter is described as a closed loop of four parts: textbook prose, a real commit, focused tests, and a failure experiment. The audience is a developer who can already write TypeScript and wants to see how the pieces of a coding agent connect, not someone shopping for a framework. The prologue chapter is explicit about the scope: it follows one README read request through the user message, two model calls, the tool call and its result, and the final answer. That single trace is the spine the rest of the course hangs on, which is a narrower and more useful promise than a survey of agent techniques.
How the 15 checkpoints are sequenced
The ordering is deliberate and worth reading as a design argument. The first block, checkpoints 01 to 05, stays inside the model boundary: a TypeScript survival chapter built on four DemoEvent values, an EventStream that must deliver both the next item and the final result regardless of which side arrives first, a message representation that stores text, tool calls and paired results together, a ScriptedModel that replays preset turns from one instance, and a provider adapter that converts course messages into provider requests and SSE responses back into unified model events. Only then do tools and the loop arrive, at checkpoints 06 to 08, where an echo call passes through schema, Registry and executor and returns a result that keeps the original call id. State and history follow at 09 to 11, and composition and evaluation close at 12 to 14. The dependency order is the teaching device: you cannot meaningfully implement context compaction before you have a session tree to compact.
The mechanism that makes the course verifiable
The claim that separates this from a prose tutorial is that the course code is not pseudocode. The README states the course code is a Git history you can check out, run and verify, with the course branch starting from a fixed upstream commit, 8479bd84, and organizing its history as course(00) through course(14). The pi-course-v1 tags and the course-v1/00 to course-v1/14 tags pin the first version of the course. That pinning matters because it turns each chapter into a diff you can inspect rather than a snapshot you have to trust. It also means the material has a defined drift boundary: the course is anchored to a specific upstream state, so later changes in the upstream project do not silently rewrite what the chapter teaches. If you have ever followed an agent tutorial whose code no longer matches the surrounding text, the fixed commit is the part of this design worth noting.
Getting the textbook and the course code running
The textbook site and the course code live in two repositories, and the README keeps them separate. To run the book locally, the documented commands are git clone https://github.com/hahhforest/pi-textbook.git, then cd pi-textbook, npm install and npm run dev. To work with the agent code instead, the README gives git clone --branch course/build-your-own-pi https://github.com/hahhforest/pi.git, then cd pi, npm install, and two workspace scripts. The first is npm run checkpoint -w @pi/course -- 05, which the README says locates the chapter's parent, target and focused tests. The second is npm run practice -w @pi/course -- 05 ../pi-practice-05, which creates a practice directory without answers or Git history. The intended study loop is to hand the chapter page, the command output and the LEARNING.md file in the practice directory to a companion agent. Nothing in the material indicates a published package you install as a dependency; the unit of delivery is a checkout.
Where the course is the wrong tool
Three limits are visible from the material itself. First, the course is Chinese-first: the repository ships a README_EN.md link and the topics list includes chinese, but the chapter titles and the online textbook are presented in Simplified Chinese, so a reader who needs English prose is reading a translation layer that is not the primary artifact. Second, this is not a library. There are no retrieved releases, and the README frames the output as a textbook plus a course branch, so you cannot depend on a versioned package with a stability contract. Third, the scope is bounded by the Pi architecture. Checkpoint 14 builds an evaluation harness around a fresh fixture and checks the active path and file results, which is a reasonable capstone for a course but not an evaluation framework for your own agent. If your goal is to ship an agent this quarter, working through 15 checkpoints against a fixed upstream commit is a detour, however well constructed.
Alternatives and the difference in approach
The obvious alternative is to read the upstream Pi source directly, since the course branch is derived from it at commit 8479bd84. The difference is ordering and instrumentation. Upstream code shows you the final structure; the course imposes a sequence of 15 checkpoints, each with a focused test and a failure experiment, so the reader meets EventStream before the agent loop and the session tree before context compaction. Another alternative is an agent framework that ships as an installable package. That gives you a dependency with releases and upgrade paths, and it hides exactly the internals this course is built to expose. A third option is a general LLM application tutorial, which typically covers prompting and retrieval rather than the tool-call pairing, call-id preservation and JSONL session records that appear in checkpoints 06 through 10. The trade is clear: this project optimizes for understanding one implementation path, and pays for it in portability.
Maintenance, licensing and what the split means
Maintenance here is a two-repository problem. The textbook site is one repo, the course branch of hahhforest/pi is another, and the README states the course branch starts from a fixed upstream commit and organizes history as course(00) to course(14), with pi-course-v1 tags pinning the first version. That pinning is what keeps the course stable, and it is also what makes upgrades manual: there is no described mechanism for rebasing the course onto a newer upstream state, so a reader following the material is following a snapshot. The repository states that the project is an unofficial community course, not affiliated with or representing Pi or Earendil Works. Licensing is split: the application and original code are MIT, the textbook prose and original media are CC BY 4.0, and upstream Pi code keeps its own license and attribution. The README points to LICENSE and LICENSE-CONTENT. What that split means for your own reuse depends on which layer you copy, and it is worth reading both files rather than assuming a single license covers the whole checkout.
Who should work through it, and what to check first
The course suits a TypeScript developer who wants to build, not just read, the internals of a coding agent and who is comfortable working from a Git history rather than a package. It suits a study group that wants a companion agent to check its practice directories against focused tests. It does not suit someone who needs English-language primary material, a stable dependency, or a general survey of agent techniques. Before spending a weekend on it, verify three things: that the course branch still resolves at commit 8479bd84, that the pi-course-v1 tags line up with the chapters you intend to read, and that the MIT and CC BY 4.0 split in LICENSE and LICENSE-CONTENT matches how you plan to reuse the prose. The checkpoint command is the fastest probe: npm run checkpoint -w @pi/course -- 05 either prints the parent, target and focused tests for that chapter or it does not.
Editorial conclusion
Adopt it if you already write TypeScript and want to understand how a coding agent's message protocol, event stream, tool loop, session tree and context compaction fit together, and you are willing to clone the course branch of hahhforest/pi and run npm run checkpoint -w @pi/course -- 05 to see how a chapter is pinned. Do not adopt it if you need a production agent library, an English-first text, or an API-stable dependency: this is teaching material tied to a fixed upstream commit, and the textbook repo itself ships the site rather than the agent. Before committing time, verify the course branch still resolves at commit 8479bd84, check that the pi-course-v1 tags match the chapters you plan to read, and confirm the split licensing in LICENSE and LICENSE-CONTENT covers how you intend to reuse the prose.
Community notes