Claude Code's Leaked Source: A Real-World Masterclass in Harness Engineering

Earlier this year, Mitchell Hashimoto coined the term "harness engineering" — the discipline of building everything around the model that makes an AI agent actually work in production. OpenAI wrote about it. Anthropic published guides. Martin Fowler analyzed it.

After studying Claude Code's leaked source — particularly its memory system, caching architecture, and security layers — the harness turns out to be far more interesting than the LLM calls themselves.

The Evolution: From Prompt to Harness

The AI engineering discipline has shifted rapidly:

2023-2024: Prompt Engineering → "How to ask the model" 2025: Context Engineering → "What information to feed the model" 2026: Harness Engineering → "How the entire system runs around the model"

2023-2024: Prompt Engineering → "How to ask the model" 2025: Context Engineering → "What information to feed the model" 2026: Harness Engineering → "How the entire system runs around the model"

Enter fullscreen mode

Exit fullscreen mode

Prompt engineering is the question. Context engineering is the blueprint. Harness engineering is the construction site — tools, permissions, safety checks, cost controls, feedback loops, and state management that let the agent operate reliably.

The leaked Claude Code source is a concrete case study for each of these harness layers.

Prompt Cache Economics: A Cost Center, Not an Optimization

One of the most revealing modules is promptCacheBreakDetection.ts. It tracks 14 distinct cache invalidation vectors and uses "sticky latches" — mechanisms that prevent mode switches from breaking cached prompt prefixes.

┌─────────────────────────────────────────────────┐ │ Prompt Cache Layer │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Vector 1│ │ Vector 2│ │Vector 14│ ... │ │ │ Mode │ │ Tool │ │ Context │ │ │ │ Switch │ │ Change │ │ Rotate │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌──────────────────────────────────────┐ │ │ │ Sticky Latch Layer │ │ │ │ "Hold current prefix until forced" │ │ │ └──────────────────────┬───────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ Cache Decision │ │ │ │ KEEP / BREAK │ │ │ └─────────────────┘ │ └─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐ │ Prompt Cache Layer │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Vector 1│ │ Vector 2│ │Vector 14│ ... │ │ │ Mode │ │ Tool │ │ Context │ │ │ │ Switch │ │ Change │ │ Rotate │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌──────────────────────────────────────┐ │ │ │ Sticky Latch Layer │ │ │ │ "Hold current prefix until forced" │ │ │ └──────────────────────┬───────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ Cache Decision │ │ │ │ KEEP / BREAK │ │ │ └─────────────────┘ │ └─────────────────────────────────────────────────┘

Enter fullscreen mode

Exit fullscreen mode

This reframes prompt caching from a performance trick into a billing optimization problem. At scale, each cache miss is real money. The code treats cache management with the same rigor as database query planning — monitoring invalidation patterns, measuring hit rates, and making explicit keep-or-break decisions.

The takeaway for agent builders: if your agent makes repeated API calls (and it does), prompt caching is not optional — it's a cost center that needs active management.

Multi-Agent Coordination: The Prompt IS the Harness

Claude Code's sub-agent system is internally called "swarms." The surprising part: coordination between agents is not handled by a state machine, a DAG executor, or an orchestration framework. It's done through natural language prompts.

┌───────────────────────────────────────────┐ │ Main Agent (Orchestrator) │ │ │ │ System prompt includes: │ │ - "Do not rubber-stamp weak work" │ │ - Tool permission boundaries │ │ - Task decomposition strategy │ │ │ │ ┌──────────┼──────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Sub- │ │ Sub- │ │ Sub- │ │ │ │ Agent A │ │ Agent B │ │ Agent C │ │ │ │ │ │ │ │ │ │ │ │ Isolated│ │ Isolated│ │ Isolated│ │ │ │ Context │ │ Context │ │ Context │ │ │ │ Scoped │ │ Scoped │ │ Scoped │ │ │ │ Tools │ │ Tools │ │ Tools │ │ │ └─────────┘ └─────────┘ └─────────┘ │ └───────────────────────────────────────────┘

