repo-harness

repo-harness

Shared context, hooks and review evidence for Claude and Codex

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

Give the agent a GitHub issue and acceptance checks. Keep changes and verification evidence in its PR.

repo-harness ships a CLI, skills and hooks for context, review evidence and handoffs. The GitHub issue and PR own task identity, scope and status. Repository files let Claude and Codex resume work across sessions.

Contents

• Get Started
• Why repo-harness
• Task Authority
• Key Features
• How It Works
• Task Workflow
• Work Across Sessions
• 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.5 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

Pi is an optional host under the default --target both. When pi is on PATH, install and update register the installed repo-harness directory with pi install <package-directory>. An existing user package entry is retained. Missing Pi skips this step. Preview with repo-harness install --dry-run --json. The minimum Pi version is MIN_PI_VERSION; there is no upper bound. repo-harness setup check and repo-harness update --check report the version, path resolver capability, package entry and skill projection.

Catalog skills use ${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/skills and the same profile selection and ownership rules as the other hosts. Uninstall removes only owned package entries and unchanged owned skills. Package commands use Pi's CLI; repo-harness does not write Pi settings, credentials or trust files. Pi covers session context, agent notices, edit/write, bash and Stop hooks. It has no fleet roles or subagent hooks. PowerShell, !/!! user shell, other extensions' file writes and third-party MCP writes are outside this coverage.

DSH (DeepSeek Harness) is a package host. repo-harness ships a Cordis plugin and a bundle patch; DSH manages the installation. Load the plugin with dsh plugin add link:<repo-harness package directory>, or with dsh plugin add repo-harness@<version> after release. The plugin needs Bun on PATH; it starts this package's dist/hook-entry.js. It maps native write, edit and bash calls to the typed guards, delivers session context through the first agent step, and records Stop at the turn boundary. It disables itself in a repository without .ai/harness/workflow-contract.json. MCP writes, pwsh, ! user commands and writes from other plugins stay outside this boundary. DSH already reads AGENTS.md and ~/.agents/skills; the plugin does not change those paths. repo-harness doctor and repo-harness setup check report whether a DSH profile declares the bundle, and list the external skills in the shared agents root. repo-harness does not write the DSH profile.

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
bun test

Success looks like this

Init writes repo-local files and two files under HOME: the repo registry entry and, when verification runs, the global Codex handoff packet under ~/.codex/handoffs/. It writes no install-managed host files. When the required Herdr skill or the architecture projection preference is missing, init reports a skipped step that names repo-harness update. repo-harness supplies tools and evidence; the Bot decides what to schedule.

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, and an --- External Tooling --- readiness block. Stable intent then lives in docs/spec.md and docs/prds/, task state in the GitHub issue and PR, 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 upgrade         # check retired leftovers; no writes
repo-harness upgrade --apply # back up and remove only proven owned leftovers
repo-harness upgrade decide --keep <path> # record an operator decision for a report-only project item
repo-harness upgrade --registered # preview project refresh for every registered repo; 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

update and setup check print one leftover count. update does not apply cleanup. Run upgrade --json for ownership and proof per item. Use --scope project|global|all to select the scan (default: all). Project scope requires a Git repository. Check exits 1 when any leftover remains.

upgrade --apply also refreshes old owned copies of still-shipped skills from this package. It refreshes the contract template only when an old ownership hash matches. It keeps changed copies. It preserves legacy workflow-state libraries. Update continues to report counts only. This puts destructive changes and copy replacement under the same explicit, backed-up transaction.

Old merge-gate state, v0.10.0 archives, and older backups are report-only by default. Use upgrade --apply --include-state-artifacts to select these artifacts for removal. This flag still requires ownership proof. Unknown artifacts stay. The third-party Claude plugin and user rule lines in ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md are always report-only. See external tooling for the plugin ID.

Project cleanup supports regular files and host hook entries. Project directories and symlinks remain report-only. Global cleanup supports verified owned directories and links.

Cleanup keeps changed and unowned files. It also keeps current global typed hook adapters and user hook entries. It backs up each target before removal. Apply exits 0 when all eligible operations succeed, even if report items remain. A second apply with no eligible items changes no bytes. The command prints the backup paths and records nonempty runs in ~/.repo-harness/upgrade-cleanup.log.jsonl.

For project rollback, use the printed repo-harness init rollback command. For global rollback, replace each target with its numbered snapshot at the original path in the backup manifest. Do not overlay directory contents. Restore symlinks verbatim. There is no install --restore-transaction command. Keep the backup until you verify the cleanup. Homes from the older v3.x–v5.x release line have no supported historical proof and remain report-only.

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, and Stop writes the handoff and resume views. 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 evidence. The PR records the changed files, checks, residual risk and rollback. Review uses the observed result for the same revision.
• Work across sessions. A handoff records the issue, branch, current result and next action. The next agent reads the current issue before it continues.

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