This content originally appeared on DEV Community and was authored by Charlie Li
Like many developers, I was curious about how Claude Code actually works under the hood. When the source maps for v2.1.88 leaked earlier this year, I decided to go through them systematically and document what I found.
It took a while — there's a lot of code — but the architecture turned out to be more interesting than I expected. Claude Code isn't just "Claude with tools bolted on." It's a carefully engineered agent system with some design decisions I genuinely didn't see coming.
Here are the highlights.
1. The "Read Before Edit" Guardrail Is Hard-Enforced
Claude Code won't let itself edit a file it hasn't read first. There's an internal fileReadTracker that records every file the model has seen during a session.
If the model tries to call the Edit tool on a file it hasn't read, the tool returns an error — not to you, but back to the model itself:
You must read the file before editing it.
This ensures you have the latest content and don't make edits based on stale or hallucinated content.
This is a simple but powerful guardrail. Without it, the model could confidently "fix" code it's never actually seen, based on what it thinks the file contains. With the tracker in place, every edit is grounded in real file content.
2. Context Management Is Surprisingly Sophisticated
When conversations get long, Claude Code doesn't just truncate old messages from the beginning. It runs a multi-pass compression system:
- Scoring: Each message gets an importance score. Tool results containing code rank higher than general conversation.
- Compression: Low-priority messages are summarized via a separate LLM call, preserving key information while reducing token count.
- Pinning: Recent messages (the "active window") are never compressed, ensuring the model always has full context for what it's currently working on.
This is why Claude Code can still reference something you mentioned 50+ messages ago in a long coding session. It's not magic — it's careful context engineering.
3. Every Shell Command Goes Through 23 Security Checks
Before any Bash command executes, it passes through a chain of regex-based security validators. These check for:
-
Dangerous commands:
rm -rf /,mkfs,ddtargeting disks - Directory traversal: attempts to escape the project directory
- Exfiltration patterns: piping sensitive data to external URLs
- Crypto mining: detecting mining-related commands
- Self-modification: attempts to edit Claude Code's own config files
-
Pipe chains: specifically blocking patterns like
curl | bash
The validators don't just block — they return structured error messages back to the model explaining why a command was rejected, so it can adjust its approach.
4. The Permission System Is a State Machine
Claude Code's permission system isn't a simple allow/deny check. It's a full state machine with transitions:
ask → allow → auto-allow
↓
deny
Permissions are tracked per tool, per directory, and per session. When you approve a tool once, the system may auto-approve similar uses in the same directory. But if you switch to a sensitive directory, it re-prompts.
The model can also escalate or de-escalate — if a normally-safe tool is being used in an unusual way, the system might step it back from auto-allow to ask.
5. Sub-Agent Coordination Uses a Coordinator Pattern
Claude Code can spawn sub-agents for parallel tasks — like searching multiple parts of a codebase simultaneously. The main agent acts as a coordinator:
- It decides what to delegate vs. handle directly
- Sub-agents run in isolated contexts (they can't see each other's work)
- Results flow back to the coordinator for synthesis
- There's a dedicated tool (
Agent) with different sub-agent types:Explorefor codebase search,Planfor architecture planning
This pattern lets Claude Code handle tasks that would blow through the context window if done sequentially.
The Full Picture
I ended up writing all of this into a book — 12 chapters covering the core loop, tool system, multi-agent coordination, context management, security architecture, MCP integration, and more.
The source code came from leaked source maps in the npm package — Anthropic accidentally included them in v2.1.88. I went through it systematically and documented the architecture in a way that's useful for anyone who wants to understand how a production AI agent is built, without having to read through the raw source code themselves.
Free Preview
Chapters 1 & 2 are completely free — no payment, no email required:
Full Book
- Claude Code from the Inside Out — $9.99 (use code LAUNCH50 for 50% off)
- 深入浅出 Claude Code — 中文版 (use code LAUNCH50CN for 50% off)
Happy to discuss any of the architecture details in the comments — there's a lot more in the book that I didn't cover here.
This content originally appeared on DEV Community and was authored by Charlie Li
Charlie Li | Sciencx (2026-04-18T18:38:48+00:00) What I Learned About Claude Code’s Architecture from the Leaked Source Maps. Retrieved from https://www.scien.cx/2026/04/18/what-i-learned-about-claude-codes-architecture-from-the-leaked-source-maps/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.