Dive into Claude Code: a source-level paper and design guide, not an installable agent

What the repository actually is, and who it is written for

This is not an agent you install. It is a paper-backed analysis of Claude Code at version 2.1.88, described in the README as covering roughly 1,900 TypeScript files and about 512K lines of code, combined with a curated set of community analyses, a design guide for agent builders, and cross-system comparisons. The README's reading guide maps four audiences to entry points: agent builders start with docs/build-your-own-agent.md, security researchers start with the safety and permissions material and the architecture document's section on seven independent safety layers, product managers start with the key highlights, and researchers go to the arXiv paper. If you are trying to decide whether to build your own coding agent, or you are auditing one you already run, the repository is aimed at you. If you want a tool to use today, this is the wrong artifact, and the README never claims otherwise.

The 1.6% claim and what it implies for your own design

The headline finding is a ratio. Only 1.6% of the analyzed codebase is AI decision logic; the other 98.4% is described as deterministic infrastructure: permission gates, context management, tool routing, and recovery logic. The README states that the agent loop itself is a simple while-loop and that the engineering complexity lives in the systems around it. That reframes the build problem. If the loop is cheap to copy, the differentiator is the harness, and the repository's own key highlights say as much: the cross-cutting harness resists reimplementation, and the loop, hooks, classifier, compaction, and isolation are not equally easy to reproduce. Treat the ratio as a claim about one specific version of one specific codebase, not a law. It is still useful as a budgeting heuristic: if your agent project is spending most of its effort on the reasoning step, the analysis suggests you are optimizing the part that was already small.

Four design questions the architecture answers

The repository frames Claude Code as answering four questions every production coding agent faces. Where does reasoning live? The README's answer is that the model reasons and the harness enforces, which is the 1.6% figure restated as a division of labour. How many execution engines? One queryLoop serves all interfaces: CLI, SDK, and IDE. Default safety posture? Deny-first, with the ordering deny > ask > allow and the strictest matching rule winning. Binding resource constraint? 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 system is decomposed into seven components (User, Interfaces, Agent Loop, Permission System, Tools, State and Persistence, Execution Environment) across five architectural layers. The count line in the README lists the scale of the surface area: 1,884 files, seven safety layers, five compaction stages, 54 tools, 27 hook events, four extension mechanisms, and seven permission modes. Those numbers are the reason a single while-loop is not the interesting part.

Safety: bounded analysis, an approval fallback, and a pre-trust window

Three findings in the key highlights are concrete enough to act on. First, bounded analysis with an approval fallback: in the legacy shell-parser path, more than 50 subcommands triggers an ask decision. That is a cap on automated parsing, with a human in the loop past the threshold, and it is the kind of limit most hand-rolled agents never define. Second, the README reports two CVEs that reveal a pre-trust window: extensions execute before the trust dialog appears. That ordering is the finding. If an extension runs before the user has been asked to trust anything, the dialog is a confirmation step rather than a gate. Third, the values section describes a 93% prompt-approval rate as evidence of approval fatigue, and says the response was to restructure boundaries rather than add more warnings. Read together, these point at a design stance: the safety layers are meant to hold when human vigilance does not. The repository does not give a remediation recipe for the pre-trust window, and the README does not claim the CVEs were fixed in a later version. If that matters to your deployment, check the version history yourself.

Getting at the material: what you clone and what you read

The repository has no releases, so there is no versioned artifact to install. You consume it as documents and images. The default branch is main, and the README points at a fixed set of paths: docs/architecture.md for the full deep dive (seven safety layers, a nine-step turn pipeline, five-layer compaction), docs/build-your-own-agent.md for the design guide, paper/Dive_into_Claude_Code.pdf as the archived April 2026 PDF, and assets/main_structure.png plus assets/layered_architecture.png for the two diagrams. The arXiv links are https://arxiv.org/abs/2604.14228 and https://arxiv.org/pdf/2604.14228v2, and the README notes the main PDF link opens arXiv v2 from July 2, 2026. There is a Chinese translation at README_zh.md. The README says the architecture sections describe v2.1.88, while the design guide and resource catalog extend through September 7, 2026. That split matters: the version-specific claims and the forward-looking guidance are not on the same footing, and the README is explicit about which is which. There are no install commands, no config keys, and no CLI to run, because the project is not software you operate.

Where it stops being the right tool

The analysis is pinned to a version. Claude Code is a moving target, and a source-level breakdown of v2.1.88 describes that build, not whatever is current when you read it. Anything you conclude about permission modes or compaction stages should be re-checked against the version you actually run. The repository also depends on being able to read the code it analyzes; where the codebase is minified, bundled, or changed in distribution, the same method would not transfer, and the README does not address that case. There is a second boundary worth naming. The key highlights include a cross-system comparison against OpenClaw and Hermes-Agent, and the repository also curates community projects and other agent projects. Those sections are catalog and comparison work, not the authors' source-level analysis, and they should be weighted differently. If you need a guarantee about a specific behaviour, the paper is evidence about one snapshot, not a specification.

The alternative, and the actual difference in approach

The natural alternative is the official Claude Code documentation and the product itself. The difference is in what each can tell you. Official documentation states intended behaviour: what a permission mode is for, what a hook event is supposed to fire on. This repository reads the implementation and reports what it finds, including things the documentation would not state, such as the ordering problem where extensions execute before the trust dialog, or the subcommand threshold in the legacy shell-parser path. That is the trade: documentation is authoritative about intent and stays current, while a source-level analysis is authoritative about a specific build and goes stale. A second alternative is to read the TypeScript yourself. At roughly 512K lines across about 1,900 files, that is the cost the repository is trying to save you, and the reading guide is organized to route you to the relevant part rather than the whole. Use the repository to decide where to look, then confirm against the code or the docs for anything you will depend on.

Licence and maintenance cost

The README's badge and the repository metadata disagree in a way you should resolve before reuse. The badge says CC-BY-NC-SA-4.0, while the repository's licence field is reported as NOASSERTION, meaning no standard licence was detected. The badge is the clearer signal, and if it is accurate, the terms include non-commercial use and share-alike obligations. That constrains copying the text or diagrams into commercial internal documentation, and share-alike can attach to derivatives. I am not giving legal advice; if you plan to redistribute any of this, check the LICENSE file in the repository directly. On maintenance: the last push is dated 2026-09-07, there are no releases, and the README says the design guide and resource catalog extend through September 7, 2026. So the catalog portion carries a visible freshness date, and the architecture portion is anchored to v2.1.88. Expect a document that ages in two different ways at once, and budget for re-verifying the version-specific claims rather than treating the repository as a maintained dependency.

Editorial conclusion

Adopt this repository if you are designing an agent harness and want a documented account of permission gating, compaction, and extension points before you commit to your own design. Skip it if you need runnable code: the repository is analysis and a resource catalog, not an agent you install. Verify two things first: that the described version, v2.1.88, still matches the Claude Code build you are reasoning about, and that the CC-BY-NC-SA-4.0 licence permits your intended reuse, since the non-commercial and share-alike terms are the binding constraint on copying any of it into internal documentation.

Official sources

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