How Claude Code Works
Deep-dive architecture analysis of Claude Code: agent loop, context engineering, tooling, and security.
- Source repo
- Windy3f3f3f3f/how-claude-code-works
- Stars
- ★ 3.8k
- Last updated
- 2mo ago
- License
- MIT
- FA score
- 0/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificClaude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers wanting to learn production-grade coding agent architecture can read the main loop and context engineering chapters.
- Not a fit if
- Users who want to run Claude Code itself — this is source analysis, not a working tool
- Teams needing authoritative official internals — it is independent research, unaffiliated with Anthropic
- Readers wanting a quick skim — the docs are dense with a steep learning curve
- Source review
- 0/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
how-claude-code-works is an in-depth architecture study of Anthropic's Claude Code, based on a snapshot of its 500k-line TypeScript source. The repository offers 21 topical documents covering the system main loop, context compaction, tool system, permission security, multi-agent collaboration, and more. It is bilingual (Chinese and English) with a Docsify online site and a companion project, claude-code-from-scratch. It's an unofficial educational project, disclaiming any affiliation with Anthropic.
This repository performs reverse engineering analysis of Claude Code's internals. It reads the source snapshot, extracts architectural decisions, and produces documentation. Documents use Mermaid diagrams to describe system flows and provide specific numbers (e.g., 235ms startup, 7-layer defense). The companion project claude-code-from-scratch offers TypeScript and Python implementations of about 4300 lines. The repository itself does not execute code but provides educational analysis.
- Developers wanting to learn production-grade coding agent architecture can read the main loop and context engineering chapters.
- Users aiming to deeply customize Claude Code can study Hooks, memory, and skills system chapters.
- Developers interested in AI safety can explore the 7-layer defense in the permission and security chapter.
- Students building a coding agent from scratch can follow the claude-code-from-scratch project.
- Users evaluating Claude Code's newer features (e.g., /goal, Auto Mode) can refer to black-box reverse engineering sections.
How do you install or deploy this agent?
This repository is a documentation project, not traditional software. To run the docs site locally: git clone https://github.com/Windy3f3f3f3f/how-claude-code-works.git. Install Node.js and Docsify: npm i docsify-cli -g.
How do you use this agent?
cd how-claude-code-works, run docsify serve docs, then open http://localhost:3000 in your browser. Alternatively, read online at https://windy3f3f3f3f.github.io/how-claude-code-works/#/.
What are this agent's strengths and limitations?
- Based on real source snapshot, offers concrete architectural details and metrics (e.g., 7-layer defense, 4-level compaction) rather than generalities.
- Bilingual (Chinese primary), with 21 in-depth chapters, beneficial for Chinese-speaking developers.
- Companion from-scratch project enables hands-on learning.
- Analysis is based on v2.1.6x snapshot and may be outdated; newer features rely on black-box reverse engineering with uncertain accuracy.
- Unofficial and disclaimed; may not match actual Claude Code internals.
- Requires technical background; documentation is dense and may have a steep learning curve.
How does this agent compare with similar options?
The repository does not mention specific alternatives, but it can be compared to architecture analyses of other agent frameworks like LangChain or AutoGPT.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| How Claude Code Works This agent | 0 · Major gaps | Web appFree | ★ 3.8k | 2mo ago | — | Claude Code |
| mu Coding Agent | 77 · Good | Desktop appFree + model costs | ★ 525 | 3d ago | TypeScript | — |
| Claude Reviews Claude Code | 46 · Major gaps | Web appFree | ★ 1.6k | 6mo ago | — | — |
| Claude Code From Scratch | 60 · Some gaps | CLIFree + model costs | ★ 2.8k | 3mo ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: The repository is an educational architecture analysis, containing no executable code or tools, so there is no actual implementation of least privilege, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, or source attribution. Deduction: These criteria are not applicable, but per rules, no evidence supports any score, hence all 0.
Evidence: The repository is a documentation collection, with no executable code or tests, so self-consistency, dependency availability, and failure messages cannot be assessed. Deduction: No actual implementation to verify these criteria.
Evidence: README clearly identifies target audiences and scenarios, but the repository itself is not a runnable Agent, so capability boundaries, trigger precision, and environment fit are not implemented. Deduction: Documentation describes Claude Code's capabilities, not this repository's product, so these criteria are not applicable.
Evidence: Clear documentation structure, MIT license, update log, and contributor list exist, but missing install notes (not an installable product), naming stability (no API), examples and FAQ (docs but no FAQ), known limitations (roadmap but not explicit), versioning changelog (update log but no formal versions). Deduction: Partially satisfied, but many criteria are not applicable or evidence is insufficient.
Evidence: Documentation provides in-depth technical analysis, offering marginal value to target audience, but output usability (no actual output) and cost-benefit (no execution cost) cannot be assessed. Deduction: As a documentation project, these criteria are not applicable.
Evidence: README claims analysis based on source snapshot and distinguishes inference from facts, but lacks specific citations or cross-validation sources. Deduction: Lack of traceable references and external verification, hence low scores.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- This repository is a documentation project, not an executable Agent product.
- Analysis is based on leaked source snapshots, may be inaccurate or outdated, and lacks specific citations.
- Unverified publisher identity; treat the analysis with caution.