Ancienttwo/repo-harness

File-backed workflow harness for reliable Claude Code and Codex sessions.

What it solves

repo-harness addresses the problem of AI coding sessions relying on volatile chat memory. When developers switch between different AI agents (like Claude and Codex) or start new sessions, the context of previous plans, progress, and decisions is often lost, forcing the agent to spend tokens and time rediscovering the repository structure and current state.

How it works

The project implements a file-backed workflow where the "truth" of a project's state lives in the repository itself rather than the chat history. It uses a CLI and a system of hooks that integrate with host adapters (such as ~/.claude/settings.json and ~/.codex/hooks.json).

Key mechanisms include:

  • Session Handoffs: Hooks write context, plans, and handoffs back into the project files (e.g., .ai/harness/handoff/resume.md), allowing new sessions to resume exactly where the last one left off.
  • Token Efficiency: It utilizes a pre-built CodeGraph index for structural queries and progressive context loading via context-map.json, reducing the need for expensive grep-and-read loops.
  • Guardrails: In-process mutation guards can block implementation edits unless an active plan is marked as "Approved" or "Executing".
  • Structured Artifacts: It organizes the repo into specific surfaces for specs (docs/spec.md), plans (plans/), and task contracts (tasks/contracts/).

Who it’s for

It is designed for AI tooling owners and developers who use AI agents (specifically Claude and Codex) for complex, long-running coding tasks and want a repeatable, verifiable, and token-efficient workflow.

Highlights

  • File-backed state: Moves agent coordination from chat threads to repo-local files.
  • Progressive context loading: Uses a small root context and capability blocks to save tokens.
  • Automated handoffs: Captures session state and dirty-bit events to facilitate seamless session resumes.
  • Hard enforcement gates: Ability to block code edits based on the status of the active plan.
  • MCP Connector: Optional sidecar to expose workflow artifacts to MCP clients.