PaperlayerView exact revision on arXiv

Source-linked AI summary

Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems

Jiacheng Liu, Xiaohan Zhao, Xinyi Shang, Zhiqiang Shen

arXiv:2604.14228v2cs.SEcs.AIcs.CLcs.LG

TL;DR

Production coding agents must answer recurring architectural questions about safety, context, extensibility, delegation, and persistence, but detailed public descriptions of Claude Code are limited. This paper analyzes its source code and compares it with OpenClaw and Hermes Agent, finding a simple model-driven loop surrounded by a dense deterministic harness whose design reflects different deployment-specific trade-offs. It also identifies open directions concerning evaluation, persistence, harness boundaries, scaling, governance, and long-term developer capability.

  • Problem

    Detailed public architectural descriptions of Claude Code are limited despite the growing importance of fully agentic coding systems.

  • Method

    The paper performs source-level analysis of Claude Code and compares its recurring design answers with OpenClaw and Hermes Agent.

  • Results

    Claude Code’s architecture is overwhelmingly deterministic operational infrastructure around model decision logic, with an estimated 1.6% of code devoted to decisions and 98.4% to the operational harness.

  • Takeaways & Limitations

    Claude Code occupies a design point that gives the model broad local autonomy while surrounding it with deterministic permissioning, tool routing, context compaction, extensibility, and session recovery.

  • Takeaways & Limitations

    The architecture’s compression mechanisms are largely invisible to users, limiting easy inspection of what context was lost.

Abstract

from arXiv · show

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 architecture by analyzing the publicly available source code and comparing it with two independent open-source AI agent systems, OpenClaw and Hermes Agent, that answer many of similar or even the same design questions. Our analysis identifies five human values, philosophies, and needs that motivate the architecture: human decision authority, safety, security, and privacy, reliable execution, capability amplification, and contextual adaptability. We then trace them through thirteen design principles to 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 and orchestration mechanism, and append-oriented session storage. Comparisons with OpenClaw and Hermes Agent show that the same design questions produce different answers across three deployment contexts. Claude Code emphasizes per-action safety, OpenClaw emphasizes perimeter-level access, and Hermes renders per-action approvals across many surfaces. At the runtime layer, Claude Code uses a single CLI loop, OpenClaw embeds the runtime within a gateway control plane, and Hermes uses one process whose role is set by its entry point. At the context and extension layer, Claude Code extends the context window, OpenClaw registers gateway-wide capabilities, and Hermes provides pluggable memory and model backends. We finally identify six open design directions for future agent systems, grounded in recent empirical, architectural, and policy literature.

1 Introduction

This study addresses the lack of detailed public architectural descriptions of Claude Code by analyzing its source code and comparing its design answers with OpenClaw and Hermes Agent. It traces human values and design principles through implementation choices, using source-level evidence to examine the system’s mechanisms and future directions.

  • Source-code analysis describes Claude Code’s architectural design decisions where detailed public architectural documentation is unavailable.
  • Design-space analysis: The paper identifies recurring design questions about reasoning, iteration, safety, extensibility, context, delegation, and session persistence.
  • Design-space analysis: Claude Code is analyzed through a seven-component high-level structure and a five-layer subsystem architecture traced to specific source files.
  • Architectural contrast: The study compares Claude Code with OpenClaw and Hermes Agent across six design dimensions to show how deployment contexts produce different architectural answers.
  • Open directions: The paper identifies six open directions for future agent systems, including observability, persistence, harness boundaries, horizon scaling, governance, and long-term developer capability.

2 Design Philosophies, Design Principles and Architectural Motivations

