Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems
Jiacheng Liu, Xiaohan Zhao, Xinyi Shang, Zhiqiang Shen
2026-04-17
Summary
This paper breaks down how Claude Code, an AI tool that can write and run code for you, is built. It doesn't just describe *what* it does, but *why* it was designed the way it was, connecting the design choices to core ideas about how AI should interact with humans.
What's the problem?
Building AI agents that can actually *do* things – like write code, access files, and use other tools – is really hard. You need to balance giving the AI enough power to be useful with keeping it safe and making sure it does what you intend. The paper tackles the problem of understanding the complex design choices made in Claude Code to achieve this balance.
What's the solution?
The researchers looked closely at the actual code of Claude Code and compared it to another similar AI system called OpenClaw. They found that Claude Code’s design is driven by five key ideas: keeping humans in control, ensuring safety, making sure things run reliably, boosting human abilities, and adapting to different situations. These ideas translate into specific features like a detailed permission system, a way to manage how much information the AI remembers, and different ways to add new abilities. The core of the system is a simple loop – ask the AI what to do, let it use tools, and repeat – but a lot of the work is in the systems *around* that loop.
Why it matters?
This research is important because it provides a detailed look under the hood of a powerful AI coding tool. By understanding the design choices and the reasoning behind them, we can build better and safer AI systems in the future. The comparison to OpenClaw also shows that there isn't one 'right' way to build these systems, and the best approach depends on how the AI will be used.
Abstract
Claude Code is an agentic coding tool that can run shell commands, edit files, and call external services on behalf of the user. This study describes its comprehensive architecture by analyzing the publicly available TypeScript source code and further comparing it with OpenClaw, an independent open-source AI agent system that answers many of the same design questions from a different deployment context. Our analysis identifies five human values, philosophies, and needs that motivate the architecture (human decision authority, safety and security, reliable execution, capability amplification, and contextual adaptability) and traces them through thirteen design principles to specific implementation choices. The core of the system is a simple while-loop that calls the model, runs tools, and repeats. Most of the code, however, lives in the systems around this loop: a permission system with seven modes and an ML-based classifier, a five-layer compaction pipeline for context management, four extensibility mechanisms (MCP, plugins, skills, and hooks), a subagent delegation mechanism with worktree isolation, and append-oriented session storage. A comparison with OpenClaw, a multi-channel personal assistant gateway, shows that the same recurring design questions produce different architectural answers when the deployment context changes: from per-action safety classification to perimeter-level access control, from a single CLI loop to an embedded runtime within a gateway control plane, and from context-window extensions to gateway-wide capability registration. We finally identify six open design directions for future agent systems, grounded in recent empirical, architectural, and policy literature.