GitReins

Git-Native Agent Co-Harness — static guards + agentic evaluator for AI-assisted code

GitReins lives inside your git repository as a quality 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.

✅ v0.10.2 — LSP diagnostics (14 languages), static analysis (9 tools), commit audit with CVE-scored severity, optional Antares CVE-localization guard, DeepSeek prompt caching, large-repo hardening, 1088 tests pass.

Quick Start

pip install gitreins
cd /path/to/your-project
gitreins install        # creates .gitreins/config.yaml + pre-commit hook
gitreins init           # smart init — detects language, size, optimal config

How It Works

1. Create tasks — Define criteria via CLI or MCP tools
2. Work with your AI agent — Claude, Hermes, Codex, or Pi does code generation
3. Complete tasks — gitreins task complete <id> triggers automatic evaluation
4. Tier 1: Static guards — secrets, build, lint, tests (configurable)
5. Tier 2: Agentic evaluator — LLM loop reads files, runs tests, delivers per-criterion PASS/FAIL
6. Verdicts persisted — stored in .gitreins/history/, browsable via gitreins report
7. Commit through harness — pre-commit hook runs guards, blocks if checks fail

Commands

gitreins install                      # Install hooks + config
gitreins init                         # Smart init (language, size, optimal config)
gitreins guard                        # Run Tier 1 static checks
gitreins security-scan [-d DIR] [--output text|json] [--force-ml]
                                       # Run the Antares CVE localization scanner
gitreins report [-n N] [--interactive]  # Browse verdict history
gitreins task create <id> <title> [criteria...] [--depends-on ...]
gitreins task start <id>
gitreins task complete <id> [--force]
gitreins task list [--status pending|in_progress|complete]
gitreins task delete <id>
gitreins judge <id>                   # Evaluate a task
gitreins commit <message>             # Commit with guard checks
gitreins mcp-server                   # Run MCP stdio server (for AI agents)

Security Scan (optional)

GitReins ships an opt-in Tier 1 security guard that localizes known CVEs against your staged Python code. It is built on the Antares CVE localization framework (FDTN-AI's 1B-parameter model fine-tuned for code-level vulnerability localization). Until the optional ML stack is installed, the guard falls back to a keyword-based heuristic that produces CVE-SIMULATED findings so the wiring can be exercised end-to-end.

CLI

# Scan staged Python files (default; used by `gitreins guard`).
gitreins security-scan

# Recursively scan a directory instead of staged files.
gitreins security-scan --directory engine/

# Machine-readable output for piping into other tools.
gitreins security-scan --output json

# Require real ML inference — fail if huggingface_hub/transformers
# are not installed (exit code 2). Without this flag the heuristic
# fallback is used.
gitreins security-scan --force-ml

Exit codes:

Install requirements

The heuristic scanner has no extra dependencies. Real ML inference requires the optional ML stack:

pip install huggingface_hub transformers
# Optional, for GPU inference:
pip install torch        # or onnxruntime

The model is downloaded on first use into ~/.cache/gitreins/antares-1b/ and reused on subsequent runs.

Configuration

Enable the guard in .gitreins/config.yaml:

defaults:
  security_scan:
    enabled: true              # opt-in: default false
    model: antares-1b          # "antares-1b" | "antares-350m"
    min_confidence: 0.7        # filter by CVSS severity score
    cve_source: nvd            # "nvd" | "github" | "both"

The CVE feed is cached at ~/.cache/gitreins/cve_feed/ with a 24-hour TTL. When the network is unreachable the feed serves stale cache; when both cache and network are unavailable the feed returns an empty list and the guard exits clean (it is opt-in and must never block a commit on missing infrastructure).

Test Modes: full vs diff

GitReins supports two strategies for when tests run on commit, controlled by test_mode in .gitreins/config.yaml.

test_mode: "full" (default for new projects)

The entire test suite runs on every commit. Safe and thorough.

Best for:

• New projects with a small, fast test suite
• Projects where all tests pass reliably
• When you want maximum safety on every commit

Tradeoff: Slow on large projects. Pre-existing failures in untouched code block unrelated commits.

guards:
  test_mode: "full"

test_mode: "diff" (recommended for mature projects)

Only tests for packages you actually changed. Uses basename mapping:

Best for:

• Projects with 5+ packages where full suite is slow
• Projects with pre-existing test failures in untouched code
• When you want fast feedback on the code you actually changed

Safety nets — diff mode falls back to full suite when:

• pyproject.toml, .gitreins/config.yaml, Makefile, or setup.cfg changed
• A test file itself changed (always included, plus its source-mapped siblings)
• Changed files don't map to any known test files (unknown file = safety)
• No staged files at all
• Test command isn't pytest (custom runners can't be narrowed)

