Teardown: Claude Code, Codex, and the Open Harnesses

Reading time ~18 min · Last reviewed Sep 2026 · Quiz at the end

Lesson 23 read one harness end to end: DeepSeek's dsh, where every subsystem is a plugin and the session event log is the single source of truth. This lesson does the opposite. It reads across many harnesses at once (Claude Code and the Claude Agent SDK, OpenAI's Codex, and a set of open harnesses: OpenCode, Pi, OpenHands, Qwen Code, Kimi Code, and LangChain's Deep Agents) and asks, dimension by dimension, where they agree and where they made different bets. One harness teaches you one team's answers. Eight at once show you which questions every team had to answer, and which answers have hardened into conventions.

One caution before the tables. These products ship weekly. Every claim below links a primary source (vendor engineering posts, official docs, or the repository itself) and reflects what those sources said in September 2026. Where I could not verify something from a primary source, the table says "not documented" rather than guessing. Treat the cells as a dated snapshot and the rows as the durable part.

Reading a harness: the ten dimensions

Lesson 2 introduced the seven subsystems of a harness. For comparing shipping products, it helps to cut the same material slightly differently, into ten questions you can ask of any harness and answer from its docs:

1. Loop and protocol. How does a turn run, and how do clients talk to the loop?
2. Context and compaction. How is the prompt assembled, how is the cache protected, and what happens when the window fills?
3. Memory files. Which instruction files load, from where, in what order, with what budget?
4. Tool surface. What does the model get out of the box?
5. Extension model. Hooks, plugins, skills, MCP: how do you change behavior without forking?
6. Permissions and sandbox. Who decides whether an action runs, and what enforces the boundary?
7. Subagents. Can the agent delegate, with what isolation and limits?
8. Surfaces and embedding. Where does it run, and can you put it inside your own product?
9. Telemetry and data flows. What leaves the machine by default?
10. License. Can you read, fork, and redistribute it?

The tool-surface row is deliberately thin in what follows. Lesson 2 already has the cross-harness tool table (file system, shell, dev IO, MCP and skills, web, delegation), and the convergence it describes holds for every product here. The interesting differences are in the other nine rows.

The comparison

Three tables, same rows. The first covers the two frontier-lab harnesses, the second and third the open ones.

Claude Code and Codex

OpenCode, Pi, OpenHands

Qwen Code, Kimi Code, Deep Agents

Loop and protocol: one harness behind every surface

The most consequential architectural fact in the tables is easy to miss because it lives in the plumbing. Both frontier labs run one harness behind every surface they ship. OpenAI says so directly: the web app, CLI, IDE extension, and macOS app are all powered by the same Codex harness, and the App Server is "the critical link between them" (OpenAI, Feb 2026). They first tried exposing Codex as an MCP server for the VS Code extension, found MCP semantics a poor fit for streaming diffs and approvals, and built a JSON-RPC protocol that mirrored the TUI loop instead. Its three primitives are worth stealing for any agent API: an Item (typed unit of input or output with started, delta, completed events), a Turn (the work triggered by one user input), and a Thread (the durable, resumable, forkable container). Approvals are server-initiated requests that pause the turn until the client answers. That MCP-server path has since been removed from the product entirely (Codex SDK docs).

Anthropic arrived at the same shape from a different direction. Claude Code's docs state the loop is identical across terminal, desktop, IDE, web, Slack, and CI (Claude Code docs), and the Agent SDK is not a reimplementation but a library that runs the Claude Code binary (SDK overview). Managed Agents then pushes the harness out of the sandbox altogether. The harness became stateless, the session became a durable event log outside the context window, and sandboxes became "cattle" reached through a generic execute(name, input) tool. Anthropic reports p50 time-to-first-token fell roughly 60% and p95 by more than 90%, because sessions no longer waited for a container to boot before thinking (Anthropic, Apr 2026).