┌───────────────────────────────────────────┐ │ Main Agent (Orchestrator) │ │ │ │ System prompt includes: │ │ - "Do not rubber-stamp weak work" │ │ - Tool permission boundaries │ │ - Task decomposition strategy │ │ │ │ ┌──────────┼──────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Sub- │ │ Sub- │ │ Sub- │ │ │ │ Agent A │ │ Agent B │ │ Agent C │ │ │ │ │ │ │ │ │ │ │ │ Isolated│ │ Isolated│ │ Isolated│ │ │ │ Context │ │ Context │ │ Context │ │ │ │ Scoped │ │ Scoped │ │ Scoped │ │ │ │ Tools │ │ Tools │ │ Tools │ │ │ └─────────┘ └─────────┘ └─────────┘ │ └───────────────────────────────────────────┘

Enter fullscreen mode

Exit fullscreen mode

Each sub-agent runs in an isolated context with specific tool permissions. The orchestrator coordinates them through instructions embedded in prompts — quality standards, scope boundaries, conflict resolution rules. All in natural language.

This is a strong signal: for LLM-based multi-agent systems, traditional orchestration frameworks may add unnecessary complexity. The model already understands natural language instructions. Why build a state machine when a well-written prompt can express the same coordination logic?

Memory and State: Progressive Disclosure at Every Layer

One of the more practical patterns in the codebase is the file-based memory system with progressive disclosure.

The design uses a two-tier structure:

┌──────────────────────────────────────────────┐ │ Memory Architecture │ │ │ │ Tier 1: Index (always loaded) │ │ ┌──────────────────────────────────────┐ │ │ │ MEMORY.md │ │ │ │ │ │ │ │ - [User role](user_role.md) — ... │ │ │ │ - [Testing](feedback_test.md) — ... │ │ │ │ - [Auth rewrite](project_auth.md) │ │ │ │ │ │ │ │ Cost: ~200 tokens (one-line hooks) │ │ │ └──────────────────────────────────────┘ │ │ │ │ Tier 2: Full content (loaded on demand) │ │ ┌────────────┐ ┌────────────┐ ┌──────────┐ │ │ │user_role.md│ │feedback_ │ │project_ │ │ │ │ │ │test.md │ │auth.md │ │ │ │ Full user │ │ Full test │ │ Full │ │ │ │ context │ │ guidelines │ │ context │ │ │ │ (~500 tok) │ │ (~300 tok) │ │(~400 tok)│ │ │ └────────────┘ └────────────┘ └──────────┘ │ │ │ │ Only fetched when the index line matches │ │ the current task context │ └──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐ │ Memory Architecture │ │ │ │ Tier 1: Index (always loaded) │ │ ┌──────────────────────────────────────┐ │ │ │ MEMORY.md │ │ │ │ │ │ │ │ - [User role](user_role.md) — ... │ │ │ │ - [Testing](feedback_test.md) — ... │ │ │ │ - [Auth rewrite](project_auth.md) │ │ │ │ │ │ │ │ Cost: ~200 tokens (one-line hooks) │ │ │ └──────────────────────────────────────┘ │ │ │ │ Tier 2: Full content (loaded on demand) │ │ ┌────────────┐ ┌────────────┐ ┌──────────┐ │ │ │user_role.md│ │feedback_ │ │project_ │ │ │ │ │ │test.md │ │auth.md │ │ │ │ Full user │ │ Full test │ │ Full │ │ │ │ context │ │ guidelines │ │ context │ │ │ │ (~500 tok) │ │ (~300 tok) │ │(~400 tok)│ │ │ └────────────┘ └────────────┘ └──────────┘ │ │ │ │ Only fetched when the index line matches │ │ the current task context │ └──────────────────────────────────────────────┘

Enter fullscreen mode

Exit fullscreen mode

The index (MEMORY.md) is always loaded into the context window — cheap, at ~200 tokens. Full memory files are only fetched when a one-line hook in the index matches the current task. This keeps the context window lean while still giving the agent access to rich historical context when needed.

This is essentially the same pattern as database indexing: maintain a small, fast lookup structure that points to larger data. Applied to LLM context windows, it's a practical solution to the "agents forget everything between sessions" problem without paying the token cost of loading everything upfront.

The memory system also categorizes memories by type — user preferences, feedback corrections, project context, external references — each with different update and retrieval patterns. This is more sophisticated than a flat memory store and mirrors how humans organize knowledge.

Security: 23 Checks and Adversarial Hardening

Every bash command execution passes through 23 security checks. This is not a theoretical threat model — it's the result of real-world adversarial usage.

The defenses include:

• Zero-width character injection — invisible Unicode characters that can alter command semantics

• Zsh expansion tricks — shell-specific syntax that can escape sandboxes

