repo-harness

repo-harness

A file-backed workflow for Claude and Codex, and an authorized runtime for the programs built on top of it

English | 简体中文 | 日本語 | Français | Español

Give the agent a complete PRD or Sprint; after that, your loop is just review and next, or start /goal and go AFK.

repo-harness ships a CLI plus skill/runtime hooks that write context, plans, handoffs, checks, and review evidence back into the project, so the next agent session continues from files instead of chat memory. It adopts an existing repo with a tasks-first agent contract that keeps Claude and Codex aligned.

On top of that contract it runs authorized programs: long-running work that holds its own authorization, budget, task offers, and leases, so a Sprint can advance across sessions without a human driving each step.

Contents

• Get Started
• Why repo-harness
• Two Layers
• Key Features
• How It Works
• Task Workflow
• Authorized Programs
• Hooks
• Local Human Control Board
• MCP Connector
• Reviewing Work
• Skills
• Maintainer Reference
• Acknowledgements
• Current Release
• License

Get Started

1. Install the CLI

Prerequisites: a Git working tree, bun, and usable herdr >=0.9.0 for host readiness; macOS/Linux also require bash, while Windows requires Git for Windows (including its Bash and usr/bin tools). jq is optional. No Node.js required — the installer uses Bun >= 1.4.0 as the runtime, installing or upgrading Bun first when needed.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.ps1 | iex

With Bun >= 1.4.0 already on PATH, skip the shell installer. Package-manager-owned Bun installs fail closed with the matching upgrade command (brew upgrade bun) instead of overwriting manager-owned files.

bunx repo-harness@latest install     # Bun one-shot bootstrap
bun add -g repo-harness              # or install the persistent CLI first
repo-harness install
npx -y repo-harness@latest install   # npx fallback; the CLI still runs on Bun

Install herdr from herdr.dev and verify herdr --version. Persistent review hosting requires POSIX process groups; on Windows use WSL. Missing or unusable herdr blocks host readiness. Before upgrading from tmux, drain existing reviewers using the previous version and explicitly rebind terminal endpoints. See runtime cutover.

2. Bootstrap the host runtime

repo-harness install

On Windows, keep Git for Windows on the install/update PATH. That explicit ceremony validates and pins git.exe, its matching bash.exe/usr/bin, and the install account's absolute TEMP directory plus native System32 tools in the OS account's ~/.repo-harness/config.json#protectedHelperRuntime. Protected workflow helpers do not rediscover tools from a caller's PATH; rerun repo-harness update after relocating or replacing Git for Windows.

The global bootstrap: installs the npm package as the global CLI, refreshes repo-harness skill aliases, installs user-level hook adapters, and records an explicit install profile. It is idempotent and does not apply repo-local workflow files to the current directory. --dry-run --json lists components to install, skip, and remove first. Profiles, native Codex delegation authority, refresh commands, and the read-only setup check audit: install-profiles.md.

3. Preview the repo-local contract

repo-harness init --dry-run

Run this from the target repository root. It reports the specs, task state, helper runtime, hook adapter target, and verification files that would be created or refreshed. It never creates an application stack; new projects and modules use repo-harness-setup's scaffold mode instead.

4. Apply and verify

repo-harness init
bash scripts/check-task-workflow.sh --strict
bun test

Success looks like this

Successful init enables automatic architecture document projection and proactive Stop-hook refactor recommendations when those preferences are unset. Explicit disabled choices are preserved. Suggestions present evidence for a user decision; they do not authorize a refactor. Dry-run does not write these preferences.

Apply ends with === Migration Report ===, naming where generated hook behavior comes from, the user-level ~/.claude/settings.json and ~/.codex/hooks.json adapter target, the repo-local surfaces created or refreshed, the .ai/harness/scripts/* helper runtime, and an --- External Tooling --- readiness block. Stable intent then lives in docs/spec.md, execution state in plans/ and tasks/, resume state in .ai/harness/handoff/. If the dry run looks wrong, stop and read hook-operations.md first.

Update and remove

repo-harness update          # reconcile CLI, mandatory deps, profile tooling, and CodeGraph
repo-harness update --check  # read-only repair guidance, no writes
repo-harness uninstall --dry-run # preview owned user configuration cleanup
repo-harness uninstall           # remove owned configuration; preserve user changes/history
repo-harness mcp uninstall --dry-run # preview independent MCP setup cleanup
repo-harness mcp uninstall --services-stopped # after stopping all MCP HTTP services

Why repo-harness

• File-backed sessions, not chat memory. Separate Claude and Codex sessions stay coordinated through the repo. SessionStart injects the prior session's resume packet, Stop writes the handoff, and each edit records a small journal event. A session can end mid-task and the next one resumes the exact next step, blockers, and changed files without re-deriving them.
• Token-lean by design. Instead of grep-and-read loops that re-scan the repo every session, the harness leans on a pre-built CodeGraph index for structural queries and on progressive context loading: a stable ~12KB root context plus capability blocks loaded only when the files you touch need them. Agents read a ~1KB capability contract instead of rediscovering structure.
• Review-ready evidence. Every task leaves a contract, structured check evidence, and a review card behind. The human decision surface is one screen — verdict, intended vs actual files, commands passed, residual risk, rollback — rather than a reconstruction of what the agent claims it did.
• Unattended work stays accountable. A program cannot start without a stored authorization, cannot exceed its budget ledger, cannot hold a task past its lease, and cannot claim acceptance without a receipt. Autonomy is bounded by artifacts, not by trust.

In an adopted repo, the surface area is intentionally small:

Two Layers

The product reads as two layers that share one set of files.

Layer 1 — the session contract. One human, one agent session, one task at a time. Plans, contracts, checks, reviews, and handoffs are the durable authority; hooks keep the session inside them. This is the whole product for a solo repo, and everything in Task Workflow belongs here. Nothing below is required to use it.

Layer 2 — authorized programs. Long-running work that outlives a session: an unattended controller stepping a Sprint, a repair campaign that authors and adopts GitHub Issues, a refactor program driven off the architecture model, a collaboration plane where several Module Engineers exchange signals and handoffs. Each program is gated on an operator-minted authorization, draws on a per-goal budget ledger, and holds work through renewable leases. See Authorized Programs.

Layer 2 does not replace layer 1: a program's every step still projects into the same plan, contract, and review artifacts a human would have written.

Key Features

How It Works

1. Source package: this repository owns the CLI, command facades, templates, typed hook handlers, the operator-helper asset, workflow contract, tests, and release gate.
2. Target repo contract: repo-harness init or migration writes repo-local files such as docs/spec.md, plans/, tasks/, .ai/context/, .ai/harness/, helper scripts, and .ai/hooks/.
3. Host adapters: user-level ~/.claude/settings.json and ~/.codex/hooks.json route Claude/Codex events into repo-harness-hook.

The hook entrypoint exits silently for non-opt-in repos. For opted-in repos, the