{ "@context": { "@vocab": "http://schema.org/", "code": "http://schema.org/code", "softwareSourceCode": "http://schema.org/SoftwareSourceCode", "softwareApplication": "http://schema.org/SoftwareApplication", "author": "http://schema.org/author", "publisher": "http://schema.org/publisher", "hasPart": "http://schema.org/hasPart", "Question": "http://schema.org/Question", "Answer": "http://schema.org/Answer", "DefinedTerm": "http://schema.org/DefinedTerm", "DefinedTermSet": "http://schema.org/DefinedTermSet", "HowTo": "http://schema.org/HowTo", "HowToStep": "http://schema.org/HowToStep", "CreativeWork": "http://schema.org/CreativeWork", "Person": "http://schema.org/Person", "Organization": "http://schema.org/Organization" }, "@type": "CreativeWork", "name": "Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems", "author": [ { "@type": "Person", "name": "Jiacheng Liu", "affiliation": { "@type": "Organization", "name": "VILA Lab, Mohamed bin Zayed University of Artificial Intelligence" } }, { "@type": "Person", "name": "Xiaohan Zhao", "affiliation": { "@type": "Organization", "name": "VILA Lab, Mohamed bin Zayed University of Artificial Intelligence" } }, { "@type": "Person", "name": "Xinyi Shang", "affiliation": [ { "@type": "Organization", "name": "VILA Lab, Mohamed bin Zayed University of Artificial Intelligence" }, { "@type": "Organization", "name": "University College London" } ] }, { "@type": "Person", "name": "Zhiqiang Shen", "email": "mailto:Zhiqiang.Shen@mbzuai.ac.ae", "affiliation": { "@type": "Organization", "name": "VILA Lab, Mohamed bin Zayed University of Artificial Intelligence" } } ], "publisher": { "@type": "Organization", "name": "Mohamed bin Zayed University of Artificial Intelligence" }, "datePublished": "2026-04-14", "url": "https://github.com/VILA-Lab/Dive-into-Claude-Code", "codeRepository": "https://github.com/VILA-Lab/Dive-into-Claude-Code", "about": "Architectural design and analysis of Claude Code, a production AI coding agent system, with comparison to OpenClaw, an open-source multi-channel AI assistant gateway.", "abstract": "This study analyzes Claude Code's architecture by source-level examination of its TypeScript codebase, identifying five human values and thirteen design principles that shape its design. It contrasts Claude Code with OpenClaw, highlighting how deployment context influences architectural choices. The paper identifies six open design directions for future AI agent systems.", "articleBody": "Claude Code is an agentic coding tool that runs shell commands, edits files, and calls external services autonomously. It uses a simple while-loop agent core surrounded by layered subsystems for permissions, context management, extensibility, delegation, and persistence. The system prioritizes human decision authority, safety, reliable execution, capability amplification, and contextual adaptability. It employs a deny-first permission system with seven modes, a five-layer context compaction pipeline, four extensibility mechanisms (MCP, plugins, skills, hooks), subagent delegation with isolated contexts, and append-only session storage. The architecture contrasts with OpenClaw, which is a persistent multi-channel gateway emphasizing perimeter-level access control and long-term memory. The paper discusses architectural trade-offs, value tensions, and open questions including observability gaps, long-term capability preservation, and governance.", "hasPart": [ { "@type": "DefinedTermSet", "name": "Design Principles", "description": "Thirteen design principles operationalizing five core human values in Claude Code's architecture.", "hasDefinedTerm": [ { "@type": "DefinedTerm", "name": "Deny-first with human escalation", "description": "Unrecognized actions are denied by default and escalated to the human for approval, ensuring safety and authority." }, { "@type": "DefinedTerm", "name": "Graduated trust spectrum", "description": "Users traverse a spectrum of permission levels over time, balancing authority and adaptability." }, { "@type": "DefinedTerm", "name": "Defense in depth with layered mechanisms", "description": "Multiple overlapping safety layers protect the system, enhancing safety, authority, and reliability." }, { "@type": "DefinedTerm", "name": "Externalized programmable policy", "description": "Policies are configurable via external files and lifecycle hooks, supporting safety, authority, and adaptability." }, { "@type": "DefinedTerm", "name": "Context as scarce resource with progressive management", "description": "Context window is managed via a graduated pipeline of compaction strategies to optimize reliability and capability." }, { "@type": "DefinedTerm", "name": "Append-only durable state", "description": "Session state is stored as append-only logs to preserve reliability and authority." }, { "@type": "DefinedTerm", "name": "Minimal scaffolding, maximal operational harness", "description": "The system invests in operational infrastructure allowing the model to reason freely, enhancing capability and reliability." }, { "@type": "DefinedTerm", "name": "Values over rules", "description": "Contextual judgment backed by deterministic guardrails is preferred over rigid decision procedures." }, { "@type": "DefinedTerm", "name": "Composable multi-mechanism extensibility", "description": "Multiple extension mechanisms at different context costs enable capability and adaptability." }, { "@type": "DefinedTerm", "name": "Reversibility-weighted risk assessment", "description": "Oversight varies by action risk, with lighter checks for reversible or read-only actions." }, { "@type": "DefinedTerm", "name": "Transparent file-based configuration and memory", "description": "User-visible, version-controllable files are used for configuration and memory to support adaptability and authority." }, { "@type": "DefinedTerm", "name": "Isolated subagent boundaries", "description": "Subagents operate in isolated contexts with rebuilt permissions to ensure reliability, safety, and capability." }, { "@type": "DefinedTerm", "name": "Graceful recovery and resilience", "description": "The system silently recovers from errors and reserves human attention for unrecoverable situations." } ] }, { "@type": "HowTo", "name": "How to Execute a Turn in Claude Code", "description": "Stepwise process of handling a user request in Claude Code's agent loop.", "step": [ { "@type": "HowToStep", "position": 1, "name": "Settings resolution", "description": "Initialize immutable parameters including system prompt, user context, permission callback, and model configuration." }, { "@type": "HowToStep", "position": 2, "name": "Mutable state initialization", "description": "Create a single State object to store mutable state across iterations." }, { "@type": "HowToStep", "position": 3, "name": "Context assembly", "description": "Retrieve messages from the last compact boundary forward, ensuring summaries replace original messages." }, { "@type": "HowToStep", "position": 4, "name": "Pre-model context shaping", "description": "Apply five sequential shapers: budget reduction, snip, microcompact, context collapse, and auto-compact." }, { "@type": "HowToStep", "position": 5, "name": "Model call", "description": "Stream model response with assembled messages, system prompt, tool set, and configuration." }, { "@type": "HowToStep", "position": 6, "name": "Tool-use dispatch", "description": "Parse tool_use blocks and route requests through the permission system." }, { "@type": "HowToStep", "position": 7, "name": "Permission gate", "description": "Evaluate each tool request against deny-first rules, permission modes, and ML classifier." }, { "@type": "HowToStep", "position": 8, "name": "Tool execution and result collection", "description": "Execute approved tools, collect results, and add tool_result messages to the conversation." }, { "@type": "HowToStep", "position": 9, "name": "Stop condition check", "description": "Terminate turn if no tool_use blocks remain or max turns/context limits are reached." } ] }, { "@type": "HowTo", "name": "How to Manage Permissions in Claude Code", "description": "Process for evaluating and enforcing tool invocation permissions.", "step": [ { "@type": "HowToStep", "position": 1, "name": "Pre-filtering", "description": "Remove blanket-denied tools from the model's view before runtime." }, { "@type": "HowToStep", "position": 2, "name": "PreToolUse hooks", "description": "Allow hooks to deny, ask, or modify tool inputs before permission evaluation." }, { "@type": "HowToStep", "position": 3, "name": "Deny-first rule evaluation", "description": "Evaluate permission rules with deny rules taking precedence over allow rules." }, { "@type": "HowToStep", "position": 4, "name": "Permission handler branching", "description": "Handle permission requests differently in coordinator, swarm, speculative classifier, or interactive modes." }, { "@type": "HowToStep", "position": 5, "name": "User interaction or automated decision", "description": "Prompt user for approval or rely on ML classifier or automated resolution." }, { "@type": "HowToStep", "position": 6, "name": "Denial as routing signal", "description": "Treat denials as signals for the model to revise its approach rather than hard stops." } ] }, { "@type": "Question", "name": "What are the core human values motivating Claude Code's architecture?", "acceptedAnswer": { "@type": "Answer", "text": "The five core human values are: Human Decision Authority, Safety, Security, and Privacy, Reliable Execution, Capability Amplification, and Contextual Adaptability." } }, { "@type": "Question", "name": "How does Claude Code manage its context window?", "acceptedAnswer": { "@type": "Answer", "text": "Claude Code uses a five-layer compaction pipeline including budget reduction, snip, microcompact, context collapse, and auto-compact, combined with a four-level CLAUDE.md hierarchy and LLM-based memory scanning." } }, { "@type": "Question", "name": "What is the default safety posture in Claude Code?", "acceptedAnswer": { "@type": "Answer", "text": "The default safety posture is deny-first with human escalation, where deny rules override ask rules, which override allow rules, and unrecognized actions are escalated to the user." } }, { "@type": "Question", "name": "How does Claude Code handle extensibility?", "acceptedAnswer": { "@type": "Answer", "text": "Claude Code supports four extensibility mechanisms: MCP servers for external tool integration, plugins for packaging and distribution, skills for domain-specific instructions, and hooks for lifecycle interception." } }, { "@type": "Question", "name": "What is the role of subagents in Claude Code?", "acceptedAnswer": { "@type": "Answer", "text": "Subagents operate in isolated contexts with rebuilt permission contexts and independent tool sets, delegating tasks such as exploration, planning, or verification, and return summary-only results to the parent." } }, { "@type": "Question", "name": "How does Claude Code persist session state?", "acceptedAnswer": { "@type": "Answer", "text": "Session transcripts are stored as mostly append-only JSONL files, preserving conversation history, tool results, and compaction boundaries. Session-scoped permissions are not restored on resume for safety." } }, { "@type": "Question", "name": "What are the main architectural differences between Claude Code and OpenClaw?", "acceptedAnswer": { "@type": "Answer", "text": "Claude Code is an ephemeral CLI coding harness with per-action deny-first safety evaluation and a single agent loop, while OpenClaw is a persistent multi-channel gateway with perimeter-level access control, multi-agent routing, and embedded agent runtimes." } }, { "@type": "Question", "name": "What tensions exist between the core values in Claude Code's design?", "acceptedAnswer": { "@type": "Answer", "text": "Tensions include Authority vs. Safety (approval fatigue vs. protection), Safety vs. Capability (performance vs. defense depth), Adaptability vs. Safety (extensibility vs. attack surface), Capability vs. Adaptability (proactivity vs. disruption), and Capability vs. Reliability (velocity vs. coherence)." } }, { "@type": "Question", "name": "What are the open design directions for future AI agent systems identified in the paper?", "acceptedAnswer": { "@type": "Answer", "text": "Open directions include addressing the observability-evaluation gap, cross-session persistence and longitudinal relationships, harness boundary evolution (where, when, what, and with whom the agent acts), horizon scaling beyond sessions, governance and oversight at scale, and long-term human capability preservation." } }, { "@type": "Question", "name": "How does Claude Code's architecture support long-term human capability preservation?", "acceptedAnswer": { "@type": "Answer", "text": "Claude Code currently offers limited explicit mechanisms for long-term human capability preservation, raising concerns about comprehension loss, codebase coherence, and developer skill atrophy, which are identified as open challenges for future systems." } } ] }