The open harnesses converge on the same idea at smaller scale. OpenCode's TUI is literally a client of a local HTTP server with a published OpenAPI spec (OpenCode docs). Pi's print, JSON, RPC, and SDK modes "use the same agent and session mechanisms" (Pi docs). And dsh, from lesson 23, reaches it through profiles over a plugin graph. The lesson for your own harness: separate the loop from the UI on day one, with a protocol between them that has explicit item lifecycles and server-initiated approval requests. OpenAI's own TUI began as a special case that talked to core types directly, and OpenAI says it plans to refactor it onto the App Server like any other client.

Context: caching discipline and compaction

OpenAI's loop post is the clearest public statement of a rule lesson 6 covers in general form: keep the old prompt an exact prefix of the new one. Codex deliberately does not use server-side conversation state, keeping every request stateless for Zero Data Retention customers, which makes the loop quadratic in bytes sent. Prompt caching makes sampling linear again, but only if nothing earlier in the prompt changes. So Codex treats cache misses as bugs. Changing tools, models, sandbox config, or working directory mid-session all break the prefix, and the fix is to append a new developer or user message describing the change rather than edit the original. One early MCP integration enumerated tools in a nondeterministic order and silently destroyed cache hits (OpenAI, Jan 2026). The MCP specification has since absorbed that lesson: the 2026-07-28 revision says servers SHOULD return tools/list in deterministic order to improve prompt-cache hit rates (MCP changelog). Dsh's "surface node" design in lesson 23 is the same discipline expressed as architecture.

Compaction strategies differ more than caching strategies. Codex calls a dedicated /responses/compact endpoint that returns an opaque, encrypted compaction item, so the summary preserves "latent understanding" the client cannot read. Claude Code clears old tool outputs before summarizing, lets you steer the summary through a "Compact Instructions" section in CLAUDE.md, and gives up with an explicit error rather than looping when one huge output refills the window after each summary (Claude Code docs). Pi keeps the original entries in its session tree and inserts a summary entry that later requests use in their place, so compaction is lossy for the model but lossless for the log. OpenHands and OpenCode expose knobs (event-count thresholds, keep-first counts, tool-output pruning). The common pattern across all of them is prune tool output first, summarize second, the same order dsh uses. Tool results are the bulkiest and least reusable tokens in a coding session. Removing them first costs the least.

Permissions: three philosophies of saying no

The permissions row is where the harnesses disagree most, and the disagreement is principled. There are three families.

Rules and prompts. The classic model is pattern rules (allow, ask, deny) plus a human who answers the prompts that fall through. OpenCode is a clean example: per-tool rules with wildcards, a doom_loop permission that catches repeated identical calls, most tools allowed by default, and no execution sandbox documented (OpenCode docs). Kimi Code's three modes and Qwen Code's Plan / Ask / Auto-Edit / YOLO ladder are variations on the same theme. The weakness is well documented. Anthropic found users approve 93% of permission prompts, which means the prompt has stopped being a decision and become a reflex (Anthropic, Mar 2026).

Sandbox first, then a reviewer at the boundary. Codex makes the OS sandbox the primary control. In workspace-write, anything inside the workspace just runs; approval only enters when the agent tries to cross the boundary (network, writes outside writable roots, escalated commands). Its auto-review option swaps the human for a separate reviewer agent at exactly that point. OpenAI is explicit that this is "a reviewer swap, not a permission grant": it never widens the sandbox. The reviewer sees a compact transcript that includes tool calls and tool outputs, but not hidden reasoning. A denial comes back to the main agent with an instruction not to work around it, and a circuit breaker aborts the turn after 3 consecutive denials or 10 in the last 50 reviews (Codex auto-review docs). One subtlety from the loop post matters here: Codex's sandbox applies to its own shell tool, and MCP tools are responsible for their own guardrails (OpenAI, Jan 2026).

