御舆: A Chinese-Language Deep Dive into Claude Code's Agent Harness

What 御舆 Actually Is, and Who It Is Written For

This is a book repository, not a package. The README describes it as a deep analysis of Claude Code's architecture, organized into 15 chapters and 4 appendices, with architecture diagrams, design trade-offs and hands-on exercises. The stated goal is to help a reader build their own Agent Harness.

The framing comes from the Kaogongji, a classical Chinese text on craft: a cart is a system of cooperating parts, and the 舆 is the carriage body that carries the rider. The book maps that image onto an agent runtime, where the conversation loop advances the task, the tool system performs actions, and the permission pipeline constrains the boundary. The harness is the thing that holds those pieces together and keeps the agent running.

So the audience is narrow and specific. It is for engineers who already work with LLM agents and want to understand the runtime layer underneath them, not for someone who wants to know how to prompt Claude Code better. The reading path in the README confirms this: a first pass goes 00 preface, then 01, 02, 04, 15. That sequence skips straight from the paradigm chapter to the conversation loop and the permission pipeline, then jumps to the build-your-own chapter. A reader who wants to use the tool rather than reimplement it will find that path strange.

The book is in Chinese, with an English README at en/README.md and a companion English edition directory. That directory exists in the repository tree, but the README does not state how complete the English translation is, so treat the Chinese chapters as the authoritative text.

The Architecture It Dissects: Loop, Tools, Permissions, Memory

The table of contents is the clearest statement of what the book covers, and it is unusually concrete. Chapter 02 describes a `while(true)` asynchronous generator main loop with five yield event types, ten termination reasons, and a `QueryDeps` dependency injection mechanism. Chapter 03 lays out a `Tool<I,O,P>` five-element protocol, a `buildTool` factory described as fail-safe, a catalogue of 45+ tools across 12 categories, and a greedy algorithm for concurrent partitioning. Chapter 04 covers a four-stage permission pipeline, five permission modes, Bash rule matching, and a speculative classifier built on a two-second `Promise.race`.

Part 2 moves into subsystems: a six-layer configuration priority chain, four closed memory types with a rule of saving only information that cannot be derived, an effective-window formula with four progressive compression levels (Snip, MicroCompact, Collapse, AutoCompact) and a circuit-breaker pattern, plus five hook types across 26 lifecycle events.

Part 3 handles composition: sub-agents and fork mode with byte-level context inheritance and recursion guards, a coordinator-worker pattern that is constrained to orchestrate and not execute, a skill system with SKILL.md frontmatter and three-level parameter substitution, and MCP integration with eight connection configuration types and a three-segment tool naming scheme.

The appendices are the part most likely to be useful as a reference rather than a read-through: a source navigation map with 16 core modules and 6 data flow paths, a full tool list, a feature flag table covering 89 flags across 13 categories, and a 100-entry bilingual glossary.

One caveat the README raises itself is worth repeating. It asks readers to distinguish behaviour confirmable from source, architectural inference, and teaching examples. That is an honest distinction, and it means the book mixes what the code does with what the author reasons about it. A reader who cannot tell those apart will over-trust the inferences.

Getting the Book and Running Its Checks

There is nothing to install in the sense of a runtime dependency. The README points to an online reading site at lintsinghua.github.io and to chapter links inside the repository. The practical first step is to clone the repository and open the preface.

git clone https://github.com/lintsinghua/claude-code-book.git
cd claude-code-book

After cloning you will see the Chinese chapter directories (第一部分 through 第四部分), the appendix directory, and an en/ directory for the English edition. The preface file is 00-前言.md at the repository root.

The repository does ship verification tooling for contributors. The README instructs contributors to run two checks before submitting changes:

python3 scripts/check_book.py
python3 -m unittest discover -s tests

The first validates the book content through a Python script, and the second runs the unit test suite. A third check covers Mermaid diagrams and requires Node.js 22 or higher, matching the `engines` field in package.json which declares `node: >=22`:

npm ci
npm run check:diagrams

That last script maps to `node scripts/check_mermaid.mjs`, with `mermaid` 11.17.2 and `jsdom` 26.1.0 as dev dependencies. Running these is useful if you plan to submit a correction, because the README asks contributors for the chapter, the section, the proposed change and a reference source, and asks that bilingual changes be mirrored in the English version. If you are only reading, you can skip all three.

