⚡ Jev Harness: The Token Optimizer & Decision Gate for AI Coding Agents

<p align="center"> <a href="https://github.com/ismaelsoilet/jev-harness/actions/workflows/ci.yml"><img src="https://github.com/ismaelsoilet/jev-harness/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a> <a href="https://github.com/ismaelsoilet/jev-harness/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/tests-626%20passed-brightgreen.svg?logo=githubactions&logoColor=white" alt="Tests Passed"></a> <a href="https://github.com/ismaelsoilet/jev-harness/releases"><img src="https://img.shields.io/github/v/release/ismaelsoilet/jev-harness?color=teal&logo=github&logoColor=white&cacheSeconds=0" alt="GitHub Release"></a> <a href="https://pypi.org/project/jev-harness/"><img src="https://img.shields.io/pypi/v/jev-harness?color=blue&logo=pypi&logoColor=white" alt="PyPI version"></a> <a href="https://www.npmjs.com/package/@ismaelsoilet/jev-harness"><img src="https://img.shields.io/npm/v/@ismaelsoilet/jev-harness.svg?color=cb3837&logo=npm&logoColor=white&cacheSeconds=0" alt="npm version"></a> <a href="https://crates.io/crates/jev-harness"><img src="https://img.shields.io/crates/v/jev-harness.svg?color=dea584&logo=rust&logoColor=white&cacheSeconds=0" alt="crates.io version"></a> <a href="https://docs.rs/jev-harness"><img src="https://docs.rs/jev-harness/badge.svg" alt="docs.rs"></a> <a href="https://pypi.org/project/jev-harness/"><img src="https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-3776ab.svg?logo=python&logoColor=white" alt="Python Versions"></a> <a href="https://search.sigstore.dev/?logIndex=2908239242"><img src="https://img.shields.io/badge/provenance-Sigstore-blue?logo=npm" alt="npm Provenance"></a> <a href="https://github.com/ismaelsoilet/jev-harness/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License MIT"></a> <a href="https://typesafe.ai"><img src="https://img.shields.io/badge/powered%20by-TypeSafe%20Jev%20System%20One-orange.svg" alt="TypeSafe Jev"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-purple.svg" alt="MCP Compatible"></a> <a href="#"><img src="https://img.shields.io/badge/dependencies-0%20(Python%20%26%20TS%20core)-success.svg" alt="Zero Dependencies in Python & TS Core"></a> <a href="docs/system_1_5/SYSTEM_1_5_IMPLEMENTATION.md"><img src="https://img.shields.io/badge/architecture-System%201.5%20Layer-8A2BE2.svg" alt="System 1.5 Architecture"></a> </p> <p align="center"> <b><a href="README.md">🇬🇧 English</a> | <a href="README.pt-BR.md">🇧🇷 Português</a></b> </p>

Stop burning 50,000 frontier tokens on missing packages, network flakiness, and circular doom loops.

jev-harness is an ultra-fast, deterministic-first token optimizer, test failure triage gate, and semantic guardrail for AI coding agents (OpenCode, Command Code, Claude Code, Cursor, Antigravity IDE, Windsurf, Zed, and Pi). Combines instant zero-token offline deterministic heuristics (< 500µs) with optional cloud-native TypeSafe AI Jev System One micro-decisions.

🤖 Operating as an AI Agent? If you are working on this repository, read AGENTS.md (Português) first. If you are integrating the tool into your own project, you do not need it — use the Universal AI Agent Integration Guide (2-minute setup, no API key required to start).

What it is: a deterministic-first System 1.5 decision layer for the code-quality loop — test-failure triage, doom-loop breaking, completion veto, reasoning-effort governance and model routing — callable as a CLI, MCP server, git/CI hook and typed SDKs across three runtimes (Python, TypeScript, Rust). What it is not: a coding agent; a runtime supervisor (that is Foreman); a tool-call guardrail (jev-guard); a context sieve (Winnow); or a capability router (JevRouter). See Where it fits.

<details> <summary><b>📑 Table of contents</b></summary>

• The Problem · How It Works · Where It Fits · Features · Quickstart · CLI · Astra-Jev effort governance · Integrations · SDKs (TS, Rust) · Git & CI guardrails · Economics & benchmarks · Architecture & roadmap · Contributing · Release · Changelog

</details>

---

⚡ 15-Second Quickstart

Get running in seconds across any stack — zero external dependencies, zero API keys required for local deterministic mode:

# 1. Try it instantly without installing (zero token cost, zero API keys needed)
npx @ismaelsoilet/jev-harness triage --sample "ModuleNotFoundError: No module named 'pytest'"

# 2. Or install in your favorite runtime:
pip install jev-harness                 # Python (CLI + SDK)
npm install @ismaelsoilet/jev-harness   # Node.js (CLI + SDK)
cargo install jev-harness               # Rust (Standalone CLI 'jev')

# 3. Verify health and active engine mode:
jev-harness status

---

🎯 The Problem

