Harness engineeringLesson 10

Harness Teardowns

Claude Code, Codex, OpenCode, Aider, Cline and OpenHands solve the same six problems differently. Read their choices as design arguments, not feature lists.

Working25 min readUpdated November 2026Test the patterns in a mission →

Harness Teardowns

Every production coding harness looks similar from the outside: a chat box, a diff, a test run. Inside, each one makes a different bet about context, permissions, edit format and how much autonomy a model should have. Those bets are the lesson.

The comparison axes

Feature tables age quickly. Design axes do not:

AxisThe question
LoopIs it a single ReAct loop, a planner plus executor, or an event-driven runtime?
ContextRepo map, retrieval, compaction, subagents, cache strategy?
Edit formatWhole file, search/replace, patch, AST-aware?
PermissionsPer-action approval, sandbox, allowlist, plan mode?
StateSession transcript, checkpoints, resumable tasks, cloud tasks?
ExtensionMCP, plugins, hooks, skills, custom commands?
ObservabilityTraces, token accounting, replay, eval hooks?
SurfaceTerminal, IDE, web, cloud, API?

A harness is coherent when its choices reinforce each other. A permissive sandbox plus a powerful shell plus auto-approval is a different product from a read-only planner plus a patch queue. Neither is universally better; they serve different trust models.

Claude Code

The bet: a terminal-native agent with a strong permission system, a small set of powerful tools, and extensibility through skills, hooks, subagents and MCP.

Patterns worth studying:

  • Permission modes and scoped approvals. The harness distinguishes read-only exploration, edits that need approval, and auto-approved actions. Plan mode separates investigation from mutation.
  • Skills. Packaged instructions and resources that load when relevant. This is context engineering as a product feature: reusable expertise without permanent prompt bloat.
  • Hooks. Deterministic callbacks around tool and session events. Hooks can enforce policy, add telemetry or transform output without asking the model nicely.
  • Subagents. Isolated context for research or parallel work, with a return contract.
  • CLAUDE.md / project memory. Durable project conventions loaded into context, versioned with the repo.
  • MCP integration. External tools and resources through a standard protocol, with the attendant security surface.

The interesting design argument is capability with explicit authority. The agent can do a lot, but the permission layer is a first-class product surface, not an afterthought.

OpenAI Codex

The bet: a coding agent available across terminal, IDE and cloud, with sandboxed execution and approval modes, and a strong emphasis on reviewable diffs and task delegation.

Patterns worth studying:

  • Sandbox plus approval mode. Execution is constrained by the environment, and the approval policy is explicit. The combination matters more than either alone.
  • Cloud tasks. Long-running work can be delegated to an isolated environment, then reviewed as a patch. This changes the latency and state model.
  • Diff-centric review. The unit of output is a change set a human can inspect, not a chat transcript.
  • Repository instructions. Project-level guidance is part of the context contract.

The design argument: separate the place work happens from the place the human reviews it. A sandboxed cloud run can be more autonomous because its blast radius is smaller and its output is reviewable.

OpenCode

The bet: an open-source, provider-agnostic harness with multiple agents, per-agent permissions, and a terminal UI that treats the model as a replaceable component.

Patterns worth studying:

  • Multiple agents with different tools and permissions. A build agent and a plan agent can have different authority. The agent is a configuration of the harness, not a separate product.
  • Provider abstraction. The same loop works across model providers, which makes routing and fallback practical.
  • Per-agent permissions. Tool access is scoped to the agent’s role.
  • Sessions and worktrees. Work can be isolated and resumed.
  • Open extension surface. MCP, plugins and custom commands.

The design argument: the harness should outlive the model. If the loop, tools and policy are decoupled from a provider, you can route, compare and migrate without rewriting the product.

Aider

The bet: a focused pair-programming tool with a repository map, explicit edit formats and git as the safety net.

Patterns worth studying:

  • Repository map. A compressed view of the codebase’s symbols and structure, not a dump of every file. This is context engineering with a budget.
  • Edit formats. Search/replace blocks and whole-file edits have different failure modes. Aider’s formats are designed to be easy for models to produce and easy to validate.
  • Git-first workflow. Every change is a commit candidate. The diff is the interface.
  • Test loop. Run tests, read failures, edit, repeat.
  • Narrow scope. It does not try to be an IDE, a cloud platform and a general agent at once.

The design argument: a narrow harness with a great edit loop can beat a general one. The repository map and edit format are the product.

Cline

The bet: an IDE-native agent that makes every action visible and approvable, with strong support for MCP and a human-in-the-loop feel.

