A 420,000-Word Anatomy of Claude Code's Agent Harness

What This Book Actually Covers

The repository is not a software project but a book, written in Chinese, titled roughly 'Decoding the Agent Harness'. It claims to be a 420,000-character analysis of Claude Code's architecture. The intended reader is someone who wants to understand how an agent runtime coordinates its parts: the conversation loop that drives tasks, the tool system that executes actions, and the permission pipeline that constrains those actions. The book is organized into 15 chapters and four appendices, with a reading path suggested for first-time readers: preface, then chapters 01, 02, 04, and 15. That path skips straight from core concepts to building your own harness, which suggests the authors expect a technically literate audience who can fill gaps by consulting the appendices later.

The Core Mechanism: Dialog Loop as the Heartbeat

Chapter 02 describes the central loop as a `while(true)` asynchronous generator, which is a concrete architectural pattern. The chapter enumerates five types of yield events and ten reasons for termination. This is not a vague overview; it points to specific implementation details. The book also introduces `QueryDeps` for dependency injection, which is a design choice that affects how components communicate. The claim is that the dialog loop is the heartbeat of the agent, meaning that every tool call, permission check, and memory access happens within this loop's lifecycle. For an engineer, this framing is useful because it explains why the system behaves as a single-threaded coordinator rather than a set of independent services.

Tool System and Permission Pipeline: The Hands and Guardrails

Two chapters focus on the tool system and the permission pipeline. The tool chapter describes a `Tool<I,O,P>` interface with five elements, and a `buildTool` factory that is labeled as 'fault-safe'. The book counts over 45 tools across 12 categories, and mentions a concurrent partitioning greedy algorithm for scheduling tool calls. The permission chapter outlines a four-stage pipeline and five permission modes. It also mentions a speculative classifier that races with a 2-second `Promise.race` timeout. These are specific mechanisms that you can look for in the codebase. The book's approach is to explain each subsystem with design trade-offs, not just list features. For example, the permission pipeline is presented as a series of gates, each with its own failure mode, which is more informative than a simple allow/deny model.

Getting Started: How to Read and Verify the Content

The repository is a collection of Markdown files, so getting started means opening the files in order or using the online reading site at https://lintsinghua.github.io/. The README gives explicit paths for different reading modes: for building your own harness, read the basic and engineering practice parts first; for reference, use the appendices to locate modules, tools, feature flags, and terms. There are no installation commands because there is no code to run. However, the repository includes scripts for contributors: `python3 scripts/check_book.py` and `python3 -m unittest discover -s tests` for validation, and a Mermaid diagram check requiring Node.js 22 or higher, run with `npm ci` and `npm run check:diagrams`. These are for maintaining the book, not for using it as a library.

Architecture Patterns and the 'Harness' Concept

The central metaphor is the 'harness' (舆), which the book uses to describe the runtime framework that carries and organizes an agent's capabilities. The appendix A provides a navigation map of 16 core modules, dependency trees, six data flow paths, a four-layer architecture, and ten design patterns. This is a strong signal that the book is not just a narrative but an attempt to provide a structured reference. The chapters on subagents and Fork mode (chapter 09) explain how context is inherited at the byte level and how recursive Fork is prevented. Chapter 10 covers coordinator-worker patterns with a 'coordinate only, do not execute' constraint. These are architectural patterns that you could apply to other agent systems, not just Claude Code.

A Genuine Limitation: Independent Analysis, Not Official Documentation

The book is an independent technical analysis, not an official Anthropic publication. The README states this clearly. The license covers only the book's text, not third-party source code. This means that any claims about Claude Code's behavior are not guaranteed to match any specific release. The book itself acknowledges this by asking readers to distinguish between source-confirmed behavior, architectural inference, and teaching examples. Feature flags and tool availability depend on build and runtime configuration. So if you are using this book to make decisions about a production system, you must verify against the actual source code or official docs. The book could become outdated quickly, given that Claude Code is an evolving product. The last push to the repository was in September 2026, but that does not mean the content is current with the latest Claude Code version.

The Real Alternative: Reading Claude Code's Source Directly

The alternative to this book is to read the Claude Code source code yourself, assuming you have access to it. The book is a secondary source that interprets the code, but it cannot replace the primary source for verification. The difference in approach is that the book provides a curated path through the architecture, with diagrams and exercises, which can save time. Reading the source directly gives you exact current behavior but requires you to build the mental model yourself. Another alternative is to study other agent harnesses, such as those built on the Model Context Protocol (MCP), which the book covers in chapter 12. MCP is an external protocol standard, and the book explains how Claude Code bridges to it. If you are more interested in protocol-level interoperability than in a specific implementation, reading the MCP specification might be more directly useful.

Maintenance and License Implications

The book's text is licensed under CC BY-NC-SA 4.0, which means you can share and adapt it only for non-commercial purposes, with attribution, and you must license your adaptations under the same terms. This has practical implications if you want to use the book's content in a commercial training course or internal documentation: you cannot do so without permission or a separate license. The repository is not archived, and the last push was in September 2026, indicating active maintenance at that time. The contribution guidelines ask for issue or PR submissions with specific details, and they require running validation scripts before submitting. This suggests the authors care about technical accuracy. However, there is no release history, so you cannot track stable versions. You have to rely on the default branch, which may change without notice. For a book, this is acceptable, but if you plan to cite it in a project, you should note the exact commit you used.

Editorial conclusion

Adopt this book if you are a developer who wants to understand the architectural decisions inside Claude Code's runtime, or if you plan to build a custom agent harness and need a structured roadmap. Do not use it if you are looking for an official Anthropic reference or a hands-on tutorial for writing Claude Code plugins, because it is an independent analysis with its own license. Before relying on its details, verify the source code yourself, since the book distinguishes confirmed behavior from inference and examples, and feature flags and tool availability depend on build and runtime configuration. The book's own checks, such as running `python3 scripts/check_book.py`, can help confirm its internal consistency, but they do not validate claims against the actual Claude Code source.

Official sources

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