Attune Harness

Run an agent's work, check it independently, and keep a receipt of which happened.

Status: 0.4.0, alpha. Interfaces, configuration formats and CLI commands may change before 1.0. What is and is not qualified is listed below, not implied.

On September 18, 2026 I ran twelve model-written implementations of a small JSONL exporter through Harness. Nine behaved correctly under the full check. The other three passed when their serializer was tested directly, and failed when run through the real command line, which is the only way anyone would ever use them (results).

That gap is what Harness is for. A participant produces output: a model, a command, or your own code. A check you supply, separate from the participant, decides whether the output counts. You get back a receipt that says which. The participant's account of its own work is recorded. It is never the evidence.

A wrong answer comes back rejected

pipx install attune-harness

or uv tool install attune-harness, or pip install attune-harness into an environment of its own. That installs everything the review, test, MCP and acceptance journeys need. Python 3.10 or later. No provider SDK, no API key, and no attune-ai installation. Harness and attune-ai cannot share one environment: they pin different lines of the MCP SDK, and installing Harness over attune-ai replaces attune-ai's; an isolated install avoids that, and mcp-serve says so if it finds the two side by side.

from attune_harness import Check, Output, Task, run

class Worker:
    def run(self, task: Task) -> Output:
        return Output("4")

receipt = run(
    Task("addition", "Compute 2 + 2", ("Return the integer result",)),
    "example-worker",
    Worker(),
    lambda task, output: Check(output.text == "4", "Compared with independent arithmetic"),
)
print(receipt.status.value)  # verified

Change the worker to return "5" and the same call returns rejected, with the output and the check's evidence still attached. If the participant or the check raises, the status is failed and the receipt names the stage and the error. run executes once. It never retries on its own.

python -m attune_harness runs the installed demonstration and prints a JSON receipt.

The CLI applies the same contract to larger work

attune-harness --help

Task execution
  plan         Define intent and accept its scope
  build        Execute accepted tasks and protected checks
  review       Assess a document against project evidence
  fix          Repair scoped files and check the result
  test         Test a captured change and retain the evidence

Task controls
  status       Inspect a saved task
  resume       Continue a saved task

AI tools and integration
  --help-all   Browse operational tools and compatibility commands

Every verb follows one pattern. You accept a scope before anything runs, the host applies the effects, and checks fixed in advance decide the outcome. fix is the clearest example: it freezes an acceptance probe before the worker starts, applies the worker's proposed replacement itself, and keeps the failed-before and passed-after probe evidence. A saved task can be inspected with status and continued with resume; completed operations replay from saved evidence instead of running again.

Reaching outside the process takes explicit permission. External command participants need --allow-external, and native model participants also need --allow-native. Approving a plan does not authorize paid calls.

Many of these commands are there for the agent and its integrations to call. Learning their syntax is not the price of entry, and attune-harness COMMAND --help covers direct use. Full usage, exit codes and recovery controls are in the CLI guide.

What the install carries

Before 0.4.0 the base had no dependencies and verify, rag, review, mcp and tokens were extras. Those names still install, as empty extras, until 1.0. Every dependency is pinned exactly and loaded on first use, so a wheel installed without its dependencies still returns an actionable unavailable report for each missing piece instead of a traceback. Keep the quotes around an extra: zsh and bash treat square brackets as glob characters.

What is qualified and what is not

I would rather you find the limits here than in your own checkout. Green software tests and model quality are different claims, and this project keeps them apart.

Harness and attune-ai

Harness is the successor I am building to attune-ai. It starts from a constraint attune-ai never had: it runs with no provider SDK and no attune-ai installation. The Attune libraries it does use, forms, claim verification and local retrieval, are part of the install, pinned exactly, and each loads only when the command that needs it runs, so what the install adds is visible and nothing calls a model unless you install an extra that does.

attune-ai is still where cross-session memory, the Claude Code plugin and the multi-agent workflows live. Harness does not replace those today. If that is what you need, install attune-ai, in its own environment: the two pin different lines of the MCP SDK and cannot share one.

Links

• Qualification guide
• CLI guide
• Portable contract
• Repository and issues

Apache License 2.0.

Built by Patrick Roebuck, working with Codex and Claude.