• Native client authentication — a DRM-style mechanism where the Zig HTTP layer computes a hash (cch=56670 placeholder replaced at transport time) to verify client legitimacy

User Input  │  ▼ ┌──────────────────────┐ │ 23 Security Checks │ │ │ │ • Zero-width chars │ │ • Zsh expansion │ │ • Path traversal │ │ • Injection patterns│ │ • ...19 more │ │ │ └──────────┬───────────┘  │  PASS? │  ┌─────┴─────┐  │ │  YES NO  │ │  ▼ ▼  Execute Block +  Command Log Event

User Input  │  ▼ ┌──────────────────────┐ │ 23 Security Checks │ │ │ │ • Zero-width chars │ │ • Zsh expansion │ │ • Path traversal │ │ • Injection patterns│ │ • ...19 more │ │ │ └──────────┬───────────┘  │  PASS? │  ┌─────┴─────┐  │ │  YES NO  │ │  ▼ ▼  Execute Block +  Command Log Event

Enter fullscreen mode

Exit fullscreen mode

The lesson: agent security is not just sandboxing. It's adversarial input hardening at every boundary. If an agent can execute shell commands, assume someone will try to make it execute the wrong ones — intentionally or not.

When NOT to Call the Model

Claude Code detects user frustration using regex, not LLM inference.

Patterns like "wtf", "so frustrating", "this is broken" are matched via simple pattern rules and trigger tone adjustments in subsequent responses. No API call needed.

This sounds almost trivially simple. But it embodies a core harness engineering principle: use the cheapest, fastest tool that solves the problem.

The codebase applies this principle consistently:

Task Solution Why not LLM?

Frustration detection Regex Fast, free, reliable enough

Terminal rendering React + Ink with Int32Array buffers Rendering is a solved problem

Cache invalidation tracking Dedicated TS module Deterministic logic, no ambiguity

Client auth Zig HTTP layer hash Security must be deterministic

LLM calls are reserved for tasks that genuinely require language understanding. Everything else uses conventional engineering. A $0 regex beats a $0.01 model call when accuracy is comparable.

The Rendering Layer: Game Engine Meets Terminal

An unexpected finding: the CLI terminal interface is built with React + Ink and uses game-engine-style rendering optimizations.

The implementation uses Int32Array buffers and patch-based updates — similar to how game engines minimize draw calls by only updating changed pixels. The team claims this achieves ~50x fewer stringWidth calls during token streaming.

This makes sense when you think about it. A terminal UI streaming LLM output has similar challenges to a game render loop: frequent partial updates, variable-length content, frame-rate sensitivity. The harness applies domain-appropriate engineering rather than treating the terminal as an afterthought.

The Big Picture: Model as Commodity, Harness as Moat

The leaked source paints a clear picture of where the real engineering effort lives in a production AI agent:

┌─────────────────────────────────────────────────┐ │ Agent Harness │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Cache │ │ Security │ │ Tool Orchestration│ │ │ │ Economics│ │ Hardening│ │ & Permissions │ │ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Memory & │ │ State │ │ Multi-Agent │ │ │ │ Retrieval│ │ Persist │ │ Coordination │ │ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Cost │ │ UI/UX │ │ Observability │ │ │ │ Control │ │ Rendering│ │ & Logging │ │ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ │ │ ┌──────────────┐ │ │ │ LLM API │ │ │ │ (the easy │ │ │ │ part) │ │ │ └──────────────┘ │ │ │ └─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐ │ Agent Harness │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Cache │ │ Security │ │ Tool Orchestration│ │ │ │ Economics│ │ Hardening│ │ & Permissions │ │ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Memory & │ │ State │ │ Multi-Agent │ │ │ │ Retrieval│ │ Persist │ │ Coordination │ │ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Cost │ │ UI/UX │ │ Observability │ │ │ │ Control │ │ Rendering│ │ & Logging │ │ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ │ │ ┌──────────────┐ │ │ │ LLM API │ │ │ │ (the easy │ │ │ │ part) │ │ │ └──────────────┘ │ │ │ └─────────────────────────────────────────────────┘

Enter fullscreen mode

Exit fullscreen mode

The LLM API call is the smallest box. Everything around it — caching, memory, security, cost control, rendering, coordination — is the actual product.

For anyone building AI agents: the model selection matters less than you think. The harness is where the engineering lives — and where the differentiation happens.