Summary
- • Researchers analyzed Claude Code's publicly available TypeScript source to map its full architecture
- • Core execution is a simple while-loop; real complexity lives in permission, context, and extensibility layers
- • Five human values and thirteen design principles traced to specific implementation choices
- • Comparison with OpenClaw shows the same design questions yield different answers by deployment context
Details
Claude Code architecture analyzed from its publicly available TypeScript source
Researchers examined the publicly available Claude Code codebase to extract architectural patterns, design principles, and the values motivating them — providing a structured look at a production AI agent system without relying on undisclosed internals.
Core loop is a while-loop; surrounding systems carry real complexity
The fundamental execution model is minimal — call the model, run tools, repeat — but five surrounding subsystems encode most architectural decisions: a 7-mode permission system with ML classifier, 5-layer context compaction pipeline, 4 extensibility mechanisms, subagent delegation with worktree isolation, and append-oriented session storage.
Five human values and thirteen design principles mapped to implementation choices
The values — human decision authority, safety and security, reliable execution, capability amplification, and contextual adaptability — are each traced to concrete architectural decisions, giving practitioners a framework for understanding why the system is structured as it is.
Claude Code vs. OpenClaw comparison reveals how deployment context shapes architecture
Where Claude Code uses per-action safety classification and a single CLI loop, OpenClaw uses perimeter-level access control and an embedded runtime within a gateway control plane. The contrast demonstrates that optimal agent architecture depends on whether the agent is a developer tool versus an embedded service.
Six open design directions identified for future agent systems
The directions are grounded in empirical, architectural, and policy literature, positioning the paper as a research agenda for the field rather than purely a descriptive analysis of existing systems.
Same recurring design questions appear across all agent systems
The authors argue agent architects face a finite set of recurring questions — around safety enforcement, context management, capability extension, and delegation — and that surfacing these explicitly enables more principled design and cross-system comparison.
Research = study findings, Tech Info = system mechanics, Market Impact = comparative/competitive implications, Insight = analytical argument
What This Means
For engineers building agent systems, this paper provides a reusable analytical vocabulary — mapping human values to design principles to concrete implementation choices — that makes architectural trade-offs explicit rather than implicit. The comparative Claude Code vs. OpenClaw analysis is particularly actionable: it shows that safety enforcement, context management, and capability extension each have multiple valid solutions, and the right choice depends on whether the agent runs as a developer CLI tool or an embedded gateway service. Teams designing new agent systems can use the paper's thirteen design principles and six open directions as a structured checklist and research agenda rather than starting from first principles.