Attune Harness
Turn a goal into a plan, put agents to work, and check the results.
Use Harness with your assistant in Codex or Claude Code to plan a change, review a document, repair files, run tests or return to saved work. Describe what you want to accomplish. Your assistant helps prepare the work, presents what needs your review and uses Harness to carry out the steps you authorize.
Harness keeps a receipt: the output, check results and any errors from a run. You can inspect what happened and use that record when you continue later.
This README describes Harness 1.8.1. Check the PyPI version listing before installing it from the package index.
Help Center
- Install Harness 1.8.1 after checking its availability.
- Get started in the Help Center to install Harness, check a local result, and connect your assistant.
- Set up the reporting course to plan, build, and check an offline report.
- Choose a goal to find a guide for the work you want to do.
Check the version on historical guides before following their commands.
Installation
Install 1.8.1
Harness 1.8.1 requires Python
3.12 or later. Install uv
if needed. If you already use Harness, check the update in a separate
environment before switching.
Run the index installation below once PyPI lists 1.8.1. Before publication,
use the reviewed local wheel and the candidate installation steps in
docs/installation.md from the same reviewed source checkout.
uv tool install --python 3.12 'attune-harness==1.8.1'
The base install needs no extras. Add optional integrations for Redis or Voyage. Keep Harness and Attune AI in separate Python environments because they require different MCP SDK versions.
To use pipx or a virtual environment, follow the 1.8.1 installation steps.
Check a local result
Check the installed version and run the local demonstration:
uv tool list --show-paths
attune-harness
The tool list shows attune-harness v1.8.1. The demonstration prints a JSON
receipt with "status": "verified" after a local worker and an independent
check agree on the arithmetic result. It needs no API key and makes no
model calls.
If your shell can't find attune-harness, follow uv's instructions for
adding the tool directory to your path.
Connect your assistant
After checking the CLI, connect the assistant you use for your project. The assistant uses the separately installed Harness runtime to run workflows.
Codex
In a Harness source checkout, Codex can discover the repository skill in
.agents/skills. For other projects, follow the
Codex plugin guide
or standalone skill guide.
Once the skill is available, invoke $attune-harness and describe your goal.
Claude Code
Add the marketplace and install the plugin:
/plugin marketplace add Smart-AI-Memory/attune-harness
/plugin install attune-harness@attune-harness
The Claude Code catalog selects a published tag independently of the Python package. For an existing installation, refresh the marketplace and update the plugin. Verify the selected version and source. The Python runtime and host plugin are separate installations.
The plugin includes Harness workflows, cross-review, roundtable and smart-test
instructions. It calls the separately installed attune-harness runtime.
Other integrations and direct commands
Use the CLI guide
for command-based integrations, MCP setup, arguments and exit codes. Run
attune-harness COMMAND --help for one command or attune-harness --help-all
for the broader tool list.
What changes in 1.8.1
- Use Windows paths with spaces and special characters. Prepared PowerShell commands preserve dollar signs, backticks, apostrophes and Unicode characters in setup, plan and repair previews, review intake, and roundtable preparation.
- Keep following options intact. Paths with spaces and trailing backslashes no longer consume the next option in Windows PowerShell 5.1.
The fix covers Windows PowerShell 5.1 and PowerShell 7. Read the 1.8.1 release notes and readiness record. Versioned links become available when the release is tagged. See the PowerShell command fix for the change and Work on Windows for existing platform requirements and limits.
What changes in 1.8.0
Read the release notes and readiness record.
- Keep legacy command configurations working. Full parent environment inheritance remains available through 1.8.0. Its earliest removal is 1.9.0. The first notice shipped in 1.6.0.
- Keep your existing memory setup. Internal preparation adds guarded projection and source freshness checks. Use your existing writer and hooks for Redis publication and session startup.
What you can do
| Your goal | How Harness helps |
|---|---|
| Plan a change | Develop the goal, affected files, tasks and checks before implementation. |
| Build from a plan | Give configured agents the accepted tasks and inspect their work against the agreed checks. |
| Review a document | Compare its claims with your criteria and supporting sources. |
| Repair existing files | Check a proposed repair against a test fixed before the repair begins. |
| Test a code change | Preview the selected tests, then inspect their output and results. |
| Continue saved work | Read the saved decisions and results before choosing the next action. |
Start with the workflow guide to choose a procedure and see what it needs.
- Goal-driven development starts with the outcome you want, then defines the work and checks.
- Spec-driven development develops and reviews requirements before starting work that needs more structure.
- How people and AI work together explains how you direct decisions and inspect the results.
Goal-driven development
Start with a small goal in a project you know. For example, ask your assistant:
Use Harness to help me plan an update to this project. Help me define the goal, affected files and checks before we build.
Or:
Use Harness to review README.md against the project sources. Show me which claims are supported and which need attention.
Your assistant prepares the inputs for the selected workflow. Review the proposed scope, configured participants and checks before accepting the work. Accepting a plan records the agreed work; starting a build is a separate action. Paid model calls require their own permission and credentials.
You can also use the commands directly:
| Command | Purpose |
|---|---|
init |
Prepare starter files for a supported workflow. |
plan |
Develop a plan and accept its scope. |
build |
Execute accepted tasks and their protected checks. |
review |
Assess a document against selected evidence. |
fix |
Repair scoped existing files against a fixed check. |
test |
Test a captured change and retain the results. |
status |
Inspect saved progress and results. |
resume |
Continue authorized remaining work. |
For guided examples, clarify your feature idea or build in reviewable steps. Each procedure supplies its setup, steps and expected result.
For a complete local example, follow your first plan and build. Prepare a small calculator change, inspect the scope and checks, accept the current plan, then start the build separately and read its saved evidence. The example uses local command participants and makes no model calls.
Preview a task from the command line
In a POSIX shell, start from the parent of a Git project named your-project.
The project must have an existing commit, no participants.json, and an
uncommitted change in src/example.py. Its .venv/bin/python interpreter must
have pytest installed, and attune-harness must be available on your path.
The sibling directory ../test-task must not already exist. The commands run
from the repository root after cd.
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
Expected result: init writes starter participant configuration.
test previews the selected tests and saves the plan for your review;
review --intake-only prepares the review intake. These commands do not
run a model. Preview and intake-only draft commands can return exit status 1
with their expected draft result. This example's executable journey is checked
on POSIX; it does not establish that the interpreter path works unchanged on
Windows.
Spec-driven development
Use a specification when the work needs more structure than a short request. Harness connects requirements to tasks, decisions and checks.
- Define the intent. Record the goal, context, affected files, constraints and acceptance criteria.
- Develop and challenge the plan. A configured planner proposes tasks; a configured critic examines them against your requirements.
- Connect tasks to checks. Identify what will show that each task met its requirements and which tasks depend on earlier work.
- Review and accept the scope. Inspect the proposed work before starting
the build. Use
statusto inspect saved decisions and progress.
Follow Create a spec with roundtable help for a worked example and review points. A reviewed spec still needs a supported, accepted plan before a build can start.
The plan-and-build guide explains the procedure. You can also import a supported Markdown plan from another project and review it before acceptance.
Work on Windows
Harness includes Windows implementations for captured testing, build and repair effects, memory-file reads, saved memory and task storage. Fixed local NTFS and the route's other input checks still apply. If process shutdown is uncertain, inspect the saved record and original process effects before continuing; an error does not prove termination or rollback.
Choose a workflow in the Windows capability table. It explains the local NTFS setup and the process, storage and recovery conditions that matter for each task. Check those requirements before relying on concurrent writes, interruption recovery or power-loss durability.
The merged repair passed installed-package and full-source checks on both
Windows Server 2022 and 2025 with Python 3.12 in PR #320. Separate supplemental
coverage passed in the windows-latest job. Windows 11 observations
are a separate standard-user smoke on ARM hardware using x64 Python emulation;
they do not qualify native ARM64 or all desktop and PowerShell workflows.
The linked guides define supported workflows and remaining storage and recovery limits. The Windows reliability reference provides the detailed requirements and evidence.
Optional integrations
The base package includes forms, document verification, local Markdown retrieval, testing, MCP serving and token counting. Select the extras you need:
| You need | Package to select |
|---|---|
| Base workflows | attune-harness==1.8.1 |
| Redis-backed memory with an existing configured service | attune-harness[redis]==1.8.1 |
| Voyage retrieval with an API key and paid API usage | attune-harness[voyage]==1.8.1 |
| Both Redis and Voyage | attune-harness[all]==1.8.1 |
| Plan OAuth software profile, with separate consent and execution gates | attune-harness[plan-oauth]==1.8.1 |
For example, to install the Redis client integration:
uv tool install --python 3.12 'attune-harness[redis]==1.8.1'
Keep quotes around package names containing extras. The all profile combines
Redis and Voyage; plan-oauth and experimental native memory remain separate.
The plan adapter accepts only macOS arm64 / CPython 3.12.2 with its pinned
optional dependencies. See participant funding
for software limits and the outstanding live qualification.
The dependency guide
lists the exact pins, service requirements and optional provider setup.
Installing an extra does not configure a service or authorize paid calls.
The existing Redis paths passed bounded disposable-service checks during 1.6.0
preparation. The requirements and verification record
identifies the tested development wheel, operations and limits. Use qualification
evidence that identifies the exact wheel hash you install; a dependency pin or
offline check alone does not establish a successful live service operation.
Grant one command the credential it needs
For example, a trusted command participant can declare:
"environment": {"profile": "command-env-v1", "passthrough": ["SERVICE_TOKEN"]}
Set SERVICE_TOKEN in the dispatching host's environment without putting its
value in the configuration or shared logs. Use an existing absolute executable
path and the participant's normal preparation/acceptance flow. Missing named
variables refuse dispatch. The profile filters environment inheritance; it is
not an operating-system sandbox.
Version 1.8.1 retains full parent environment inheritance for configurations
without an environment policy. See Migrate legacy configurations
for the unchanged deprecation schedule.
Upgrade and keep a rollback path
Install 1.8.1 in a separate Python 3.12 environment before switching a working setup. Select the same extras you use today. Keep your previous runtime, original participant configuration, saved tasks, memory sources and writer and hook settings.
Version 1.5.1 retains its original Python 3.10 minimum and rejects the new command
environment field. To return to that version, select its retained runtime and
original configuration. Keep saved approvals and Redis data unchanged. Inspect older saved tasks with
their original runtime first; reinstalling an older package does not undo file
effects or prove that a newer saved task can safely resume in that version.
The migration guide covers command-environment grants, memory-reader selection and retained Attune AI setups. The v1 compatibility contract remains in effect.
Keep your existing memory setup working
Harness can read configured memory files, read an existing Redis memory index
and save memories explicitly. Choose a file or Redis backend explicitly for
scratch memory. Redis-backed scratch requires the redis extra and reports
unavailable if the configured service can't be reached. The optional
generation reader identifies the snapshot and source associated with its results.
Keep the writer and host hooks that maintain and deliver your existing memory. A complete Redis projection writer and RedisVL adoption remain unfinished. Version 1.8.0 extends the internal preparation for a future hydration writer. Use existing writers and hooks for generation publication, cleanup and automatic recall. Saving a memory and making it available for session recall are separate steps. Follow the memory guidance for the path you use.
Use Harness for new work. If you use Attune AI, keep its existing environment and host setup until you have verified the workflows you depend on.
Browser forms
Use the forms companion to answer questions in an existing task draft, save your answers, review the request and inspect its accepted content. Ask the person or agent running Harness for the complete private launcher link and keep the local launcher running while using the form.
Saving answers, approving a request and opening a saved form do not execute work. Browser build dispatch and execution resume are unavailable in this implementation; use the supported CLI workflow after inspecting its saved scope. Follow the forms guide for setup and available controls.
Understand the results
Read the receipt to see the output, check results and errors. For a document review, distinguish the source checks from the model's judgments. For a repair or build, inspect the agreed checks and their results before deciding what to do next.
Use status before continuing saved work. If an operation was interrupted
or its effects are uncertain, inspect the recovery guidance before trying it
again. Trusted commands should run in a dedicated checkout; process supervision
is not an operating-system sandbox.
The published 1.6.0 release record identifies its source, distributions and verification boundaries. The qualification guide explains what the software checks cover.
Documentation archive
The published 1.5.1 guide remains available with its original installation instructions and evidence.
The documentation archive keeps earlier guides, release records and screenshots under their original version labels. Use those labels to distinguish historical observations from current instructions.
Repository · Issues · CLI guide
Apache License 2.0.
Built by Patrick Roebuck, working with Codex and Claude.
Contact: Patrick Roebuck.
Metadata
Release files for attune-harness 1.8.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| attune_harness-1.8.1.tar.gz | 488.9 kB | With provenance | Details for attune_harness-1.8.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| attune_harness-1.8.1-py3-none-any.whl | Python 3 | none | any | Details for attune_harness-1.8.1-py3-none-any.whl |
Total release size: 1.0 MB
Release files / attune_harness-1.8.1.tar.gz
| Download URL | attune_harness-1.8.1.tar.gz |
|---|---|
| Size | 488.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5244b883f11cee9a1995e3ae477d75d30ac9cf8b92ccbad7fb491e0fabf477cc
|
|
BLAKE2b-256 checksum How to use checksums |
8561c364a1e45704b08fb6f0187015ba8d4e3a6474d660eb7f62e480f6752ad5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / attune_harness-1.8.1-py3-none-any.whl
| Download URL | attune_harness-1.8.1-py3-none-any.whl |
|---|---|
| Size | 559.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f83e924599b0eb0b3d40c428a80cb8fc5794c22cf2341752702cccf2f98ceaae
|
|
BLAKE2b-256 checksum How to use checksums |
ee6ac8c9114992e56835724a49d8c0cd293c1c1fe4c26a8d1abe9375c09b7639
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for attune-harness 1.8.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for attune_harness-1.8.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.