Githeri

Contract Engine for AI Coding Agents.
Turn natural language feature requests into deterministic, validated YAML specifications and phased implementation plans. Prevent route drift, schema breaks, and agent hallucinations before code merges.

---

Why Githeri?

AI coding agents (Cursor, Claude Code, Antigravity, Aider) write code quickly, but they frequently:

• Drift API routes (e.g. implementing /api/v2/register when the client expects POST /v1/auth/register).
• Break database schemas & auth contracts (fabricating missing fields or hallucinating session objects).
• Invent bug reports and introduce regressions without reproducible assertions.

Githeri acts as an immutable contract gate. It synthesizes deterministic OpenAPI/YAML contracts and phased execution plans before code is written, then verifies the codebase against the specification with mathematical precision.

---

60-Second Quickstart

1. Install CLI

pip install githeri

2. Initialize in your project

cd your-project
githeri init

Creates .githeri/ (specs, plans, runs registry, and config).

3. Synthesize Specification & Plan

githeri plan "Add POST /v1/checkout endpoint with JWT auth"

Outputs:

• .githeri/specs/checkout.spec.yaml: Deterministic API & schema contract.
• .githeri/plans/checkout.plan.md: Phased, AST-grounded implementation runway.

4. Execute with Sandbox Isolation & Ruff Polish

githeri run --isolated

Auto-provisions a disposable sandbox virtual environment, executes plan stages with AST entrypoint mounting, auto-polishes code with Ruff, and asserts 0% contract drift.

5. Inspect & Pull to Local Codebase

githeri diff                         # Inspect created files & line counts
githeri diff --patch                 # View full unified colored diffs
githeri pull <run-id>                # Pull verified artifacts into workspace

---

Terminal Power Suite

Built for engineers who live in tmux, Neovim, and the terminal.

githeri doctor

Diagnose your local Python runtime, active virtualenv, Ruff installation, Git hooks, and contract registry in one view:

githeri doctor

githeri diff [run-id] [--patch]

Inspect exactly what an agent or executor created or modified in any recorded run:

githeri diff                         # Summary table of files and router mounts
githeri diff --patch                 # Git-style unified colored diffs (+/-)

githeri watch

Continuous contract sentinel. Watches app/, src/, and tests/ in real-time. Whenever an AI agent saves a file, Githeri validates contracts in milliseconds:

githeri watch
# [14:22:01] ⚡ Change detected in app/routers/checkout.py
# ✔ CONTRACT PASS: 3/3 endpoints matched. Zero drift.

githeri hook install

Install a pre-commit contract gate into .git/hooks/pre-commit:

githeri hook install                 # Enforces contract verification on every commit
githeri hook status                  # Verify active enforcement
githeri hook remove                  # Uninstall

Aborts git commit if an AI agent generates code that drifts from .githeri/specs/.

githeri purge -r <run-id>

Instant, zero-risk rollback. Cleans up generated files, reverses AST router mounts from main.py, and destroys sandbox virtualenvs:

githeri purge -r run_20261002_014023_092

githeri check-pr (CI/CD Quality Gate)

Enforce contracts in GitHub Actions or CI/CD pipelines. Exits 1 on contract violations:

githeri check-pr

# .github/workflows/contract-gate.yml
name: Contract Gate
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install githeri
      - run: githeri check-pr

---

Two Execution Paths

Githeri supports two distinct execution patterns:

Feature	Path A: Native Executor	Path B: Agent Handoff (Primary)
Target Engine	Autonomous local execution loop	Cursor, Claude Code, Antigravity, Aider
Command	githeri run --isolated	Feed .githeri/specs/ to your agent
Sandbox	Disposable .githeri/sandbox_venv	Developer workspace / container
Code Polish	Auto-runs ruff check --fix --ignore B008	Agent / IDE formatters
Router Mounting	Surgical AST insertion (preserves main.py)	Agent edits entrypoint
Verification Gate	Evaluated automatically at end of run	Verified via githeri verify or githeri watch

---

Specification Anatomy

Generated specifications (.githeri/specs/<name>.spec.yaml) are deterministic, machine-readable contracts:

task_id: checkout_service
summary: "Add POST /v1/checkout endpoint with JWT auth"
environment:
  required_packages:
    - "fastapi>=0.110.0"
    - "python-jose[cryptography]>=3.3.0"
local_goals:
  - id: L1
    description: "Checkout processing router"
    type: create
    target_file: "app/routers/checkout.py"
    verification:
      type: http
      method: POST
      url: "http://localhost:8000/v1/checkout"
      expect:
        status_code: 200
        response_schema:
          type: object
          required: ["status", "order_id"]

---

Configuration

Settings are resolved hierarchically:

1. CLI flags (--provider, --model, --specs, --code)
2. Local workspace: .githeri/config.yaml
3. Global credentials: ~/.githeri/credentials.json
4. Environment variables: GITHERI_API_KEY, GEMINI_API_KEY, OLLAMA_BASE_URL

# Authenticate CLI with Githeri Cloud
githeri login --key git_live_...

# Display environment & license status
githeri status

---

Contributing & Development

git clone https://github.com/karakana-labs/githeri.git
cd githeri
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/

License

Apache-2.0 © Karakana Labs