Claude Code’s architecture is motivated by five human values and thirteen design principles that organize recurring production-agent design questions. These principles favor human control, layered protection, reliable operation, capability amplification, contextual adaptation, and progressive context management.

  • Five values: The architecture is framed around human decision authority, safety, security and privacy, reliable execution, capability amplification, and contextual adaptability.
  • Contextual adaptability: The extension architecture provides configurability across CLAUDE.md, skills, MCP, hooks, and plugins, while longitudinal data describes changing auto-approval rates across sessions.Auto-approve rates increase from approximately 20% at fewer than 50 sessions to over 40% by 750 sessions.
  • Design principles: These values are operationalized through thirteen design principles, each answering a recurring design question for production coding agents.
  • Design principles: Claude Code combines minimal decision scaffolding with layered policy enforcement, values-based judgment with deny-first defaults, and progressive context management with composable extensibility.
  • Architectural boundaries: The architecture does not impose explicit planning graphs, provide one unified extension mechanism, or restore all session-scoped trust state across resume.
  • Long-term capability: Long-term developer understanding is treated as a cross-cutting concern because AI assistance may amplify short-term capability while weakening comprehension and supervision skills.Independent research reports developers in AI-assisted conditions scoring 17% lower on comprehension tests.

3 Architecture Overview

Claude Code organizes production agent execution around a shared query loop surrounded by deterministic infrastructure for safety, context, tools, state, and execution. Its architecture answers recurring design questions by separating model reasoning from harness enforcement, using one loop across surfaces, and treating context as the binding constraint.

  • Design questions: Claude Code separates model reasoning from action execution: the model emits tool requests, while the harness validates permissions, dispatches tools, and collects results.The model does not directly access the filesystem, run shell commands, or make network requests.
  • Design questions: A single queryLoop() function serves the interactive terminal, headless CLI, Agent SDK, and IDE integration, with only rendering and interaction layers varying.
  • Design questions: The default safety posture is deny-first with human escalation, supported by permission rules, hooks, an optional classifier, and optional shell sandboxing.Deny rules override ask rules, which override allow rules; unrecognized actions are escalated rather than silently permitted.
  • Design questions: The context window is the binding resource constraint, so five context-reduction strategies run before every model call and other components limit context consumption.Earlier, cheaper reductions precede costlier compaction, with auto-compact providing semantic compression as a last resort.
  • System structure: The seven-component architecture connects interfaces, the agent loop, permissions, tools, state and persistence, and the execution environment through a shared data flow.
  • System structure: The five-layer view expands this structure into surface, core, safety/action, state, and backend layers mapped to specific source directories.

4 Turn Execution: The Agentic Query Loop

Claude Code uses a simple ReAct-style while-loop in which model responses generate tool actions, the harness executes them, and results feed the next iteration. Streaming, concurrency controls, progressive compaction, recovery mechanisms, and explicit stop conditions make the minimal loop operationally robust.

  • Turn flow: Each turn resolves settings, initializes mutable state, assembles context, applies five shapers, calls the model, executes tools, and feeds results back into the loop.
  • Turn flow: The loop follows the ReAct pattern: the model generates reasoning and tool invocations, the harness executes actions, and results inform subsequent iterations.
  • Tool execution: StreamingToolExecutor starts tools while model output streams, runs read-only operations concurrently, and serializes state-modifying operations such as shell commands.
  • Tool execution: Tool results are buffered and emitted in request order, preserving the ordering expected by the model despite parallel execution.
  • Context management: Five sequential context shapers apply progressively broader reductions: budget reduction, snip, microcompact, context collapse, and auto-compact.
  • Recovery and termination: Recovery includes output-token escalation and reactive compaction, while the loop can stop on no tool use, turn limits, overflow, hook intervention, or explicit abort.Output-token recovery allows up to three attempts per turn.
  • Permission posture: Users begin with minimal autonomy and expand it by approving tool invocations that become permanent rules.

5 Tool Authorization and Control Boundaries

Claude Code places tool authorization between model decisions and execution, combining user approvals, configurable autonomy modes, automated classification, hooks, and sandbox isolation. Denials can redirect the agent toward safer alternatives rather than simply stopping execution.

  • Permission modes: Seven permission modes span Claude Code’s autonomy spectrum from approval-required planning to minimally prompted bypassPermissions.The auto mode is conditionally available when the transcript classifier is enabled, while bubble is internal to subagent escalation.
  • Permission rules: Deny-first rule evaluation gives deny rules precedence over more specific allows, including content-level and server-level tool matches.A broad shell-command denial cannot be overridden by a narrow rule allowing npm test.
  • Authorization pipeline: The authorization pipeline combines pre-filtering, hooks, rule evaluation, contextual handlers, and classifier-mediated decisions before tools execute.Hooks can deny, request approval, or modify inputs, while the classifier returns allow, deny, or manual-approval decisions when enabled.
  • Recovery: Permission denials return reasons and can trigger safer retries, making enforcement a behavioral routing signal rather than only a hard stop.The PermissionDenied hook can provide retry guidance after auto-mode denials.
  • Isolation: Application-level authorization and shell sandboxing operate on separate axes: an approved command may still be isolated, while a denied command never reaches sandbox evaluation.Sandboxing checks global enablement, opt-outs, and exclusion patterns, and provides filesystem and network isolation.