Patterns worth studying:

  • Per-action approval. The user sees the proposed tool call and can accept or reject it. This is high-friction but high-trust.
  • IDE context. Open files, selections and diagnostics are natural context that a terminal agent has to reconstruct.
  • Browser and terminal tools. The agent can inspect a running app, not just source code.
  • MCP marketplace. A broad integration surface, with the usual supply-chain caveats.

The design argument: visibility is a safety feature. When the human can see each action in the editor, the approval can be meaningful.

OpenHands

The bet: an open platform for software agents with a sandboxed runtime, an event stream and a browser-based workspace.

Patterns worth studying:

  • Event-driven runtime. Actions and observations are events, which makes replay and orchestration natural.
  • Sandboxed execution. The agent works in an isolated environment with a browser and shell.
  • Trajectory as a first-class object. The run is inspectable, not just the final patch.
  • Pluggable agents and runtimes. The platform separates the agent policy from the execution environment.

The design argument: the runtime is the product. If the environment and event model are solid, different agents can share them.

The patterns that keep appearing

Figure 10.1Harness anatomy
The anatomy of an agent harnessThe model sits at the center. Around it, the harness supplies a loop, tools, context, policy, state and observability. The model is one component; the harness turns it into an agent.The model is the engine. The harness is the vehicle.SIX SURROUNDING SYSTEMS TURN A COMPLETION INTO AN ACTIONMODELweights + sampling01 · LOOPobserve → plan → act → verify → stop02 · TOOLSread, edit, shell, search, MCPtyped schemas + errors03 · CONTEXTsystem, history, retrieved files,compaction, pinned decisions04 · STATEsessions, checkpoints, event log05 · POLICYpermissions, sandbox, approvals,secrets, budgets, allowlists06 · TRACESspans, costs, evals,replay and auditMost agent failures are not “the model was too small.” They are missing context, missing verification, or missing authority boundaries.
Across very different products, the same six systems appear. The differences are in how each one is scoped and exposed.
  1. Plan mode. Separate investigation from mutation. It reduces accidental edits and gives the human a checkpoint.
  2. Repository context. A map, retrieval or explicit file references beat dumping files. Context is budgeted.
  3. Diff as the interface. A reviewable change set is more trustworthy than a prose claim of success.
  4. Scoped permissions. Read-only, workspace write, shell, network and external actions are different risk classes.
  5. Sandbox by default. The environment enforces what the prompt cannot.
  6. Skills and hooks. Reusable instructions for capability; deterministic callbacks for policy and telemetry.
  7. Subagents. Context isolation and parallelism, with an explicit handoff.
  8. Session state. Resumability, checkpoints and worktrees.
  9. MCP. A standard tool surface, and a standard attack surface.
  10. Traces. Token accounting, tool logs and replay are table stakes for improvement.

What to copy, and what not to

Copy:

  • The separation of plan and act.
  • Diff-based review.
  • Explicit permission classes.
  • A stable prompt prefix for caching.
  • A trace format that can be replayed.
  • A small set of composable tools.
  • A test loop that produces evidence.

Do not copy blindly:

  • A permission mode designed for a trusted single developer, deployed to a multi-tenant service.
  • A tool surface that assumes a local filesystem when your code runs in a shared cluster.
  • A context strategy tuned for a 200K window applied to a 32K model.
  • A benchmark number from a vendor’s best-case workload.
  • An extension marketplace without supply-chain review.
  • A “fully autonomous” mode without a sandbox and a budget.

A teardown checklist

When you evaluate a harness, ask:

  • What is the loop, and what are its stopping conditions?
  • What is in context by default, and what is retrieved?
  • What happens when context fills?
  • Which tools exist, and what are their side effects?
  • How are permissions enforced — prompt, policy, sandbox or all three?
  • What state survives a crash?
  • Can a run be replayed?
  • How are subagents isolated and merged?
  • What is the extension surface, and how is it secured?
  • What does a completed task look like, and who verifies it?

The answers reveal the product’s real theory of trust. Features are downstream of that theory.

Next: build your own harness — a minimal, testable implementation of the loop, tools, policy and trace.

Sources and further reading

One question before you go

retrieval check
What is the most useful thing to copy from a mature harness?
Why: Harness quality is mostly architecture: how it scopes permissions, exposes tools, manages context and verifies work. Prompts alone do not transfer.
Type at least two characters. Search is indexed after the production build.
Lessons · labs · glossary↑↓ to browse · esc to close