🤖 The Plumbing Behind Claude Code
Core Insight
A deep technical analysis of Claude Code's leaked source code revealing the engineering decisions behind building an AI coding tool that runs locally, touches user files, and burns their money.
1. Prompt Cache — The Biggest Cost Lever
The system prompt is split by a boundary marker: __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__
- Static (cacheable): Identity, coding rules, tool descriptions, tone — same across users/sessions
- Dynamic: Memory, MCP instructions, language, output style — per-session
Cache Break Detection: 77% of tool-related cache breaks come from tool descriptions changing (e.g., AgentTool embeds dynamic sub-agent lists). The fix: track why the cache breaks and fix the source.
Result: 90% cost reduction on cache hits.
2. Auto-Compaction with Circuit Breakers
Auto-compaction triggers at 13,000 buffer tokens. Before the circuit breaker: 1,279 sessions had 50+ consecutive failures, one session hit 3,272 failures — ~250K wasted API calls/day globally.
The Compaction Prompt: 9-section rigid template preserving:
- Primary request and intent
- Key technical concepts
- Files and code sections (full snippets)
- Errors and fixes
- All user messages — verbatim (not paraphrased)
3. Bash Security — 5 Layers of Defense
src/tools/BashTool/bashSecurity.ts — 2,592 lines of paranoia:
- Layer 1: Pattern matching — 13 categories of dangerous shell syntax (process substitution, $(), ${}, etc.)
- Layer 2: Zsh dangerous commands — zmodload, emulate, ztcp, etc.
- Layer 3: Tree-sitter AST parsing for nested quotes/escapes
- Layer 4: OS-level sandbox runtime
- Layer 5: Permission rules (enterprise → project → user → defaults)
Why This Matters
Understanding the plumbing behind Claude Code reveals what actually matters when building production AI tools:
- Cost control — Prompt caching gives 90% savings
- Structured summarization — Rigid templates beat naive truncation
- Circuit breakers — Any automated process can fail in a loop
- Security is layered — Regex alone is never enough