Model or dataset
Windy3f3f3f3f/how-claude-code-works avatar
Windy3f3f3f3f/how-claude-code-works

how-claude-code-works reads a leaked snapshot, then switches to black box capture

Deep dive into Claude Code internals: architecture, agent loop, context engineering, and more.

3,830 stars723 forksUnknownMIT

At a glance

What is it?
Windy3f3f3f3f/how-claude-code-works is a documentation site that reverse engineers Claude Code from a leaked 500,000 line TypeScript snapshot, with 21 chapters covering the agent loop, context compaction, tool execution and permissions. Later chapters move past the snapshot to string scraping and plaintext capture of features added after the leak.
Who is it for?
This project suits a developer who wants to understand why an agentic coding tool behaves the way it does, and who reads architecture notes better than vendor documentation. It does not suit anyone needing an official specification, since the project states its own conclusions are independent research and may not match the real implementation.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 90 days ago.
What is it written in?
GitHub does not report a main language for this repository.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Windy3f3f3f3f/how-claude-code-works3,830 ★ · +219
Star history
Repository2026-09-102026-11-15
Windy3f3f3f3f/how-claude-code-works3.6k3.8k

219 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The published site is a static bundle with two language trees

The repository is a documentation site rather than a program, and the root entries show how it is assembled. There is README.md and README_EN.md for the two languages, a docs directory holding the numbered chapters, an en directory for the English tree, and the four files a docs style site needs: index.html, _sidebar.md, _navbar.md and _coverpage.md. The .nojekyll file and the assets directory complete the static bundle, and the live copy is published at a GitHub Pages address ending in a hash route. Chapters are numbered by topic rather than by difficulty, from 01-overview through 20-agent-teams, and the navigation table lists 21 entries in total. Because the chapters are Markdown files, the same source produces both the website and the repository view, which is why a reader can read online or clone the text.

The starting point is a snapshot that leaked in late March

The premise is stated plainly in the opening note. A snapshot of roughly 500,000 lines of TypeScript spread through the developer community, which the authors describe as the first opportunity to look at a production coding agent running on millions of machines. They also frame their own motivation: reading a codebase that large is hard, so the approach was to read it together with Claude Code itself, letting it write documentation while they read source, and then to publish that documentation. The disclaimer is as explicit as the premise. The project calls itself an educational architecture analysis, states that its conclusions come from independent research and reasoning, says they are not Anthropic's official design and are not guaranteed to match the real implementation, notes that Claude Code is a trademark of Anthropic, and records that the project has no affiliation and distributes no Anthropic source code.

Perceived speed comes from three separate mechanisms

The first design question the notes attack is why the tool feels fast when model inference itself takes tens of seconds. Three answers are given. The first is streaming across the whole chain: every generated token is displayed immediately, and the path from API call to terminal rendering is streamed end to end rather than buffered. The second is tool pre-execution. When the model says it wants to read a file, that read has already started, so parsing and executing tool calls overlaps with generation and hides about one second of tool latency inside the five to thirty second window in which the model is still producing tokens. The third is a nine stage parallel startup, where unrelated initialisation tasks run at the same time and the critical path is reduced to about 235 milliseconds. Three unrelated mechanisms, and the perceived speed is the sum of them rather than any one optimisation.

Seven continue sites absorb failures the user never sees

Error handling is described as silent by design, on the premise that recoverable errors should not reach the person using the tool. Two examples are given. When a conversation outgrows the context window, the context is compacted quietly and the request retried without an error dialog. When the token output limit is reached, the system raises the budget from 8K to 64K and retries. Underneath those examples sits the structure: the agent loop defines seven different continue strategies, each mapped to one failure recovery path, which is why a run rarely stops with a visible failure. The compaction pipeline behind the first example has four levels applied in order: trimming large blocks such as old tool output from history, removing duplicates at close to zero cost, folding inactive conversation segments without modifying the original text so they can be expanded again, and summarising the whole conversation with a sub agent as the last resort. Any level may free enough space that the later ones never run.

After compaction, the last five edited files come back

One detail sits at the end of the compaction section and explains a lot of behaviour. After the pipeline finishes, the system automatically restores the contents of the five most recently edited files, so the model does not lose what it was just working on. Combined with the folding level, which keeps the original text intact, this is a deliberate design against amnesia rather than a simple truncation. The restoration and skill reactivation behaviour is what one of the chapters documents in detail, alongside prompt cache strategy and cache break detection, which is the point at which a cached prefix stops being reusable and the cost model changes. The same chapter group also covers memory, where four memory types are described with a closed taxonomy, semantic recall runs on a smaller model with asynchronous prefetch, an agent extracts memories in the background, and defences exist against memory drift.

Seven layers of defence, with a syntax tree check in the middle

