claude-code-book

<div align="center"> # Decoding Agent Harness — A Deep Dive into Claude Code Architecture <br/> While everyone teaches you how to **use** AI Agents — this book takes you inside to **dissect** them <br/> [](https://github.com/lintsinghua/claude-code-book/stargazers) [](LICENSE) [](https://lintsinghua.github.io/) <img width="2880" height="1558" alt="image" src="https://github.com/user-attachments/assets/39efa7d4-4521-444e-a222-fd0acb756e51" /> </div> --- How does the conversation loop drive everything? Why is tool permission a four-stage pipeline? How does context compression operate within token budgets? How do sub-agents inherit parent context through Fork? Understanding Claude Code's design decisions gives you a **transferable mental model** for any Agent framework. > **Disclaimer:** This book is based on architectural analysis of Claude Code's public documentation and product behavior, without referencing or using any unpublished or unauthorized source code. Claude Code is an Anthropic PBC product, and this book is not affiliated with, authorized by, or representative of Anthropic. --- ## What Makes This Book Different **Not a usage tutorial, no Prompt tricks.** The market is flooded with guides on "how to write good Prompts" and "how to call Agent APIs." But if you want to know how a production-grade Agent system's **skeleton** is built — why async generators instead of callbacks? Why four-stage permission checks? What to do when the context window is full? — there's almost no reference material available. This book fills that gap. Using Claude Code as a case study, it dissects **every** core subsystem of an Agent Harness and explains the "why" behind each engineering decision. ### Three Core Features - **Architecture analysis, not API documentation** — Not "how to call," but "why was it designed this way." Every module traces design motivations, analyzes engineering tradeoffs, and points out anti-pattern pitfalls - **Design philosophy, not usage tutorials** — From async generators to circuit breakers, from dependency injection to cache-aware architecture, each chapter extracts transferable design principles - **Transferable cognitive models** — Whether you use LangChain, AutoGen, CrewAI, or build from scratch, the 139 architecture diagrams and design pattern analyses in this book are directly reusable ### Book Data | Metric | Count | |------|------| | Main Chapters | 15 Chapters + 4 Appendices | | Mermaid Architecture Diagrams/Flowcharts/State Machines | 139 | | Core Subsystems Covered | Tool System, Permission Pipeline, Context Compression, Memory System, Hook System, Sub-agent Scheduling, MCP Integration, Skill Plugins, Streaming Architecture, Plan Mode | | Design Decisions Analyzed | 50+ "Why This Design" | | Term Entries (Chinese-English) | 100 | | Feature Flags | 89 | | Registered Tools | 50+ | --- ## Table of Contents ### Part 1. Fundamentals — Building Mental Models > Understand the paradigm shift in Agent programming, establish an overall cognitive framework for Agent Harness. | | Chapter | What You'll Learn | |:-:|------|---------| | 01 | [New Paradigm of Agent Programming](第一部分-基础篇/01-智能体编程的新范式.md) | AI programming tool evolution timeline from Copilot to Claude Code; Five Agent Harness design principles (async generator first, security boundaries embedded, cache-aware, progressive capability extension, immutable state stream); Tech stack analysis (Bun + React/Ink + Zod v4) | | 02 | [Conversation Loop — Agent's Heartbeat](第一部分-基础篇/02-对话循环-Agent的心跳.md) | Complete lifecycle of `while(true)` async generator main loop (initialization→preprocessing→API call→tool execution→result filling); Five yield event types; Ten termination reasons and state machine model; `QueryDeps` dependency injection for testability design | | 03 | [Tool System — Agent's Hands](第一部分-基础篇/03-工具系统-Agent的双手.md) | `Tool<Input, Output, Progress>` five-element protocol (name/Schema/permission/execution/rendering); `buildTool` fail-safe factory function; 45+ tools registered in 12 categories; Greedy algorithm for concurrent partitioning; `StreamingToolExecutor` four-state state machine; Lazy tool discovery (ToolSearchTool) | | 04 | [Permission Pipeline — Agent's Guardrails](第一部分-基础篇/04-权限管线-Agent的护栏.md) | Four-stage pipeline (Schema validation→rule matching→context evaluation→interactive confirmation); Five permission mode spectrum (default→plan→auto→bubble→bypass); Bash rule matching (exact/prefix/wildcard); Speculative classifier's 2-second Promise.race; `ResolveOnce` concurrent-safe atomic declaration | ### Part 2. Core Systems — Deep Dive into Subsystems > Dissect the four core subsystems of Agent Harness — configuration, memory, context, and hooks. | | Chapter | What You'll Learn | |:-:|------|---------| | 05 | [Settings & Configuration — Agent's DNA](第二部分-核心系统篇/05-设置与配置-Agent的基因.md) | Six-layer configuration priority chain (plugin→user→project→local→flag→policy); Merge rules (array concatenation deduplication/deep object merge/scalar override); Security boundary: why `projectSettings` is excluded from security checks (preventing malicious repository supply chain attacks); Compile-time `feature()` and runtime GrowthBook dual-layer feature gates | | 06 | [Memory System — Agent's Long-term Memory](第二部分-核心系统篇/06-记忆系统-Agent的长期记忆.md) | Four types of closed memory (user/feedback/project/reference); "Only save information that cannot be derived from current state" design philosophy; MEMORY.md index file (200 lines/25KB limit); Fork's automatic memory extraction and main agent mutual exclusion mechanism; `CacheSafeParams` impact on prompt cache sharing | | 07 | [Context Management — Agent's Working Memory](第二部分-核心系统篇/07-上下文管理-Agent的工作记忆.md) | Effective window formula and multi-level buffer thresholds; Four-level progressive compression strategy (Snip→MicroCompact→Collapse→AutoCompact); Circuit breaker pattern (trip after 3 consecutive failures, derived from 1,279 real sessions); Compression prompt engineering with two-stage output (`<analysis>` discard + `<summary>` keep); Compressed token budget (50K total/5K per file) | | 08 | [Hook System — Agent's Lifecycle Extension Points](第二部分-核心系统篇/08-钩子系统-Agent的生命周期扩展点.md) | Five Hook types (Command/Prompt/Agent/HTTP/Function); 26 lifecycle events (tool call/user interaction/session/sub-agent/compression); Structured JSON response protocol (approve/block + `updatedInput`/`additionalContext`); Six-layer Hook source priority; Three-layer security mechanism (global switch/enterprise control/workspace trust) | ### Part 3. Advanced Patterns — Agent Composition & Extension > Explore how Agents compose, orchestrate, and extend — from sub-agents to MCP protocol bridging. | | Chapter | What You'll Learn | |:-:|------|---------| | 09 | [Sub-agents & Fork Pattern](第三部分-高级模式篇/09-子智能体与Fork模式.md) | `BaseAgentDefinition` type and three Agent sources (built-in/custom/plugin); Four built-in Agents (Explore read-only/Plan structured/General full/Verification adversarial); Fork's byte-level context inheritance (`CacheSafeParams` five dimensions + placeholder tool results maximizing cache hit area); Recursive Fork protection; Markdown frontmatter format for custom Agents | | 10 | [Coordinator Pattern — Multi-agent Orchestration](第三部分-高级模式篇/10-协调器模式-多智能体编排.md) | Coordinator-Worker architecture with dual gating; Coordinator's "orchestrate only, don't execute" constraint; `INTERNAL_WORKER_TOOLS` and tool isolation; `TeamCreateTool`/`SendMessageTool` four addressing modes (peer-to-peer/broadcast/UDS/Bridge); Session path-based Scratchpad collaboration space; Four-stage workflow (Research→Synthesis→Implementation→Verification) | | 11 | [Skill System & Plugin Architecture](第三部分-高级模式篇/11-技能系统与插件架构.md) | 11 core built-in skills; `SKILL.md` frontmatter complete fields (name/description/arguments/allowed-tools/model/effort/context/agent/paths/hooks); Three-level parameter substitution (`$ARGUMENTS`/positional `$0-$1`/named `$foo`); Layered loading (managed→user→project→plugin→bundled); `discoverSkillDirsForPaths` dynamic skill discovery; Plugin cache-first loading and MCP indirect registration | | 12 | [MCP Integration & External Protocols](第三部分-高级模式篇/12-MCP集成与外部协议.md) | 8 transport protocols (stdio/sse/sse-ide/http/ws/ws-ide/sdk/claudeai-proxy); `MCPConnectionManager` five-state connection management; Three-segment tool naming (`mcp__{server}__{tool}`); 7 configuration scopes with server approval/rejection lists; Bridge bidirectional communication system (SSE sequence number continuity/`BoundedUUIDSet` echo deduplication/v1-v2 transport abstraction/triple permission gating) | ### Part 4. Engineering Practice — From Principles to Building > Engineering details of performance optimization, and a practical roadmap for building a complete Harness from scratch. | | Chapter | What You'll Learn | |:-:|------|---------| | 13 | [Streaming Architecture & Performance Optimization](第四部分-工程实践篇/13-流式架构与性能优化.md) | `QueryEngine` stateful query lifecycle manager; `StreamingToolExecutor` concurrency control (safe tools parallelizable/non-safe tools exclusive); Startup performance optimization (parallel prefetch 160ms→65ms, 59% savings); Lazy `require()` and Zod lazy schema evaluation; `updateUsage` `>0` guard; `CacheSafeParams` five-dimension sharing and `skipCacheWrite` one-time Fork | | 14 | [Plan Mode & Structured Workflow](第四部分-工程实践篇/14-Plan模式与结构化工作流.md) | Plan mode's "think before act" philosophy with construction industry analogy; `prepareContextForPlanMode` pattern switching; `ExitPlanModeV2Tool` circuit breaker defense; Three-layer plan file recovery strategy (direct read→file snapshot→message history); `ScheduleCronTool` local scheduling (file lock for deduplication/7-day auto-expiry/Jitter for anti-thundering herd); `RemoteTriggerTool` remote API trigger | | 15 | [Build Your Own Agent Harness](第四部分-工程实践篇/15-构建你自己的Agent-Harness.md) | Decision matrix: Agent Harness vs simple API calls; Six-step implementation roadmap (AsyncGenerator conversation loop→Fail-closed tool system→four-stage permission pipeline→Snip+Summary context management→memory storage→Hook executor); Circular dependency solutions (lazy require/centralized type export); Layered feature switch strategy; Four-layer observability system; Multi-environment adaptation (CLI/IDE/SDK/Server); Security threat model and audit checklist | ### Appendix — Quick Reference | | Content | |:-:|------| | [A](附录/A-源码导航地图.md) | **Architecture Navigation Map** — 16 core module responsibilities, module dependency tree, 6 quick reference paths for data flow, four-layer architecture explanation, 10 design patterns quick reference | | [B](附录/B-工具完整清单.md) | **Complete Tool Inventory** — 50+ tools organized in 12 categories, annotated with readOnly/destructive/concurrencySafe attributes, 6 common tool combination patterns, performance characteristics overview | | [C](附录/C-功能标志速查表.md) | **Feature Flag Quick Reference** — 89 Feature Flags organized in 13 categories, annotated with compile-time/runtime types, dependency graph, and 6 common configuration scenario recommendations | | [D](附录/D-术语表.md) | **Glossary** — 100 Chinese-English term definitions with cross-references and chapter locations | --- ## How to Read **Short on time?** Ch1 (mental model) → Ch2 (conversation loop) → Ch4 (permission pipeline) → Ch15 (hands-on building). Get the core understanding and practical ability. **Experienced architect?** Jump straight to Part 2 (core systems) and Part 3 (advanced patterns), trace back to Part 1 when encountering concept gaps. Focus on "design philosophy" and "anti-pattern warnings" sections in each chapter. **Systematic learning?** Read through from start to finish, complete hands-on exercises for each chapter, and build your own Harness in Ch15. Expect 2–3 weeks of deep reading. **Just need reference?** Skip to the appendices — A for module locations, B for tool attributes, C for feature flags, D for term definitions. --- ## Who This Book Is For - **Architects** — You want to build your own Agent framework, need a complete design space map and engineering tradeoff analysis - **Senior Engineers** — You're not satisfied with just calling APIs, want to understand the underlying mechanisms of tool calling, streaming, and permission control - **Researchers** — You want to understand how Agent systems work from an implementation perspective, need publication-grade system analysis - **Claude Code Users** — You want to understand design intent, use it more accurately, tune it more deeply, and maximize its capabilities --- ## Background On March 31, 2026, security researcher [Chaofan Shou (@Fried_rice)](https://x.com/Fried_rice) discovered a build configuration issue with the `@anthropic-ai/claude-code` package in the npm registry. The disclosure tweet received over 17 million views, sparking unprecedented discussion about Agent architecture in the tech community. This book was born from that discussion — when Agent architecture became a hot topic in the developer community, we realized there was a need for a systematic book explaining Agent Harness design principles. --- ## Contributing Issues and PRs welcome — fix technical errors, add practical examples, improve chapter structure. ## Acknowledgments [Linux.Do](https://linux.do/) Community --- ## Star History [](https://star-history.com/#lintsinghua/claude-code-book&Date) --- <p align="center"> <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/"> <img src="https://img.shields.io/badge/license-CC%20BY--NC--SA%204.0-lightgrey" alt="CC BY-NC-SA 4.0" /> </a> <br/><br/> Freely share and adapt, but must attribute, non-commercial use, and share under the same license. </p>