6 Extensibility: MCP, Plugins, Skills, and Hooks

Claude Code uses four distinct extension mechanisms because they intervene at different points in the agent loop and impose different context costs. MCP, plugins, skills, and hooks collectively expand tools, package components, shape behavior, and control execution.

  • Tool assembly: Claude Code assembles a tool pool from built-in tools, MCP tools, skills, plugins, and meta-tools, with deferred tools queryable through ToolSearch.The shared assembly function supports consistent tool sets across the REPL and worker-agent paths.
  • Extension points: The agent loop exposes three extension points: assemble() controls model-visible context, model() controls reachable capabilities, and execute() controls action execution.The extension surface therefore spans what the model sees, what it can call, and how calls run.
  • Mechanisms: MCP servers provide external callable tools, plugins distribute bundles of components, skills shape agent behavior, and hooks intercept lifecycle events.These mechanisms extend different parts of the loop rather than serving as interchangeable interfaces.
  • Plugins: Plugins can package commands, agents, skills, hooks, MCP servers, LSP servers, output styles, channels, settings, and user configuration in one manifest.The loader routes each component to its corresponding registry, making plugins the primary distribution vehicle for third-party extensions.
  • Design rationale: The four mechanisms trade context cost against extensibility: MCP consumes schema-heavy context, skills use mainly frontmatter descriptions, and hooks have no context footprint by default.Hooks can still inject context when configured, while a single mechanism would force unnecessary trade-offs across extension types.

7 Context Construction and Memory

Claude Code treats context as a scarce resource and manages it through layered assembly, transparent file-based memory, late injections, and graduated compaction. This preserves user inspectability while accepting complexity and probabilistic instruction following.

  • Context assembly: Claude Code’s context window combines system and environment information, CLAUDE.md files, rules, tools, history, runtime outputs, memory, subagent summaries, and compact summaries.Some sources are assembled initially, while memory, MCP, agent, and background-task updates can arrive later in the turn.
  • Transparency: Plain-text CLAUDE.md files make stored instructions inspectable, editable, and version-controllable, unlike opaque retrieval or database-backed memory.The system does not use embeddings or a vector similarity index for memory retrieval.
  • Memory hierarchy: CLAUDE.md uses managed, user, project, and local memory levels, with files closer to the current directory receiving higher priority.Nested-directory rules can load lazily as the agent explores new parts of the codebase.
  • Instruction control: CLAUDE.md guidance is delivered as user context rather than system-prompt content, so compliance is probabilistic while permission rules provide deterministic enforcement.This separates contextual guidance from authorization enforcement.
  • Compaction: The five-layer compaction pipeline progressively applies budget reduction, snipping, microcompact, context collapse, and auto-compact.Budget reduction is always active; other stages are feature-gated or user-configurable.
  • Trade-offs: The graduated compaction strategy reduces disruption before escalating to stronger compression, but its interacting layers make behavior difficult to predict.Auto-compact produces a visible transcript summary, whereas context collapse can occur without user-visible output.

8 Subagent Delegation and Orchestration

