Ancienttwo/repo-harness

What it solves

repo-harness solves the problem of "chat memory loss" and token inefficiency when using AI agents (like Claude and Codex) for software development. Instead of relying on a chat thread's history, it moves the state of the project—plans, contracts, handoffs, and evidence—directly into the repository files. This ensures that when a new session starts, the agent can resume exactly where the previous one left off without needing to re-scan the entire codebase or re-derive the current status.

How it works

The system operates across two layers:

1. Session Contract Layer: It uses a CLI and host adapters (for Claude and Codex) to route events through a typed hook runtime. These hooks write context, plans, and review evidence into the repo. It implements a strict lifecycle: Plan $\rightarrow$ Contract $\rightarrow$ Review, where work is projected from an approved plan into a specific contract and verified with structured evidence before closeout.
2. Bot-Scheduled Programs Layer: For long-running work, it supports "authorized programs" where tasks are managed via renewable leases and engineer bindings, allowing work to persist across multiple sessions and different agents.

To keep token usage low, it uses progressive context loading (loading only necessary capability blocks) and integrates with a CodeGraph index for structural queries instead of repeated grep-and-read loops.

Who it’s for

It is designed for developers and teams using AI agents (specifically Claude and Codex) to manage complex, multi-session software engineering tasks, Sprints, and PRDs.

Highlights

• File-backed sessions: Resumes work from repo artifacts (handoffs, journals) rather than chat history.
• Token-lean architecture: Uses a small root context (~12KB) and structural CodeGraph queries to reduce token consumption.
• Review-ready evidence: Generates structured check evidence and review cards for human verification.
• Typed hook runtime: Provides managed routes and fail-closed guards at the edit boundary to keep agents aligned with the project contract.
• MCP planner sidecar: Allows ChatGPT to write PRDs and Sprints while Codex executes them without direct source-code write access.