A classifier on the transcript. Claude Code's auto mode layers a model-based classifier over rules and a sandbox. Built-in allowlisted reads and in-project edits skip it; shell commands, external operations, and out-of-project access go through it. The key design choice is what the classifier is not shown: Claude's own prose, tool outputs, and file contents. It judges only user messages and the actual tool-call payloads, so the agent cannot talk its way past it and injected text in a tool result cannot address it directly. A separate server-side probe scans tool outputs for injection and adds a warning to context. Anthropic published its error rates honestly: 0.4% false positives on real traffic, but a 17% false-negative rate on a small set of real overeager actions (Anthropic, Mar 2026). Qwen Code also offers an LLM-classifier Auto mode (Qwen Code docs), and OpenHands offers an LLMSecurityAnalyzer alongside deterministic pattern analyzers and an ensemble that takes the highest risk (OpenHands docs).

Notice the direct disagreement between the two frontier designs. Codex's reviewer sees tool outputs because context makes a better judge. Claude Code's classifier is denied tool outputs because tool outputs are where prompt injection lives. These are different bets on whether the larger risk is an under-informed judge or a manipulated one, and lesson 14 gives you the threat model to choose. At the far end sits Pi, which does not gate tool calls at all and says plainly that watching the transcript and reviewing changes "do not create a security boundary." Its answer is to run the whole agent inside a container or VM (Pi security docs). That is a legitimate position, arguably the most honest one, as long as the operator actually does it.

Here is roughly the same local policy ("edit inside the repo, ask before leaving it, keep network narrow") in the two frontier harnesses. The shapes differ in a telling way. Codex expresses it as a boundary plus an escalation policy. Claude Code expresses it as a mode plus rules plus an optional sandbox.

# ~/.codex/config.toml  (Codex)
sandbox_mode          = "workspace-write"   # OS-enforced: edits and routine commands inside the workspace
approval_policy       = "on-request"        # stop when an action needs to cross the boundary
approvals_reviewer    = "user"              # or "auto_review": a reviewer agent decides instead
project_doc_max_bytes = 32768               # AGENTS.md budget (the default)

[sandbox_workspace_write]
writable_roots = ["/tmp/build-cache"]       # widen the boundary narrowly, not globally

// .claude/settings.json  (Claude Code; comments shown for teaching, remove in real JSON)
{
  "permissions": {
    "defaultMode": "default",                // Manual: ask before edits and shell commands
    "allow": ["Bash(npm test)", "Read"],     // pre-approved
    "deny":  ["Bash(git push *)"]            // deny wins in every mode, even bypassPermissions
  },
  "sandbox": {
    "enabled": true,                         // Seatbelt / bubblewrap around Bash and children
    "network": { "allowedDomains": ["github.com", "*.npmjs.org"] }
  }
}

Where the harnesses converge

Memory files: AGENTS.md won, CLAUDE.md coexists

Every harness in the tables reads a markdown instruction file from the repository, and almost all of them read AGENTS.md. The format is now stewarded by the Agentic AI Foundation under the Linux Foundation and emerged from Codex, Amp, Jules, Cursor, and Factory (agents.md). The loading semantics have converged too: a global file, then files from the repo root down to the working directory, with nearer files later in the prompt so they win. Claude Code, historically the CLAUDE.md holdout, now reads AGENTS.md by default when no CLAUDE.md is present and can load both together (Claude Code memory docs). OpenCode, Pi, and OpenHands read CLAUDE.md as a fallback. The upshot: write one short AGENTS.md, and have CLAUDE.md import it if you also use Claude Code. OpenAI's harness-engineering post supplies the sizing advice: roughly 100 lines, treated as "the table of contents," pointing at a docs/ directory that is the real system of record (OpenAI, Feb 2026). Lesson 9 develops that idea.

Two details differ and matter. Budgets: Codex stops concatenating at 32 KiB by default, and Claude Code recommends under 200 lines per file. Trust: Pi loads AGENTS.md and CLAUDE.md even when you decline to trust the project, and warns you to treat them as untrusted input, while Claude Code asks for approval before following imports that point outside the repository. A memory file in a cloned repository is text written by a stranger that lands in your system prompt. Harnesses are starting to treat it that way.

Skills: one folder format everywhere