Claude Code delegates work through isolated subagents with configurable routing, isolation, lifecycle, tools, permissions, and memory. It conserves the parent context by returning summaries while preserving separate transcripts and inspectable coordination state.

  • Delegation architecture: The Agent tool dispatches built-in or custom subagents along routing, isolation, and lifecycle axes, each with an isolated context and independent tool set.Supported choices include teammate routing, worktree or remote isolation, and asynchronous or synchronous execution.
  • Custom agents: Custom agents can define their own system prompt, tools, model, permissions, hooks, memory scope, turn limit, and isolation mode.Users define them in .claude/agents/*.md files, while plugins can contribute agent definitions.
  • Isolation semantics: AgentTool always spawns a new isolated subagent, whereas SkillTool typically injects instructions into the current context unless fork mode is enabled.The default isolated path requires a self-contained delegation prompt rather than inheriting the parent conversation wholesale.
  • Isolation modes: Worktree isolation gives a subagent a temporary repository copy, remote isolation runs in an internal remote environment, and in-process isolation shares the filesystem but separates conversation context.These modes trade workspace separation, infrastructure requirements, and conversational isolation differently.
  • Context conservation: Subagents write separate JSONL transcripts, but only their final response and metadata return to the parent context.This preserves histories for debugging and auditing without inflating the parent session file or context window.
  • Coordination costs: Agent teams consume approximately 7× the tokens of a standard session in plan mode, increasing the importance of summary-only returns.Multi-instance coordination uses locked inbox JSON files, trading throughput for zero-dependency deployment and debuggability.

9 Session Persistence and Recovery

Claude Code separates durable conversation records from live session state, using append-oriented storage for auditability while deliberately rebuilding permissions on resume or fork. Recovery restores messages and compaction structure, but not prior trust decisions.

  • Recovery: Session-scoped permissions remain in memory and are not serialized, so resume rebuilds permission context from CLI arguments and disk settings.Unrecognized requests fall back to deny-first prompting rather than inheriting opaque session state.
  • Durable storage: Three independent persistence channels store session transcripts, global prompt history, and separate subagent sidechains.Transcripts are project-scoped, history stores user prompts globally, and each subagent has its own JSONL and metadata files.
  • Durable storage: Claude Code writes messages, tool results, and compaction boundaries to project-specific, mostly append-only JSONL transcripts as events occur.The format favors human readability, inspectability, version control, auditability, and simplicity over database-style query power.
  • Recovery: Resume replays the transcript to rebuild the conversation, while fork creates a new session from an existing one.Compaction boundaries preserve UUID metadata so the loader can reconnect preserved message chains during recovery.
  • Recovery: Resume and fork require users to grant permissions again because sessions are treated as isolated trust domains.The design accepts user friction to avoid carrying stale trust decisions into a changed context.

10 Comparative Analysis: Claude Code, OpenClaw, and Hermes Agent

Claude Code, OpenClaw, and Hermes Agent answer shared agent-design questions differently because they target different deployment contexts. Their contrasts span system scope, trust models, runtime placement, extensibility, context management, delegation, and composability.

  • Deployment model: Claude Code is an ephemeral repository-bound CLI, OpenClaw is a persistent multi-channel gateway, and Hermes is a long-lived Python process whose role depends on its entry point.These deployment models place the agent runtime and surrounding control surfaces differently.
  • Runtime architecture: Claude Code centers its queryLoop, OpenClaw embeds an agent runtime inside a gateway control plane, and Hermes runs a synchronous loop within one process.OpenClaw adds gateway validation, session resolution, event emission, and queueing around the embedded runner.
  • Extensions: Claude Code organizes MCP, plugins, skills, and hooks by context cost, while Hermes adds pluggable memory and model providers alongside comparable extension surfaces.OpenClaw combines skills from multiple sources with a public registry and MCP support.
  • Context and memory: Claude Code manages context pressure through a five-layer compaction pipeline, whereas OpenClaw injects workspace files and manages durable memory with optional hybrid retrieval.Hermes’s comparison in the supplied passages emphasizes pluggable memory and model backends rather than a single shared context strategy.
  • Trust model: Claude Code emphasizes graduated per-action safety, OpenClaw emphasizes perimeter-level identity and access control, and Hermes uses per-action approvals across many surfaces.The systems therefore address different threat models rather than implementing one universal security posture.
  • Composability: The comparison treats the systems as composable rather than exclusive alternatives because OpenClaw can host Claude Code and Hermes can operate on both sides of the ACP host/guest split.This supports a layered view of the agent design space.

11 Related Work

Related work positions Claude Code within research on coding-agent autonomy, agent loops, context management, safety, tool protocols, and software architecture. This paper differs by providing a source-grounded design-space analysis of a production coding agent and contrasting its choices with independent systems.

  • Coding agents: Coding tools range from inline completion through IDE-integrated assistants to agentic CLI systems that perform increasingly autonomous multi-step actions.Claude Code belongs to the agentic CLI category while retaining interactive approval by default.
  • Agent loops: Claude Code’s core loop follows ReAct: the model generates reasoning and tool calls, the harness executes them, and results feed the next iteration.The paper examines this harness and its surrounding permissions rather than focusing only on benchmark performance.
  • Context management: Context-management research identifies detail loss from summarization and iterative rewriting, while Claude Code uses a five-layer compaction pipeline with cache-aware compression and virtual-view-on-read semantics.The pipeline applies multiple strategies at different granularities before escalating.
  • Safety and architecture: Production agent safety architectures vary by approval model, isolation boundary, and recovery mechanism.The paper analyzes Claude Code’s permission, sandbox, and recovery choices as a source-grounded design-space point.
  • Protocols and extensibility: MCP research documents threats including tool poisoning, rug pulls, and cross-server shadowing, while Claude Code’s permission and pre-filtering mechanisms provide runtime-side mitigations.Broader guidance treats MCP security as spanning protocol design, scheduling, external-service integration, and monitoring.
  • Positioning: This paper contributes a source-grounded design-space analysis that maps recurring design questions to implementation choices and contrasts Claude Code with OpenClaw and Hermes Agent.It characterizes one specific point in the broader design space rather than proposing a universal architecture.

12 Discussion

Claude Code’s architecture prioritizes deterministic operational infrastructure around a model-driven loop, preserving model decision latitude while supporting safety, reliability, adaptability, and human control. The discussion also identifies trade-offs and empirical signals that complicate this design, including shared safety-layer failure modes, initialization-order vulnerabilities, opaque context compression, extensibility complexity, and possible long-term maintenance costs.

  • Design Philosophy: 1.6% of the codebase constitutes decision logic, while 98.4% is deterministic operational infrastructure that creates conditions for model decision-making.The harness includes permission gates, tool routing, context management, and recovery logic, while the LLM acts as a stateless completion endpoint.
  • Design Philosophy: Claude Code gives the model maximum decision latitude within a rich operational harness, contrasting with explicit planning or graph-based scaffolding in other agent frameworks.The paper characterizes the core loop as kernel-like, with surrounding infrastructure functioning more like an operating system.
  • Design Philosophy: As model capability grows, decision scaffolding may become less necessary in domains where models already solve tasks independently, but context management, recovery, safety, approvals, and project adaptation remain necessary.The paper argues that stronger models do not remove finite context, session-resumption, security, human-authority, or project-specific adaptation requirements.
  • Design Philosophy: The harness remains consequential as models improve: changing only the surrounding harness shifts Fable 5’s functional and security pass rates by ten points or more.The paper reports that capability growth primarily changes the need for decision scaffolding, not the importance of the other harness functions.
  • Architectural Trade-offs: Users approve approximately 93% of permission prompts, while auto-approve rates rise from approximately 20% below 50 sessions to over 40% by 750 sessions.Sandboxing reduced permission-prompt frequency by an estimated 84%, framing approval reliability as a human-factors issue.
  • Architectural Trade-offs: Defense-in-depth can fail when safety layers share performance constraints: commands with more than 50 subcommands may receive a generic approval prompt instead of per-subcommand deny-rule checks.The paper therefore evaluates safety by considering simultaneous layer failures and shared failure modes, not isolated bypassability.
  • Architectural Trade-offs: Initialization ordering creates a pre-trust execution window in which hooks, MCP connections, and settings resolution run before the trust dialog and deny-first enforcement.This adds a temporal security dimension to the otherwise spatial depiction of the permission pipeline.
  • Architectural Trade-offs: Five-layer context compaction improves context management but makes information loss largely invisible, limiting user transparency into discarded tool outputs and history.The pipeline can replace outputs with references, collapse messages into summaries, and trim older history without an easy inspection path.

13 Future Directions

The paper identifies open directions for agent systems spanning observability, persistence, harness boundaries, horizon scaling, governance, and long-term developer capability. These questions remain unresolved by Claude Code’s source-level, session-scoped analysis and require empirical, architectural, or policy investigation.

  • Observability and Evaluation: The observability-evaluation gap remains unresolved, including whether evaluation scaffolding belongs inside the harness or in a separate layer.The paper also leaves open whether the existing hook pipeline can host such scaffolding within its current context-cost envelope.
  • Cross-Session Persistence: Cross-session persistence remains an open design question between static CLAUDE.md instructions and append-oriented session transcripts.Related work explores reusable procedural traces, self-reflection traces, and dynamic memory for tool-use dialogue, research, coding, and computer use.
  • Harness Boundary Evolution: Future harnesses may extend across where, when, what, and with whom an agent acts, but how these extensions compose remains unresolved.The paper also raises governance questions for hosted harness components and reversibility questions for physical effects.
  • Horizon Scaling: Long-horizon deployment tests whether context management, output-return policies, persistence, and orchestration remain reliable across multi-session programs.A benchmark shows that reasonable local tool calls can still terminate before a verifier confirms sufficient valid work units, making an external notion of done important.
  • Governance: Emerging regulation leaves open which logging, transparency, and human-oversight affordances coding-agent architectures should expose.The paper specifically contrasts internal transcript auditability with the external auditability contemplated by emerging frameworks.
  • Long-Term Developer Capability: The architecture exposes no per-session signal for comprehension or convention drift, leaving open how systems should measure and respond to long-term developer capability.The paper does not settle whether the harness, IDE, organization, or human development loop is the appropriate locus for intervention.

14 Conclusion

The paper presents production coding agents as coherent answers to recurring design questions, with Claude Code combining broad model autonomy and a dense deterministic harness. Comparisons with OpenClaw and Hermes show that deployment context changes these answers, while long-term preservation of human capability remains a central open concern.

  • Claude Code’s Design Point: Claude Code gives the model broad local autonomy while surrounding it with deterministic infrastructure for permissioning, tool routing, context, delegation, and persistence.The paper interprets these choices through five values and thirteen design principles.
  • Architectural Contrast: The same design questions yield different architectures: Claude Code uses per-action safety and CLI compression, OpenClaw uses perimeter access and gateway memory, and Hermes uses approvals across surfaces with pluggable backends.The three systems can also compose through ACP at multiple host/guest positions.
  • Long-Term Capability: Future systems face a sustainability gap because current architecture provides limited mechanisms for preserving long-term human understanding, codebase coherence, and the developer pipeline.The paper identifies preserving human capability over time as the most consequential open question for agent builders.

Evidence Base and Methodology

The appendix records the study’s evidence sources, analytic procedure, and limitations.

  • The appendix documents the evidence sources used in the study.
  • It also records the analytic procedure supporting the architectural analysis.
  • The appendix states the limits of the study.

Evidence Base and Evidence Tiers

The study grounds its architectural analysis in explicit evidence tiers, a TypeScript source corpus, and traced subsystem implementations, while distinguishing reconstructed material from code-verified claims. It also records version, reverse-engineering, scope, and comparison-snapshot limitations.

  • Evidence tiers: Three evidence tiers separate product-documented intent, code-verified implementation claims, and reconstructed analyses from community or comparative sources.Tier B, based on specific files and functions in the extracted TypeScript codebase, is identified as the strongest evidence tier.
  • Corpus and comparisons: The source corpus contains approximately 1,884 files and roughly 512K lines of TypeScript, while OpenClaw and Hermes Agent serve as comparative reference points rather than ground-truth standards.
  • Analytical method: Design questions are identified across recurring subsystem choice points, and Claude Code’s answers are traced through specific source files and function implementations.The package structure maps source directories and key files to runtime responsibilities, including tools, commands, compaction, MCP, permissions, and query-loop components.
  • Limitations: The analysis is bounded by a static v2.1.88 snapshot, build-time feature variability, limits on inferring intent or runtime prevalence from source, single-system scope, and comparison-system snapshots.The paper states that different build targets may produce functionally different applications and that OpenClaw and Hermes findings may not represent their current capabilities.
  • Analytical method: The reconstructed package analysis covers runtime responsibilities, but its Figure 9 mapping is Tier C evidence rather than official Anthropic documentation.
Loading 2604.14228v2…