repo-harness: a workflow for Claude, Codex and Pi agents in a repository
repo-harness
A CLI, hooks and skills for long Claude, Codex and Pi work: the issue and PR own the task and review gets a PR with checks
- 435 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The installer adds hooks to `~/.claude/settings.json` and `~/.codex/hooks.json`, and they run in every session of opted-in repositories
- The `repo-harness publication merge` command merges a PR when the `acceptance_merge` policy is on in the base branch
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/repo-harnessDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The installer adds hooks to `~/.claude/settings.json` and `~/.codex/hooks.json`, and they run in every session of opted-in repositories
- The `repo-harness publication merge` command merges a PR when the `acceptance_merge` policy is on in the base branch
This is third-party code. Review the repository files before installing.
What it does
`repo-harness` wraps an existing repository so that Claude, Codex and Pi can carry out long engineering work in it across sessions, machines and worktrees. The task is owned by the GitHub issue and PR: the branch name points to the issue, and a new agent session rereads the issue and PR and continues from the step named there, not from a recap of an old chat. The `repo-harness init` command puts `AGENTS.md` and `CLAUDE.md`, the `docs/` and `.ai/` folders, a `tasks/lessons.md` file and a block in `.gitignore` into the repository. The helpers themselves are not copied in; they run through `repo-harness run`. Global adapters in `~/.claude/settings.json` and `~/.codex/hooks.json` route agent events to typed handlers: at session start they load context, and the guards `RepoScopeGuard`, `ExternalReferenceGuard`, `OpsPrivateGuard`, `EditScopeGuard` and `ApplyPatchScopeGuard` block edits outside the task boundary with one reason line and a `Fix:` hint. In repositories that are not opted in, the hook stays silent. In the PR the agent leaves the changes, the checks that ran, a list of what remains open and a rollback plan. When strict acceptance is needed, a separate sandboxed reviewer runs up to three rounds of repairs. There is a local web board, `repo-harness operator serve`, on loopback only, a local MCP server, `repo-harness mcp serve`, and 12 skills split into skills for the orchestrator («Bot») and for executors («Worker»).
Who it is for. Solo developers and small teams who hand the code to agents and keep the decision whether to accept a change.
Good fit when
- A task grows beyond one chat and a new session has to continue from the branch, the issue and the PR
- Work alternates between Claude and Codex on different machines or in different worktrees
- Agents edit files outside the task and you need hooks that block such edits with a clear reason
- A PR arrives for review with the checks, open questions and rollback plan collected in one place
- A local MCP client reads repository state and writes PRDs without access to the source code
Not a fit when
- Tasks are tracked outside GitHub: the issue and PR serve as the source of truth
- A scheduler or background dispatcher is needed: repo-harness runs and queues nothing by itself
- You need an environment to host agents or a replacement for build, tests and release: the tool replaces none of them
- Access to global agent settings is unavailable: the adapters are written to `~/.claude/settings.json` and `~/.codex/hooks.json`
Example request
Take issue 42 from this repository, do the task in a separate branch and open a PR with the checks, open questions and a rollback planLimitations
Git, Bun 1.4 or newer (the installer installs or upgrades it itself) and `hc` (herdr-core) for agent readiness checks are required. macOS and Linux need `bash`, Windows needs Git for Windows. Installing with `bunx repo-harness@latest install` needs no Node.js.
For Codex the hooks file is marked as trusted in the app settings. A repository joins the workflow only after `repo-harness init`; until then the hook exits silently. Merging a PR with `repo-harness publication merge` is allowed only when the `acceptance_merge` policy is on in the base branch.
How to disable. The `repo-harness uninstall --dry-run` command shows what would be removed, and `repo-harness uninstall` removes the global runtime and the adapters from agent settings. Delete the files in the repository by hand.
FAQ
How do I install repo-harness?
Run `curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh`; if Bun is already installed, `bunx repo-harness@latest install` works. Then in the repository root run `repo-harness init --dry-run` and, after reviewing, `repo-harness init`.
Which agents does repo-harness work with?
Claude (5 hook routes through `~/.claude/settings.json`), Codex (5 routes through `~/.codex/hooks.json`) and Pi. Pi connects automatically when `pi` is on the PATH.
What stays in the repository after init?
`AGENTS.md`, `CLAUDE.md`, `docs/`, `tasks/lessons.md`, `.ai/`, `deploy/`, the private `_ops/` folder and one managed block in `.gitignore`. Helper scripts are not copied into the repository.
What is acceptance review?
A persistent sandboxed reviewer works in a linked checkout and makes up to three repair rounds per PR. The result is recorded as an acceptance receipt bound to the final content. Commands: `repo-harness review round`, `status` and `close`.
What does the repo-harness MCP server do?
The `repo-harness mcp serve --repo . --profile planner` command lets a local MCP client read repository state and write PRDs. Source-code writes are off by default, and `repo-harness mcp doctor --repo .` checks the setup.
Discussion
No questions or reviews yet.
Related
CLI toolsRepository Harness installs an AGENTS.md entrypoint, a document map and explicitly invoked onboarding skills into a repo and updates them safely
Gives each coding agent its own repository copy with separate ports and a database, then verifies results in one shared pipeline.
A Claude Code plugin with /readiness and /setup skills that scores a repo for agent work and installs rules, hooks and checks.
Python runtime for agent work: task boundaries, independent verification of results and a saved handoff between sessions
Agent Harness Kit: structured agent workflow
Agent Harness Kit
The ahk CLI sets up five agent roles, a task MCP server and spec skills in your project for Claude Code, Codex and Cursor
Codely team skills that run agent work in phases: a plan in a file or GitHub issues, review after each phase and a clean commit
README in short
The README explains why an agent needs a harness (context lives in the issue and PR, checks are separate from acceptance) and shows installation, the workflow diagram and a two-session example. It continues with a command table, the operator console, the skill list, supported agents and documentation links. MIT license.