Tradeoff: Less safety on cross-cutting changes. Config changes always trigger full suite.

guards:
  test_mode: "diff"

Which mode should I use?

Output examples

Full mode:

Tier 1 Guards: PASS  (test mode: full)
  ✓ secrets — clean
  ✓ lint — ok
  ✓ tests — passed

Diff mode (targeted):

Tier 1 Guards: PASS  (test mode: diff, 3 test file(s))
  ✓ secrets — clean
  ✓ tests — passed

Diff mode (safety trigger — full suite):

Tier 1 Guards: PASS  (test mode: diff, full suite — safety trigger)
  ✓ secrets — clean
  ✓ tests — passed

Verdict History

Every gitreins task complete and gitreins judge saves a verdict to .gitreins/history/. Configure in .gitreins/config.yaml:

history:
  enabled: true              # false = don't save verdicts
  storage: "git"             # "git" = auto-commit to gitreins branch
                             # "filesystem" = write files only, no git commits
  max_verdicts: 1000         # auto-prune old entries

Browse history:

gitreins report              # last 10 evaluations
gitreins report -n 20        # last 20
gitreins report --interactive  # TUI with arrow-key navigation (requires textual)

Task Dependencies

Tasks can depend on other tasks. Evaluation is blocked until dependencies pass:

gitreins task create build "Project builds" \
  "CGO_ENABLED=0 go build ./cmd/server exits 0"

gitreins task create api-crud "CRUD endpoints" --depends-on build \
  "POST /api/users creates a user" \
  "GET /api/users lists users"

gitreins task complete api-crud
# → "Cannot complete 'api-crud' — depends on: build"

gitreins task complete build      # complete the dependency first
gitreins task complete api-crud   # now this works

# Or force-skip dependency checks:
gitreins task complete api-crud --force

Configuration

Full .gitreins/config.yaml reference:

# ── Global defaults ──────────────────────────────────
defaults:
  model: deepseek-v4-flash
  max_iterations: 100
  check_for_updates: true

# ── Tier 1 guards ────────────────────────────────────
guards:
  secrets: true
  lint: true
  tests: true
  test_mode: "full"          # "full" or "diff"
  test_command: "pytest -x --tb=short"

  # Go projects (auto-detected via go.mod):
  go:
    build: true
    lint: true
    tests: true

# ── Tier 2 evaluator caps ────────────────────────────
evaluator:
  max_iterations: 25         # LLM reasoning turns
  max_time: "5m"             # wall clock cap
  max_input_tokens: "200k"
  max_output_tokens: "50k"
  tool_call_weight: 0.1      # tool calls cost 0.1 iterations

# ── Verdict history ──────────────────────────────────
history:
  enabled: true
  storage: "git"
  max_verdicts: 1000

Tech Stack

• Language: Python 3.10+
• Dependencies: mcp, pyyaml, requests, packaging (4 packages)
• MCP Transport: stdio (26 tools)
• Config: YAML in .gitreins/ directory
• Evaluator Default Model: DeepSeek V4 Flash (~$0.01/eval)
• Test suite: ~1088 tests across 28 test files (parallelized with pytest-xdist)

Architecture & Docs

License

MIT