The Agent Skills format (a folder with a SKILL.md carrying a name and description, plus optional scripts and references) was originally developed by Anthropic and released as an open standard (agentskills.io). Claude Code, Codex, OpenCode, OpenHands, and Pi all appear in its client list, and Codex's own App Server post cites skills as the example of a cross-provider standard done right (OpenAI). Every implementation uses progressive disclosure: only names and descriptions load at startup, and full instructions load when the skill is selected. Codex caps the startup listing at 2% of the context window or 8,000 characters (Codex skills docs). Folder locations still vary (.claude/skills, .agents/skills, .opencode/skills), and each harness adds extensions such as Claude Code's context: fork or OpenHands' keyword triggers. Portable skills stick to the core fields.

MCP and ACP: two protocols, two directions

MCP connects the agent to tools; every harness here speaks it. Its 2026-07-28 revision made the core stateless, removed the initialize handshake, and moved tasks into an extension (MCP changelog), changes that suit harnesses running many short-lived sessions. Lesson 11 covers the design questions. The Agent Client Protocol runs the other way, connecting an editor to an agent. It standardizes editor-to-agent communication and reuses MCP's JSON representations where possible (ACP docs). OpenCode, Kimi Code, and Qwen Code ship ACP entry points, and OpenHands can front any ACP agent. The two frontier harnesses instead lead with their own richer protocols, and OpenAI names the tradeoff: cross-provider protocols tend to converge on the common subset of capabilities.

The filesystem-and-shell core

Finally, the tool surface itself has converged on the shape in lesson 2's table: read, edit or patch, glob and grep, a shell, web fetch, a todo or task tracker, and delegation. Deep Agents states the lineage outright: it was "inspired by Claude Code," an attempt to identify what makes it general-purpose (Deep Agents repo). A harness missing one of those tools needs a reason.

Where they diverge

One product harness versus embeddable libraries

Codex and Claude Code are products first that expose their harness for embedding: the App Server, Codex SDK, and codex exec on one side, and the Agent SDK, headless mode, and Managed Agents on the other. OpenAI now frames Codex explicitly as a platform, an open-source harness that applications can embed, with "model access and managed services" remaining separate (OpenAI Developers). Deep Agents and OpenHands' SDK sit at the opposite pole. They are libraries you compose, with pluggable backends for state, filesystem, and sandbox, and no assumption that a terminal UI exists. The real question is who owns the loop's defaults: the vendor, tuned against its own model and evals, or you, with control of every seam and the obligation to tune it.

Classifier versus rules

Rules are auditable but breed approval fatigue; classifiers and reviewers cut fatigue but add a judge with nonzero miss rates. The field is converging not on one answer but on layering: deterministic denies no mode can override, a sandbox for blast radius, and a model-based judge only for what falls between.

Plugin-everything versus opinionated core

Dsh (lesson 23) is the extreme of one pole: no privileged core, even the agent loop is a replaceable plugin. Pi is close behind with a minimal core and in-process TypeScript extensions that can register tools, providers, and UI. OpenCode's npm-installable plugins sit in the middle. Claude Code and Codex keep an opinionated core and expose extension through bounded seams: lifecycle hooks with defined blocking semantics, skills, subagents, and MCP. Pi's extension docs note that an extension "can inspect prompts, tool calls, files, credentials, and session history," which is the price of total flexibility. Claude Code's hooks are narrower but have defined semantics. Exit code 2 from a PreToolUse hook blocks the call; other nonzero codes are non-blocking errors (hooks docs). Narrow seams are easier to secure and to keep stable across releases. Open cores are easier to bend.

Telemetry and data flows

Claude Code sends usage metrics by default on the Anthropic API, excluding code, prompts, and paths, and keeps plaintext transcripts under ~/.claude/projects/ for 30 days (Claude Code data usage). Codex sends anonymous usage and health metrics by default and redacts user prompts from opt-in OTel logs unless you enable them (Codex config docs). Qwen Code's usage statistics default to on. Dsh, per lesson 23, uploads the canonical session log to DeepSeek by default, a much larger data flow than metrics. For several open harnesses I could not find telemetry documented at all. That is not the same as "none," and your security review should treat it as a question to answer by reading the source.

Harness changes are releases