Where This Book Will Not Help You

The most important limitation is stated in the README and is easy to skim past: Claude Code is an Anthropic product, and this book is an independent technical analysis, not an official publication. Nothing here carries Anthropic's endorsement, and the behaviour described is the author's reading of a system that Anthropic controls and can change.

The README also warns that feature flags and tool availability depend on build and runtime configuration, and that the counts and timing examples in the book do not represent commitments from the current release. That is a direct admission that specific numbers, such as the 45+ or 50+ tool counts, the 89 flags, or the two-second classifier race, are snapshots rather than guarantees. If you are making an architecture decision based on one of those figures, verify it against the actual source before you commit to it.

A second limitation is language. The book is written in Chinese. The repository carries an English directory and an English README, but the README does not describe the English edition's completeness, so a reader who needs English cannot assume parity with the Chinese chapters.

A third is scope. This will not teach you to use Claude Code as a product. There is no getting-started guide for the CLI, no workflow cookbook, no prompt patterns. Search demand around this project leans toward PDF and download requests, and the README does not describe a PDF distribution or an ebook edition. If a downloadable PDF is what you need, this repository does not document one.

Finally, the licence is listed as unknown in the repository metadata, while the README states the text is under CC BY-NC-SA 4.0. Those two signals do not agree, and the README adds that third-party material keeps its own rights and that the book's licence does not cover third-party source code.

Alternatives and How Their Approaches Differ

The honest alternative is not another book about the same subject. It is the source itself, plus first-party documentation. Anthropic's own documentation describes how to use Claude Code, and the repository's appendices point at the code the book analyses. Reading the source gives you current behaviour with no translation lag and no inference layer, at the cost of the structure the book imposes. The book's value is that it groups 16 modules, 6 data flow paths and 10 design patterns into a narrative you can follow in order.

A second alternative is a general agent-building framework, such as one of the open source agent libraries that ship a runtime you can import. Those give you a working harness immediately, but they do not explain why a production harness makes the choices it does. The book is explicitly about the reasoning behind a specific implementation, including the trade-offs. If your goal is to ship an agent next week, a framework is the faster path. If your goal is to understand what a harness is doing when it compresses context or partitions tool calls, the book is the more direct route.

A third option is to treat the appendices alone as a reference and skip the chapters. The glossary, the tool list and the feature flag table are lookup material. That is a legitimate way to use the repository, and it is cheaper in time than reading 15 chapters, though it gives you no argument about design.

Maintenance, Licensing and the Cost of Keeping Up

The repository is not archived, and the last push was on 2026-09-05. No releases have been published, so there is no versioned artifact to track and no changelog to follow. Upgrades happen as commits to Markdown files on the main branch.

That has a real consequence for anyone who wants to cite the book. Because there are no releases, there is no stable snapshot. A chapter can change between your reading and your citation. If you need a fixed reference, record the commit hash you read rather than pointing at main.

The contributor checks are the maintenance mechanism. `python3 scripts/check_book.py` and the unittest suite guard content, and the Mermaid check guards diagrams. Anyone can submit an issue or pull request, and the README asks for the chapter, section, suggested change and a reference source, plus the reading platform and reproduction steps for rendering problems. That is a reasonable review bar for a documentation project, though it depends on a maintainer actually reviewing.

On licensing, the README states the book text is CC BY-NC-SA 4.0: attribution required, non-commercial use only, and adaptations shared under the same terms. The non-commercial clause is the one that matters most in practice. If you want to use chapters in paid training material or an internal commercial course, that clause is a direct constraint, and the repository metadata listing the licence as unknown adds ambiguity you would need to resolve with the author. This is not legal advice; read the licence text and the README's note that third-party material keeps its own terms.

Editorial conclusion

Adopt this book if you are building your own agent runtime and want a structured walkthrough of the subsystems that make one work, and if you read Chinese or are willing to work through the English README and chapter files alongside it. Skip it if you want a quickstart for using Claude Code as a product, or if you need an officially endorsed reference: the README states plainly that this is an independent technical analysis, not an Anthropic publication. Before relying on any specific claim, check the chapter against the source it cites, because the README itself warns that feature flags and tool availability depend on build and runtime configuration, and that the counts and timings in the text are not commitments from the current release.

Frequently asked questions

Official sources

1. Issues
2. lintsinghua/claude-code-book on GitHub
3. Project website
4. README