File-backed sessions, not chat memory.
repo-harness turns Claude and Codex coding sessions into a repeatable, repo-local workflow. Hand the agent an approved plan or sprint — your loop is just review and next.
Chat memory forgets. The repo remembers.
The same coordination problem, two ways. repo-harness moves the source of truth out of the thread and into files every agent — and every human — can read.
- Context evaporates when a session ends or hits its limit
- Each session re-derives structure with grep-and-read loops
- No durable record of what was decided, or why
- Claude and Codex drift out of sync across threads
- Review means re-reading the whole conversation
- Resume the exact next step from .ai/harness/handoff/
- A ~12KB stable root context plus a CodeGraph index
- Plans, contracts, checks, and reviews live in the repo
- Claude and Codex read the same source artifacts first
- Review from one Human Review Card plus machine evidence
The surface area is intentionally small.
Inspect a repo, install repo-local workflow files, route host events through hooks, and keep the workflow surfaces consistent across Claude, Codex, and humans.
File-backed sessions
Handoffs, plans, and resume packets live in the repo. A session can end mid-task; the next one resumes the exact next step, blockers, and changed files.
Token-lean by design
A ~12KB stable root context plus a CodeGraph index for structural queries — instead of grep-and-read loops that re-scan the repo every session.
Hooks that guard & trace
Eight managed routes warn, block, trace, and hand off work. Edit gates hold until the plan is approved; done-claim gates verify file-backed evidence.
One Human Review Card
A single-screen decision surface per task: verdict, intended vs actual files, commands passed, residual risk, and rollback.
Isolated worktrees
Agents work in a linked branch or worktree, constrained to the contract’s allowed paths — unrelated dirty state stays protected.
Local & auditable
Durable truth is repo files, not chat history or hosted threads. Optional MCP sidecar exposes only workflow artifacts — no source writes, no shell.
Local, auditable, agent-native.
Eight layers, one source of truth. The CLI orchestrates; contracts and the filing system hold durable state; the verification layer proves the work — and ChatGPT Pro plans locally while Claude or Codex executes.
One layered chain, all the way down.
The planning chain is intentionally tiered. Each step writes a decision-complete artifact the next agent reads first — chat is never the source of truth.
Map the territory: the files, surfaces, and prior art the change touches.
Trace impact: callers, callees, and the cause chain behind it.
Decision & rationale: the chosen approach, and why — recorded for the next agent.
A guided direction pass, then an upper-layer PRD under plans/prds/.
PRD becomes a sprint with machine-checkable acceptance lines.
A bounded /goal prompt runs each sprint slice through the loop on either agent.
Accept only when the review recommends pass, the card verdict is pass, and external acceptance passes. Then inspect the contract, latest trace, and changed files.
Plan with ChatGPT Pro. Execute with Claude or Codex.
The optional repo-harness mcp sidecar exposes only workflow artifacts to MCP clients. ChatGPT Pro plans against real repo state and moves an idea through PRD → Sprint → Goal handoff — then your existing Claude or Codex session executes the file-backed Sprint.
The reverse direction: the Oracle browser engine drives your signed-in ChatGPT Web session for consults and reviews — local → web, no API key, every run saved as a repo-local record.
- 1 Read repo state
ChatGPT reads workflow files through the MCP sidecar — plans, contracts, checks, handoffs.
- 2 Write the PRD
write_prd_from_idea drafts a decision-complete PRD under plans/prds/.
- 3 Write the Sprint
write_checklist_sprint turns it into an ordered backlog with machine-checkable acceptance.
- 4 Prepare the handoff
prepare_codex_goal_from_sprint writes .ai/harness/handoff/codex-goal.md.
- 5 Claude or Codex executes
Your existing Claude or Codex session runs the host-native /goal prompt and stages each completed Sprint phase.
Eight managed hook routes.
The installed adapter owns eight routes. The tuple event + routeId + matcher is the stable contract — they warn, block, trace, and hand off work across sessions.
guard routes fail closed — required gates block when their scripts are missing.
Accept or reject from one screen.
Every task writes a Human Review Card — the one-screen decision surface. See what changed, why it was in scope, what verified it, what risk remains, and how to roll it back.
Accept only when the review recommends pass, the card verdict is pass, and external acceptance is pass, not_required, or an explicit manual override.
Bun-powered. One command to bootstrap.
The default installer runs on Bun — no Node setup needed, and it installs Bun for you if it’s missing. Already on Node? It works too. Bootstrap the runtime once, then preview the repo-local contract with a dry run before anything is applied.
repo-harness adopt --dry-run from the repo root. It reports every file that would be created or refreshed — apply only when the report looks right.Built on good work by others.
These skills, repos, and runtimes shaped the workflow contract while repo-harness was designed and shipped. They are acknowledged here as influences — not ordinary bundled dependencies.
The P1/P2/P3 due-diligence method and Geju practice behind the planning, tracing, and decision-rationale discipline.
think, hunt, check, and health skills for daily planning, bug hunts, verification, and Codex-first skill sync.
Product discovery, plan and design review, post-ship doc hygiene, knowledge sync, and long-form repo memory.
Human-readable architecture and system-flow diagrams.
Symbol-aware navigation, impact tracing, and readiness checks.
Primary execution agent for repo-local implementation and verification.
GPT-5 Pro consults from explicit context and files — the engine behind the browser-based ChatGPT provider in repo-harness.
When Codex materially contributes to a commit, it carries Co-authored-by: codex <[email protected]> — opt-in and visible per commit.
Make your next agent session resumable.
Bootstrap the runtime, preview the contract with a dry run, then prove the workflow. Free and open source under MIT.