In April 2026 Anthropic traced a period of degraded Claude Code quality to three harness changes, none of them to the model: a default reasoning effort lowered from high to medium, a bug that cleared prior reasoning on every turn instead of once after an idle hour, and a system-prompt line capping text between tool calls at 25 words, which cost about 3% on their evals. Their fixes were process fixes: per-model evals for every system prompt change, soak periods, and gradual rollouts (Anthropic, Apr 2026). Read that alongside Anthropic's observation that "every component in a harness encodes an assumption about what the model can't do on its own" (Anthropic, Mar 2026), and alongside OpenAI's claim that retained reasoning and compaction alone roughly tripled one model's ARC-AGI-3 score (OpenAI Developers). The harness is not packaging around the model. It moves results by amounts that rival model upgrades, in both directions, so it needs the same release discipline. Lesson 18 and lesson 21 are how you give it that discipline.

Choosing or building

The real decision is not "which harness is best" but which of three relationships to have with one.

Adopt a harness when the work is software engineering by people at terminals and in IDEs, and your differentiation is not the agent itself. The frontier harnesses have absorbed years of tuning against their own models, and you get prefix-stable prompt assembly, tested compaction, OS sandboxes, and a permission system for free. Your job becomes configuration: a good AGENTS.md, a small set of skills, deny rules, hooks for your non-negotiables, and a sandbox policy you have actually tested. Prefer open source when you need to audit data flows or switch model providers; prefer a proprietary harness when its model pairing wins on your own evals.

Embed an SDK when the agent belongs inside your product: an operations console, a review bot, a support tool. Codex App Server and the Claude Agent SDK give you a production loop with your UI, your tools over MCP, and your approval flow. OpenAI's sample app puts the agent beside a dashboard and requires human approval before any consequential write. Deep Agents or the OpenHands SDK fit when you want a model-agnostic library and you are prepared to own tuning. Embedding a harness keeps its defaults, including its telemetry defaults, so read that row before you ship.

Build your own when the loop itself is the product or the research object: a non-coding domain whose tool surface and permission model look nothing like a repository and a shell, a model you are co-designing with its harness (as DeepSeek did), or a search loop over harness designs (lesson 22). Even then, steal the conventions from the converged rows. Read AGENTS.md, load Agent Skills, speak MCP, keep prompts prefix-stable, prune tool output before summarizing, and separate boundary from judge. Build only the rows where you have a reason to differ, as the capstone does.

A teardown worksheet

Use this for any harness, including one that did not exist when this lesson was written. Fill every field from a primary source and write "not documented" when you cannot. The blanks are findings.

harness:            # name, version or commit, date reviewed
sources:            # primary URLs only; mark anything secondary
loop:
  turn_shape:       # model call -> tool calls -> repeat; stop condition
  client_protocol:  # JSON-RPC / HTTP / RPC over stdio / in-process only
  state:            # where history lives; stateless requests? resumable? forkable?
context:
  prefix_stability: # what edits the prompt mid-session? appended or rewritten?
  compaction:       # trigger, order (prune tool output? summarize?), what survives
memory_files:       # names, scopes, load order, byte budget, trust handling
tool_surface:       # diff against lesson 2's table; what is missing, and why?
extension:
  hooks:            # events, handler types, how a hook blocks
  skills:           # Agent Skills compatible? progressive disclosure?
  mcp: / acp:       # client, server, both, neither
  plugins:          # in-process code? same privileges as the agent?
permissions:
  boundary:         # OS sandbox, container, VM, none; what the sandbox covers (MCP tools?)
  judge:            # rules / human / reviewer agent / classifier; what the judge can see
  hard_denies:      # what no mode can override
subagents:          # definition format, context isolation, depth and concurrency limits
surfaces:           # CLI / IDE / web / desktop / CI; one loop behind all?
embedding:          # SDK languages, protocol stability promises
data_flows:         # telemetry defaults, transcript upload, local retention, opt-outs
license:            # and what is NOT covered (model access, hosted services)
open_questions:     # every "not documented" above, with an owner to resolve it