98.4% Harness

When a play works, the audience claps for the actor. Nobody claps for the rigging, the lighting board, or the stage manager whispering cues in the dark — the crew that did most of the work and gets none of the credit. Agentic AI runs the same way, and a new paper just measured how lopsided the split really is.

I build with AI agents most days, and the same questions keep circling back. Where should the model actually think? How much of the wheel do I hand it? What snaps first when a task runs long? Everyone has an answer, and almost every answer is opinion, because the systems we point at are sealed shut. You can read the pitch. You cannot read the source.

So when a paper landed that reverse-engineers Claude Code — the agent I lean on hardest — straight out of its shipped TypeScript, I couldn’t not read it. This is post one of a series where I work through it part by part, because I don’t actually understand a thing until I write it down for someone else. Hand-waving survives a hallway chat; it does not survive a paragraph. And here’s my confession up front: for as long as I’ve used it, I’ve handed the model credit for work it never did, and this series is me correcting the ledger. Call it scar tissue.

First, what this paper is not

Before a single finding is worth repeating, you have to know what you’re holding. The paper is “Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems” (Liu, Zhao, Shang et al., April 2026), with source and notes mirrored at github.com/VILA-Lab/Dive-into-Claude-Code.

It is a reconstruction. The authors pulled Claude Code’s TypeScript out of a public npm package — one snapshot, version 2.1.88, roughly 1,884 files and 512,000 lines — and read the whole thing. Nobody at Anthropic handed them a diagram. This is not official documentation, and that is not a footnote to skim past. It sets a ceiling on how hard any single claim can lean.

So the authors grade their own evidence, and I’ll carry the grading through every post:

• Tier A — product-documented: Anthropic said it, so it tells you intent, not implementation.
• Tier B — code-verified: they found it in the source, and this is the strongest kind.
• Tier C — inferred from patterns or community analysis; useful, hedged, never load-bearing alone.

Keep those three letters handy. The headline number in the next section is Tier C, and I’ll say so out loud rather than let an estimate calcify into a fact it hasn’t earned.

The performer is 1.6% of the show

Here’s the number the title is built on. By a community estimate of the extracted source, about 1.6% of the codebase is AI decision logic. The other ~98.4% is operational harness — the deterministic machinery wrapped around the model (§3.1, §12.1).

Flag it before you quote it: that split is Tier C. It’s an estimate over reconstructed code, not something Anthropic published or the authors formally counted, and I wouldn’t defend the exact decimal to anyone. But the precise digit isn’t the point — the shape is. The center of gravity is not the model call. It’s everything staged around the model call.

Because the model call really is that plain. Strip Claude Code to its spine and it’s a while loop — an async generator the paper names queryLoop() — that asks the model what to do, runs the tool it named, feeds the result back, and asks again. The model never touches your machine; it emits tool_use blocks and stops, and the harness parses them, checks them against permissions, and decides whether anything runs at all. That seam buys a real security property: a compromised or jailbroken model still can’t widen its blast radius past the harness to cancel a deny rule or climb out of the sandbox (§3.1). Authority lives in code you can audit, not weights you can’t.

Anthropic describes the tool internally as “a Unix utility rather than a traditional product” (§2.1), and you can read that bet in the tool count: a full internal build exposes up to 54 tools (19 always on, 35 gated behind flags or user type), while a stripped-down mode runs on as few as 3 (§3.3, Appendix). Most of that surface isn’t intelligence. It’s stagecraft.

Five rooms behind the curtain

If nearly all the code is harness, the fair question is: harness for what? The paper splits the system into five layers — the map for everything that follows. I go deep on each later; here I just want you to know the floor plan.

