What it does This repo is a source-level architectural autopsy of Claude Code v2.1.88 — 1,884 TypeScript files, ~512K lines — plus a design guide for anyone building production AI agents. It maps the system’s values, safety layers, context compaction pipeline, and extension hooks, then compares against OpenClaw and Hermes-Agent.

The interesting bit The agent loop itself is a dead-simple ReAct while-loop. The other 98.4% of the codebase is deterministic infrastructure: permission gates with 7 graduated modes, 5-stage context compaction before every model call, 27 hook events, and recovery logic that retries, falls back, and degrades gracefully. The paper treats this as a design-space catalog — every choice (deny-first? append-only state? isolated subagents?) becomes a principle you can steal.

Key highlights

• 1.6% AI, 98.4% harness — the model reasons; the system enforces, recovers, and protects
• 7 safety layers with a deny-first posture, though shared performance constraints create a bypass path for commands with 50+ subcommands
• 5 compaction shapers run before every model call (Budget Reduction → Snip → Microcompact → Context Collapse → Auto-Compact)
• 4 patched CVEs reveal a pre-trust execution window where hooks and MCP servers run before the permission dialog appears
• 13 design principles trace from 5 human values (authority, safety, reliability, capability, adaptability) to concrete implementation

Caveats

• The analysis is pinned to v2.1.88; Claude Code ships frequently and internals shift
• Some security findings (CVE details, exact classifier behavior) are summarized rather than reproduced in full
• The “build your own agent” guide is aspirational — you’ll still need to write the 98.4%

Verdict Agent builders and security researchers should read this twice. If you’re just using Claude Code as an end user, the paper is overkill — but if you’re deciding whether to allow auto mode in your org, the permission-system deep dive is essential.