repo-harness: file-backed state for Claude Code and Codex sessions
File-backed workflow harness for reliable Claude Code and Codex sessions.
At a glance
- What is it?
- repo-harness is an MIT-licensed TypeScript CLI that writes agent context, plans, handoffs and review evidence into the repository, so a new session resumes from files rather than chat history. It is opinionated about its host runtime and is not a fit for every machine.
- Who is it for?
- Adopt repo-harness if you run Claude Code or Codex across sessions on macOS, Linux or WSL, and you want plans, handoffs and review evidence to live in the repo instead of a chat log. Skip it if you work on native Windows without WSL, if you cannot install herdr 0.9.0 or newer, or if you only want a terminal multiplexer.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem repo-harness targets: sessions that forget
A Claude Code or Codex session ends, and the reasoning behind the last edit goes with it. The next session re-scans the repository, re-derives what was in progress, and often re-reads files that were already understood. The README frames this as the gap repo-harness fills: it writes context, plans, handoffs, checks and review evidence back into the project so the next session continues from files instead of chat memory. The audience is a developer or small team already running one or both of those agents on a real repository, who wants the work to survive the session boundary. The project describes its contract as tasks-first, which means the unit of work is a task with a contract and evidence attached, not a freeform conversation. That framing also sets the ceiling. If your agent usage is a single question and answer, or if you never leave a task half-finished, the harness adds ceremony without removing any of your pain.
Two layers: the task contract and authorized programs
The README separates the project into two layers. The first is the workflow contract: a CLI plus skill and runtime hooks that keep Claude and Codex aligned on the same task state, with stable intent in docs/spec.md, execution state in plans/ and tasks/, and resume state in .ai/harness/handoff/. The second layer is what the README calls authorized programs: long-running work that carries its own authorization, budget, task offers and leases. The claim is that a Sprint can advance across sessions without a human driving each step. Those are different commitments. The first is a bookkeeping convention with hooks attached; the second is a delegation model where the harness holds authority on your behalf. The README does not spell out how a lease is granted, revoked or expires, so treat the authorized-programs layer as the part to inspect before you rely on it.
The mechanism: hooks, a journal, and progressive context
The data flow is concrete in the README. A SessionStart hook injects the prior session's resume packet. A Stop hook writes the handoff. Each edit records a small journal event. Hook behavior is generated and installed at the user level, targeting ~/.claude/settings.json and ~/.codex/hooks.json, while the repo-local surfaces and the .ai/harness/scripts/* helper runtime are created by repo-harness init. Context loading is progressive: a stable root context of roughly 12KB, with capability blocks pulled in only when the files being touched require them, and a capability contract of roughly 1KB that the agent reads instead of rediscovering structure. Structural queries lean on a pre-built CodeGraph index rather than grep-and-read loops. The token argument is stated as a design intent, not a measured result, and the README supplies no benchmark. The trade-off is that a pre-built index has to be kept current; repo-harness update is the command that reconciles CodeGraph along with the CLI and profile tooling.
Getting it running: install, bootstrap, init, verify
The README gives a specific sequence. Install the CLI with the shell installer (curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh on macOS and Linux), the PowerShell equivalent on Windows, or bunx repo-harness@latest install. Prerequisites listed are a Git working tree, bun, and herdr 0.9.0 or newer for host readiness; macOS and Linux also need bash, Windows needs Git for Windows including its Bash and usr/bin tools, and jq is optional. No Node.js is required, since the installer uses Bun 1.4.0 or newer as the runtime and will install or upgrade Bun first. Package-manager-owned Bun installs fail closed and print the matching upgrade command (brew upgrade bun) rather than overwriting manager-owned files. Then run repo-harness install for the global bootstrap, which installs the CLI, refreshes skill aliases, installs user-level hook adapters and records an install profile. It is idempotent and does not apply repo-local files to the current directory. Preview with repo-harness init --dry-run from the target repository root, apply with repo-harness init, then verify with bash scripts/check-task-workflow.sh --strict and bun test. Apply ends with a migration report naming the adapter targets and the external tooling readiness block. If the dry run looks wrong, the README says to stop and read docs/reference-configs/hook-operations.md first.
Where repo-harness breaks or is the wrong tool
The runtime requirements are the sharpest constraint. Missing or unusable herdr blocks host readiness outright, and persistent review hosting requires POSIX process groups, which the README says means using WSL on Windows. If you cannot run WSL, the review-hosting path is closed to you. On Windows, the install and update PATH must carry Git for Windows, and the ceremony validates and pins git.exe, its matching bash.exe and usr/bin, the install account's absolute TEMP directory, and native System32 tools into ~/.repo-harness/config.json under protectedHelperRuntime. Protected workflow helpers do not rediscover tools from a caller's PATH, so relocating or replacing Git for Windows requires rerunning repo-harness update. That is a deliberate safety choice with a maintenance cost attached: your environment is now recorded in a config file and has to be re-recorded when it moves. There is also a migration hazard. The README instructs anyone upgrading from tmux to drain existing reviewers with the previous version and explicitly rebind terminal endpoints before the switch. Arriving mid-flight with live reviewers is the failure mode to avoid.
The alternative: tmux plus a hand-written conventions file
The obvious comparison is the setup repo-harness is replacing: a terminal multiplexer such as tmux holding long-lived agent panes, plus a CLAUDE.md or AGENTS.md file of conventions that a human maintains. The difference is where state lives and who writes it. With tmux, the session persists only while the process does, and continuity depends on a person updating the conventions file. repo-harness moves that state into the repository itself, with hooks writing the handoff at session end and a journal recording each edit, so continuity survives a reboot and does not depend on anyone remembering to write it down. The cost is an installed CLI, a host runtime with readiness checks, generated hook adapters in your user-level settings, and a pinned helper runtime on Windows. tmux asks nothing of your machine and guarantees nothing about your next session. repo-harness asks for herdr, Bun and a working Bash environment, and in exchange the next session starts from a resume packet you can read in the repository.
Maintenance, upgrades and the MIT licence
Upgrade cost is visible in the release cadence: v0.16.2, v0.17.0 and v0.17.1 landed within about three weeks in August 2026, so this is a project that moves. The README provides reconciliation commands rather than a migration guide: repo-harness update reconciles the CLI, mandatory dependencies, profile tooling and CodeGraph, and repo-harness update --check gives read-only repair guidance without writing. Removal is staged too. repo-harness uninstall --dry-run previews cleanup of owned user configuration, repo-harness uninstall removes owned configuration while preserving user changes and history, and MCP cleanup is independent through repo-harness mcp uninstall --dry-run, with repo-harness mcp uninstall --services-stopped to be used after stopping all MCP HTTP services. The licence is MIT, which permits commercial use and modification, but the README does not state how the installed hook adapters in ~/.claude/settings.json and ~/.codex/hooks.json interact with files you already maintain there. That question is worth resolving with your own counsel rather than inferring from the repository.
Editorial conclusion
Adopt repo-harness if you run Claude Code or Codex across sessions on macOS, Linux or WSL, and you want plans, handoffs and review evidence to live in the repo instead of a chat log. Skip it if you work on native Windows without WSL, if you cannot install herdr 0.9.0 or newer, or if you only want a terminal multiplexer. Before committing, run repo-harness init --dry-run from the repository root and read the migration report, then confirm the protected helper runtime recorded in ~/.repo-harness/config.json matches the Git for Windows and TEMP paths you actually use.
Community notes