How Claude Code Works: A Source-Level Anatomy of a Production Coding Agent

What This Repository Actually Is

This is not a tool you run. It is a collection of 18 markdown documents, each a deep dive into a specific part of Claude Code's internal architecture. The repository was born from a practical problem: a 500,000-line TypeScript codebase leaked in snapshot form, and the authors needed a way to read it. Their solution was to use Claude Code itself to help write documentation while they studied the source. The result is a structured set of chapters that cover the agent loop, context engineering, tool systems, skills, memory, hooks, multi-agent modes, plan mode, code editing strategies, permission and security, system prompt design, user experience, minimal components, observability, and two newer features that came after the snapshot: /goal and /loop, plus Auto Mode. The intended audience is developers who want to build their own AI agent or who want to understand Claude Code more deeply. The README is explicit that this is independent research and inference, not an official Anthropic design document.

The Agent Loop and Why It Feels Fast

The core of Claude Code, according to the analysis, is a query main loop that sits between a QueryEngine for session management and the Claude API. The loop parses responses, streams text output, and dispatches tool calls to an execution engine. The repository claims three specific techniques make the system feel responsive. First, full streaming: every token is displayed as soon as it is generated, not after the model finishes. Second, tool pre-execution: when the model says it wants to read a file, the file is already being read. The system parses and executes tool calls while the model is still generating output, hiding about one second of tool latency inside the model's 5-30 second generation window. Third, a 9-stage parallel startup that keeps the critical path to roughly 235ms. These are concrete claims from the README, though they are based on source analysis, not on benchmarks you can reproduce from this repository alone.

Context Engineering: The 4-Level Compression Pipeline

A central chapter covers how Claude Code handles conversations that grow to millions of tokens. The repository describes a four-level progressive compression system. Level one is truncation: it cuts large blocks from old tool outputs. Level two is deduplication, which removes repeated content at near-zero cost. Level three is folding: it collapses inactive conversation segments without modifying the original content, so they can be expanded later. Level four is summarization, the last resort, where a sub-agent summarizes the entire conversation. Each level may free enough space that the next level never runs. After compression, the system automatically restores the last five edited files to prevent the model from losing track of what it was doing. The README also mentions prompt caching strategies and cache break detection, which are detailed in the context engineering chapter. This is the kind of design detail that a typical demo agent never considers, and it is the strongest argument for reading this repository.

The 7-Layer Security Model and the 200ms Race

The repository dedicates a full chapter to permission and security, describing a seven-layer defense that includes workspace trust, permission modes, rule-based allow/deny/ask lists, and a Bash command analysis that uses a syntax tree, not regular expressions, to understand what a shell command actually does. That AST analysis runs 23 static checks covering command injection, environment variable leaks, and special character attacks. The layers also include tool-level validation, sandboxing with macOS Seatbelt or Linux namespaces, Git Worktree isolation, and finally user confirmation for dangerous operations. The confirmation mechanism is described as a race: the user dialog competes with hooks and an LLM classifier, with a 200ms debounce to prevent accidental clicks. Once the user acts, human intent always wins. This design directly addresses the question of how an agent can run commands on your machine without letting a malicious repository pre-scripted hook execute. The repository argues that no single layer is sufficient, which is a reasonable position given that the agent has shell access.

Tool Coordination and Multi-Agent Isolation

The tool system chapter explains how dozens of built-in tools, plus third-party MCP tools, all follow the same interface specification. That uniformity means third-party tools go through the same execution pipeline, the same security checks, and the same permission controls as built-in ones. Read-only tools run in parallel automatically, while write operations run serially, so developers do not have to manage concurrency manually. When a tool output exceeds 100K characters, it is written to disk and the model receives only a summary and file path. The multi-agent chapter covers three modes: sub-agents that report back to a main agent, a coordinator that only assigns tasks and cannot read or write code itself, and Swarm where named agents communicate peer-to-peer. To prevent conflicts when multiple agents edit the same file, the system gives each agent its own Git Worktree. This is a practical answer to the concurrency problem that any multi-agent framework must solve.

How to Use This Repository

The repository has no installation steps because it is documentation. You read it online at the GitHub Pages site or in the markdown files under docs/. The README lists 18 chapters with titles like 01-overview.md, 02-agent-loop.md, and 03-context-engineering.md. Each file corresponds to a row in the table. The repository also links to a companion project called Claude Code From Scratch, which is a clean-room educational implementation in about 4300 lines of TypeScript and Python, with a 13-chapter tutorial. If you want to build your own agent, that companion project is the practical counterpart to this analysis. The README suggests that the authors used Claude Code itself to help write the documentation, so reading the chapters is a way to see how an AI-assisted analysis of a large codebase can be structured.

Limitations and What to Verify Before Trusting It

The repository has several limitations you should keep in mind. First, the analysis is based on a leaked snapshot of the source code, not on an official release. The README itself says the content is independent research and does not guarantee consistency with the real internals. Second, the analysis covers features that were added after the snapshot, such as /goal and /loop, using black-box reverse engineering methods like static strings and plaintext proxy capture. That means those sections are inferences from observed behavior, not from source code. Third, the repository is a study guide, not a reference manual. It explains design decisions, but it does not provide a complete API reference or configuration guide for Claude Code. If you need to configure Claude Code for your own use, the official documentation is the right source. Finally, the repository is written primarily in Chinese, with an English README link, so English-only readers may find some chapters less accessible if the translations are incomplete.

Alternatives and How They Differ

The most direct alternative is the companion project, Claude Code From Scratch, which provides a clean-room implementation of a coding agent in TypeScript and Python. That project is code you can run and modify, whereas this repository is analysis you read. If you want to learn by building, the companion project is the better starting point. Another alternative is to read the actual Claude Code source code if you have access to it, but the repository exists precisely because the source is 500,000 lines and hard to navigate. A third alternative is to use official Anthropic documentation for Claude Code, which describes features and configuration but does not explain internal mechanisms. The difference is that this repository focuses on why and how the internals work, while official docs focus on what you can do with the tool.

Maintenance, License, and the Bottom Line

The repository is MIT-licensed, so you can reuse the text and structure for your own educational purposes, as long as you preserve the license notice. The README does not mention any contribution guidelines or a roadmap, but the last push date is August 2026, which suggests the authors are actively updating it to cover new Claude Code features. The maintenance cost for you as a reader is low: the content is static markdown, so there is no dependency to update. The risk is that the analysis may become stale as Claude Code evolves, especially for the reverse-engineered features like /goal and /loop. The repository is not affiliated with Anthropic and does not distribute any Anthropic source code, so you are not getting the actual implementation, only a description of it. For a developer who wants to understand the architecture of a production coding agent, this repository offers a structured path through a codebase that would otherwise be overwhelming.

Editorial conclusion

Adopt this repository if you are a developer who wants to understand how a production-grade coding agent is built, especially the agent loop, context compression, and permission systems. It is also useful for Claude Code users who want to understand features like /goal and /loop. Do not use it as an official reference; the README explicitly states it is independent research and may not match real internals. Before relying on any specific claim, verify it against the linked docs or the companion clean-room project, since the analysis is based on a leaked snapshot and black-box reverse engineering, not on official source. The repository is MIT-licensed, so you can reuse the text, but the trademark and code from Anthropic are not included. Check the last push date (August 2026) to see if the content is current with Claude Code updates.

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. Windy3f3f3f3f/how-claude-code-works on GitHub