What is an AI coding-agent harness?

A coding-agent harness is the environment a coding agent runs inside: the layer that assembles the prompt, exposes the tools the agent acts with, carries context and session state between steps, and records what the run did. It is everything wrapped around the agent except two things — the model that does the thinking, and whatever system decided the work was worth doing. When Pi introduces itself as "a minimal terminal coding harness," and when Terminal-Bench describes its evaluation framework as a harness that "handles orchestrating agents, spinning up multi-container docker environments, logging agent actions, and verifying container state," both use the word the way test engineers have always used it: scaffolding that runs something under controlled conditions and watches what happens.

That first paragraph is the definition. The part worth keeping — and the part vendor pages tend to blur — is where the harness ends. "Harness" currently does duty for anything from a model name to an entire platform, so this guide draws the boundary explicitly: against the model, against the agent, against your IDE, and against the control plane, using YYLO's own layering as the worked example.

Why one word covers so many products

The searches tell the story. People look for a "Claude harness," a "Codex harness," a "Pi coding harness," or an "OpenCode harness"; others ask for an "Anthropic agent harness" or an "OpenAI harness"; and a third group searches "code as agent harness" or "Pydantic AI harness" for frameworks where your own program assembles the loop. The same word is pointing at a model vendor, a CLI product, a terminal app, and a framework you code against — because from the outside they all look like "the thing that makes the agent go."

The word survives anyway because it names a real seam. Borrowed from test harnesses, it settled in coding-agent usage on the agent-side runtime: the program that owns prompt transport, tool exposure, context and session management, and the extension surface you configure. That is the scope this guide defends. What the word must not absorb is the model doing the reasoning, the loop that turns reasoning into tool calls, or the coordination layer deciding what work deserves a run — those are different layers with different owners.

Five layers, five boundary questions

The boundary is easiest to hold as one question per layer. Each layer below names the question it answers, what it owns, and where you can see it in a real system:

• Model — which weights produce the next action? The inference layer behind everything: an API serving a trained model. It reasons over the prompt it is handed and proposes the next step. It is chosen per run, not per product: in YYLO, -m :sonnet selects a different model through the same service, each documented service carries its own default model, and multi-provider agents like Pi expose several providers behind one interface.
• Agent — what turns model output into repository changes? The loop that hands the model tools — reading and editing files, running commands — and executes what it decides. Anthropic's engineering writing describes such systems as "typically just LLMs using tools based on environmental feedback in a loop." The agent is that loop and its tool surface, not the weights and not the app around it.
• Harness — what hosts one agent run? The environment the loop runs inside: prompt assembly and transport, the tool bindings, context and session management, and the extension points. Pi's one-line self-description is exactly this scope — a harness you adapt through extensions, skills, and prompt templates instead of forks. The harness serves the agent; it is not itself intelligent.
• IDE — where does the human read and edit? An editor is a different serving surface: it exists for your eyes and hands. An IDE can embed an agent — Cursor does — and the same product can then expose its agent as a drivable service: YYLO's --subagent flag documents cursor alongside claude, codex, gemini, and pi. But a harness needs no IDE at all; terminal harnesses run headless in CI where no editor will ever open.
• Control plane — what decides which work is worth doing, and what happened? The coordination layer above harnesses: task truth and dependencies, bounded delegation, isolated worktrees, validation gates, review, and integration evidence. This is the layer YYLO occupies — its documentation positions it as the control plane for agentic engineering work, with YYLO Ledger preserving Git-native task truth and YYLO Benchmark retaining evaluation evidence.

Read as a stack: the model infers, the agent acts, the harness hosts, the IDE serves you, the control plane coordinates. Every "what is a harness" argument dissolves once you can name which of those five jobs is actually being discussed.

Watch the boundary move in one command

One YYLO invocation shows the layers separating cleanly:

yy start -b shell -s claude -i 1 -v

-s claude selects the agent — the service CLI whose loop does the work; the CLI reference documents the service flag, and the README's backends table lists each documented service's default model. -b shell selects the backend, the transport that invokes the agent service and captures its events; custom backends are ordinary Python scripts in ~/.yylo/services/ that accept -p/--prompt, -m/--model, and -v/--verbose and emit JSON events. -m would select the model behind the agent. -i 1 is the control plane bounding the run to one reviewed iteration, and the run's response, commit, logs, and session id land as control-plane evidence rather than console scrollback — yy pi --execution-envelope emits a single juno_execution_envelope.v1 JSON object whose provider, model, session, version, and cost fields come from marked backend terminal evidence instead of the agent's own prose.

The layering is the point: YYLO does not replace your harness. It drives installed agent CLIs and keeps orchestration and evidence above them, so the agent, model, and harness choices stay yours while every bounded run leaves coordination-layer truth behind. The runner contracts that carry that evidence have their own guide in auditable agent workflows, and the prompt surfaces a harness must keep safe are covered in prompt and shell-context safety.

Why the boundary earns its keep

Two practical payoffs make this more than vocabulary.

Swapping costs live at different layers. A model is a flag; an agent is a service selection, plus whatever tool surface it assumes; a harness is your accumulated configuration — extensions, skills, sessions — which may or may not travel; a control plane is your task truth, evidence, and gates, the thing you cannot swap without moving history. Portability conversations go wrong precisely when they conflate these: "we're locked in" often means "our harness configuration is stuck," not "our model is."

Failure attribution gets a place to stand. When a run goes wrong, ask which layer failed: the model reasoned badly; the harness mangled the prompt, lost the session, or fed it stale context; the control plane let the run happen unbounded or merged it unreviewed. "My agent went rogue" is almost always "my control plane is missing" — an unbounded loop with no review gate is a coordination failure, not a model property. That is also why the first YYLO habit worth learning is the bounded loop, and why the coordination layer's memory — the task truth that survives every harness swap — has its own guide in Kanban as agent task truth.

Reuse this boundary

The five questions — model, agent, harness, IDE, control plane — are the citable artifact on this page. The public definitions quoted above were verified against the linked Pi, Terminal-Bench, and Anthropic pages, and the YYLO layering claims against the committed README and documentation, on 2026-08-27; both sides are dated, so re-verify before relying on them after either changes. If the boundary questions are useful to you, cite this page's stable URL with attribution rather than paraphrasing them uncredited — that attribution is exactly what lets a public definition stay maintained.