Summary

This repository, repo-harness, addresses the challenge of making AI coding sessions (like those with Claude and Codex) repeatable and context-aware within a project. It transforms ephemeral chat-based interactions into a structured, file-backed workflow, enabling AI agents to coordinate effectively, reduce token consumption, and resume sessions from persistent artifacts rather than chat history. This is beneficial for engineers and power users seeking to integrate AI assistance robustly into their development lifecycle.

How It Works

The core innovation is the shift from chat memory to file-backed sessions. repo-harness uses a system of hooks and repository-local files to manage context, plans, handoffs, and review evidence. It leverages a pre-built CodeGraph index for efficient structural queries and employs progressive context loading via configuration files (.ai/context/context-map.json, capabilities.json) to minimize token usage. Agents interact with stable root contexts and capability blocks, drastically reducing the need to re-scan the repository in each session.

Quick Start & Requirements

• Primary Install/Run: Install the CLI via a shell script (curl ... | sh for macOS/Linux, irm ... | iex for Windows PowerShell) or using Bun/npx. Follow with repo-harness install for global bootstrap.
• Prerequisites: Bash, Bun (recommended for verification/assembly), Git working tree. jq is optional but recommended for --dry-run.
• Setup: The repo-harness install command bootstraps the host runtime globally. To preview changes in a target repository, use repo-harness adopt --dry-run. To apply, use repo-harness adopt for existing repos or repo-harness-scaffold for new projects.
• Verification: Run scripts/check-task-workflow.sh --strict and bun test.
• Links: Repository: https://github.com/Ancienttwo/repo-harness.

Highlighted Details

• File-Backed Sessions: AI agent state and coordination are managed through repository files (e.g., .ai/harness/handoff/, tasks/current.md), ensuring continuity across sessions.
• CodeGraph Index: Enables token-efficient structural queries (callers, callees, definitions) for faster context loading and agent understanding.
• Structured Review Path: Provides distinct artifacts for human review (tasks/reviews/<task>.review.md) and agent tracking, separating AI-generated evidence from human oversight.
• MCP Connector: Facilitates integration with external AI services (like ChatGPT) by exposing workflow artifacts via a Message Queue Protocol (MCP) interface, with granular read/write permissions.
• Layered Hook System: Manages AI agent interactions through a series of scripts and adapters, enforcing policies at various stages (session start, pre-tool use, post-tool use).

Maintenance & Community

The project is actively maintained, with the latest release noted as 0.8.1. Release notes are available in docs/CHANGELOG.md. No specific community channels (like Discord or Slack) or notable contributors/sponsorships are mentioned in the provided README.

Licensing & Compatibility

The provided README does not explicitly state the software license. This omission makes it impossible to determine compatibility for commercial use or closed-source linking without further inquiry.

Limitations & Caveats

The absence of a stated license is a significant blocker for adoption assessment. The system relies heavily on specific tooling like Bun and Bash, potentially limiting cross-platform compatibility or ease of setup in environments without these prerequisites. Advanced features like the MCP connector require substantial additional configuration and understanding of its protocols.