Home

⚡ Jev Harness — Wiki Home

🇬🇧 English | 🇧🇷 Português

---

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

jev-harness is a zero-dependency System One decision harness, test failure triage gate, and semantic guardrail for AI coding agents — powered by TypeSafe AI's Jev System One non-autoregressive decision model.

---

🎯 The Core Problem

When an autonomous AI coding agent hits a test failure or compiler error, the default behavior is catastrophically wasteful:

Test fails → Agent dumps 500-line traceback → Frontier LLM (GPT-6 Astra / Claude Fable 5.1)
→ 15 seconds + $0.50–$2.50 per call → Output: "pip install scipy"

This happens 70–80% of the time for trivially mechanical failures:

Failure Type	Root Cause	Without Jev	With Jev
Missing dependency	ModuleNotFoundError, Cannot find module, E0463	💸 50,000 tokens burned ($0.50–$2.50)	⚡ 90ms triage ($0.00004) → pip install. 0 LLM tokens
Flaky transient	Network timeout, ECONNREFUSED, port busy	💸 LLM hallucinates architectural changes	⚡ Auto-retry once. 0 code changes
Doom loop	Same fix attempted 3+ times	💸 200,000+ tokens in circular failure	🛑 Abort gate triggers. Developer alerted
Trivial task	Fix typo, reformat, git status	💸 Frontier tier burns $0.80+ reasoning	⚡ Route to local script or fast tier

---

🧠 How It Works: System 1 vs. System 2

Inspired by Daniel Kahneman's cognitive science framework:

                    ┌────────────────────────────────────────────────────────┐
                    │                 AI Coding Agent Loop                   │
                    └──────────────────────────┬─────────────────────────────┘
                                               │
                                     Command/Test Execution
                                               │
                                               ▼
                                      [Test / Step Output]
                                               │
                         ┌─────────────────────┴─────────────────────┐
                         ▼                                           ▼
                   [PASS: Continue]                           [FAIL: Error Log]
                                                                      │
                                                                      ▼
                                                          ┌───────────────────────┐
                                                          │   jev-harness gate    │
                                                          │ (System One — 70ms)   │
                                                          └───────────┬───────────┘
                                                                      │
                              ┌───────────────────────────────────────┴──────────────────────────────────┐
                              ▼                                                                          ▼
                   [skip_llm = true]                                                          [skip_llm = false]
          (Env missing / Flaky / Trivial)                                                       (Deep Logic Bug)
                              │                                                                          │
                              ▼                                                                          ▼
                 Deterministic Shell Action                                                  Dispatch Targeted Trace
              (pip/npm install or fast retry)                                                  to Frontier LLM (System 2)
           ⚡ 0 Frontier Tokens / Instant Fix                                               💸 Cost Reduced by ~80%

• System 1 (Jev): Non-autoregressive, parallel, typed decisions in 70–300ms at $0.042/1M tokens
• System 2 (Frontier LLMs): Slow, deliberative, generative — used only when truly needed

---

✨ Key Features

Feature	Detail
🛡️ Zero Dependencies	Pure Python stdlib (urllib.request, dataclasses, json). No pip bloat. Instant startup < 50ms
🔌 Universal MCP Server	Exposes 6 Jev tools over stdio (jev-mcp) for Cursor, Claude Desktop, Antigravity, Windsurf, Zed, OpenCode
🚦 UNIX Philosophy	Semantic exit codes: 0 (safe/skip_llm), 1 (abort/logic defect), 2 (syntax error). Clean pipe composition
🔄 Offline Simulation	Intelligent local heuristics (< 500µs) if offline or no API key. CI never crashes
🌐 Multi-Provider	TypeSafe AI Direct, OpenCode Zen (free tier), OpenRouter adapter
🧠 Astra-Jev	Per-generation reasoning effort modulation — eliminates 3-minute CoT latency on mechanical tasks

---

🚀 5-Second Quickstart

# Python
pip install jev-harness

# Node.js / TypeScript
npm install @ismaelsoilet/jev-harness

# Rust
cargo add jev-harness

# Pipe your test runner through Jev
pytest 2>&1 | jev-harness test-gate

# → exit 0 (skip_llm=true): fix deterministically, no LLM call
# → exit 1 (skip_llm=false): forward to frontier model

---

📖 Wiki Navigation

Page	Description
🏗️ Architecture	Tri-runtime layout, data flow, zero-dependency contracts
🚦 Gates Reference	All 5 semantic gates: inputs, outputs, exit codes, examples
⚡ Astra-Jev	Dynamic reasoning effort governance for 2026 frontier models
🔌 Integrations	Config snippets for every IDE and agent
📦 SDK Reference	Python, TypeScript, and Rust API documentation
🔁 CI/CD & Git Hooks	GitHub Actions, pre-commit, Husky integration
📋 Changelog	Release notes and version history

---

📊 Economics at a Glance

Metric	Frontier Reasoning (GPT-6 Astra, Claude Fable 5.1)	Fast Tier (Gemini 3.8 Flash)	Jev System One
Input Pricing	$10.00 / 1M tokens	$0.75 / 1M tokens	$0.042 / 1M tokens
Output Pricing	$50.00 / 1M tokens	$3.75 / 1M tokens	$0.00 (non-autoregressive)
Latency	10,000–30,000ms	1,500–4,000ms	70–300ms
Hallucination	Stochastic	Stochastic	Zero — calibrated typed bounds

---

🤖 AI Agents: Read This First

If you are an autonomous AI agent operating in this repository, you MUST read AGENTS.md before executing any task.

---

Powered by TypeSafe AI's Jev System One — MIT License