Attune Harness

Updated on October 23, 2026.

Run agent tasks, check the results independently, and keep the evidence.

Attune Harness checks work from AI agents, commands, or your own code against criteria you supply. Each run returns a receipt with the output, check result, and any errors.

For a small working example, see checks and receipts.

Version 1.5.1 · Release record · PyPI package

This maintenance release helps you choose a workflow, follow clearer guidance, inspect assessment evidence and return to saved work. It also strengthens plugin signature validation and Windows full-suite checks. Read the release notes and readiness record for the changes, evidence and remaining limits.

Run the index-install commands below after 1.5.1 appears on PyPI. Until then, published 1.5.0 remains available. Links to the new release tag become available when that release is created.

The v1 compatibility contract remains in effect.

Install · Help Center · Spec-Driven Development · User guide · 1.5.1 release notes

Help Center

The Harness Help Center brings together step-by-step guides, expected results, troubleshooting and command references. Harness owns the Help Center source and static build. Its goals guide, versioned instructions and portable export are maintained here; website cutover remains a separate change. Start with the installation guide to select a runtime and check a local result. While 1.5.1 is unpublished, the Help Center's 1.5.0 getting-started guide identifies the available release. Use AI tools and integrations to find commands by task, follow their order and understand where approval is needed.

For hands-on practice, choose a current 1.5.1 preparation walkthrough. These procedures were exercised with an explicitly identified local validation wheel before final release-artifact selection. They do not replace the final release checks. If 1.5.1 is not yet on PyPI, use the published 1.5.0 installation above. The goals guide helps you choose a task; website publication follows its separate release gate.

Advanced planning for Spec-Driven Development

Harness connects requirements, planning, scoped implementation and verification. Use plan to develop the work contract, then build to execute accepted work.

• Define the intent. Record the goal, context, file scope, constraints and acceptance criteria. Harness selects plain-prompt, XML or specification-backed authoring from explicit work requirements.
• Develop and challenge the plan. A configured planner proposes tasks; a configured critic examines the proposal against its requirements before you stage and accept it.
• Connect requirements to tasks. Map acceptance criteria to dependent tasks and their checks. Import supported Markdown plans with a receipt that records the conversion; importing a plan does not carry over approval.
• Approve a precise scope. Accept the exact checkpoint before building, with protected verification commands fixed in advance. Inspect saved decisions, progress and evidence with status, and continue saved work with resume.

See Plan and build for the workflow and plan imports for bringing an existing specification into Harness.

Windows capabilities in 1.5.1

Windows users can install Harness and use its documented CLI workflows within the supported profiles. The Windows implementations include captured test execution, native file-memory reads, saved memory and task storage, and experimental native-memory transport. Use the capability and reliability table to choose a workflow and check its process-completion, storage and recovery requirements.

Hosted software checks exercise Windows Server 2022 and 2025 with Python 3.10 and 3.12. Full Windows parity, complete saved-store acceptance, broader process recovery, live native-memory acceptance, and Windows 11 desktop and shell qualification remain open. The linked table explains which limits apply to each workflow; the release evidence identifies the source and artifacts tested.

Plan, build, review, fix, and test

attune-harness --help

Getting started
  init         Write a starter participant registry

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.

Use Harness with Codex, Claude, or other models

This repository includes an Attune Harness skill for the existing plan, build, review, fix, test, status and resume workflows. Invoke $attune-harness and describe the task; the agent prepares the CLI inputs and reports the saved evidence. It preserves the workflow's scope and execution permissions. The older /attune command belongs to Attune AI.

For an Attune Harness entry in Codex Plugins, use the plugin packaging and installation guide. You can also use standalone skill discovery in this checkout or another project. Installing the Python package alone installs neither integration.

In Claude Code, add this repository as a plugin marketplace, then install the plugin. It carries the Harness skill plus cross-review, roundtable and smart-test, and it calls the attune-harness command installed above:

/plugin marketplace add Smart-AI-Memory/attune-harness
/plugin install attune-harness@attune-harness

Claude Code does not read the .agents/skills/ folder that Codex discovers, so this plugin is how the skill reaches it. Installing the plugin authorizes no paid calls.

Installation

After publication, install 1.5.1 in an isolated tool environment:

uv tool install 'attune-harness==1.5.1'

uv keeps Harness and its dependencies isolated and provides the attune-harness command. The base includes forms, verification, local retrieval, review, test, MCP and acceptance dependencies. Add Redis or Voyage when needed; all includes both. Inspect the selected tool and check that its command is available:

uv tool list --show-paths
attune-harness --help

If Harness is already installed, inspect its version and path before selecting 1.5.1 explicitly. Preserve saved task directories and retained evidence environments; changing the tool version does not qualify saved-work migration. The installation guide covers environment selection and agent setup for 1.5.1.

Python 3.10 or later. The worked example needs no API key or attune-ai installation; Voyage retrieval needs a Voyage API key and makes paid calls. 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.

What the install carries

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.

Your first five minutes

Follow the installation guide for runtime selection and a local check. Then use the user guide to choose a workflow. For a practice form, ask the person or agent running Harness for its complete private link and keep the local launcher running.

For a quick preview in a project you have already prepared:

From a Git project with an uncommitted change and a virtual environment that has pytest, after the install above:

cd your-project
attune-harness init
attune-harness test --project . --scope src/example.py --interpreter .venv/bin/python --task-dir ../test-task --format markdown
attune-harness review --goal "Check README.md against project evidence" --intake-only

init writes a participants.json with two offline demo participants. test previews exactly which tests it will run for your change and saves that plan; accept it with the checkpoint it prints to run them. review shows the intake form for an evidence review: the document, its evidence and who assesses it. Nothing here calls a model. CI runs these commands, as written, on every platform job.

For a consultation, use init --for roundtable --question "Review the selected source" with an explicit --model claude=YOUR_CLAUDE_MODEL_ID and --model codex=YOUR_CODEX_MODEL_ID. It writes roundtable.json, reports local seat preflight and prints the next prepare command. See the roundtable starter and participant mapping.

Evidence and reliability

Use these records to check your installation and workflow:

• 1.5.1 preparation readiness: candidate checks, publication gates and remaining limits.
• Earlier 1.5.0 release record: published source, wheel and source archive hashes, and installed-package checks.
• Supported journeys: available workflows, evidence and reliability requirements.
• Qualification guide: the CI matrix and installed-wheel procedure.

Software checks establish the behavior they exercise; model quality and live provider acceptance require their own evidence. Receipts retain local task, output and check evidence; they are not signed attestations. Run trusted commands in a dedicated checkout: process supervision is not a security sandbox.

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. Installing an extra does not call a model; invoking a paid provider path requires separate permission and credentials.

Harness can read and save memory through its documented paths. Attune AI still provides the hydrate writer and broader Claude Code and multi-agent workflows; Harness does not replace those today. If you need them, keep attune-ai in its own environment: the two pin different lines of the MCP SDK and cannot share one.

Use the workflow guide to choose a Harness entry point and check its requirements before replacing an existing Attune AI workflow.

Links

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

Apache License 2.0.

Built by Patrick Roebuck, working with Codex and Claude.

Browser forms

Open a registered draft, save answers, approve a request and inspect its accepted content through the forms companion. Saving and approving a request do not execute work. Launch it with the selected Harness interpreter and keep its local server running. See the forms workflow for setup and the available controls.