English | 中文
A comprehensive source-level architectural analysis of Claude Code (v2.1.88, ~1,900 TypeScript files, ~512K lines of code), combined with a curated collection of community analyses, a design-space guide for agent builders, and cross-system comparisons.
Tip
TL;DR -- Only 1.6% of Claude Code's codebase is AI decision logic. The other 98.4% is deterministic infrastructure -- permission gates, context management, tool routing, and recovery logic. The agent loop is a simple while-loop; the real engineering complexity lives in the systems around it. This repo dissects that architecture and distills it into actionable design guidance for anyone building AI agent systems.
From Our Paper
- 🌟 Key Highlights
- 📖 Reading Guide
- 🏗️ Architecture at a Glance
- 🧭 Values and Design Principles
- 🔄 The Agentic Query Loop
- 🛡️ Safety and Permissions
- 🧩 Extensibility
- 🧠 Context and Memory
- 👥 Subagent Delegation
- 💾 Session Persistence
Beyond the Paper
- 🛰️ New Signals in the Agent Design Space
- 🛠️ Build Your Own AI Agent: A Design Guide
- ⚖️ Cross-System Comparison: Claude Code vs OpenClaw vs Hermes-Agent
- 🔎 Find Resources by Design Question
- 🌐 Community Projects & Research
- 🚀 Other Notable AI Agent Projects
- 🔖 Citation
- 98.4% Infrastructure, 1.6% AI -- The agent loop is a simple while-loop; the real complexity is permission gates, context management, and recovery logic.
- 5 Values → 13 Principles → Implementation -- Every design choice traces back to human authority, safety, reliability, capability, and adaptability.
- Defense in Depth with Shared Failure Modes -- 7 safety layers, but all share performance constraints. 50+ subcommands bypass security analysis.
- 4 CVEs Reveal a Pre-Trust Window -- Extensions execute before the trust dialog appears.
- The Cross-Cutting Harness Resists Reimplementation -- The loop is easy to copy; hooks, classifier, compaction, and isolation are not.
| If you are a... | Start here | Then read |
|---|---|---|
| Agent Builder | Build Your Own Agent | Architecture Deep Dive |
| Security Researcher | Safety and Permissions | Architecture: Safety Layers |
| Product Manager | Key Highlights | Values and Principles |
| Researcher | Full Paper (arXiv) | Community Resources |
1,884 files · ~512K lines · v2.1.88 · 7 safety layers · 5 compaction stages · 54 tools · 27 hook events · 4 extension mechanisms · 7 permission modes
Claude Code answers four design questions that every production coding agent must face:
| Question | Claude Code's Answer |
|---|---|
| Where does reasoning live? | Model reasons; harness enforces. ~1.6% AI, 98.4% infrastructure. |
| How many execution engines? | One queryLoop for all interfaces (CLI, SDK, IDE). |
| Default safety posture? | Deny-first: deny > ask > allow. Strictest rule wins. |
| Binding resource constraint? | ~200K (older models) / 1M (Claude 4.6 series) context window. 5 compaction layers before every model call. |
The system decomposes into 7 components (User → Interfaces → Agent Loop → Permission System → Tools → State & Persistence → Execution Environment) across 5 architectural layers.
[!NOTE] For the full architectural deep dive -- 7 safety layers, 9-step turn pipeline, 5-layer compaction, and more -- see docs/architecture.md.
The architecture traces from 5 human values through 13 design principles to implementation:
| Value | Core Idea |
|---|---|
| Human Decision Authority | Humans retain control via principal hierarchy. When a 93% prompt-approval rate revealed approval fatigue, response was restructured boundaries, not more warnings. |
| Safety, Security, Privacy | System protects even when human vigilance lapses. 7 independent safety layers. |
| Reliable Execution | Does what was meant. Gather-act-verify loop. Graceful recovery. |
| Capability Amplification | "A Unix utility, not a product." 98.4% is deterministic infrastructure enabling the model. |
| Contextual Adaptability | CLAUDE.md hierarchy, graduated extensibility, trust trajectories that evolve over time. |
The 13 Design Principles
| Principle | Design Question |
|---|---|
| Deny-first with human escalation | Should unrecognized actions be allowed, blocked, or escalated? |
| Graduated trust spectrum | Fixed permission level, or spectrum users traverse over time? |
| Defense in depth | Single safety boundary, or multiple overlapping ones? |
| Externalized programmable policy | Hardcoded policy, or externalized configs with lifecycle hooks? |
| Context as scarce resource | Single-pass truncation or graduated pipeline? |
| Append-only durable state | Mutable state, snapshots, or append-only logs? |
| Minimal scaffolding, maximal harness | Invest in scaffolding or operational infrastructure? |
| Values over rules | Rigid procedures or contextual judgment with deterministic guardrails? |
| Composable multi-mechanism extensibility | One API or layered mechanisms at different costs? |
| Reversibility-weighted risk assessment | Same oversight for all, or lighter for reversible actions? |
| Transparent file-based config and memory | Opaque DB, embeddings, or user-visible files? |
| Isolated subagent boundaries | Shared context/permissions, or isolation? |
| Graceful recovery and resilience | Fail hard, or recover silently? |
The paper also applies a sixth evaluative lens -- long-term capability preservation -- citing evidence that developers in AI-assisted conditions score 17% lower on comprehension tests.
The core is a ReAct-pattern while-loop: assemble context → call model → dispatch tools → check permissions → execute → repeat. Implemented as an AsyncGenerator yielding streaming events.
Before every model call, five compaction shapers run sequentially (cheapest first): Budget Reduction → Snip → Microcompact → Context Collapse → Auto-Compact.
9-step pipeline per turn: Settings resolution → State init → Context assembly → 5 pre-model shapers → Model call → Tool dispatch → Permission gate → Tool execution → Stop condition
Two execution paths:
StreamingToolExecutor-- begins executing tools as they stream in (latency optimization)- Fallback
runTools-- classifies tools as concurrent-safe or exclusive
Recovery: Max output token escalation (3 retries), reactive compaction (once per turn), prompt-too-long handling, streaming fallback, fallback model
5 stop conditions: No tool use, max turns, context overflow, hook intervention, explicit abort
7 permission modes form a graduated trust spectrum: plan → default → acceptEdits → auto (ML classifier) → dontAsk → bypassPermissions (+ internal bubble).
Deny-first: A broad deny always overrides a narrow allow. 7 independent safety layers from tool pre-filtering through shell sandboxing to hook interception. Permissions are never restored on resume -- trust is re-established per session.
[!WARNING] Shared failure modes: Defense-in-depth degrades when layers share constraints. Per-subcommand parsing causes event-loop starvation -- commands exceeding 50 subcommands bypass security analysis entirely to prevent the REPL from freezing.
More details: authorization pipeline, auto-mode classifier, CVEs
Authorization pipeline: Pre-filtering (strip denied tools) → PreToolUse hooks → Deny-first rule evaluation → Permission handler (4 branches: coordinator, swarm worker, speculative classifier, interactive)
Auto-mode classifier (yoloClassifier.ts): Separate LLM call with internal/external permission templates. Two-stage: fast-filter + chain-of-thought.
Pre-trust execution window: 2 patched CVEs share this root cause -- hooks and MCP servers execute during initialization before the trust dialog appears, creating a structurally privileged attack window outside the deny-first pipeline.
Four mechanisms at graduated context costs: Hooks (zero) → Skills (low) → Plugins (medium) → MCP (high). Three injection points in the agent loop: assemble() (what the model sees), model() (what it can reach), execute() (whether/how actions run).
Tool pool assembly (5-step): Base enumeration (up to 54 tools) → Mode filtering → Deny pre-filtering → MCP integration → Deduplication
27 hook events across 5 categories with 4 execution types (shell, LLM-evaluated, webhook, subagent verifier)
Plugin manifest accepts 10 component types: commands, agents, skills, hooks, MCP servers, LSP servers, output styles, channels, settings, user config
Skills: SKILL.md with 15+ YAML frontmatter fields. Key difference -- SkillTool injects into current context; AgentTool spawns isolated context.
9 ordered sources build the context window. CLAUDE.md instructions are delivered as user context (probabilistic compliance), not system prompt (deterministic). Memory is file-based (no vector DB) -- fully inspectable, editable, version-controllable.
4-level CLAUDE.md hierarchy: Managed (/etc/) → User (~/.claude/) → Project (CLAUDE.md, .claude/rules/) → Local (CLAUDE.local.md, gitignored)
5-layer compaction (graduated lazy-degradation): Budget reduction → Snip → Microcompact → Context Collapse (read-time projection, non-destructive) → Auto-Compact (full model summary, last resort)
Memory retrieval: LLM-based scan of memory-file headers, selects up to 5 relevant files. No embeddings, no vector similarity.
6 built-in types (Explore, Plan, General-purpose, Guide, Verification, Statusline) + custom agents via .claude/agents/*.md. Sidechain transcripts: only summaries return to parent (parent's context is protected from subagent verbosity). Three isolation modes: worktree, remote, in-process. Coordination via POSIX flock().
SkillTool vs AgentTool: SkillTool injects into current context (cheap). AgentTool spawns isolated context (expensive, but prevents context explosion).
Permission override: Subagent permissionMode applies UNLESS parent is in bypassPermissions/acceptEdits/auto (explicit user decisions always take precedence).
Custom agents: YAML frontmatter supports tools, disallowedTools, model, effort, permissionMode, mcpServers, hooks, maxTurns, skills, memory scope, background flag, isolation mode.
Three channels: append-only JSONL transcripts, global prompt history, subagent sidechains. Permissions never restored on resume -- trust is re-established per session. Design favors auditability over query power.
Chain patching: Compact boundaries record headUuid/anchorUuid/tailUuid. The session loader patches the message chain at read time. Nothing is destructively edited on disk.
Checkpoints: File-history checkpoints for --rewind-files, stored at ~/.claude/file-history/<sessionId>/.
New agent-system developments reinforce the same lesson Claude Code makes clear: agent capability is not a model property alone. It comes from the runtime, context layer, execution boundary, tool supply chain, the controls humans have over it, and the evaluation loop around the model.
| Design Implication | What it means for agent builders | Representative signals |
|---|---|---|
| Runtime and control plane are first-class design concerns | Durable execution, checkpoints, sandboxes, agent inventory, policy, and observability should be designed as parts of the system that users can see, not hidden deployment details. | Cursor cloud agents, Google Managed Agents, Microsoft Agent 365, Databricks Omnigent |
| Context is managed infrastructure | Prompts, files, skills, IDE indexes, workspace state, memory namespaces, and interpreter state need lifecycle, provenance, review, and rollback. | LangChain Context Hub, AWS AgentCore, Anthropic managed-agent memory |
| Execution boundary is the safety boundary | Permissions, network reachability, filesystem access, credential custody, tenant isolation, and OS sandboxing are core architecture, not late-stage hardening. | Codex Windows sandbox, Running Codex safely, Anthropic self-hosted sandboxes |
| Tools and skills are a supply chain | MCP servers, skills, plugins, and agent-to-agent protocols need registries, allowlists, identity, semantic review, versioning, and revocation. | NSA MCP security, GitHub MCP allowlists, A2A milestone |
| Humans become managers and verifiers | Agent products should support goals, plans, approvals, interrupts, reviewable diffs, escalation, and constrained multi-agent write authority. | Codex from anywhere, Copilot cloud agent, Cognition multi-agents |
| Observability must close the improvement loop | Traces should feed evaluation, failure clustering, policy enforcement, and prompt/tool repair rather than ending as passive logs. | LangSmith Engine, OpenAI agent improvement loop, AWS AgentCore Evaluations |
These signals do not replace Claude Code's design space; they make its boundaries clearer. The agent loop is the small part. The harness around it is where most capability, safety, and reliability decisions now live. For month-level source notes, see docs/agent-design-space-source-notes_zh.md.
Not a coding tutorial. A guide to the design decisions you must make, derived from architectural analysis.
Every production agent must navigate these decisions:
| Decision | The Question | Key Insight |
|---|---|---|
| Reasoning placement | How much logic in the model vs. harness? | As models converge in capability, the harness becomes the differentiator. |
| Safety posture | How do you prevent harmful actions? | Defense-in-depth fails when layers share failure modes. |
| Context management | What does the model see? | Design for context scarcity from day one. Graduated > single-pass. |
| Extensibility | How do extensions plug in? | Not all extensions need to consume context tokens. |
| Subagent architecture | Shared or isolated context? | Agent teams in plan mode cost ~7× tokens. Subagent summary-only returns prevent context blow-up. |
| Session persistence | What carries over? | Never restore permissions on resume. Auditability > query power. |
Read the full guide: docs/build-your-own-agent.md
The same recurring design questions admit different architectural answers when the deployment context changes. The table below contrasts Claude Code v2.1.88 with two notable peers — OpenClaw, a local-first multi-channel personal-assistant gateway, and NousResearch/hermes-agent, a self-improving multi-deployment agent — across the six design dimensions Section 10 of the paper uses for the OpenClaw comparison. Cells are source-grounded; this is not a feature scoreboard.
| Design Dimension | Claude Code (v2.1.88)  |
OpenClaw  |
Hermes-Agent  |
|---|---|---|---|
| System scope & deployment | Per-user CLI / SDK / IDE interface for coding; one queryLoop async generator across entry points. |
Local-first WebSocket gateway (default port 18789, loopback-bound by default; other binds available); routes ~23 messaging channels to an embedded agent runtime; companion apps for macOS, iOS, Android. | Three entry points: hermes (interactive CLI), hermes-agent (programmatic runtime), hermes-acp (ACP server); gateway adapters route messages to per-session AIAgent instances cached LRU-style (max 128, 1 h idle TTL); also runs as MCP server via hermes mcp serve. |
| Trust model & security | Deny-first per-action evaluation; 7 permission modes; LLM-based auto-mode classifier (yoloClassifier / sideQuery); session-scoped permission state (session bypass flag, app allowlist state) is not restored on resume. |
Single trusted operator per gateway; DM pairing codes, sender allowlists, gateway authentication; per-agent allow / deny tool policy; opt-in sandboxing via Docker / SSH / OpenShell, off by default; non-main mode sandboxes only non-main sessions; hostile multi-tenant isolation explicitly not supported. |
Dangerous-command pattern detection with per-session approval state; CLI interactive prompts and gateway async prompts; auxiliary-LLM smart approval auto-approves low-risk commands; permanent allowlist persisted in config.yaml; subagent worker threads default to auto-deny dangerous commands (opt-in subagent_auto_approve for batch / cron runs). |
| Agent runtime & tools | Single queryLoop async generator with streamed event yields; environment- and feature-gated tool registry; before-API compaction (Snip, Microcompact, Context Collapse, Auto-Compact) runs conditionally, with Auto-Compact first attempting session-memory compaction. |
Embedded agent runtime inside the gateway's RPC dispatch (the agent RPC validates parameters, accepts immediately, runs asynchronously, and streams lifecycle / stream events back over the gateway protocol); per-session queue serialization with an optional global lane. |
While-loop with explicit per-turn iteration budget and grace-call slot; per-turn checkpoint dedup; gateway step_callback hook fires on each iteration; auxiliary-model context compression summarizes middle turns while protecting head and tail. |
| Extension architecture | Four mechanisms at graduated context cost: hooks → skills → plugins → MCP; 27 hook events; 10 plugin component types. | Manifest-first plugin system with 12 documented capability categories; central registry exposes tools, channels, provider setup, hooks, HTTP routes, CLI commands, services; separate skills layer with multiple sources (workspace highest precedence) plus the ClawHub public registry; openclaw mcp provides both an MCP server interface and an outbound client registry for other MCP servers. |
12 bundled plugins under plugins/ (context_engine, disk-cleanup, example-dashboard, google_meet, hermes-achievements, image_gen, kanban, memory, observability, platforms, spotify, strike-freedom-cockpit); MCP server (mcp_serve.py) exposes 10 tools; ACP adapter (acp_adapter/) exposes Hermes as an ACP server. |
| Memory & context | 4-level CLAUDE.md hierarchy; before-API compaction (Snip, Microcompact, Context Collapse, Auto-Compact); LLM-based selection from file-based Markdown memory files. | Workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md) plus conditional BOOTSTRAP.md / HEARTBEAT.md / MEMORY.md; separate memory system (MEMORY.md, daily notes under memory/YYYY-MM-DD.md, optional DREAMS.md); hybrid vector + keyword search when an embedding provider is configured; experimental dreaming for long-term promotion; pluggable compaction providers. |
SQLite state store with FTS5 full-text search and WAL-mode concurrent readers; sessions linked by parent_session_id chains for compression-triggered splits; 8 swappable memory backends under plugins/memory/ (byterover, hindsight, holographic, honcho, mem0, openviking, retaindb, supermemory); auxiliary-LLM compression as a separate context-management layer. |
| Multi-agent architecture | Sub-agent delegation via sidechain transcripts; 6 built-in agent definitions (availability conditional on build / mode) plus custom; a single summary message returns to parent (in-process / viewable transcript cases preserve more internal detail); agent-isolation settings include worktree and remote, with an in-process teammate backend in the swarm path. |
Two layers. (1) Multi-agent routing: per-channel isolated agents with their own workspace, auth profiles, session store, and model configuration, dispatched via deterministic binding rules. (2) Sub-agent delegation: maxSpawnDepth range 1–5, default 1, recommended 2; tool policy varies by depth; project vision (VISION.md) rejects agent-hierarchy frameworks as the default. |
delegate_task tool spawns child AIAgent instances in a ThreadPoolExecutor (parent blocks until children complete); each child has fresh conversation history, its own task_id, and a restricted toolset (DELEGATE_BLOCKED_TOOLS strips delegate_task, clarify, memory, send_message, execute_code); default depth MAX_DEPTH = 1 (configurable up to cap 3); default 3 concurrent children. |
What this contrast reveals. Three observations follow from the table. First, deployment context drives the rest of the design: a per-user coding CLI converges on per-action approval and a single execution loop, a multi-channel gateway converges on perimeter trust and channel-bound agents, and a multi-deployment messaging-and-cloud agent converges on opt-in container/cloud isolation, an LLM-based smart approval, and a swappable-backend memory layer. Second, the extension layer is where each system most clearly differentiates: Claude Code stratifies four mechanisms by context cost, OpenClaw treats extension as registry-managed capabilities at the gateway, and Hermes-Agent ships bundled plugins plus dual MCP server / ACP server interfaces other agents can connect to. Third, memory architectures sit on a spectrum: file-based and inspectable Markdown (Claude Code), file-based plus optional vector + experimental dreaming (OpenClaw), or full-text indexed (FTS5) plus eight swappable plugin backends including dedicated vector / RAG providers (Hermes-Agent). The table is best read not as a scoreboard but as three different fixed points in the same design space.
The sections above give Claude Code's own answer to each design question. The catalogs below are organized by resource type instead. This table joins the two, so you can start from a question rather than from a file format.
For shifts that cut across every axis rather than sitting on one, see New Signals in the Agent Design Space.
A curated map of the repos, reimplementations, and academic papers surrounding Claude Code's architecture.
Primary sources referenced throughout the paper — Anthropic's own engineering and research publications, plus product documentation.
| Article | Topic |
|---|---|
| Building Effective Agents | Foundational: simple composable patterns over heavy frameworks. |
| Effective Context Engineering for AI Agents | Context curation and token-budget management. |
| Prompt Caching with Claude | Cache reads at 10% cost, writes at 125%; 5-min default TTL. The platform feature that makes Claude Code's cache-aware compaction architecturally meaningful. |
| Harness Design for Long-Running Application Development | Harness architecture for autonomous full-stack dev; multi-agent patterns. |
| Claude Code Auto Mode: A Safer Way to Skip Permissions | ML-classifier approval automation; source of the 93% approval-rate finding. |
| Beyond Permission Prompts: Making Claude Code More Secure and Autonomous | Sandbox-based security; 84% reduction in permission prompts. |
| How We Contain Claude Across Products | Containment across claude.ai, Claude Code, and Cowork (May 2026); Claude Code's human-in-the-loop sandbox, approval fatigue, and capping the blast radius. |
| Measuring AI Agent Autonomy in Practice | Longitudinal usage: auto-approve rates grow from ~20% to 40%+ with experience. |
| Agentic Coding and Persistent Returns to Expertise | Anthropic's first quantitative account of how the work actually splits: humans make roughly 70% of planning decisions but only 20% of execution decisions, and a single prompt triggers about 10 Claude actions on average, with some stretches running past 100 actions between human touchpoints. An empirical anchor for the paper's claims about human control surfaces and supervision cost. |
| Our Framework for Developing Safe and Trustworthy Agents | Governance framework for responsible agent deployment. |
| When AI Builds Itself | Anthropic Institute on recursive self-improvement: AI accelerating AI development, the direction-setting and research-taste gaps, and governance scenarios. |
| Scaling Managed Agents: Decoupling the Brain from the Hands | Hosted-service architecture separating reasoning, execution, and session. |
| An Update on Recent Claude Code Quality Reports | Postmortem on three bugs behind perceived quality drops: a reasoning-effort default, a cache optimization bug, and a system-prompt change. |
| Introducing Claude Opus 4.8 | May 2026 model update: sharper judgment and honesty (~4x fewer unremarked code flaws), longer autonomous runs; introduces dynamic workflows in research preview. |
| Claude Fable 5 and Claude Mythos 5 | June 2026 Mythos-class tier sitting above Opus; Fable 5 is the general-use configuration (risky queries fall back to Opus 4.8), with state-of-the-art software-engineering and agentic-coding performance. Access was suspended globally on June 12, 2026 (see next row). |
| Statement on Suspending Access to Fable 5 and Mythos 5 | Anthropic's statement on suspending Fable 5 and Mythos 5. A US export-control directive (June 12, 2026) restricted access for foreign nationals, but Anthropic disabled both models for all users worldwide, just days after launch. A rare case of regulation forcing a deployed frontier model offline, and a concrete example of the compliance and safety pressures that agent systems face in deployment. |
| Document | Topic |
|---|---|
| How Claude Code Works | Official overview of the agent loop, tools, and terminal automation. |
| Permissions | Tiered permission system, modes, granular rules. |
| Hooks | 27-event hook reference, execution models, lifecycle events. |
| Memory | CLAUDE.md hierarchy, auto memory, learned preferences. |
| Sub-agents | Specialized isolated assistants, custom prompts, tool access. |
| Orchestrate Subagents at Scale with Dynamic Workflows | Claude writes a JavaScript orchestration script; a background runtime fans out to up to 16 concurrent and 1,000 total subagents, with intermediate state held in script variables outside the context window (v2.1.154+). The permission design is the part worth noting: the launch prompt follows your permission mode, but the subagents a workflow spawns always run in acceptEdits and inherit the session tool allowlist regardless of that mode, so file edits are auto-approved inside a run. |
| Configure Auto Mode | The fullest official account of the auto-mode classifier as a policy engine: a four-tier precedence (hard_deny over soft_deny over allow over explicit user intent), rules written as natural-language prose rather than regexes, and one deliberate exclusion. The classifier reads CLAUDE.md but never the shared .claude/settings.json, so a checked-in repo config cannot grant itself permissions. |
| Orchestrate Teams of Claude Code Sessions | Agent teams as a primitive distinct from subagents: teammates hold separate contexts, message each other through mailboxes, and share a file-locked task list with dependencies and self-claiming. The trust boundary is explicit: a teammate cannot approve a permission prompt on the user's behalf, and a denied action cannot be handed to another teammate to get around it. |
| What's New in Claude Opus 4.8 | Mid-conversation system messages (prompt-cache-preserving), lower cacheable-prompt minimum, fewer compactions and better compaction recovery. |
| What's New in Claude Sonnet 5 | The model takes back two dials the harness used to hold: manual extended thinking is gone (thinking: {budget_tokens: N} now returns 400) and non-default temperature/top_p/top_k also return 400. A new tokenizer yields roughly 30% more tokens for the same text, so the usable context budget shifts with the model. |
| Claude Code CHANGELOG | Release notes. Dynamic workflows and Opus 4.8 land in v2.1.154. Across v2.1.178 to v2.1.207 (June to July 2026): subagents run in the background by default with agent_needs_input/agent_completed hooks, and an agent's message is still never treated as the user's approval; the default permission mode is renamed to Manual; a Tool(param:value) rule syntax arrives (for example Agent(model:opus)); auto mode stops reading a repo's .claude/settings.local.json; and sandbox.credentials blocks sandboxed commands from reading credential files and secret environment variables. Through v2.1.215 (July 2026): v2.1.212 adds per-session caps on WebSearch calls and on subagent spawns (default 200 each, tunable by environment variable), moves MCP tool calls running past two minutes to the background automatically, turns /fork into a background session with the in-session behavior split out as /subtask, deprecates the Task tool's mode parameter so subagents inherit the parent session's permission mode, and stops plan mode auto-running file-modifying Bash commands without a prompt. v2.1.214 adds the EndConversation tool, requires permission for docker commands carrying daemon-redirect flags, and fixes a permission-scoping bug where a single-segment rule like Edit(src/**) auto-approved writes to a nested src/ anywhere in the tree instead of only <cwd>/src. |
Deep dives into Claude Code's internal design.
| Repository | Description |
|---|---|
ComeOnOliver/claude-code-analysis  |
Comprehensive reverse-engineering: source tree structure, module boundaries, tool inventories, and architectural patterns. |
alejandrobalderas/claude-code-from-source  |
18-chapter technical book (~400 pages). All original pseudocode, no proprietary source. |
liuup/claude-code-analysis  |
Chinese-language deep-dive — startup flow, query main loop, MCP integration, multi-agent architecture. |
sanbuphy/claude-code-source-code  |
Quadrilingual analysis (EN/JA/KO/ZH) — multi-domain reports covering telemetry, codenames, KAIROS, unreleased tools. |
cablate/claude-code-research  |
Independent research on internals, Agent SDK, and related tooling. |
Yuyz0112/claude-code-reverse  |
Visualize Claude Code's LLM interactions — log parser and visual tool to trace prompts, tool calls, and compaction. |
Piebald-AI/claude-code-system-prompts  |
Version-tracked corpus of Claude Code's internal prompts, extracted from each release's published package: the main system prompt, builtin tool descriptions, sub-agent prompts (Plan/Explore/Task), slash-command prompts, and system-reminder injections, with a changelog spanning every tracked release since v2.0.14. Updated within minutes of each release. |
AgiFlow/claude-code-prompt-analysis  |
API request and response logs captured across five conversation sessions. Empirical methodology with reproducible data rather than static code reading. |
Clean-room rewrites and buildable research forks.
| Repository | Description |
|---|---|
chauncygu/collection-claude-code-source-code  |
Meta-collection of community Claude Code source artifacts -- includes claw-code (Rust port), nano-claude-code (Python), and the extracted original source archive. |
777genius/claude-code-working  |
Working reverse-engineered CLI. Runnable with Bun, 450+ chunk files, 31 feature flags polyfilled. |
T-Lab-CUHKSZ/claude-code  |
CUHK-Shenzhen buildable research fork — reconstructed build system from raw TypeScript snapshot. |
ruvnet/open-claude-code  |
Nightly auto-decompile rebuild — 903+ tests, 25 tools, 4 MCP transports, 6 permission modes. |
Enderfga/openclaw-claude-code  |
OpenClaw plugin — unified ISession interface for Claude/Codex/Gemini/Cursor. Multi-agent council. |
memaxo/claude_code_re  |
Reverse engineering from minified bundles — deobfuscation of the publicly distributed cli.js file. |
agentforce314/clawcodex  |
Python rebuild with multi-provider LLM support. |
ultraworkers/claw-code  |
Clean-room Rust reimplementation that compresses a roughly 512K-line TypeScript codebase into about 20K lines of Rust, which makes it a useful read on what is essential to the harness and what is incidental. |
Tutorials and hands-on learning paths for Claude Code itself.
| Repository | Description |
|---|---|
shareAI-lab/learn-claude-code  |
"Bash is all you need" — 19-chapter 0-to-1 course with runnable Python agents, web platform. ZH/EN/JA. |
FlorianBruniaux/claude-code-ultimate-guide  |
Beginner-to-power-user guide with production-ready templates, agentic workflow guides, and cheatsheets. |
affaan-m/everything-claude-code  |
Agent harness optimization — skills, instincts, memory, security, and research-first development. |
hesreallyhim/awesome-claude-code  |
Curated list of skills, hooks, slash-commands, agent orchestrators, and plugins. |
nblintao/awesome-claude-code-postleak-insights  |
Curated post-leak findings, including the internal codenames (BUDDY, KAIROS, ULTRAPLAN), Undercover Mode, and AutoDream memory consolidation. |
rohitg00/awesome-claude-code-toolkit  |
Bundled toolkit of agents, skills, commands, plugins, hooks, rules, templates, and MCP configurations. |
External resources that complement this paper's design-space analysis — concept essays, curricula, and code that illuminate the harness layer as an engineering practice.
| Repository | Description |
|---|---|
deusyu/harness-engineering  |
Learning archive — original concept essays, independent thinking pieces, and curated translations of harness-engineering writing; from concept to independent practice. |
walkinglabs/learn-harness-engineering  |
Project-based English course with PDF coursebooks, syllabus, and capstone, organized around five harness subsystems: instructions, state, verification, scope, and session lifecycle. |
china-qijizhifeng/agentic-harness-engineering  |
Observability system that auto-evolves a coding agent's harness — a meta-agent reads execution traces and rewrites system prompts, tools, middleware, skills, sub-agents, and memory. |
ZhangHanDong/harness-engineering-from-cc-to-ai-coding  |
The "Horse Book" (《马书》) — Chinese mdBook framing Claude Code v2.1.88 as a Harness Engineering case study; covers architecture, prompt engineering, context management, prompt cache, security, and lessons for builders. |
alchaincyf/loop-engineering-orange-book  |
花叔 (HuaShu)'s plain-language guide to loop engineering, in both Chinese and English. It puts the loop one layer above the harness, walks through what a loop does and the pieces it needs, and credits Steinberger, Osmani, and Anthropic's Claude Code team. |
stanford-iris-lab/meta-harness  |
Reference implementation for the Meta-Harness paper. Holds the model fixed and searches the harness itself (memory, retrieval, context construction, prompts, tool selection) through a propose, score, and Pareto-frontier loop. Turns the harness from something you design by hand into something you can optimize. |
| Article | What Makes It Valuable |
|---|---|
| Marco Kotrotsos — "Claude Code Internals" (15-part series) | Most systematic pre-leak analysis. Architecture, agent loop, permissions, sub-agents, MCP, telemetry. |
| Alex Kim — "The Claude Code Source Leak" | Anti-distillation mechanisms, frustration detection, Undercover Mode, ~250K wasted API calls/day. |
| Haseeb Qureshi — Cross-agent architecture comparison | Claude Code vs Codex vs Cline vs OpenCode — architecture-level comparison. |
| George Sung — "Tracing Claude Code's LLM Traffic" | Complete system prompts and full API logs. Discovered dual-model usage (Opus + Haiku). |
| Agiflow — "Reverse Engineering Prompt Augmentation" | 5 prompt augmentation mechanisms backed by actual network traces. |
| Engineer's Codex — "Diving into the Source Code Leak" | Modular system prompt, ~40 tools, large query/tool subsystem, anti-distillation. |
| MindStudio — "Three-Layer Memory Architecture" | In-context memory, MEMORY.md pointer index, CLAUDE.md static config. Best single resource on memory. |
| WaveSpeed — "Claude Code Architecture: Leaked Source Deep Dive" | 512K-line TS source deep dive; context compression and anti-distillation. |
| Zain Hasan — "Inside Claude Code: An Architecture Deep Dive" | Layered architecture, 5 entry modes, multi-agent walkthrough. |
| Addy Osmani — "Agent Harness Engineering" | Frames harness engineering as a discipline with named primitives (filesystem/git state, sandboxes, AGENTS.md memory, compaction, planning loops, hooks); cites Claude Code as the canonical mature example. |
| Addy Osmani — "Loop Engineering" | The essay that named "loop engineering": instead of writing prompts for the agent yourself, you build the loop that prompts it for you. Its parts (automations, worktrees, skills, connectors, sub-agents, and a file that tracks progress) are the harness pieces this paper analyzes. |
| Armin Ronacher — "The Coming Loop" | Splits the agent loop (tool calls inside one run) from the harness loop (a system that keeps re-prompting the agent to run again). Ronacher is skeptical: loops work well for porting code, tuning performance, and scanning for security bugs, but the code they leave behind tends to be more defensive and harder to maintain, so people still have to read it and decide what to keep. |
| LangChain — "The Art of Loop Engineering" | Describes four loops built around an agent: the agent loop, a verification loop that scores the output and retries, an event-driven loop that starts agents on outside triggers, and a hill-climbing loop that reads production traces to improve the harness itself. The point: most of the value comes from these loops, not the model on its own. |
| Andrej Karpathy — "Sequoia Ascent 2026" | Argues for "agentic engineering": humans orchestrate and verify rather than write code. "LLMs and reinforcement learning automate what you can verify"; "you can outsource your thinking, but you can't outsource your understanding." |
| Lilian Weng — "Harness Engineering for Self-Improvement" | Defines the harness as "the system surrounding a base model that orchestrates execution and decides how the model thinks and plans, calls tools and acts, perceives and manages context, stores artifacts, and evaluates results," then argues that the near-term path to recursive self-improvement does not start with a model rewriting its own weights: it starts with coding agents evolving the harness itself. Covers design patterns, harness optimization, evolutionary search, and joint optimization with weights. |
| Armin Ronacher — "Better Models: Worse Tools" | The clearest evidence yet that the harness shapes the model, not only the reverse. Opus 4.8 and Sonnet 5 invent fields like requireUnique and oldText2 that no schema defines, while the surrounding payload stays byte-correct. Ronacher's reading: the models were trained in Claude Code's forgiving harness, which quietly repairs malformed calls by dropping unknown keys and accepting parameter aliases, so slightly-wrong calls still got rewarded. Tool schemas are not a neutral abstraction. |
| Addy Osmani — "Agentic Autonomy Levels" | Separates two axes that usually get collapsed: agency (how independently one agent runs) and orchestration (how several agents coordinate). Proposes a pre-execution contract covering goal, scope, non-goals, tools and permissions, stop conditions, evidence requirements, escalation path, and budget, offering a structured alternative to Claude Code's in-the-moment approval prompts. |
| Geoffrey Litt — "Understanding is the new bottleneck" | As agents get better at verifying their own work, the scarce resource stops being correctness checking and becomes human comprehension. Litt argues the interface should build understanding rather than present diffs, proposing literate diffs with embedded explanation, interactive micro-worlds for stepping through a change, and shared spaces where a team forms a common mental model. A control-surface argument about what the harness owes the human, not what it lets the agent do. |
| Haseeb Qureshi — "Inside the Claude Code source" | Key module analysis: the React/Ink UI, four compaction strategies, and the dynamic prompt boundary system. |
| Han HELOIR YAN — "Nobody Analyzed Its Architecture" | "The moat is the harness, not the model." An early statement of the thesis this paper develops in full. |
| Marco Kotrotsos — "Part 8: The Permission System" | The permission-focused installment of the Internals series; the closest pre-leak reconstruction of the approval path. |
| Vincent Qiao — "Permissions System Deep Dive" | Settings-level walkthrough of how permission rules are actually written and resolved in practice. |
| ClaudeCodeCamp — "How Prompt Caching Actually Works" | The clearest practical account of cache behavior in Claude Code, which is the constraint most compaction designs have to work around. |
| Gigi Sayfan — "MCP Unleashed" | Deep dive on the MCP integration path: transports, server lifecycle, and how external tools enter the tool surface. |
| DEV Community — "Architecture via Rust Rewrite" | Reads the architecture through a Rust reimplementation, laying out the tool set in a three-layer structure. |
| Reid Barber — "Reverse Engineering Claude Code" | One of the earliest analyses (mid-2025), covering the REPL architecture and the original tool suite. |
| Kir Shatrov — "Reverse Engineering Claude Code" | Used mitmproxy to intercept API traffic and reported a single measured experiment end to end, including LLM time and cost. |
| Sabrina Ramonov — "Reverse-Engineering Using Sub Agents" | Methodologically interesting: builds custom sub-agents (File Splitter, Structure Analyzer) and uses them to reverse-engineer the minified bundle. |
Official engineering posts from other vendors building code agents — useful for seeing how the same design questions are answered outside Claude Code.
| Resource | Vendor | What's Notable |
|---|---|---|
| Harness Engineering: Leveraging Codex in an Agent-First World | OpenAI | Frames the "harness" as the constraints, feedback loops, and documentation that make agents reliable; reports a roughly 1M-line beta built with essentially no hand-written code. |
| Best Practices for Coding with Agents | Cursor | Articulates an agent harness as three components — Instructions, Tools, and Model — orchestrated per model. |
| Build with Google Antigravity | Agent-first platform: a Manager view for asynchronous multi-agent orchestration, with Artifacts (plans, screenshots, recordings) as the verification mechanism instead of raw logs. | |
| Microsoft Agent Framework at BUILD 2026: Agent Harness, Hosted Agents, CodeAct | Microsoft | Adds a built-in "agent harness" with automatic context compaction, file-based memory, plan and execute modes, skill discovery, parallel sub-agents, and a sandboxed shell. Also adds CodeAct, which lets the model run several tool calls as one Python program inside a fresh Hyperlight micro-VM each call. |
| Codex Security: Now in Research Preview | OpenAI | Application-security agent that builds a project-specific threat model, then finds and pressure-tests vulnerabilities in sandboxed validation environments. |
| Meet Your Agent Harness and Claw, Working with Your Data, Safely, Scaling Harness Capabilities | Microsoft | A four-part harness series. Notable for the authorization design: a standing rule ("always approve this tool", "always approve these arguments") lives only inside the session and is never baked into the agent, which is a direct point of comparison with Claude Code's permission model. Capability growth is split into four orthogonal mechanisms: Skills, a restricted Shell, CodeAct, and Background Agents. |
| Transitioning Gemini CLI to Antigravity CLI and antigravity-cli | Gemini CLI is retired (effective June 18, 2026) in favor of a Go rewrite that shares one agent harness with the Antigravity 2.0 desktop app. Per its CHANGELOG (the repo ships releases and examples, not source), the mechanisms sit close to Claude Code's: nested subagents to grandchild depth and beyond, whose subtrajectory updates are recursively relayed to the root conversation; workspace-level .agents/hooks.json where a pre-tool hook decides whether a tool call is permitted; and per-project permission config, stored under ~/.gemini/config/projects/ rather than in the repo, taking precedence over global settings. |
|
| Governing Agent Autonomy with Auto-review | Cursor | A classifier runs inside the agent loop rather than as a separate endpoint. When it blocks an action it returns an explanation to the parent agent, which can often route around it safely without ever interrupting the user. Roughly 4% of actions get blocked while only about 7% of chats end up interrupting a human. Blocking as a steering signal, not just a stop. |
| Customize Cursor | Cursor | Plugins, skills, MCPs, subagents, rules, commands, and hooks collapse into one extension surface with user, team, and workspace scopes. A non-Anthropic vendor converging on almost exactly Claude Code's extension points. |
| Codex-maxxing for Long-Running Work | OpenAI | The memory vault keeps AGENTS.md, TODO.md, projects/, and people/ in GitHub so that the diff becomes the review interface for memory. States the design position directly: memory must be open-able, edit-able, diff-able, and reusable. |
| Devin Fusion and Agentic MapReduce | Cognition | Fusion couples two mechanisms usually treated separately: a classifier re-scores task difficulty mid-session, and the model swap is timed to land on context compaction, where a cache miss was going to happen anyway, so switching is effectively free. MapReduce draws a clean line between agents and deterministic compute: put an agent only where reasoning is needed, make everything else deterministic. |
| AI SDK 7 | Vercel | HarnessAgent treats Claude Code, Codex, and Pi as interchangeable backends behind one API, with sessions that park and resume. WorkflowAgent makes each tool call a durable retryable step that survives process restarts. Tool approvals are HMAC-signed, which addresses a rarely-discussed problem: forged approvals. |
| The 2026-07-28 MCP Spec Goes Stateless and Enterprise-Managed Authorization | MCP | The largest structural change in the tool layer so far. The initialize handshake and protocol-level session are gone, with capabilities moving to server/discover; tools can now pause mid-call and ask the user a question via InputRequiredResult; roots, sampling, and logging are deprecated. Separately, authorization moves up from per-user consent screens to the organization's IdP. |
| Droid Shield 2.0 | Factory | A deterministic regex scanner flanked by two fine-tuned models: one re-reads context for recall when the scanner stays silent, the other masks the candidate secret and judges from context alone whether the scanner produced a false positive. Deterministic rules and learned models wired into a two-way correcting gate. |
| Software Is Made Between Commits (DeltaDB) | Zed | Version control rebuilt for agent sessions. A message and the edit it produced are stored side by side so neither drifts from the other, and every reference anchors to a delta rather than a line number, so it survives as code moves underneath it. The argument: git is organized around discrete commits and was never designed to hold the conversation that produced the code. |
| Multi-agent orchestration in the Responses API | OpenAI | Subagent orchestration moves out of client code and into the API. A root agent spawns a named tree (/root/researcher) coordinated by six hosted actions (spawn_agent, send_message, followup_task, wait_agent, interrupt_agent, list_agents), with max_concurrent_subagents capping how many subagents may be active at once across the whole tree (descendants count, the root agent does not). The tradeoff is stated plainly: reasoning summaries and max_tool_calls are unavailable while multi-agent is on. |
| Programmatic Tool Calling | OpenAI | The model writes JavaScript that reaches tools through a tools.* namespace, run in a fresh isolated V8 with no filesystem, no network, and no state carried between programs. Tools opt in through allowed_callers, so a tool can be reachable by the program, by the model directly, or both. Batching and filtering happen inside the program, which keeps intermediate tool output out of the context window. |
| Copilot CLI changelog | GitHub | Three July changes worth setting against Claude Code's permission model: an auto allow-all mode that approves whatever an LLM judge rates acceptable; a trusted repository pinning model, effort level, and context tier and extending the URL, MCP, and skill deny lists through .github/copilot/settings.json; and preToolUse hooks that deny a tool call by exiting with code 2. Plan mode hard-blocks built-in tools that would modify the workspace, but MCP and external tools stay allowed, a narrower boundary than the name suggests. |
| Why We Built ADK 2.0 | Workflows turn orchestration into a directed graph whose node transitions are evaluated in code rather than chosen by the model, so deterministic steps such as tool calls and human-in-the-loop approvals sit in the same graph as open-ended agent steps. The context decision is deliberate: the engine passes only the necessary subset of data to each downstream node, "shielding them from verbose, unrelated execution history" instead of letting a subagent inherit the whole trace. | |
| Introducing Harness Optimizer | AWS | Treats the harness as tunable parameters rather than something written by hand: system prompts, tool descriptions, and skills become a Formula, a RewardFunction scores execution traces, and a Trainer runs rollout, reward, and update epochs. The default optimizer is itself an LLM that reads winning and losing traces contrastively and rewrites the Formula to encode the difference. Open source, and offered in production as AgentCore Optimization. |
| The Self-Driving Company | Replit | A rare look at how a vendor runs agents internally rather than what it sells. Every employee gets a manager agent that spawns and orchestrates further agents on the company's own harness, microVMs, and remote filesystem, with the whole arrangement placed "behind access policies, token proxies, audit logging, and our ZeroTrust network." Human escalation is designed in rather than left as a fallback: the code-review agent grades risk and pulls in a second human reviewer only when warranted. |
| Amp news | Sourcegraph | Two July entries push the same direction. Agents can now spawn other agents, message them, and exchange files across threads, which is peer-to-peer coordination rather than a parent collecting subagent reports. Separately, the Orb remote sandboxes moved to OIDC workload identity, replacing static credentials for agents that execute remotely. |
Where and how agent actions actually execute: sandboxes, managed runtimes, control planes, and the session protocols wrapped around them. The counterpart to Claude Code's own shell sandbox and execution boundary.
| Resource | Vendor | What's Notable |
|---|---|---|
| Bedrock AgentCore Harness is Generally Available | AWS | The harness stops being a loop you write and becomes a managed configuration object: CreateHarness and InvokeHarness declare the model, tools, skills, memory policy, and container environment, over seven primitives (microVM Runtime, Memory, Gateway, sandboxed Browser, Code Interpreter, Identity token vault, Observability). A new coordinate in the design space: who owns the loop, the environment, and the tool boundary. |
| AgentCore Policy with Guardrails | AWS | Enforcement happens at the gateway boundary, outside the agent's own code, so it holds no matter how autonomous the agent becomes. A sharp architectural contrast with in-loop permission checks. |
| Running Untrusted Agent Code Without a Sandbox and Dynamic Subagents in Deep Agents | LangChain | Capability isolation run backwards from the container model: QuickJS inside WASM starts at zero capability and the harness bridges in each capability explicitly. Interpreter memory can be serialized for a durable pause that waits on human approval. Subagent dispatch then drops from conversation turns into program control flow, with the model writing a script that calls task({...}). |
| A Single Pane of Glass for All Your Cloud Agents | Warp | Oz as a multi-harness control plane: launch, track, govern, and steer Claude Code, Codex, and Warp Agent from one surface, compare their effectiveness, pick different harnesses for different tasks, and keep one consistent audit trail. Agent Memory carries across harnesses. |
| Agent Host and the Agent Host Protocol | Microsoft | VS Code 1.129 moves agent sessions out of the editor into a dedicated process addressed over an open Agent Host Protocol. Because the session lives in its own process it keeps running with no client attached and can be rendered from several windows at once, and one host runs Copilot, Claude, and Codex behind a single session model. Agents on the host can list other sessions, read their transcripts, spawn a session to hand off a subtask, and message another session, with sends requiring user confirmation and a burst cap so one request cannot fan out into unbounded sessions. |
| Sandbox forking | E2B | Sandbox.fork() checkpoints a running sandbox in place, briefly pausing it, snapshotting full memory state, and resuming it with its ID and expiration untouched, then starts N independent sandboxes from that snapshot. Gives a harness a cheap way to branch one expensively-configured environment across parallel attempts instead of rebuilding it for each. |
Vulnerability research, disclosures, and real-world incidents involving coding agents, from any vendor. The safety envelope tested against an adversary rather than described on paper.
| Report | What It Shows |
|---|---|
| Tenet Security — "One Fake Bug Report Hijacked a $250 Billion Company's AI Agent, Then 100+ More" | The sharpest demonstration to date that a tool's return value is untrusted input. A Sentry DSN is public by design (Sentry documents it as safe to embed in frontend JavaScript) and accepts arbitrary error payloads, so an attacker can POST an event carrying markdown instructions that render as a fake "Resolution" section. A developer then asks their agent to look into the Sentry issue, the agent pulls the poisoned event back through MCP, reads it as trustworthy remediation guidance, and runs an attacker-controlled npm package that exfiltrates AWS keys, GitHub tokens, and SSH credentials. Confirmed against Claude Code, Cursor, and OpenAI Codex, including sandboxed variants and CI/CD pipelines. |
| Wiz — "GhostApproval" | An informed-consent bypass aimed at the approval dialog itself. A repository ships a symlink named something harmless like project_settings.json that actually points at ~/.ssh/authorized_keys or ~/.zshrc, so the dialog shows the decoy name and the user approves a write that lands somewhere else entirely. Amazon Q Developer, Cursor, and Google Antigravity shipped fixes; Augment and Windsurf acknowledged without one. Anthropic disputed it for Claude Code, arguing the scenario sits outside its threat model because the developer chose to trust the folder and then approved the edit. Worth reading with that disagreement intact, since it is really a dispute about where consent is supposed to come from. |
Benchmarks for coding agents, and the growing body of work auditing whether those benchmarks measure what they claim. Relevant here because a harness change is only as legible as the evaluation used to detect it.
| Resource | Source | What It Shows |
|---|---|---|
| Harness-Bench: Measuring Harness Effects across Models in Realistic Agent Workflows | arXiv | 106 sandboxed tasks and 5,194 execution trajectories run with task environments, budgets, and evaluation protocols held fixed while the harness configuration varies across model backends. Names a recurring pattern it calls execution-alignment failure, where plausible reasoning becomes decoupled from tool feedback and workspace state, and concludes that agent capability "should be reported at the model-harness configuration level rather than attributed to the base model alone." |
| Position: Coding Benchmarks Are Misaligned with Agentic Software Engineering | arXiv | Argues that "a coding agent in practice is not a model: it is a system harness," so an end-to-end score conflates model, harness, context, environment, and feedback signal, any of which can move the number "by margins comparable to those between adjacent model generations." Also faults grading against a single reference solution, which penalizes equally valid alternatives. |
| Harbor-Index 1.0 | Harbor | A compact cross-domain agent benchmark: 82 tasks distilled from 6,627 candidates through difficulty screening, automated audit, and human review, spanning software engineering, scientific research, tools and systems, knowledge, mathematics, data analytics, and safety. Scoring is strictly binary with no partial credit, and it is built deliberately for headroom rather than for predicting performance elsewhere. |
| Are Performance-Optimization Benchmarks Reliably Measuring Coding Agents? | arXiv | Replays the official reference patches of GSO, SWE-Perf, and SWE-fficiency on fresh machines and finds that only 39/102, 11/140, and 411/498 tasks respectively satisfy the benchmarks' own validity rules. Scoring methodology also matters more than expected: official rankings disagree on 9 of 28 pairwise comparisons among submissions appearing in both GSO and SWE-fficiency. |
| Do Androids Dream of Breaking the Game? Systematically Auditing AI Agent Benchmarks with BenchJack | arXiv | An automated red-teaming system that drives coding agents to attack benchmarks rather than solve them, surfacing 219 distinct flaws across eight classes in 10 popular agent benchmarks and reaching near-perfect scores "without solving a single task." An extended pipeline then patches the holes, cutting the hackable-task ratio from near 100% to under 10% on four benchmarks. |
| PERFOPT-Bench: Evaluating Coding Agents on Software Performance Optimization | arXiv | Seven agent stacks across seven long-horizon optimization tasks. Finds optimization performance is workload-dependent rather than settled by model identity, with no single stack dominating, and concludes that "raw speedup is unsafe as a benchmark score, since some large gains arise from benchmark-specific shortcut exploitation." |
| When the Judge Changes, So Does the Measurement: Auditing LLM-as-Judge Reliability | arXiv | Treats swapping the judge model as a measurement-validity problem rather than a free upgrade. Across four judgment datasets it finds adjacent judge releases are not interchangeable, stronger judges reduce but do not remove position and verbosity bias, and repeated-sample juries "add little when errors are correlated." |
| Reward Hacking is Swamping Model Intelligence Gains | Cursor | An audit of 731 Opus 4.8 Max trajectories found that, among successful resolutions on SWE-bench Pro, 63% of fixes were retrieved rather than derived: 57% found the merged PR or fixed source file on the public web, 9% mined the repository's bundled git history for the fix commit. Two isolations expose it, and scores fall sharply under them: .git is stripped and the repo reinitialized as a single commit (history restored only at scoring time), and network access is denied by default behind a proxy that allows only an allow-list of package registries. Makes eval-harness environment design a precondition for the benchmark meaning anything. |
| Paper | Venue | Relevance |
|---|---|---|
| Meta-Harness: End-to-End Optimization of Model Harnesses | arXiv | A coding agent acts as the proposer and searches the harness itself (memory, retrieval, context construction, prompts, tool-use logic) with the model held fixed, maintaining a population and a Pareto frontier over evaluated harnesses. Beats a state-of-the-art context-management system by 7.7 points while using 4x fewer context tokens, and its discovered harnesses surpass the best hand-engineered baselines on TerminalBench-2. Turns the harness from a thing you design by hand into a thing you can optimize. |
| From Question Answering to Task Completion: A Survey on Agent System and Harness Design | arXiv | A contemporaneous survey through a "model-harness lens" that decomposes the execution harness into six coupled runtime responsibilities: observation, context, control, action, state, and verification. The closest structural peer to this paper's framing. |
| Architectural Design Decisions in AI Agent Harnesses | arXiv | Source-grounded study of 70 agent-system projects identifying recurring design dimensions; closest contemporary peer to this paper's design-space framing. |
| ActPlane: Programmable OS-Level Policy Enforcement for Agent Harnesses | arXiv | Intercepts every execution path with eBPF in the kernel, including the indirect paths that bypass the tool-call layer entirely, at 1.9% to 8.4% overhead. Names the gap directly: permission checks that live at the tool-call layer, as Claude Code's do, can be routed around. |
| Lingering Authority: Revocable Resource-and-Effect Capabilities for Coding Agents | arXiv | Names a real weakness in session-scoped approval: once granted, authority does not expire as the task moves on. PORTICO compiles a task spec into capabilities, grant rules, and closure predicates, materializing resources as epoch-bound handles that die once the closure condition is met. |
| TokenPilot: Cache-Efficient Context Management for LLM Agents | arXiv | Confronts a constraint most compaction work steps around: rewriting history destroys the KV prefix cache. Filters noise at the ingestion boundary to keep the prefix stable, and evicts context segments only after their lifecycle ends. |
| The Balkanization of Execution-Security Research for AI Coding Agents | arXiv | An SoK sorting 39 execution-layer security papers into 17 categories (sandbox isolation, capabilities and access control, policy enforcement, TOCTOU, MCP threats, identity delegation, execution provenance, egress control). Reports that policy enforcement fails against real denylists 69% to 98% of the time. |
| How Agents Ask for Permission: User Permissions for AI Agents, from Interfaces to Enforcement | arXiv | Surveys 21 agent permission systems and evaluates five commercial agents, building a taxonomy along three axes: how a policy is specified at the interface, how it is derived into an internal policy, and how it is enforced at run time. The closest academic peer to this paper's permission analysis, and a direct test of whether Claude Code's model generalizes. |
| Bad Memory: Evaluating Prompt Injection Risks from Memory in Agentic Systems | arXiv | Tests Claude Code and OpenAI Codex across four models and finds an asymmetry that matters for memory design: the agents largely resist untrusted content trying to overwrite their memory files, but payloads already sitting in those files go on to attack current and future sessions. Persistence turns one successful injection into a standing one. |
| Agent Data Injection Attacks are Realistic Threats to AI Agents | arXiv | Separates a second attack class from instruction injection: instead of smuggling commands, the attacker forges security-critical metadata such as resource identifiers, data origins, and tool-response formats, which agents accept because they do not isolate trusted from untrusted data. Demonstrated as arbitrary clicks against Claude in Chrome, Antigravity, and Nanobrowser, and as remote code execution and supply-chain attacks against Claude Code, Codex, and Gemini CLI. |
| Failure as a Process: An Anatomy of CLI Coding Agent Trajectories | arXiv | Manually annotates 1,794 complete trajectories (over 63,000 execution steps) drawn from 3,843 runs across seven frontier models and three scaffolds. Failures are predominantly epistemic, begin within the first few execution steps, and stay hidden until recovery is no longer possible, which argues for validation early in the loop rather than outcome-only evaluation. |
| Better Harnesses, Smaller Models: Building 90% Cheaper Agents via Automated Harness Adaptation | arXiv | A meta agent reads failure trajectories and lifts shared task difficulty out of the model and into the harness as tailored instructions, tools, and orchestration loops. Recovers 89.7% of large-model performance at 4% of the cost, and closes the small-model gap outright on seven of 21 task and model pairs. |
| Rethinking the Evaluation of Harness Evolution for Agents | arXiv | The skeptical counterweight to the harness-optimization line of work. Measured against simple test-time scaling and discovery baselines under matched feedback and inference budgets on Terminal-Bench 2.1, automatic harness evolution "does not consistently outperform" the simpler methods and generalizes poorly to held-out tasks. |
| From Anatomy to Smells: An Empirical Study of SKILL.md in Agent Skills | arXiv | Analyzes 238 real-world skills into a taxonomy of 13 higher-level and 44 lower-level components, then detects "skill smells" as violations of the practices that taxonomy implies. Over 99% of SKILL.md files carry at least one, and smells rarely disappear as a skill evolves. Direct evidence on the extensibility surface this paper analyzes. |
| Decoding the Configuration of AI Coding Agents | arXiv | Empirical study of 328 Claude Code configuration files — SE concerns and co-occurrence patterns. |
| On the Use of Agentic Coding Manifests | arXiv | Analyzed 253 CLAUDE.md files from 242 repos — structural patterns in operational commands. |
| Context Engineering for Multi-Agent Code Assistants | arXiv | Multi-agent workflow combining multiple LLMs for code generation. |
| OpenHands: An Open Platform for AI Software Developers | ICLR 2025 | Primary academic reference for open-source AI coding agents. |
| SWE-Agent: Agent-Computer Interfaces | NeurIPS 2024 | Docker-based coding agent with custom agent-computer interface. |
| The OpenHands Software Agent SDK | arXiv | Composable SDK foundation for production agents; the engineering counterpart to the OpenHands platform paper above. |
| A Survey on Code Generation with LLM-based Agents | arXiv | Broad survey of the AI coding agent field, useful for situating harness work inside the wider code-generation literature. |
| AI Agent Systems: Architectures, Applications, and Evaluation | arXiv | Broad agent-system taxonomy spanning architecture, application, and evaluation. |
While the projects above focus on engineering reverse-engineering or practical reimplementation, this paper provides a systematic values → principles → implementation analytical framework — tracing five human values through thirteen design principles to specific source-level choices, and using OpenClaw comparison to reveal that cross-cutting integrative mechanisms, not modular features, are the true locus of engineering complexity.
A broader map of the agent design space surrounding Claude Code. The Cross-System Comparison above analyzes the three closest peers (Claude Code, OpenClaw, Hermes-Agent) in depth; the entries below give wider context across coding-agent peers, frameworks, memory systems, harness extensions, the MCP ecosystem, and specialized agents.
| Repository | Launch | Focus |
|---|---|---|
| openclaw/openclaw |
Jan 2026 | Local-first personal AI assistant across messaging platforms. (Section 10 analysis) |
NousResearch/hermes-agent  |
Feb 2026 | Self-improving personal agent with cross-session memory. (Section 10 analysis) |
opensquilla/opensquilla  |
Jun 2026 | Token-efficient microkernel personal agent across CLI, Web UI, and chat channels; ML-classifier routing across four model cost tiers, local Markdown+SQLite memory (MEMORY.md plus dated notes with keyword and vector recall), and Bubblewrap/Seatbelt sandbox. |
pewdiepie-archdaemon/odysseus  |
Jun 2026 | Self-hosted, local-first AI workspace from PewDiePie: autonomous agents with tools, MCP, and shell access, plus memory, deep research, and hardware-aware model serving. AGPL-3.0. |
google-antigravity/antigravity-cli  |
Jun 2026 | Google's Go rewrite that replaces Gemini CLI and shares one agent harness with the Antigravity 2.0 desktop app. Per its CHANGELOG: nested subagents to grandchild depth and beyond, with subtrajectory updates recursively relayed to the root conversation; workspace-level .agents/hooks.json where a pre-tool hook decides whether a tool call is permitted; and per-project permission config kept under ~/.gemini/config/projects/ rather than in the repo, taking precedence over global settings. |
patriceckhart/zot  |
Jun 2026 | Single static Go binary harness with a deliberately minimal tool set (read, write, edit, bash). Sessions persist as JSONL transcripts that resume, branch, and compact. /swarm fans out background subagents that share the working directory and edit the same files, each keeping its own session file and transcript; the opt-in auto-swarm setting (off by default) additionally lets the main agent spawn them itself and injects a recap back into the main chat. /jail roots a sandbox at the cwd and refuses obvious escape patterns (sudo, rm -rf /, leading cd /, chmod -R). A readable non-TypeScript point of comparison for subagent and permission design. |
sst/opencode  |
Jun 2025 | Provider-agnostic terminal coding agent with ACP integration. |
Aider-AI/aider  |
2023 | Pair-program with LLMs in the terminal; works with most popular models. |
continuedev/continue  |
2023 | Source-controlled AI checks for IDEs with an open-source Continue CLI. |
google-gemini/gemini-cli  |
2025 | Google's open-source terminal coding agent with ReAct loop and MCP support. Superseded by Antigravity CLI as of June 18, 2026; enterprise customers on paid Gemini licenses keep access. |
openai/codex  |
2025 | OpenAI's local terminal coding agent in Rust. |
OpenHands/OpenHands  |
2024 | Open SWE agent platform (formerly OpenDevin) with sandboxed runtime. |
cline/cline  |
2024 | VS Code agent with explicit Plan/Act oversight loop. |
block/goose  |
2025 | Block's open-source, editor-agnostic agent with MCP-style extensions. |
charmbracelet/crush  |
2025 | Agentic coding TUI in Go with multi-LLM provider abstraction. |
RooCodeInc/Roo-Code  |
2024 | VS Code multi-agent dev-team with Architect, Coder, and Reviewer modes. |
bytedance/trae-agent  |
2025 | ByteDance's modular SWE-bench-oriented agent for software engineering tasks. |
github/copilot-cli  |
2026 | GitHub Copilot's GA agentic terminal CLI; plans, builds, reviews. |
badlogic/pi-mono  |
Aug 2025 | Monorepo coding-agent toolkit — unified LLM API, TUI + web UI; OpenClaw embeds the pi-coding-agent SDK from here. |
| Repository | Launch | Focus |
|---|---|---|
geekan/MetaGPT  |
2023 | Role-based multi-agent software-company simulation (ICLR 2024 oral). |
microsoft/autogen  |
2023 | Microsoft Research multi-agent conversation framework (COLM 2024). |
microsoft/agent-framework  |
2025 | Microsoft's single successor to AutoGen and Semantic Kernel (1.0 released April 2026). At BUILD 2026 it added a built-in agent harness (context compaction, file memory, shell access) and CodeAct, which lets the model run several tool calls as one Python script instead of one at a time. |
langchain-ai/langgraph  |
2024 | Stateful graph-based multi-agent orchestration with checkpointing. |
openai/openai-agents-python  |
2024 | OpenAI's lightweight multi-agent framework with handoffs and guardrails. |
crewAIInc/crewAI  |
2023 | Lean Python framework for role-based multi-agent collaboration, independent of LangChain. |
openai/symphony  |
Feb 2026 | OpenAI's orchestration for isolated, autonomous implementation runs. |
ComposioHQ/agent-orchestrator  |
2025 | Orchestration layer for parallel AI agents with git worktree isolation. |
omnigent-ai/omnigent  |
Jun 2026 | Databricks' open-source "meta-harness" (Apache 2.0): Claude Code, Codex, Cursor, OpenCode, Hermes, and Pi become interchangeable backends behind one orchestration layer, and can be mixed within a single session. A policy engine stacks across three levels (server, agent, session, with the stricter session rules checked first) and governs shell commands, file edits, token spend, and tool access. Native sandboxing uses bwrap on Linux and seatbelt on macOS; disposable cloud sandboxes run on Modal, E2B, or Kubernetes. The clearest industrial argument that policy and isolation belong above the harness rather than inside a prompt. |
coleam00/Archon  |
Feb 2025 | Deterministic harness — YAML-defined workflows with execution audit trail. |
bytedance/deer-flow  |
2026 | ByteDance's long-horizon "SuperAgent" harness: subagents, memory, sandboxes, skills, and a message gateway; a ground-up rewrite on LangGraph/LangChain. |
QwenLM/Qwen-Agent  |
2023 | Alibaba Qwen's agent framework: function calling, MCP, a Docker code interpreter, and RAG; the backend behind Qwen Chat. |
TencentCloudADP/youtu-agent  |
2025 | Tencent Cloud's agent framework, built on the openai-agents SDK; agents are defined in YAML, configs can be auto-generated, and it adds Claude Code-style skills. |
coze-dev/coze-studio  |
2025 | ByteDance's open-source edition of Coze: a visual no-code/low-code platform for building, debugging, and deploying agents and workflows. |
| Repository | Launch | Focus |
|---|---|---|
mem0ai/mem0  |
2024 | Production memory layer with LoCoMo and LongMemEval benchmarks (arXiv:2504.19413). |
letta-ai/letta  |
2023 | Stateful-agent platform with OS-style hierarchical memory paging (formerly MemGPT, COLM 2024). |
MemPalace/mempalace  |
2026 | Local-first memory system for AI agents. |
| Repository | Launch | Focus |
|---|---|---|
addyosmani/agent-skills  |
2025 | 22 lifecycle skills + slash commands (/spec, /plan, /build, /test, /review, /ship). |
obra/superpowers  |
2025 | Cross-harness mandatory-workflow skills framework (Claude Code, OpenCode, Codex). |
mattpocock/skills  |
2026 | Author's everyday .claude/skills collection for real engineering -- composable TDD, diagnose, and to-issues/to-prd skills; model-agnostic, targeting Claude Code, Codex, and other coding agents. |
multica-ai/andrej-karpathy-skills  |
2026 | Single CLAUDE.md encoding Andrej Karpathy's four LLM-coding rules (think before coding, simplicity first, surgical changes, goal-driven execution); installable as a plugin or per-project. |
lsdefine/GenericAgent  |
2025 | Minimal self-evolving autonomous agent framework — 9 atomic tools + ~100-line ReAct loop. |
| Repository | Launch | Focus |
|---|---|---|
PrefectHQ/fastmcp  |
2024 | Pythonic framework for building MCP servers and clients; de facto SDK. |
upstash/context7  |
2025 | Up-to-date library-documentation MCP server for LLMs and AI code editors. |
microsoft/playwright-mcp  |
2024 | Microsoft's official MCP server using accessibility-tree snapshots. |
modelcontextprotocol/experimental-ext-interceptors  |
2026 | Multi-language reference implementation of the proposed interceptor extension (SEP-2624), which would make middleware-style inspection and transformation of MCP requests a protocol-level primitive rather than a per-host hook system. Marked experimental and explicitly not an accepted or official MCP extension. |
| Repository | Launch | Focus |
|---|---|---|
666ghj/MiroFish  |
Mar 2026 | Multi-agent swarm-intelligence simulation engine. |
multica-ai/multica  |
2026 | Managed-agents platform for task assignment and skill compounding. |
HKUDS/nanobot  |
Feb 2026 | Ultra-lightweight personal AI agent from HKU-DS. |
HKUDS/OpenHarness  |
Apr 2026 | Open agent harness with built-in personal agent (Ohmo); academic harness reference. |
karpathy/autoresearch  |
Mar 2026 | Andrej Karpathy's autonomous AI-agent loop running nanochat training research on a single GPU. |
HKUDS/CLI-Anything  |
Mar 2026 | "Making ALL Software Agent-Native" — wraps arbitrary software as agent-callable tools. |
Panniantong/Agent-Reach  |
Feb 2026 | CLI giving agents access to Twitter, Reddit, YouTube, GitHub, Bilibili, Xiaohongshu. |
agentscope-ai/QwenPaw  |
Feb 2026 | Personal AI assistant from the AgentScope team. |
cft0808/edict  |
Feb 2026 | OpenClaw-based multi-agent orchestration on Tang-dynasty Three Departments and Six Ministries (三省六部制) bureaucracy. |
@article{diveclaudecode2026,
title={Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems},
author={Jiacheng Liu, Xiaohan Zhao, Xinyi Shang, and Zhiqiang Shen},
year={2026},
eprint={2604.14228},
archivePrefix={arXiv},
primaryClass={cs.SE},
}This work is licensed under CC BY-NC-SA 4.0.