# how-claude-code-works: an independent analysis of Claude Code's architecture

> how-claude-code-works is a repository of 16+ technical documents describing the internal architecture of Claude Code, covering the agent loop, context compression, tool execution, security model, and multi-agent coordination. The analysis is independent research, not official Anthropic documentation.

**Windy3f3f3f3f/how-claude-code-works** — Deep dive into Claude Code internals — architecture, agent loop, context engineering, and more. / 深入解析 Claude Code 源码：架构、Agent 循环、上下文工程、工具系统等

- Repository: https://github.com/Windy3f3f3f3f/how-claude-code-works
- Website: https://windy3f3f3f3f.github.io/how-claude-code-works/#/
- Stars: 3,696 · Forks: 710
- Language: Unknown
- License: MIT
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/windy3f3f3f3f-how-claude-code-works

## What this repository documents and who it is for

how-claude-code-works is a study of Claude Code, the AI coding agent developed by Anthropic. The repository originated when a snapshot of Claude Code's TypeScript source (described in the README as approximately 500,000 lines) became available in the community. The authors used Claude Code itself to help read and document the source, then published the resulting notes as a set of topic-specific documents.

The README states clearly that all content is independent research and inference, does not represent Anthropic's official design documentation, and makes no guarantee of correspondence with Claude Code's actual internal implementation. The project is aimed at developers who want to understand how a production-grade AI coding agent is built, particularly those working on their own agents or wanting to use Claude Code more effectively.

A companion project mentioned in the README, Claude Code From Scratch, provides a clean-room TypeScript and Python implementation of the same concepts in a step-by-step tutorial format.

## The agent loop: streaming, tool pre-execution, and fault recovery

The README describes three performance techniques that explain why Claude Code feels responsive despite the underlying model inference taking seconds per response.

First, full-chain streaming output: every token produced by the model is displayed immediately as it is generated. Second, tool pre-execution: the system begins executing tool calls (such as reading a file) while the model is still generating the output that includes that tool call. The README states this hides approximately one second of tool latency inside the five-to-thirty-second window while the model is generating. Third, a nine-stage parallel startup: independent initialization tasks run concurrently, compressing the critical path to approximately 235 milliseconds.

The README includes a Mermaid architecture diagram that maps the data flow at a high level:

```mermaid
graph TB
    User[用户输入] --> QE[QueryEngine 会话管理]
    QE --> Query[query 主循环]
    Query --> API[Claude API 调用]
    API --> Parse{解析响应}
    Parse -->|文本| Output[流式输出]
    Parse -->|工具调用| Tools[工具执行引擎]
    Tools --> ReadTool[读文件]
    Tools --> EditTool[编辑文件]
    Tools --> ShellTool[Shell 执行]
    Tools --> SearchTool[搜索工具]
    Tools --> MCPTool[MCP 工具]
    Tools -->|结果回注| Query
```

The diagram shows user input entering a QueryEngine that manages the session, which drives a main query loop that calls the Claude API, parses the response as either text output or tool calls, executes tools, and injects tool results back into the loop.

The README also describes seven types of continuation behavior in the agent loop, each corresponding to a different fault recovery path. Examples include silent context compression and retry when the context window is exceeded, and automatic retry with an expanded token limit when the model's output reaches the current limit. The README characterizes this as a design choice to absorb errors internally rather than surface them to the user.

## Context compression: the four-level pipeline

When a conversation grows long enough to threaten the context window limit, the README describes a four-level graduated compression process:

First, truncation: large blocks from older tool outputs in conversation history are cut. Second, deduplication: repeated content is removed at near-zero computational cost. Third, folding: inactive conversation segments are collapsed in place without discarding them, so they can be expanded later. Fourth, summarization: a sub-agent is invoked to summarize the entire conversation, used only when the earlier levels have not freed enough space.

Each level is applied only if necessary, stopping once sufficient space is recovered. After compression, the README states that the system automatically restores the content of the five most recently edited files so the model retains context about active work.

The README also documents prompt caching strategy and cache-break detection, though detailed mechanics fall in the third document of the series rather than the README summary.

## The seven-layer security model

The README documents a seven-layer defense system that controls what shell commands and file operations the agent can execute.

Workspace trust is the first layer: the first time Claude Code enters a directory, it asks for confirmation. If the directory is not trusted, custom hooks are disabled, blocking scripts pre-seeded in a malicious repository. Permission modes at the second layer restrict available operations by trust level. The third layer is a rule-based allow/deny/ask list matched against command patterns.

