# Claude-Code-Source-Study is a 34 chapter reading of one agent codebase > The repository is a deep dive into Claude Code's source code, organised as thirty four chapters that follow a single session from startup to output, with the project itself enforcing its own editorial rules through a chain of prose lint checks. It is a study document rather than a library, it ships no releases, and the last push was on 2026-06-03. **luyao618/Claude-Code-Source-Study** — Deep dive into Claude Code's source code— learn from the best agent implementation out there. - Repository: https://github.com/luyao618/Claude-Code-Source-Study - Stars: 1,739 · Forks: 579 - Language: TypeScript - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/luyao618-claude-code-source-study ## A study document with a CI gate, not a library The repository describes itself as a deep dive into Claude Code's source code, for learning from what it calls the best agent implementation. The subject is a commercial product, and the object of study is its source, which the README says covers system prompt engineering, multi agent orchestration, the tool system, permission security, bridge IPC, remote sessions, enterprise proxying and terminal UI. That is an unusual thing for a GitHub repository to be, and the repository layout reflects it. There is no library in src/, no exported function and no installable API. The content is documentation: a docs/ directory holding the chapters, a scripts/ directory holding the tooling that generates appendices and runs the editorial checks, a package.json that wires those scripts together, and a README that is really a table of contents. The package manifest makes the status plain. The name is claude-code-source-study, the version is 0.0.0, and the package is marked private. There is nothing to install and nothing to depend on. The output is the text. The two things that make this more than a blog series are the level of detail and the enforcement. The README describes the analysis as file by file and function by function, with each chapter precise to source line numbers and with key code snippets, and it claims to cover every core module across thirty four chapters. The organisation follows the runtime lifecycle of the software, moving from what happens before you enter the program, through the mechanics of one turn, the tool family, agents and coordination, protocol and security, the network and remote layers, the terminal interface and multimodal input, and finally memory, extensions and summarisation. The enforcement is the part that is genuinely unusual, and it is described below. ## Eight parts that follow one session from cold start to summary The chapter table is organised as a journey rather than as a catalogue of subsystems, and the ordering is the argument of the document. Part one, before entering the software, covers the project overview and the four entry shapes, the startup path and cold start optimisation, the configuration system with enterprise device management, and configuration migrations treated as code. The first chapter's claim is that one codebase serves as a CLI, an SDK, an MCP server and a sandbox runner, which is a framing decision that shapes every later chapter. Part two is the kernel of a single turn: the query engine and the conversation main loop, system prompt and output style injection, the family of context compaction mechanisms, the prompt cache as a cross cutting concern, and the thinking, effort and advisor settings. The compaction chapter in particular is described as covering six separate compaction paths, and the prompt cache chapter as organising the cache boundary problem across modules. Part three is the tool family, split into the tool protocol with its registration and search mechanism, the dual shell tools with a four layer security defence, the file, code and language server collaboration tools, and the communication, scheduling, querying and synthesis tools. Part four covers the agent system and sub agent calls, the design patterns of the built in agents, the task model and its wire level type spectrum, and the coordinator with cron style scheduling. Part five moves to protocol and extension interfaces: the MCP implementation, the permission system, hooks, the three extension points of skills, plugins and output styles, and feature flags with compile time optimisation. Part six covers the transport layer, bridge IPC with remote sessions, and direct connect with upstream proxying. Part seven is the terminal interface and multimodal input, and part eight is memory, extensions and summarisation. Four reading routes are offered: a seven chapter introduction, a nine chapter route for people focused on agent design, a five chapter route for remote and enterprise topologies, and the full thirty four chapters in order. ## The tool system is modelled as a table with three columns Two chapters show how the project thinks about its own internal structure, and they are the clearest signal of what a reader can expect to learn. The tool protocol chapter describes a Tool interface, a builder function for constructing tools, and a model organised in three columns: family, runtime leaf and feature gated. Appendix A is a quick reference table for that same three column model, which means the model is load bearing across the document rather than an aside in one chapter. The task chapter applies the same discipline elsewhere. It describes a spectrum of seven wire level task types, broken down as four default, two feature gated and one special case, and Appendix E is the matching quick reference. The built in agent chapter uses a similar split, distinguishing what the source defines from what is actually available at runtime, with Appendix D as the lookup table. The hooks chapter gives a comparable inventory: twenty seven hook events and four kinds of hook command, with the stop hooks and notification events called out by name, and Appendix C tabulating the same events and command types. The commands chapter counts a hundred and one top level entries across built in commands, skills, plugins and workflows, and Appendix B indexes them. The last appendix is a two way matrix between modules and chapters, plus a listing of orphan directories, which is a self audit of the document's own completeness. For a reader building an agent, this is the most transferable part of the study. Not the line numbers, but the habit of putting the tool surface into a table with a fixed number of columns and then generating the table from the source rather than writing it by hand. ## Ten lint checks decide whether a chapter is allowed to land The package scripts are the most unusual thing in the repository. A documentation project normally has a formatter and maybe a link checker. This one has a chain of ten checks, and the composite script runs all of them: ```json "check:docs": "bun run check:source-commits && bun run check:no-fuzzy && bun run check:no-revision-codenames && bun run check:no-frontmatter && bun run check:no-spec-jargon && bun run check:prose-diff && bun run check:headings && bun run check:code-ratio && bun run check:section-titles && bun run check:orphans" ``` The names describe the rules, and they are the kind of rules a long technical book needs. Source commits are checked, so that a claim about what the code does can be traced to a specific commit. Fuzzy quantifiers are rejected, which is a direct attack on the vague writing that long technical documents drift into. Revision codenames are forbidden, so the text does not depend on internal version nicknames. Frontmatter is not allowed in chapters. Specification jargon is kept out of prose. A prose diff ratio check watches how much of a revision is rewording rather than new content. Heading preservation checks that an edit does not silently drop a section. A code ratio check keeps the balance between snippets and explanation. Section titles are linted for style. And the orphan check, which reuses the module matrix generator, confirms that every directory in the studied source is accounted for by some chapter. The appendices are generated rather than written, and the generator scripts make that explicit: ```json "gen:appendix": "bun scripts/gen-tool-table.ts && bun scripts/gen-commands-table.ts && bun scripts/gen-hooks-table.ts && bun scripts/gen-agents-table.ts && bun scripts/gen-tasktypes-table.ts && bun scripts/gen-module-matrix.ts", ``` Six generators, one per appendix, each reading the studied source and emitting a table. A change in the source that adds a tool therefore changes the table, and a chapter that stops covering a module shows up as an orphan. This is the part of the repository worth copying even if you never read a chapter. For a long document that claims to describe a moving codebase, generating the reference tables and gating the prose is the only way the claims stay true. ## Bilingual by design, with a v2 revision and separate English tree The repository exists in two languages, and the structure makes the decision explicit rather than incidental. The README is written in Chinese with a link to an English version, README-en.md, and the prose of the main edition is Chinese while technical terms are kept in their original English. The chapters live in a docs/ directory, and there is a separate docs-en/ directory for the English edition. The README states the goal plainly, that the body text is Chinese and technical vocabulary stays in English, which is the usual choice for a document about an English language codebase written for Chinese speaking engineers. There is also a version dimension. A V2-CHANGELOG file explains why the project has a v2 and what it added compared with v1, and the package description records the v2 revision along with the CI gate and the appendix generation. So the repository has already been through at least one significant restructure, and the change record is in the repository rather than in a blog post. The maintenance picture is mixed, and it is worth being plain about it. The repository is not archived and the last push was on 2026-06-03, which is more than four months before the current date. There are no GitHub releases, so the document has no version tags of its own; its versions are tracked in the changelog and in the source commit references inside the chapters. For a reader, that combination is workable. The subject, Claude Code, changes often, so a study document is always describing a particular build. The source commit checks are the mechanism that keeps those references honest, and they are the first thing to look at if you want to know how fresh a given chapter is. ## Conclusion Adopt this repository as a reading and design reference if you are building an AI coding agent and want to see how a production tool organises its tool system, permission model, hooks, context compaction and terminal interface, and if you are willing to read a long, detailed document rather than skim a summary. Do not adopt it as a codebase you can depend on, because there is no published package, no versioned release and no API, and the package manifest marks the project private at version 0.0.0. Before you quote anything from it, run the check:docs gate yourself, read the source commit checks, and compare the chapter line references against the Claude Code version they describe, since a line number is only meaningful for a specific build of the software being studied. ## FAQ ### What is the Claude-Code-Source-Study repository? It is a 34 chapter deep dive into the source code of the Claude Code command line assistant, organised by the runtime lifecycle of a session, with each chapter going down to file and function level and citing source line numbers. All the articles live in the docs/ directory. ### How is the study organised into chapters? The chapters run in eight parts: before entering the software, the kernel of one turn, the tool family, agents and coordination, protocol, security and extension interfaces, the network layer and remote collaboration, the terminal interface and multimodal input, and memory, extensions and summarisation. Four reading routes of different lengths are suggested. ### What do the appendices contain? Six generated reference tables: a tool quick reference by family, runtime leaf and feature gated column, a commands index, a hooks event table covering the hook events and the command types, a built in agent table, a task type spectrum, and a two way matrix between modules and chapters that also lists orphan directories. ### How does the project check the quality of its own chapters? A composite script named check:docs runs ten checks in sequence, including checks for source commits, fuzzy quantifiers, revision codenames, frontmatter, specification jargon, prose diff ratio, heading preservation, code ratio, section titles and orphan directories. The appendix tables are generated from the studied source by six generator scripts run with bun. ### Is the study available in English? There is an English README, README-en.md, and a separate docs-en/ directory for the English edition, while the main body text is written in Chinese with technical terms kept in English. The repository is licensed under the MIT licence. ## Sources - [Issues](https://github.com/luyao618/Claude-Code-Source-Study/issues) - [License: MIT](https://github.com/luyao618/Claude-Code-Source-Study/blob/main/LICENSE) - [luyao618/Claude-Code-Source-Study on GitHub](https://github.com/luyao618/Claude-Code-Source-Study) - [README](https://github.com/luyao618/Claude-Code-Source-Study/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/luyao618-claude-code-source-study