Adaptive Harness
Keep your coding client. Add verifiable governance.
Adaptive Harness is a local-first governance runtime for software-development agents. It works alongside the client you already use—Claude Code, Codex, OpenCode, Cursor, or a plain terminal—instead of replacing it with another agent workflow.
It adds four guarantees that client prompts alone cannot provide:
- Stable task identity: every task is bound to a real Git worktree and base SHA.
- Typed capability boundaries: permissions follow declared side effects, paths, networks, and execution limits—not task names or model intent.
- Trusted evidence: executor results and failures are recorded as evidence; model self-assessment is not accepted as proof.
- A real completion gate:
completedis available only when current, authorized acceptance evidence satisfies the task.
Canonical policy stays in versioned .harness/*.json files, while client
instructions and hooks remain thin, replaceable projections.
For source-of-truth ownership and implementation status, start with the documentation control plane. Product, architecture, contracts, decisions, acceptance evidence, and implementation order have separate owners.
How it fits
flowchart LR
Claude["Claude Code"] -->|"PreToolUse hook<br/>enforced"| Gateway
Codex["Codex"] -.->|"AGENTS.md guidance<br/>observe"| Gateway
OpenCode["OpenCode"] -.->|"AGENTS.md guidance<br/>observe"| Gateway
Cursor["Cursor"] -.->|"AGENTS.md guidance<br/>observe"| Gateway
Gateway["Task Envelope<br/>+ Capability Gateway"] --> Executor["Controlled Executor"]
Executor --> Evidence["Append-only evidence"]
Evidence --> Verifier["Completion Gate"]
At the client edge, the solid arrow represents verified interception. Dotted arrows represent prompt-level guidance: the client can follow the Harness path, but the instructions cannot prevent it from bypassing that path.
Integrate with your existing client
Install adp-harness first if it is not already available, then choose
the client you use in the repository. Run adp-harness integration list at any
time to inspect the supported adapters and their verified capability modes.
| Client | Integration level | Project entry point | Mode | Blocks mutating-tool bypasses? |
|---|---|---|---|---|
| Claude Code | Official adapter | CLAUDE.md + .claude/settings.json |
enforced when healthy |
Yes, through PreToolUse and the controlled executor |
| Codex | Official adapter | Managed AGENTS.md block |
observe |
No—prompt-only |
| OpenCode | Compatible instructions | Root AGENTS.md |
observe |
No—prompt-only |
| Cursor | Compatible instructions | Root AGENTS.md |
observe |
No—prompt-only |
OpenCode and Cursor are compatibility paths through the Generic adapter, not native adapters in the current MVP.
AGENTS.md and CLAUDE.md guide client behavior; they are not security
boundaries. Adaptive Harness uses the word enforced only for a verified
native interceptor, and its controlled executor fails closed when the required
host sandbox is unavailable.
Claude Code: native PreToolUse enforcement
Run the first command to inspect every proposed file, then apply the same plan:
adp-harness init --adapter claude-code
adp-harness init --adapter claude-code --apply
adp-harness doctor --verbose
This preserves existing CLAUDE.md content, adds a versioned managed block,
creates the canonical .harness/ files, and merges the following hook into
.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"hooks": [
{
"command": "\"$HOME/.local/bin/adp-harness\" adapter-hook claude-code || exit 2",
"statusMessage": "Adaptive Harness policy check",
"timeout": 5,
"type": "command"
}
],
"matcher": "Bash|Edit|Write|NotebookEdit|MultiEdit|mcp__.*"
}
]
}
}
The hook permits read-only tools, rejects direct mutating tools, and accepts
only the exact "$HOME/.local/bin/adp-harness" capability run --task … --capability … launcher. The absolute user-level path keeps the hook working
when Claude Code is launched from a GUI that does not inherit your terminal
PATH.
Copying the JSON alone is not a complete integration: it does not create the
canonical task policy or the managed CLAUDE.md projection.
Claude Code is enforced only while adp-harness doctor reports the adapter hook
and managed projection healthy. Capability execution additionally requires a
supported host sandbox and fails closed without one. Linux enforcement requires
Bubblewrap and working user namespaces; otherwise the base CLI and explicit
observe workflows remain available.
Codex: managed AGENTS.md
adp-harness init --adapter codex
adp-harness init --adapter codex --apply
adp-harness doctor --verbose
Adaptive Harness preserves existing AGENTS.md content and adds a small,
versioned block instructing Codex to start tasks, request capabilities, and
verify through Harness. The integration is intentionally observe: Codex can
read and follow the instructions, but the file cannot intercept a bypassing
tool call.
OpenCode and Cursor: portable AGENTS.md instructions
OpenCode project rules and
Cursor rules both support a
root-level AGENTS.md. Initialize the client-independent runtime first:
adp-harness init --adapter generic
adp-harness init --adapter generic --apply
adp-harness doctor --verbose
Then add this plain Markdown fragment to the repository's existing
AGENTS.md, or create the file if it does not exist:
## Adaptive Harness
Use Adaptive Harness for repository-changing tasks.
Start a new task through `"$HOME/.local/bin/adp-harness" task start`, request capability
escalation through Harness, and run Harness verification before completion.
Treat Harness task status and executor evidence as authoritative.
This fragment is immediately readable by both clients, but remains a
prompt-only observe integration. Because it is copied manually rather than
generated as a managed projection, adp-harness doctor does not drift-check the
fragment.
Switch an initialized project between official adapters
Canonical task policy and evidence do not belong to the client projection. Review and apply a projection change without reinitializing the project:
adp-harness integration install claude-code
adp-harness integration install claude-code --apply
adp-harness doctor --verbose
Use codex in place of claude-code to switch to the Codex projection. The
transaction preserves unrelated user content and replaces only
Harness-managed instructions and native hook settings.
Try it in 5 minutes
After the Codespace is ready, the Python quickstart takes about five minutes to preserve a failing test as evidence, record a successful fix, and pass the completion gate. One additional minute enables progressive TDD guidance and shows it activate only for the next matching task. The same Dev Container works locally in VS Code.
Contributing
Contributions are welcome:
- Read the contributing guide before opening a pull request.
- Pick a scoped task from the good first issues.
- Follow current priorities in the public roadmap.
For substantial behavior or architecture changes, open an issue before implementation. The product requirements own product scope and safety invariants; use the documentation control plane to find architecture, contracts, decisions, acceptance evidence, and implementation order.
Install
Install the published, self-contained CLI for the current user. This does not require Python, a Python package manager, or sudo, and it does not modify the current repository:
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/hilt21/Adaptive-Harness/releases/latest/download/install.sh | sh
adp-harness --version
To install a fixed release instead of latest, set its SemVer explicitly:
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/hilt21/Adaptive-Harness/releases/latest/download/install.sh \
| HARNESS_VERSION=0.3.0 sh
The installer selects the platform artifact, verifies its checksum, and installs
adp-harness in ~/.local/bin. If that directory is not available in a clean
new shell, it shows one small managed change to the default zsh, bash, or fish
configuration and asks once before writing it atomically. Declining stops the
installation without leaving a partial Runtime. Open a new terminal after the
installer finishes; no temporary export PATH=... is required.
Non-interactive installation proceeds only when the clean-shell check already
passes or the caller explicitly sets HARNESS_CONFIRM_PATH=1. An unknown
default shell, an unrelated adp-harness elsewhere on PATH, or an
unverifiable file at the target path stops the installer without overwriting
anything.
If an install, update, rollback, or uninstall process is interrupted, a fail-closed lock may remain. The next command prints the exact lock-file path; first confirm that no Adaptive Harness lifecycle command is still running, then remove only that lock file and retry.
To inspect and verify the installer before executing it, download both release files and compare the published SHA-256 entry:
curl --proto '=https' --tlsv1.2 -LsSf \
-o install.sh \
https://github.com/hilt21/Adaptive-Harness/releases/latest/download/install.sh
curl --proto '=https' --tlsv1.2 -LsSf \
-o SHA256SUMS \
https://github.com/hilt21/Adaptive-Harness/releases/latest/download/SHA256SUMS
expected=$(awk '$2 == "install.sh" { print $1 }' SHA256SUMS)
actual=$(shasum -a 256 install.sh | awk '{ print $1 }')
test -n "$expected" && test "$actual" = "$expected"
less install.sh
HARNESS_VERSION=0.3.0 sh install.sh
Python packaging remains an advanced alternative for users who already manage isolated CLI tools:
pipx install adaptive-harness
# or
uv tool install adaptive-harness
The MVP supports macOS arm64 and glibc Linux on arm64 and x86_64. WSL2 follows
the Linux path experimentally; native Windows is not supported in 0.3.0.
macOS x86_64 standalone publication requires a self-hosted Intel runner and is
not included in the current GitHub-hosted release matrix. The
documentation control plane identifies the distinct sources
for product scope, architecture, contracts, decisions, and evidence.
Linux enforced execution also requires Bubblewrap and working user namespaces. The installer reports a missing sandbox dependency but never invokes sudo or a system package manager. Base CLI and explicit observe operation remain available.
For this source tree, use the development environment:
uv sync --dev
uv run adp-harness --version
Self-contained installations update only on explicit request:
adp-harness self update
adp-harness self rollback # returns to the one verified previous Runtime
adp-harness self uninstall # preserves local records and repository config
adp-harness self uninstall --purge-data
Running the installer again does not perform a normal upgrade; it points a
healthy installation to adp-harness self update. If the v2 installation
manifest proves that a damaged launcher or Runtime belongs to Adaptive Harness,
the same installer shows a repair plan and asks before replacing it. If
ownership cannot be established, it stops for manual inspection.
Package-manager installations must be updated and removed with the package
manager that installed them; self update, self rollback, and standalone
repair do not manage those installations.
Initialize without a client projection
Use the Generic adapter for a terminal-only workflow, CI, or a client whose
instruction file you manage manually. The project must be a Git repository
with an initial commit. Deterministic scanning needs a declared test command;
for example, a Python project can declare pytest in pyproject.toml, while a
Node project can declare a test script in package.json.
Initialization is review-first. The first command prints a complete diff and writes nothing:
adp-harness init --adapter generic
adp-harness init --adapter generic --apply
adp-harness doctor --verbose
The Generic adapter creates no client instruction file and is explicitly
observe. To add an official projection later, use adp-harness integration install as shown above. Commit the three canonical files and any client
projection you selected before starting the first task:
.harness/config.json
.harness/capabilities.json
.harness/modules.lock.json
Run the first governed task
Give the task an explicit ID, scope, capability, and optional module traits:
adp-harness task start \
--id first-task \
--goal "Fix the failing example" \
--scope src \
--scope tests \
--capability project-tests \
--trait code-change
adp-harness capability run \
--task first-task \
--capability project-tests
adp-harness task verify first-task
completed is produced only when required acceptance evidence, workspace identity, scope, and security invariants all pass. task accept-risk can waive only explicitly waivable verification gaps.
Capabilities with approval_policy: "ask" or high-risk side effects require a separately reviewed, task/SHA/worktree/path/count/expiry-bound approval:
adp-harness capability approve \
--task first-task \
--capability project-tests
adp-harness capability approve \
--task first-task \
--capability project-tests \
--apply
The plan command changes no task history. An applied approval is append-only and cannot be reused outside its exact scope or use count.
Local records and storage
Runtime records are isolated by repository identity under the user data directory. The default is ~/.local/share/harness/projects/<repository-id>/, or $XDG_DATA_HOME/harness/projects/<repository-id>/ when XDG is configured. Project statistics are shared by linked worktrees, while task records and artifacts live under a worktree-specific worktrees/<worktree-id>/ directory. Different repositories and worktrees do not share task evidence.
An advanced, per-clone mode keeps records in the Git common directory, normally .git/adaptive-harness/. It does not write runtime data beside the committed .harness/*.json files and is not offered during first-time initialization:
adp-harness storage mode
adp-harness storage migrate repository-local
adp-harness storage migrate repository-local --apply
adp-harness storage migrate user-data --rollback
adp-harness storage migrate user-data --rollback --apply --yes
Migration is review-first. It is rejected while a task is active or when the target already contains records; apply copies and verifies data, atomically changes the local mode, and retains the source as a rollback copy. An immediate --rollback may switch to that retained copy only while it still exactly matches the active records. A later reverse migration follows the normal process after the retained target has been explicitly archived or pruned; existing records are never merged automatically.
Progressive modules and templates
Modules are installed but unloaded by default. Enablement is review-first; task JSON and human output report installed, enabled, suggested, activated, or blocked. Context appears only for activated modules.
adp-harness module enable tdd-guidance --policy auto
adp-harness module enable tdd-guidance --policy auto --apply
adp-harness task start \
--id tdd-task \
--goal "Add validation" \
--scope src \
--capability project-tests \
--trait code-change
The v0.2 caller-classified Trial commands have been removed. Behavioral Trial
mutation is accepted only through a qualified Recommendation, immutable Trial
declaration or decision, exact Review/Approval, and the registered Evolution
handler; a human beneficial annotation never grants promotion authority.
Templates are inert and only write after an explicit render, diff review, and confirmation:
adp-harness template render handoff --output docs/handoff.md
adp-harness template render handoff --output docs/handoff.md --apply
Development and verification
uv sync --dev
uv run ruff check .
uv run mypy src tests
uv run pytest
uv build
Real host sandbox tests are opt-in locally because nested test-runner sandboxes may block them:
HARNESS_RUN_OS_SANDBOX_E2E=1 uv run pytest -q \
tests/modules/test_runner.py \
tests/core/test_verifier.py \
tests/cli/test_cli.py \
-k 'runner or enforced' --no-cov
All commands provide stable exit codes and JSON output through their local --json option. Mutations show the proposed change before confirmation. init --json emits the exact Evolution proposal and review; non-interactive init --apply requires a matching external Approval JSON document through --approval PATH. Interactive init --apply still asks the local human to confirm the displayed diff.
Human summaries and top-level help support English and Simplified Chinese. The locale option precedes the command; JSON fields and protocol values remain stable English:
adp-harness --locale zh-CN doctor
adp-harness --locale zh-CN doctor --json
Metadata
Release files for adaptive-harness 0.3.0
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 |
|---|---|---|---|---|
| adaptive_harness-0.3.0.tar.gz | 539.4 kB | With provenance | Details for adaptive_harness-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| adaptive_harness-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for adaptive_harness-0.3.0-py3-none-any.whl |
Total release size: 890.6 kB
Release files / adaptive_harness-0.3.0.tar.gz
| Download URL | adaptive_harness-0.3.0.tar.gz |
|---|---|
| Size | 539.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4ef878bd995a0446fb6e981a5e28bb523e95b0337338ab65cef156d70ed08732
|
|
BLAKE2b-256 checksum How to use checksums |
e372bef2817686d305e911e4b2790e7b686cfd2724a7e5b3e0514f7bd9e87991
|
| 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 Aug 31, 2026.
Transparency logRelease files / adaptive_harness-0.3.0-py3-none-any.whl
| Download URL | adaptive_harness-0.3.0-py3-none-any.whl |
|---|---|
| Size | 351.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
11af47dd5bf5f525e1b63ad40115e39f4d59ca15dd6c5dedbaf443fd4332b31e
|
|
BLAKE2b-256 checksum How to use checksums |
4d38ee38eb58960243ab52dc430b40b66350b1908fee88af734676cb67754516
|
| 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 Aug 31, 2026.
Transparency logSecurity for adaptive-harness 0.3.0
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 adaptive_harness-0.3.0.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 Aug 31, 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.