The fourth layer is described as the most technically detailed: a syntax-tree analysis of Bash commands using a parser (not regular expression matching) that applies 23 static security checks covering command injection, environment variable leakage, and special character attacks. The fifth layer applies input validation and path restriction logic per tool. The sixth layer uses process-level sandboxing on macOS (Seatbelt) and Linux (namespaces), combined with Git Worktree file isolation. The seventh layer presents a confirmation dialog for risky operations, with a 200-millisecond debounce to prevent accidental dismissal.

The README states that any single layer intercepting a command prevents execution, and that a human confirmation in layer seven always overrides the automated layers.

## Multi-agent architecture: subagents, coordinators, and swarms

The README describes three multi-agent patterns present in Claude Code. In the subagent pattern, the main agent delegates a task to a child agent and waits for the result. In the coordinator pattern, one agent acts as a pure orchestrator that can only dispatch tasks and cannot directly read files or write code. In the swarm pattern, multiple named agents communicate point-to-point and work independently.

To prevent conflicts when multiple agents modify the same files, the README states that each agent receives an isolated copy of the codebase via Git Worktree. This means each agent works on a separate branch without interfering with other agents working in parallel.

Later chapters in the repository (chapters 17 through 21, marked with a 'reverse-engineered after snapshot' indicator in the README) document newer features including the /goal and /loop commands for autonomous operation, the Auto Mode permission classifier, Dynamic Workflows for scripted multi-agent fan-out, and Agent Teams for cross-session agent coordination.

## Repository structure and how to read the documentation

The repository is organized as a docsify documentation site. The main index.html, _sidebar.md, and _navbar.md files configure the docsify reader. The docs/ directory contains individual numbered Markdown files for each topic. The en/ directory appears to hold English translations or alternate versions of some documents. The assets/ directory holds images and diagrams referenced by the documents.

The online readable version is hosted at windy3f3f3f3f.github.io/how-claude-code-works. The last push to the repository was on 2026-08-17.

Documents 1 through 16 are based on direct source code analysis from the snapshot. Documents 17 and later are described in the README as black-box reverse engineering through static strings analysis and network interception, since the snapshot predates those features. The README's table of contents marks newer chapters with a distinct icon to distinguish their methodology from the source-based earlier chapters.

The official Claude Code documentation published by Anthropic covers the tool from a user and configuration perspective rather than an internals perspective. That documentation is maintained directly by Anthropic and reflects the current released behavior, whereas how-claude-code-works reflects a specific snapshot with inference-based extensions for newer features.

## Conclusion

how-claude-code-works is useful for developers building AI coding agents who want to understand the production-grade patterns Claude Code uses, and for Claude Code users who want to understand why the tool behaves as it does. The disclaimer in the README is a real constraint: the analysis is independent research based on a snapshot of source code that leaked, not official Anthropic documentation, and newer features covered in later documents (chapters 17 onward) are based on reverse engineering rather than source inspection. Readers who need authoritative behavior guarantees should use the official Claude Code documentation instead.

## FAQ

### Is how-claude-code-works an official Anthropic project?

No. The README explicitly states the project is independent research and inference, does not represent Anthropic's official design, and carries no guarantee that it matches Claude Code's actual internal implementation. The project notes that 'Claude Code' is an Anthropic trademark and states the project has no affiliation with Anthropic.

### How are the documents in this repository organized?

The repository contains 16 or more numbered Markdown files in the docs/ directory, each covering a specific topic such as the agent loop, context compression, the tool system, or the security model. Documents 1 through 16 are based on direct source code analysis. Documents 17 onward are based on reverse engineering and are marked with a distinct indicator in the README's table of contents.

### What is the companion Claude Code From Scratch project?

The README mentions Claude Code From Scratch as a companion repository offering approximately 4300 lines of TypeScript and Python across 13 chapters that implement a Claude Code-inspired coding agent from scratch. The README describes it as a clean-room educational implementation rather than a reproduction of the actual Claude Code source.

## Sources

- [Issues](https://github.com/Windy3f3f3f3f/how-claude-code-works/issues)
- [License: MIT](https://github.com/Windy3f3f3f3f/how-claude-code-works/blob/main/LICENSE)
- [Project website](https://windy3f3f3f3f.github.io/how-claude-code-works/#/)
- [README](https://github.com/Windy3f3f3f3f/how-claude-code-works/blob/main/README.md)
- [Windy3f3f3f3f/how-claude-code-works on GitHub](https://github.com/Windy3f3f3f3f/how-claude-code-works)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/windy3f3f3f3f-how-claude-code-works