{
  "@context": {
    "@vocab": "http://schema.org/",
    "codeRepository": {
      "@id": "http://schema.org/codeRepository",
      "@type": "@id"
    },
    "sourceCode": {
      "@id": "http://schema.org/sourceCode",
      "@type": "@id"
    },
    "hasPart": {
      "@id": "http://schema.org/hasPart",
      "@type": "@id"
    },
    "about": {
      "@id": "http://schema.org/about",
      "@type": "@id"
    },
    "author": {
      "@id": "http://schema.org/author",
      "@type": "@id"
    },
    "publisher": {
      "@id": "http://schema.org/publisher",
      "@type": "@id"
    },
    "mainEntity": {
      "@id": "http://schema.org/mainEntity",
      "@type": "@id"
    },
    "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",
    "SoftwareSourceCode": "http://schema.org/SoftwareSourceCode",
    "TechArticle": "http://schema.org/TechArticle",
    "CreativeWork": "http://schema.org/CreativeWork",
    "Person": "http://schema.org/Person",
    "Organization": "http://schema.org/Organization",
    "ImageObject": "http://schema.org/ImageObject"
  },
  "@type": "TechArticle",
  "headline": "Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems",
  "author": [
    {
      "@type": "Person",
      "name": "Jiacheng Liu"
    },
    {
      "@type": "Person",
      "name": "Xiaohan Zhao"
    },
    {
      "@type": "Person",
      "name": "Xinyi Shang"
    },
    {
      "@type": "Person",
      "name": "Zhiqiang Shen",
      "email": "Zhiqiang.Shen@mbzuai.ac.ae",
      "affiliation": [
        {
          "@type": "Organization",
          "name": "VILA Lab, Mohamed bin Zayed University of Artificial Intelligence"
        },
        {
          "@type": "Organization",
          "name": "University College London"
        }
      ]
    }
  ],
  "publisher": {
    "@type": "Organization",
    "name": "arXiv",
    "url": "https://arxiv.org/abs/2604.14228"
  },
  "datePublished": "2026-04-14",
  "codeRepository": "https://github.com/VILA-Lab/Dive-into-Claude-Code",
  "sourceCode": "https://github.com/VILA-Lab/Dive-into-Claude-Code",
  "abstract": "This study analyzes Claude Code, an agentic coding tool by Anthropic, through source code analysis and architectural comparison with OpenClaw. It identifies five human values and thirteen design principles shaping Claude Code's architecture, detailing its seven-component system and five-layer subsystems. The paper contrasts Claude Code's design with OpenClaw's, highlighting how deployment context influences architectural choices, and discusses 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 architecture is motivated by five human values: human decision authority, safety and security, reliable execution, capability amplification, and contextual adaptability. Thirteen design principles operationalize these values, including deny-first with human escalation, graduated trust spectrum, defense in depth, and composable extensibility. The system comprises seven components: user interfaces, agent loop, permission system, tools, state & persistence, and execution environment. The agent loop iteratively calls the model, dispatches tool requests through a permission gate, executes approved tools, and manages context pressure via a five-layer compaction pipeline. Extensibility is provided through four mechanisms: MCP servers, plugins, skills, and hooks, each with different context costs. Subagent delegation isolates work in separate contexts with permission overrides and worktree isolation. Session persistence uses append-only JSONL transcripts supporting resume and fork but does not restore session-scoped permissions for safety. A comparative analysis with OpenClaw, a multi-channel personal assistant gateway, reveals how different deployment contexts lead to different architectural answers on trust models, runtime embedding, extensibility, memory, and multi-agent routing. The paper discusses architectural trade-offs, value tensions, and empirical predictions, emphasizing the importance of deterministic infrastructure over decision scaffolding. It identifies open questions including observability-evaluation gaps, long-term memory and relationship persistence, harness boundary evolution, horizon scaling, governance, and long-term human capability preservation. The study is grounded in detailed source code analysis and official documentation, providing a comprehensive design-space analysis of a production AI coding agent system.",
  "hasPart": [
    {
      "@type": "DefinedTermSet",
      "name": "Design Principles",
      "description": "Thirteen design principles operationalizing human values in Claude Code's architecture.",
      "hasDefinedTerm": [
        {
          "@type": "DefinedTerm",
          "name": "Deny-first with human escalation",
          "description": "Unrecognized actions are denied or escalated to the human; deny rules override allow rules.",
          "about": "Authority, Safety"
        },
        {
          "@type": "DefinedTerm",
          "name": "Graduated trust spectrum",
          "description": "Users traverse a spectrum of permission levels over time rather than fixed permission levels.",
          "about": "Authority, Adaptability"
        },
        {
          "@type": "DefinedTerm",
          "name": "Defense in depth with layered mechanisms",
          "description": "Multiple overlapping safety boundaries using different techniques.",
          "about": "Safety, Authority, Reliability"
        },
        {
          "@type": "DefinedTerm",
          "name": "Externalized programmable policy",
          "description": "Policy is externalized as configs with lifecycle hooks rather than hardcoded.",
          "about": "Safety, Authority, Adaptability"
        },
        {
          "@type": "DefinedTerm",
          "name": "Context as scarce resource with progressive management",
          "description": "Context is managed through a graduated pipeline rather than single-pass truncation.",
          "about": "Reliability, Capability"
        },
        {
          "@type": "DefinedTerm",
          "name": "Append-only durable state",
          "description": "State is stored as append-only logs rather than mutable snapshots.",
          "about": "Reliability, Authority"
        },
        {
          "@type": "DefinedTerm",
          "name": "Minimal scaffolding, maximal operational harness",
          "description": "Invest in operational infrastructure that lets the model reason freely rather than scaffolding.",
          "about": "Capability, Reliability"
        },
        {
          "@type": "DefinedTerm",
          "name": "Values over rules",
          "description": "Contextual judgment backed by deterministic guardrails rather than rigid decision procedures.",
          "about": "Capability, Authority"
        },
        {
          "@type": "DefinedTerm",
          "name": "Composable multi-mechanism extensibility",
          "description": "Multiple layered extension mechanisms at different context costs.",
          "about": "Capability, Adaptability"
        },
        {
          "@type": "DefinedTerm",
          "name": "Reversibility-weighted risk assessment",
          "description": "Lighter oversight for reversible and read-only actions.",
          "about": "Capability, Safety"
        },
        {
          "@type": "DefinedTerm",
          "name": "Transparent file-based configuration and memory",
          "description": "User-visible, version-controllable files rather than opaque databases or embeddings.",
          "about": "Adaptability, Authority"
        },
        {
          "@type": "DefinedTerm",
          "name": "Isolated subagent boundaries",
          "description": "Subagents operate in isolated contexts with rebuilt permission and tool sets.",
          "about": "Reliability, Safety, Capability"
        },
        {
          "@type": "DefinedTerm",
          "name": "Graceful recovery and resilience",
          "description": "Silently recover from errors and reserve human attention for unrecoverable situations.",
          "about": "Reliability, Capability"
        }
      ]
    },
    {
      "@type": "HowTo",
      "name": "How to execute a turn in Claude Code's agent loop",
      "description": "Stepwise process of handling a user prompt through the agent loop, permission gate, tool execution, and context management.",
      "hasPart": [
        {
          "@type": "HowToStep",
          "position": 1,
          "name": "Settings resolution",
          "text": "Initialize immutable parameters including system prompt, user context, permission callback, and model configuration."
        },
        {
          "@type": "HowToStep",
          "position": 2,
          "name": "Mutable state initialization",
          "text": "Create a single State object to store mutable state across iterations."
        },
        {
          "@type": "HowToStep",
          "position": 3,
          "name": "Context assembly",
          "text": "Retrieve messages from the last compact boundary forward to ensure compacted content is summarized."
        },
        {
          "@type": "HowToStep",
          "position": 4,
          "name": "Pre-model context shaping",
          "text": "Apply five sequential shapers: budget reduction, snip, microcompact, context collapse, and auto-compact."
        },
        {
          "@type": "HowToStep",
          "position": 5,
          "name": "Model call",
          "text": "Stream the model's response, passing assembled messages, system prompt, tool set, and configuration."
        },
        {
          "@type": "HowToStep",
          "position": 6,
          "name": "Tool-use dispatch",
          "text": "Parse tool_use blocks and route requests through the permission system."
        },
        {
          "@type": "HowToStep",
          "position": 7,
          "name": "Permission gate",
          "text": "Evaluate each tool request against deny-first rules, permission modes, and ML classifier."
        },
        {
          "@type": "HowToStep",
          "position": 8,
          "name": "Tool execution and result collection",
          "text": "Execute approved tools, collect results, and add tool_result messages to the conversation."
        },
        {
          "@type": "HowToStep",
          "position": 9,
          "name": "Stop condition check",
          "text": "Terminate the 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.",
      "hasPart": [
        {
          "@type": "HowToStep",
          "position": 1,
          "name": "Pre-filtering",
          "text": "Remove blanket-denied tools from the model's view before runtime evaluation."
        },
        {
          "@type": "HowToStep",
          "position": 2,
          "name": "PreToolUse hooks",
          "text": "Run hooks that can deny, ask, or modify tool input parameters."
        },
        {
          "@type": "HowToStep",
          "position": 3,
          "name": "Deny-first rule evaluation",
          "text": "Evaluate deny rules first; deny always overrides allow."
        },
        {
          "@type": "HowToStep",
          "position": 4,
          "name": "Permission handler branching",
          "text": "Branch into coordinator, swarm worker, speculative classifier, or interactive approval paths."
        },
        {
          "@type": "HowToStep",
          "position": 5,
          "name": "ML-based auto-mode classification",
          "text": "Use an ML classifier to evaluate tool safety and automate approval or denial."
        },
        {
          "@type": "HowToStep",
          "position": 6,
          "name": "Shell sandboxing",
          "text": "Optionally sandbox shell commands to restrict filesystem and network access."
        },
        {
          "@type": "HowToStep",
          "position": 7,
          "name": "Hook-based interception",
          "text": "Use hooks to modify permission decisions asynchronously or alongside user dialogs."
        }
      ]
    },
    {
      "@type": "HowTo",
      "name": "How to extend Claude Code",
      "description": "Four extension mechanisms and their integration points.",
      "hasPart": [
        {
          "@type": "HowToStep",
          "position": 1,
          "name": "MCP servers",
          "text": "Integrate external tools via Model Context Protocol servers with multiple transport types."
        },
        {
          "@type": "HowToStep",
          "position": 2,
          "name": "Plugins",
          "text": "Package and distribute bundles of commands, agents, skills, hooks, and other components."
        },
        {
          "@type": "HowToStep",
          "position": 3,
          "name": "Skills",
          "text": "Define domain-specific instructions and meta-tools via SKILL.md files with YAML frontmatter."
        },
        {
          "@type": "HowToStep",
          "position": 4,
          "name": "Hooks",
          "text": "Register lifecycle event handlers to block, rewrite, or annotate tool calls with zero default context cost."
        }
      ]
    },
    {
      "@type": "Question",
      "name": "Where does reasoning live in Claude Code?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Reasoning lives in the model, which generates tool_use blocks. The harness executes actions, validates permissions, and manages tool dispatch, ensuring security by separating reasoning from enforcement."
      }
    },
    {
      "@type": "Question",
      "name": "What is the default safety posture in Claude Code?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Claude Code adopts a deny-first safety posture with human escalation. Deny rules override allow rules, and unrecognized actions are escalated to the user. Multiple independent safety layers operate in parallel."
      }
    },
    {
      "@type": "Question",
      "name": "How does Claude Code manage context window constraints?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "It uses a five-layer compaction pipeline including budget reduction, snip, microcompact, context collapse, and auto-compact, applying graduated compression to manage context pressure progressively."
      }
    },
    {
      "@type": "Question",
      "name": "How does Claude Code handle extensibility?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Extensibility is provided through four mechanisms: MCP servers for external tool integration, plugins for packaging and distribution, skills for domain-specific instructions, and hooks for lifecycle event interception."
      }
    },
    {
      "@type": "Question",
      "name": "What are the main components of Claude Code's architecture?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Seven components: user interfaces, agent loop, permission system, tools, state & persistence, execution environment, and extensibility subsystems."
      }
    },
    {
      "@type": "Question",
      "name": "How does Claude Code ensure session persistence and recovery?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Sessions are stored as append-only JSONL transcripts with sidechain files for subagents. Resume and fork rebuild conversation state but do not restore session-scoped permissions for safety."
      }
    },
    {
      "@type": "Question",
      "name": "What is the role of subagents in Claude Code?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Subagents run in isolated contexts with rebuilt permission and tool sets, often using worktree isolation. They delegate tasks from the main agent and return summary-only results to conserve context."
      }
    },
    {
      "@type": "Question",
      "name": "How does Claude Code's architecture differ from OpenClaw?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Claude Code is a CLI coding harness with per-action deny-first safety and graduated context compression, while OpenClaw is a persistent multi-channel gateway with perimeter-level access control and structured long-term memory. OpenClaw can host Claude Code as an external harness."
      }
    },
    {
      "@type": "Question",
      "name": "What are the key value tensions 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 open design directions does the paper identify for future AI agent systems?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Open directions include closing the observability-evaluation gap, cross-session persistence and memory, harness boundary evolution, horizon scaling beyond sessions, governance and regulatory compliance, and preserving long-term human capability."
      }
    }
  ]
}