Inside Claude Code's Architecture: 500K Lines of TypeScript, 1.6% AI Logic

A research paper has made all of Claude Code's architecture details public, and the findings are more interesting than expected. The codebase spans almost 2,000 files and 500,000 lines of TypeScript, yet only 1.6% of the code handles actual AI decision logic. The rest is infrastructure -- a harness that creates the conditions for the model to decide well, rather than constraining its choices.

The Agent Loop

A user sends a prompt through any interface -- CLI, IDE, or SDK -- and they all hit the same agent loop. The core agent loop itself is deceptively simple and works the same way as every other coding agent out there: it just decides whether to keep calling a tool or not. The real complexity builds around it.

The Compaction Pipeline

Before every model call, five shapers run to keep the context window in check. Budget Reduction caps tool outputs. Snip trims older history. Microcompact does cache-aware compression. Context Collapse creates a read-time projection over the full history without touching it. And AutoCompact is the last resort -- a full model-generated summary. This pipeline is critical to keeping long sessions functional.

The Permission System

When the agent decides to call a tool, it goes through a permission system with seven independent layers. It could be a critical tool asking permission to be executed, plan mode ready to go, or an agent asking to accept changes. There is even an ML classifier for Auto mode, because Anthropic found that 93% of permission prompts get approved without even being read.

Tools and Execution

The agent sees up to 54 built-in tools -- file operations, shell commands, and WebFetch. MCP servers, plugins, and skills all merge into the same pool. The model just sees one flat list of things it can call and explore. The execution environment runs with optional shell sandboxing as a separate isolation layer that works independently of the permission system. A command can be permission-approved and still run inside a sandbox.

Session and Context Assembly

Sessions are stored as append-only transcripts on disk. When you resume, permissions are deliberately not restored -- every session starts from zero trust. Before every model call, the context window gets assembled from system prompt, CLAUDE.md instructions, auto memory, conversation history, and accumulated tool results. The model sees all of it at once after compaction.

Key Takeaways

• Only 1.6% of Claude Code's 500K-line TypeScript codebase handles actual AI decision logic
• Five compaction shapers run before every model call to manage the context window
• The permission system has 7 independent layers, with an ML classifier that handles 93% of auto-approved prompts
• The agent sees 54 built-in tools plus MCP servers, plugins, and skills in one flat list
• Sessions start from zero trust on resume -- permissions are deliberately not restored
• The architecture is a harness that creates conditions for good decisions, not one that constrains choices

Resources

• Claude Code Research Paper -- The public research paper detailing Claude Code's architecture
• Claude Code Source -- Claude Code's open-source repository