What Is Harness Engineering¶

A coding agent is a model running inside a harness: the software that decides what the model sees, which tools it can call, how it remembers, how its work is checked, and what it is allowed to do. The harness, not the model alone, determines how the agent behaves.

Harness engineering is the practice of treating that surrounding system as a real engineering artifact: something you design, write down, measure, and improve, instead of a hidden default you inherit from a product.

SuperQode is a harness engineering framework for coding agents, optimized for local and open models. This page explains the idea, why it matters now, and the four moves SuperQode gives you on a harness you own.

The third layer¶

The way teams get value out of models has moved through three layers:

1. Prompt engineering. Write a better instruction.
2. Context engineering. Assemble the right context around the instruction.
3. Harness engineering. Design the whole system the model runs inside: tools, memory, search, approvals, sandbox, workflow, checks, and model routing.

Each layer wraps the one before it. A great prompt inside a weak harness still produces an unreliable agent, because the harness is what controls retries, tool calls, context limits, and verification. The harness is now the layer that decides whether a coding agent works on real code.

Why this matters most for local and open models¶

Closed coding products ship a large, fixed harness tuned to one model family. You cannot see it, version it, or change it, and it is built to keep you on that vendor's model. That harness can be very good, but it is theirs.

Open Models are in the opposite position. The weights are yours to run, but they arrive with no harness at all. A local model dropped into a harness designed for a frontier API will look weak, not because it cannot code, but because the harness wastes its context, assumes a native tool head it does not have, and never verifies its edits.

This is the gap SuperQode closes. It treats the harness as the product you own, and it is tuned for the realities of local and Open Models. See Local Agentic Coding for the model-by-model details.

The model is the part you can swap. The harness is the part you build. Own it.

A harness is a file you own¶

In SuperQode a harness is a single YAML artifact that lives in your repository. It can be reviewed in code review, committed to version control, and run anywhere the same way.

# harness.yaml: the portable run contract
name: my-coder
flavor: coding
runtime:
  backend: builtin
model_policy:
  primary: ollama/qwen3-coder
  temperature: 0.1
  tool_call_format: prompt      # for models without a reliable native tool head
execution_policy:
  sandbox: docker
  approval_profile: balanced
  allow_write: true
  allow_shell: true
  allow_network: false
agents:
  - id: coder
    tools: [read_file, grep, glob, repo_search, edit_file, patch, bash]

Read exactly what any harness will do, in plain English, before you run it:

superqode harness explain --spec harness.yaml

The four moves¶

Harness engineering in SuperQode is four repeatable actions on that file.

Build¶

Author a harness without writing YAML from scratch. Answer a few questions with the wizard, or start from a model-family template and edit from there.

superqode harness wizard
superqode harness init my-coder -t qwen-coding
superqode harness explain --spec harness.yaml

See Bring Your Own Harness and the Harness System reference.

Measure¶

A harness you cannot measure is a guess. Run an eval task file to produce a scorecard, and use it as a regression gate: a candidate that breaks a task the baseline solved fails the gate.

superqode harness eval --spec harness.yaml --tasks eval-tasks.yaml --live --json > baseline.json
superqode local bench --agentic

See Run, Measure, Optimize and the Benchmark Runner.

Extend¶

The same harness contract runs across runtimes and connects outward when you choose: builtin, OpenAI Agents, Google ADK, Codex SDK, Claude Agent SDK, DeepAgents, and PydanticAI, plus MCP tools, ACP agents, and A2A workflows. Only the route changes; the contract stays the same.

superqode harness run --spec harness.yaml --runtime codex-sdk --prompt "review this repo"

See Runtime Backends and Connection Modes.

Optimize¶

Improve the harness with evidence instead of guesswork. Every optimizer follows the same safe contract: start from a versioned artifact, measure it, stage a candidate, gate it against regressions, and let a human adopt it. The live agent never rewrites itself blindly.

superqode local optimize                 # best local/open model routing per role
superqode harness optimize --spec harness.yaml --tasks eval-tasks.yaml
superqode skills optimize review --engine gepa --harness harness.yaml --tasks eval-tasks.yaml --live

See the Optimization Story and Skill Optimization.

Why build a custom harness¶

You can. SuperQode connects to hosted providers, Codex, Claude Code, and other agents through BYOK, ACP, and runtime SDKs. The difference is who owns the contract.

A harness you own, not a harness you rent¶

The harness is a distinct layer of the agent stack and is also available as a managed cloud service. In this model, users declare an agent in configuration and a hosted platform assembles and executes the agent loop.

SuperQode stores the harness as a file in the repository and executes it on infrastructure controlled by the user. The harness can be versioned and reviewed with the rest of the codebase, and its behavior remains consistent across local models, hosted providers, and remote runtimes. This approach is intended for teams that require direct control over harness configuration and execution.

Even when you borrow another agent's strengths, SuperQode stays the controlling harness. It can import an Omnigent spec, for example, and convert it into a portable HarnessSpec rather than handing control to another runtime.

Start here¶

1. Install SuperQode and generate a local harness for your machine: superqode local init --repo .. See Installation.
2. Build and explain your first harness in Bring Your Own Harness.
3. Measure and improve it with the Optimization Story.
4. Read the full field reference in the Harness System.