%%{init: {"flowchart": {"wrappingWidth": 280}}}%%
flowchart TD
    U(["you"]) --> S
    S["<b>SURFACE</b><br/>how you reach it"]
    C["<b>CORE</b><br/>the while-loop — the 1.6%"]
    A["<b>SAFETY / ACTION</b><br/>what's allowed to run"]
    ST["<b>STATE</b><br/>what it knows and keeps"]
    B["<b>BACKEND</b><br/>where actions land"]
    S --> C --> A --> ST --> B
    classDef you fill:#f3f4f6,stroke:#9ca3af,color:#111827
    classDef surface fill:#dbeafe,stroke:#2563eb,color:#111827
    classDef core fill:#fed7aa,stroke:#ea580c,color:#111827,stroke-width:3px
    classDef safety fill:#fecaca,stroke:#dc2626,color:#111827
    classDef state fill:#bbf7d0,stroke:#16a34a,color:#111827
    classDef backend fill:#ede9fe,stroke:#7c3aed,color:#111827
    class U you
    class S surface
    class C core
    class A safety
    class ST state
    class B backend

Top to bottom, that’s the architecture. Surface is every way you reach it, and the quiet surprise is that all four surfaces (terminal, headless claude -p, the Agent SDK, the IDE) run the same loop — only the rendering changes. Core is that loop plus the pipeline that keeps the context window from overflowing. Safety/action is where a proposed call gets vetted: permission modes, hooks, the sandbox, the subagent machinery. State is memory in the wide sense — context assembly, what CLAUDE.md adds, what survives to disk. Backend is where an approved action lands. Each one is a post; the job of this one is to show they exist at all, and that the design lives there, not in the model.

One cue, and the whole crew moves

Layers stay abstract until you watch a request move through them, so here’s the one the paper threads from §3 to §9: “Fix the failing test in auth.test.ts.”

You type it. Surface hands it to the loop; State assembles what the model will see — system prompt, your CLAUDE.md, the files that matter — and packs the window. Core calls the model, and the model does the only thing it’s allowed to: it proposes. Every proposal stops at safety/action before it runs — a Read waves through, a Bash call gets sandboxed or bounced to you — and only a call that clears the gate reaches backend and executes. The result flows back into the loop, the model reads the failure and proposes an Edit, clears the gate again, and around it goes until the suite passes or a stop condition ends the turn.

sequenceDiagram
    actor You
    participant H as Harness
    participant M as Model
    participant Sh as Shell / tools
    You->>H: "Fix the failing test in auth.test.ts"
    H->>M: assemble context, ask what to do
    M-->>H: propose Read auth.test.ts, then run the tests
    Note over H: permission gate — Read allowed, Bash sandboxed or asks
    H->>Sh: run the approved calls
    Sh-->>H: test output (still failing)
    H->>M: here is the result
    M-->>H: propose an Edit to fix it
    Note over H: permission gate again
    H->>Sh: apply edit, re-run tests
    Sh-->>H: tests pass
    H-->>You: done
    Note over M: the model only proposes — the harness disposes

Notice what never happened. The model never edited a file. It never ran a command. It proposed, every turn, and the harness disposed. That is the 1.6% and the 98.4% in motion.

The four questions the whole series keeps asking

A source teardown earns eight posts instead of one because the paper isn’t really cataloguing features. It’s using Claude Code to answer questions every agent system has to answer, whether its builders wrote them down or not. Four of them anchor the rest (§3.1):

1. Where does reasoning live? Here the model reasons and the harness executes — a clean seam, where other systems fuse the two or hand control to an explicit planning graph. This is the question that 1.6% / 98.4% ratio is really answering.
2. How many execution engines? One: that single queryLoop() serves every surface. A system could run a separate engine per interface, but Claude Code deliberately refuses to.
3. What’s the default safety posture? Deny-first — deny beats ask beats allow, and anything unrecognized escalates to you, the opposite of allow-now, apologize-later. (Escalating to a human who rubber stamps everything is its own problem, and that’s a later post.)
4. What’s the binding constraint? The context window: 200K tokens on older models, 1M on the Claude 4.6 series. Nearly every core-layer choice exists to ration that scarcity, which is why five separate compaction strategies run before every model call.

