gitreins 0.3.1

Git-native AI agent co-harness — MCP server, static guards, and agentic evaluator for LLM-assisted coding

GitReins (PoC)

Git-Native Agent Co-Harness — Proof of Concept

GitReins lives inside your git repository as a co-harness. It provides MCP tools for task lifecycle management, an agentic evaluator that judges code completeness against task definitions, and git hooks that ensure nothing bypasses the quality gates.

✅ Proof of Concept — Implemented (v0.1.0) — All engine modules, MCP server, CLI, and git hooks are built and working. 322 tests pass.

Install

# PyPI (recommended)
pip install gitreins

# GitHub
pip install git+https://github.com/totalwindupflightsystems/gitreins.git

# From source
git clone https://github.com/totalwindupflightsystems/gitreins.git
cd gitreins && pip install -e .

Then activate in any repo:

cd /path/to/your-project
gitreins install

How It Works

1. Create tasks — Define criteria via CLI or MCP tools
2. Work with your AI agent — Pi, Claude, Hermes, or Codex does code generation
3. Complete tasks — Agent calls task.complete
4. Automatic evaluation — Tier 1 static guards (secrets, lint, tests) + Tier 2 agentic evaluator
5. Commit through harness — commit tool runs guards, blocks if checks fail

The evaluator is an agentic loop: it reads files, runs tests, searches patterns, and delivers a structured verdict with per-criterion PASS/FAIL. No single-shot LLM judgment.

Architecture & Docs

Document	Purpose
Full Architecture	System design and data flow
Component Map	Module inventory with paths and line counts
Agentic Evaluator Design	How the 7-tool agentic loop works
Sandbox	Evaluator scratch space (in-memory, with filesystem plans)
Implementation Plan	Phase history

Full reverse-engineered specs are in specs/ — one per component, with realized-by links to actual code files.

Status

Phase: Fully Implemented (v0.1.0) — All seven engine modules, MCP server (9 tools), CLI (5 top-level commands: task, guard, judge, commit, mcp-server), git hooks, and install script are built. See Component Map for current state.

Quick Start

cd gitreins-poc
./gitreins/install                    # Activate hooks in <10 seconds

# Create a task and evaluate it
python3 gitreins/cli.py task create demo "Demo task" \
  "File exists" "Has tests" "No secrets"

# Start the MCP server for your AI agent
python3 gitreins_mcp/server.py

Demos

Three demo projects are included showing GitReins in action:

Project	Type	What it tests
demo-slugify/	Single-file	URL slug generator — basic criteria verification
demo-calc/	Multi-file CLI	Calculator with operations, parser, CLI — 13 pytest tests
demo-string-utils/	Single-file	String utilities with intentional palindrome bug — FAIL→FIX→PASS cycle

Run any demo:

Tech Stack

• Language: Python 3.10+
• Dependencies: mcp, pyyaml, requests (3 packages)
• MCP Transport: stdio
• Config: YAML in .gitreins/ directory
• Evaluator Model: Haiku / GPT-4o-mini (<2s, ~$0.001/check)