repo-harness

Repo-use is an open‑source command‑line tool that turns Claude or Codex coding sessions into a repeatable, file‑backed workflow. It moves the source of truth from chat memory into files stored in the repository, letting both the AI agents and humans read the same artifacts. The project is hosted on GitHub and currently at version 0.14.2.

The tool is aimed at developers who want a durable record of planning, execution, and review when using Claude or Codex. You start by initializing the runtime with a single command (`npx -y repo-use init`). The CLI then installs a set of repo‑local workflow files, including adapters, skills, and a CodeGraph index. After that you can preview a contract with `repo-use adopt --dry-run`, which produces a migration report showing the surfaces that will be managed. The workflow proceeds in a loop: you hand the agent an approved plan or sprint, the agent runs the task, and you review the results before moving to the next step.

Each session writes its state to a stable root context (about 12 KB) and a CodeGraph index, so the system stays token‑lean. Handoffs, plans, and resume packets live under `.ai/use/handoff/`, allowing a session to pause and later resume exactly where it left off, including any blockers or file changes. Hooks guard the process: edit gates block progress until a plan is approved, and done‑claim gates verify that file‑backed evidence exists. A single Human Review Card presents the verdict, intended versus actual file changes, commands executed, residual risk, and rollback options. Isolated worktrees keep unrelated dirty state protected, and an optional MCP sidecar can give read‑only repo access to external clients without allowing writes.

The architecture consists of eight managed routes that warn, block, trace, and hand off work. Contracts and the filing system hold durable state, while a verification layer proves that work matches the plan. Planning can be done with ChatGPT Pro, which generates PRD and sprint artifacts that Claude or Codex then executes. The system also supports a reverse direction where an Oracle browser engine drives a signed‑in ChatGPT Web session for consults.

Key features

• File‑backed sessions store plans, contracts, and reviews in the repository instead of chat memory.
• Token‑lean design uses a ~12 KB root context plus a CodeGraph index for structural queries.