Because the tool runs commands on your machine, the security design is a seven layer stack rather than one confirmation dialog. The layers, in order: workspace trust, where entering a directory requires confirming trust and an untrusted project has all its custom hooks disabled, which blocks scripts pre-planted in a hostile repository; permission modes that limit what a given trust level may do; rule matching through allow, deny and ask lists keyed to command patterns; deep analysis of Bash commands using a syntax tree rather than regular expressions, with 23 static security checks covering command injection, environment variable leaks and special character attacks; per tool safety with input validation and its own logic, such as blocking dangerous paths in the file edit tool; sandboxing and isolation through a process level sandbox, named macOS Seatbelt or Linux namespaces, plus Git Worktree file isolation; and user confirmation, which races against hooks and an LLM classifier, carries a 200 millisecond debounce, and always yields to a human decision once the user acts.

One interface for built-in tools and MCP tools, with parallel reads

The tool chapter's claim is that every tool follows the same interface specification, whether it reads a file, writes a file, runs a shell command, searches, or comes from a third party through MCP. The consequence is that a third party tool goes through exactly the same execution pipeline and receives exactly the same safety checks and permission control as a built-in one, with no separate hardening path to get wrong. Concurrency is handled by tool class rather than by the caller: read only tools are executed in parallel automatically and write operations are serialised automatically, so nobody has to manage the concurrency by hand. Output size has its own rule, since tool output beyond 100K characters is written to disk and the model receives a summary plus a file path, reading the full text only when it needs to. The tool chapter also documents six MCP transports, a connection state machine and OAuth 2.0 with PKCE.

Three multi-agent modes, each isolated with its own worktree

Coordination is split three ways. A subagent mode dispatches tasks from the main agent and waits for results. A coordinator mode is pure command: the coordinator can only assign work and cannot read files or write code itself, which enforces a division of labour by construction rather than by instruction. A swarm mode lets several named agents talk point to point and work independently. Whatever the mode, conflicts are avoided with Git Worktree, giving each agent its own copy of the code, which is the same mechanism used for file isolation in the sandbox layer. Later chapters extend this past the snapshot. Agent teams describe moving from master and slave orchestration to peer grouping, with SendMessage addressing, a team treated as a task list, shared memory and artifacts, and a cross session rule that another session does not carry the user's authority, so a forwarded action cannot launder a permission. Dynamic workflows replace the model as coordinator with a deterministic script that fans out dozens or hundreds of subagents.

Editorial conclusion

This project suits a developer who wants to understand why an agentic coding tool behaves the way it does, and who reads architecture notes better than vendor documentation. It does not suit anyone needing an official specification, since the project states its own conclusions are independent research and may not match the real implementation. Before treating any chapter as fact, check the date each page was last verified against, and read the disclaimer: the work is educational and no Anthropic source code is redistributed.

Frequently asked questions

What is how-claude-code-works and where does its information come from?

It is a documentation site with numbered chapters that reverse engineer Claude Code, starting from a snapshot of about 500,000 lines of TypeScript that spread through the developer community. The project states its conclusions are independent research, are not Anthropic's official design and are not guaranteed to match the real implementation.

How does how-claude-code-works explain why the tool feels fast?

With three mechanisms: streaming the whole path from API call to terminal rendering, pre-executing tool calls while the model is still generating so about one second of tool latency is hidden, and a nine stage parallel startup that brings the critical path to about 235 milliseconds.

What happens when the context window fills up in the system how-claude-code-works describes?

The context is compacted quietly and the request retried rather than raising an error, through a four level pipeline: trimming old large tool output, removing duplicates, folding inactive segments without changing the original text, and summarising with a sub agent as the last resort. The five most recently edited files are then restored automatically.

How does the analysed system stop the model from running dangerous commands?

With seven layers: workspace trust, permission modes, allow and deny and ask rule lists, syntax tree analysis of Bash commands with 23 static checks, per tool input validation, a process sandbox using macOS Seatbelt or Linux namespaces with Git Worktree isolation, and a user confirmation that races hooks and an LLM classifier with a 200 millisecond debounce.

Does how-claude-code-works cover features added after the leaked snapshot?

Yes. Later chapters are marked as reverse engineered after the snapshot, covering /goal and /loop with reproducible methods based on static strings and plaintext capture, Auto Mode where permissions move to a machine learning classifier deciding per action, dynamic workflows driven by deterministic scripts, and agent teams with a cross session authority rule.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/windy3f3f3f3f-how-claude-code-works.svg)](https://hysenlabs.com/projects/windy3f3f3f3f-how-claude-code-works)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/windy3f3f3f3f-how-claude-code-works.svg)](https://hysenlabs.com/projects/windy3f3f3f3f-how-claude-code-works)

Was this useful?