Dive into Claude Code: a source-level map of Claude Code's architecture and a design guide for agent builders

What Dive into Claude Code actually is, and who should read it

This is not software you install. The repository is a research artifact: a paper, a set of architecture documents under docs/, images under assets/, and a catalog of community analyses. Its subject is Claude Code, examined at version v2.1.88, which the README describes as roughly 1,900 TypeScript files and about 512K lines of code. The stated purpose is twofold: explain how Claude Code is built, and distill that into guidance for people designing other agent systems.

The audience is narrow and specific. The README's own reading guide routes agent builders to docs/build-your-own-agent.md and then docs/architecture.md, security researchers to the safety sections, product managers to the highlights and principles, and researchers to the arXiv paper. If you fall into none of those groups, the repository has little for you. There is no package to depend on, no service to run, and no API surface.

The central claim is stated bluntly in the README: only 1.6% of the codebase is AI decision logic, and the remaining 98.4% is deterministic infrastructure covering permission gates, context management, tool routing, and recovery logic. Whether or not you accept that split as a general law, it is the thesis the whole document is organized around.

The architecture the analysis describes: one loop, seven safety layers, five compaction stages

The README frames Claude Code as answering four design questions. Where does reasoning live? The model reasons and the harness enforces. How many execution engines exist? One queryLoop serves all interfaces, including CLI, SDK, and IDE. What is the default safety posture? Deny-first, with the ordering deny > ask > allow and the strictest matching rule winning. What constrains the system? The context window, given as roughly 200K for older models and 1M for the Claude 4.6 series, with context-management stages activating under their own conditions.

The decomposition is seven components (User, Interfaces, Agent Loop, Permission System, Tools, State and Persistence, Execution Environment) across five architectural layers, illustrated by assets/layered_architecture.png. The README also tallies concrete counts: 7 safety layers, 5 compaction stages, 54 tools, 27 hook events, 4 extension mechanisms, and 7 permission modes. These are the numbers worth checking against the paper, because they define the scope of what was analyzed.

The most useful idea for a builder is the one the README calls out as resisting reimplementation. The agent loop itself is described as a simple while-loop. What is hard to copy is the cross-cutting harness: hooks, the classifier, compaction, and isolation. That is a design argument, not a feature list, and it is the part of the repository most likely to change how you scope your own project.

Getting the material: cloning the repository and reading the paper

There is no install step. The README points to the arXiv paper for the full analysis and to the docs/ directory for the extended material. Cloning gives you the Markdown documents, the paper PDF, and the diagrams.

git clone https://github.com/VILA-Lab/Dive-into-Claude-Code.git
cd Dive-into-Claude-Code
ls docs paper assets

The listing should show the architecture and design-guide documents in docs/, the archived paper PDF in paper/, and the figures in assets/. The README states that the main PDF link opens arXiv v2 from July 2, 2026, while the repository copy at paper/Dive_into_Claude_Code.pdf is kept as the April 2026 archive. If you are citing a specific figure, note which of the two you read.

The README also carries a Chinese translation at README_zh.md, so both language versions sit in the same checkout. For a first pass, the README's reading guide is the fastest route: pick your role from the table and follow the two links it gives you rather than reading the document front to back.

Where the analysis is thin, and where it is the wrong tool

The repository describes Claude Code. It does not evaluate it against a baseline, and the README presents no measurements of agent success rates, latency, or cost. The headline 1.6% versus 98.4% figure is a characterization of code composition at one version. Treating it as a performance claim would be a misreading.

Version drift is a real limitation. The architecture sections cover v2.1.88, and the README is explicit that the design guide and resource catalog extend the analysis with work reviewed through September 7, 2026. Anything you conclude about the permission system or the query loop is tied to that version. The README does not document a changelog or a migration path between versions, so if Claude Code ships a new permission model, this document will not tell you what changed.