Hold those four. When the final post lines Claude Code up against OpenClaw and Hermes Agent, the whole story is that they answer these same four questions differently, because they’re built for different worlds. The questions are stable; the answers are contextual. That gap is the “design space” the title points at.

Why the crew is the interesting part

It’s tempting to read “1.6% is the AI” as a letdown, like the trick is smaller than the poster promised. I read it the other way, and there’s evidence for that.

Hold the model perfectly fixed. Change only the harness around it. On one long-horizon benchmark, a single model’s score swings by as much as 18 points (§12.1). Same weights, different stagecraft, wildly different outcome. The harness is not overhead sitting on top of the intelligence — it’s a large slice of where the usable capability comes from. And for those of us who build these systems, that’s oddly hopeful: the weights are Anthropic’s to improve, but the harness is ours to shape.

Which sets up the one genuinely provocative thread, and I’ll flag it hard as Tier C — this is the authors reasoning, not code they verified. As models get dramatically better, does the harness stop mattering? Their answer is mostly no. Only one of the system’s five values, capability amplification, is really sensitive to raw model strength; the other four — safety, human authority, adaptability, plain token economics — don’t dissolve when the model gets smarter. A frontier model still can’t void a deny rule, still spends tokens you pay for, still has to fit your conventions. They point at harness choice alone moving even a very strong model’s pass rates by ten points or more. Inferred, not proven. But it’s the question this series keeps circling, and I’ll come back to it at the end.

The payoff isn’t abstract. Anthropic’s own survey of 132 engineers found ~27% of Claude Code-assisted tasks were work that wouldn’t have been attempted at all without the tool (§1) — not faster work, work that otherwise wouldn’t have happened. That’s what a good harness buys, and why the 98% deserves a closer look than the 2%.

The performer is easy. The crew is the job.

The teardown’s first lesson is almost anticlimactic: the smart part of Claude Code is a small, plain loop, and the reason the thing feels dependable is the unglamorous 98% built around it. The performer takes the bow. The crew runs the show.

That rewired my mental model. The whole time, I’d been handing the model credit for work the harness was quietly doing — the permission checks that kept me safe, the compaction that held long sessions together, the isolation that kept a subagent from poisoning my context. I’m going to reassign that credit for the rest of the series, one layer at a time.

Next post: the core layer. The one loop, and the five things it does to your context before it ever calls the model.

So here’s what to sit with, whatever agent you lean on. The model is not the part that most decides whether it works. The 98.4% you never look at is. How much of what you call “the model being smart” is really the crew doing its job — and when it fails you, would you even know which one to blame?

Notes: the sections I cited

Each §-marker above points to a part of the paper. Here’s the key, and where the series takes each one further:

• §1 — Introduction: the arc from autocomplete to agentic tools, and the survey of 132 engineers where ~27% of tasks “would not have been attempted” without Claude Code.
• §2.1 — The five values: Human Decision Authority, Safety, Reliable Execution, Capability Amplification, Contextual Adaptability, plus the “Unix utility” framing. (Post 2 goes deep.)
• §3.1 — The four design questions and the ~1.6% / 98.4% decision-vs-harness split (Tier C).
• §3.2 — The seven-component structure (Figures 1–2): user, interfaces, loop, permissions, tools, state, execution environment.
• §3.3 — The five-layer decomposition (Figure 3): the surface / core / safety / state / backend map drawn above.
• §12.1 — Design philosophy: why the harness carries so much capability (the 18-point swing) and the Tier-C “is the harness still needed for a much better model?” argument. (Post 8 closes on it.)
• Appendix — Evidence base: the A/B/C tiers, and the ~1,884-file / ~512K-line source corpus everything here is reconstructed from.

Everything else — the loop internals, the permission layers (§5), extensibility (§6), memory (§7), subagents and persistence (§8–§9), the three-system comparison (§10) — gets its own post. That’s the series.