When an autonomous coding agent encounters a test failure or compiler error, the standard reaction is to dump 500 lines of raw traceback into an expensive frontier reasoning model (GPT-6 Astra, Claude Fable 5.1).

| Failure Scenario | Without Jev Harness | With Jev Harness | | :--- | :--- | :--- | | Missing dependency (ModuleNotFoundError, Cannot find module, TS2307, E0463) | 💸 ~50,000 LLM tokens (estimate) (~$0.50 - $2.50) + 15s delay to output pip/npm install ... | ⚡ Jev triage (measured: < 1 ms offline in-process, ~80–100 ms offline CLI, ~0.5–1 s live; ≈ $0.00002/call at ~470 input tokens) → Action: install package deterministically. 0 LLM tokens. | | Flaky transient error (network timeout, port busy, ECONNREFUSED) | 💸 LLM hallucinates architectural changes to "fix" an ephemeral glitch | ⚡ Jev detects flaky transient → Auto-retry worker once. 0 code changes. | | Circular refactoring (Doom Loop: attempting the same fix 3+ times) | 💸 200,000+ tokens burned in endless circular loops | 🛑 Jev Abort Gate triggers (exit 1) → Stops loop, alerts developer. | | Trivial typo / formatting | 💸 Heavy reasoning frontier tier used for simple regex/typo | ⚡ Jev Route directs task to local script or Gemini 3.8 Flash. |

---

🏗️ How It Works: System 1 → System 1.5 → System 2

Daniel Kahneman's cognitive paradigm applied to agentic engineering, with this harness acting as the System 1.5 executive governance layer between System 1 perception and System 2 deliberation:

• System 1 (Fast, Intuitive, Calibrated): TypeSafe Jev System One provides non-autoregressive, parallel, typed micro-decisions. Latency: 70–300 ms (measured: ~80–100 ms offline CLI, ~0.5–1.0 s live on the free tier). Pricing: $0.042 per 1M input tokens ($0 output tokens). It answers specific closed-world questions (triage_category, severity_score, should_abort, target_tier, completion_status) without generative hallucinations.
• System 1.5 (Deterministic Connective Tissue & Executive Gate): jev-harness is the executive decision layer that coordinates System 1 and System 2 into a robust, bounded feedback loop (Josh Rosen's cognitive agent paradigm):
  • Zero-trust state sanitization & focused perception: Redacts sensitive credentials, masks prompt injections, and extracts targeted assertion slices (≤15 lines) instead of flooding models with 500-line terminal logs.
  • Deterministic short-circuits & auto-recovery: Instantly diagnoses missing dependencies (pip, npm, cargo) and transient network/port hiccups in < 500 µs locally without spending any LLM tokens.
  • Uncertainty calibration & entropy envelopes: Computes confidence margins and normalized entropy to guard against borderline calls, automatically escalating ambiguous cases to System 2.
  • Reasoning-effort leasing & doom-loop breaking: Regulates cognitive effort tiers (low to extra_high) for frontier models and trips an automatic circuit breaker (exit 1) when agents get stuck in repetitive repair loops.
  • Cross-runtime parity: Implemented natively in Python (pure stdlib, zero runtime dependencies), TypeScript (zero runtime dependencies), and Rust (compiled high-performance binary) with full offline fallback.
• System 2 (Slow, Deliberative, Generative): Frontier reasoning models (GPT-6 Astra, Claude Fable 5.1, Claude Opus 5) write complex code, architect multi-file refactorings, and solve deep logic defects. System 1.5 ensures System 2 is only invoked when strictly necessary, cutting token spend by up to ~80–90%.

       ┌────────────────────────────────────────────────────────────────────────┐
       │                   AI Coding Agent Execution Loop                       │
       │     (OpenCode / Claude Code / Cursor / Windsurf / Antigravity IDE)     │
       └───────────────────────────────────┬────────────────────────────────────┘
                                           │
                                [Step / Test Execution]
                                           │
                                           ▼
                                 [Execution Output]
                                           │
                 ┌─────────────────────────┴─────────────────────────┐
                 ▼                                                   ▼
         [✅ PASS: Continue]                                  [❌ FAIL: Traceback]
                                                                     │
 ════════════════════════════════════════════════════════════════════╪══════════════════════════════════
 🧠 SYSTEM 1.5: EXECUTIVE DECISION & GOVERNANCE LAYER (jev-harness)  │
 ────────────────────────────────────────────────────────────────────┼──────────────────────────────────
                                                                     ▼
                                                     ┌───────────────────────────────┐
                                                     │ 1. Perception & Sanitization  │
                                                     │  • Credential Redaction       │
                                                     │  • Focused Traceback Slicing  │
                                                     │  • Injection Screening Guard  │
                                                     └───────────────┬───────────────┘
                                                                     │
                                                                     ▼
                                                     ┌───────────────────────────────┐
                                                     │ 2. Local Deterministic Fast   │
                                                     │    Heuristics (< 500 µs)      │
                                                     │  • Missing packages (regex)   │
                                                     │  • Transient network / ports  │
                                                     │  • Doom loop pattern match    │
                                                     └───────────────┬───────────