Two claims in the highlights are worth reading carefully rather than skimming. The README notes that in the legacy shell-parser path, more than 50 subcommands triggers an ask decision, which is a bounded-analysis heuristic with an approval fallback, not a guarantee. It also states that two CVEs reveal a pre-trust window in which extensions execute before the trust dialog appears. Those are the kind of findings that make the repository useful to security researchers, and they are also the kind that age fastest.

Finally, this is the wrong tool if you wanted a Claude Code alternative, a wrapper, or a configuration guide. Nothing here runs.

Compared with OpenClaw and Hermes-Agent: what the cross-system section adds

The repository includes a comparison section titled Cross-System Comparison: Claude Code vs OpenClaw vs Hermes-Agent. That is the closest thing to an alternative analysis inside the document, and the difference in approach is the point: rather than presenting another agent you could adopt, it places Claude Code's choices next to two other systems so you can see which decisions are Claude Code specific and which recur.

That framing matters because the README's core argument is that the loop is easy to copy but the surrounding harness is not. A comparison across three systems is the natural test of that claim. If hooks, compaction, and isolation show up in similar form elsewhere, the harness is a pattern. If they do not, it is a differentiator.

The section is a comparison of designs, not a benchmark. The README gives no performance numbers for OpenClaw or Hermes-Agent, and the repository contains no evaluation harness. Read it for architectural contrast, and read the original projects if you need to know what they actually do.

Licence, maintenance, and the cost of keeping up

The repository metadata reports the licence as NOASSERTION, which is GitHub's way of saying it could not classify the file. The README's own badge, however, links to LICENSE and displays CC-BY-NC-SA-4.0. Those two signals disagree, so read the LICENSE file itself before you reuse a diagram, a table, or a passage. The non-commercial and share-alike terms of that licence family are the parts most likely to affect reuse in a product context. This is a description of what the files say, not legal advice.

The last push to the repository was on 2026-09-07. The repository is not archived. There are no releases, so there is no versioned artifact to pin and no upgrade path to follow. Updating means pulling the branch and diffing Markdown and PDFs.

The practical maintenance cost is therefore low but asymmetric. Nothing breaks when the repository changes, because nothing depends on it. What does change is the accuracy of the analysis relative to the current Claude Code release. The README anchors its architecture sections to v2.1.88; if you are building against a later version, you are the one who has to check whether the permission modes, hook events, and compaction stages still match.

How to use the design guide without over-reading it

The design guide is the part of the repository aimed at people who are not studying Claude Code for its own sake. It sits under docs/build-your-own-agent.md, and the README positions it as the first stop for agent builders, with docs/architecture.md as the follow-up.

The useful way to read it is as a set of questions rather than a set of answers. The README's architecture table is the model: each row is a question every production coding agent faces, and each answer is one system's choice. Where does reasoning live? How many execution engines? What is the default safety posture? What is the binding resource constraint? You can apply those four questions to your own design without accepting any of Claude Code's answers.

The values-to-principles chain is the more debatable layer. The README traces five values through thirteen design principles to implementation, and it illustrates the chain with a concrete anecdote: when a 93% prompt-approval rate revealed approval fatigue, the response was restructured boundaries rather than more warnings. That is a specific design move worth studying. The full thirteen principles are collapsed behind a details element in the README, so you will need to expand it or read the paper to see all of them.

Editorial conclusion

Adopt Dive into Claude Code if you are designing an agent harness and want a documented case study of how Claude Code separates model reasoning from deterministic infrastructure, or if you are writing about Claude Code and need a citable source. Skip it if you want a library, a CLI, or runnable code; the repository is documentation, a paper, and assets. Before relying on any number, open the arXiv paper at 2604.14228 and check that the version you cite matches the one the README describes, since the README states the architecture sections cover v2.1.88 while the resource catalog extends through 2026-09-07. Also read LICENSE directly, because the repository metadata reports NOASSERTION while the README badge says CC-BY-NC-SA-4.0.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. VILA-Lab/Dive-into-Claude-Code on GitHub