Integrations

🔌 Integrations

Complete configuration reference for integrating jev-harness v0.1.6 into every major AI coding IDE and agent. Each section contains copy-paste–ready config snippets, system-prompt rules, and setup instructions.

⚡ Overview: 4 Integration Modes

Choose the integration mode that fits your agent's execution environment. All modes expose the same 5 semantic decision gates — the difference is only in how the agent calls them.

┌───────────────────────────────────────────────────────────────────────────────┐
│                          YOUR PROJECT REPOSITORY                              │
└──────────────────────────────────────┬────────────────────────────────────────┘
                                       │
           ┌───────────────────────────┼───────────────────────────┐
           │                           │                           │
           ▼                           ▼                           ▼
  ┌─────────────────┐        ┌──────────────────┐       ┌──────────────────────┐
  │  Mode 1: MCP    │        │ Mode 2: CLI Pipe  │       │  Mode 3: Native SDK  │
  │   Server        │        │   (Shell Pipe)    │       │  Python/TS/Rust      │
  │                 │        │                   │       │                      │
  │ Claude Code     │        │ Pi, Oh My Pi      │       │ Custom Agent Loops   │
  │ Cursor IDE      │        │ Codex CLI scripts │       │ LangChain, CrewAI    │
  │ CommandCode     │        │ pytest | jev-...  │       │ AutoGen, LlamaIndex  │
  │ Antigravity IDE │        │ npm test | jev-...│       │ Rust/TS Pipelines    │
  │ Claude Desktop  │        │ cargo test | jev  │       └──────────────────────┘
  │ Windsurf        │        └──────────────────┘
  │ Zed             │
  │ OpenCode        │        ┌──────────────────┐
  └─────────────────┘        │  Mode 4: CI/CD   │
                             │  GitHub Actions   │
                             │  pre-commit hooks │
                             │  Husky / Cargo    │
                             └──────────────────┘

Mode	Best For	Latency	Setup Effort
MCP Server	IDE-native agents with tool-calling capability	70–300ms (remote) / <500µs (local)	~30 seconds
CLI Pipe	Shell-based agents, Unix-native pipelines	Same	10 seconds
Native SDK	Custom Python / TypeScript / Rust agent loops	Same	Minutes
CI/CD	Pre-commit hooks, GitHub Actions, automated gates	Same	Minutes

1. 🤖 Claude Code (`claude` CLI by Anthropic)

Claude Code is Anthropic's fully autonomous agentic command-line tool. It natively supports MCP servers over stdio and executes bash commands in a sandboxed loop.

MCP Registration (Recommended)

# Register jev-harness via npm/npx (zero install required)
claude mcp add jev-harness -- npx -y @ismaelsoilet/jev-harness mcp

# Alternative: register via Python (if jev-harness is pip-installed)
claude mcp add jev-harness -- jev-mcp

# Verify registration
claude mcp list

CLAUDE.md System Rules

Add this block to your project's CLAUDE.md (or global ~/.claude/CLAUDE.md):

# Jev Harness Token Governance Protocol

## Rule 1 — Zero-LLM Triage on Failures
- NEVER forward raw tracebacks (>20 lines) directly to a frontier reasoning model.
- ALWAYS run `jev-harness test-gate` or MCP tool `jev_triage_test_failure` first.
- If `skip_llm == true` (exit 0): execute `action_recommendation` directly. No LLM call.
- If `skip_llm == false` (exit 1): forward ONLY the filtered `action_recommendation`
  to the frontier model — NOT the full raw traceback.

## Rule 2 — Circuit Breaker on Repetitive Actions
- If any operation fails TWICE in a row, MUST run `jev-harness abort-check`
  or MCP tool `jev_abort_check` before any third attempt.
- If `should_abort == true` (exit 1): HALT. Explain the dead end. Ask user for direction.

## Rule 3 — Per-Generation Reasoning Modulation (Astra-Jev)
- For mechanical operations (git commands, file reads, formatting, simple edits):
  call `jev_modulate_reasoning_effort` and inject the returned `provider_params`
  into the API call to disable or lower reasoning effort.
- Reserve high/adaptive reasoning ONLY for architectural decisions and
  complex algorithmic problems.

How It Works Inside Claude Code

Claude Code runs a test suite and it fails → calls jev_triage_test_failure via MCP.
If skip_llm == true → Claude Code executes action_recommendation immediately (e.g., pip install pytest-mock) — zero frontier tokens burned.
For repetitive failures → Claude Code calls jev_abort_check before hallucinating a third attempt.
For every generation → Claude Code calls jev_modulate_reasoning_effort and injects the returned provider_params to eliminate unnecessary reasoning latency.

CLI Pipe Fallback

# If not using MCP, pipe test output directly
pytest 2>&1 | jev-harness test-gate
npm test 2>&1 | npx @ismaelsoilet/jev-harness test-gate

# Trajectory guard before retrying
jev-harness abort-check \
  --plan "Retry rewriting the database migration with forced schema reset" \
  --history "Attempt 1 timed out. Attempt 2 failed on FK constraint."

2. 🧠 OpenAI Codex / Astra-Codex

OpenAI Codex workflows (CLI runners, autonomous scripts, and Astra-Codex implementations) operate on fast multi-turn tool loops where reasoning effort management is critical.

AGENTS.md / CODEX.md System Rules

# Astra-Jev Dynamic Reasoning Protocol (OpenAI Codex)

- Modulate reasoning effort per turn:
  - Set `reasoning_effort="low"` for mechanical inspection steps (git status, file reads, formatting).
  - Set `reasoning_effort="medium"` for standard feature implementation.
  - Set `reasoning_effort="high"` ONLY for architecture design and complex algorithms.
- Keep message prefixes clean: pass provider dialect parameters at ROOT API level
  to preserve 100% prompt cache (KV cache). NEVER inject into the message array.
- Filter test failures with `jev-harness test-gate` BEFORE passing back to GPT-6 Astra.
- Check trajectory viability with `jev-harness abort-check` BEFORE any third retry.

Per-Generation Reasoning Modulation (CLI)

# Query Astra-Jev for the appropriate effort level before calling the API
jev-harness reasoning-effort \
  --context "Inspect git diff and identify modified imports" \
  --target-provider openai \
  --model gpt-6-astra \
  --json
# → {"reasoning_effort": "low"}

jev-harness reasoning-effort \
  --context "Design the distributed consensus module across 12 services" \
  --target-provider openai \
  --model gpt-6-astra \
  --json
# → {"reasoning_effort": "high"}

Python SDK Integration (Zero-Cache-Invalidation)

from jev_harness import modulate_reasoning_effort, JevClient

client = JevClient()

# Called BEFORE each generation step in your Codex loop
effort = modulate_reasoning_effort(
    context=task_step_description,
    provider="openai",
    model="gpt-6-astra",
    client=client,
)

# Root-level payload injection preserves 100% of the GPU prefix KV-cache
# across 50+ turns — NEVER mutate the messages array with reasoning params!
response = openai_client.chat.completions.create(
    model="gpt-6-astra",
    messages=session_history,      # NEVER mutate message prefix
    **effort.provider_params        # Injects: {"reasoning_effort": "low" | "medium" | "high"}
)

Per-Step Hooks in Astra-Codex

# Astra-Codex pre-step hook pattern
def astra_jev_pre_step_hook(step_context: str, history: list[str]) -> dict:
    """Called before every generation. Returns provider_params to inject."""

    # 1. Guard against doom loops
    if len(history) >= 2:
        abort = should_abort_trajectory(
            proposed_step=step_context,
            recent_attempts_summary="\n".join(history[-3:]),
            client=client,
        )
        if abort.should_abort:
            raise TrajectoryAbortError(abort.reasoning_summary)

    # 2. Get optimal reasoning effort
    effort = modulate_reasoning_effort(
        context=step_context,
        provider="openai",
        model="gpt-6-astra",
        client=client,
    )

    return effort.provider_params  # e.g. {"reasoning_effort": "low"}

Test Failure Triage

# Pipe directly in Codex scripts
pytest 2>&1 | jev-harness test-gate

# JSON for programmatic consumption
pytest 2>&1 | jev-harness test-gate --json
# → {"skip_llm": true, "recommendation": "pip install scipy", "category": "ENV_MISSING"}

3. 🐚 Pi & Oh My Pi

Mario Zechner's minimalist terminal agent (pi) and community shell harnesses like oh-my-pi are designed for lightning-fast, Unix-native execution with composable pipe-first workflows.

Pipe-First Integration

# Python / Pytest
pytest 2>&1 | jev-harness test-gate

# Node.js / Jest / Vitest
npm test 2>&1 | npx @ismaelsoilet/jev-harness test-gate

# Rust / Cargo
cargo test 2>&1 | jev test-gate

# Semantic exit code branching:
# Exit 0 (skip_llm=true)  → Jev identified a deterministic fix. Execute it, no LLM.
# Exit 1 (skip_llm=false) → Deep logic bug. Pi should call the frontier model.
# Exit 2                  → Invocation error. Check jev-harness syntax.

PI.md / `~/.pi_rules`

# Pi / Oh My Pi Frugal Execution Rules

- Wrap ALL test runs:
    npm test 2>&1 | npx @ismaelsoilet/jev-harness test-gate
    pytest 2>&1 | jev-harness test-gate
- If exit code is 0: auto-apply the action_recommendation shell command.
- If exit code is 1: summarize failure concisely for the frontier model.
- NEVER pass raw >20-line tracebacks to the model without triage.
- ALWAYS run `jev-harness abort-check` before any second retry of a failed step.

`oh-my-pi` Shell Plugin (`~/.config/oh-my-pi/plugins/jev.sh`)

#!/usr/bin/env bash
# Jev Harness guard wrapper for oh-my-pi
# Source this plugin to wrap all test/build commands with Jev triage.

jev_guard() {
  local cmd="$*"
  local output
  output=$(eval "$cmd" 2>&1)
  local raw_exit=$?

  if [ $raw_exit -ne 0 ]; then
    # Pipe failure log through jev-harness test-gate
    echo "$output" | jev-harness test-gate
    return ${PIPESTATUS[1]}
  fi

  echo "$output"
  return 0
}

# Aliases for common test runners
alias pytest_jev='pytest 2>&1 | jev-harness test-gate'
alias npm_test_jev='npm test 2>&1 | npx @ismaelsoilet/jev-harness test-gate'
alias cargo_test_jev='cargo test 2>&1 | jev test-gate'

# Trajectory abort guard
jev_abort() {
  jev-harness abort-check --plan "$1" --history "$2"
  if [ $? -eq 1 ]; then
    echo "⛔ JEV ABORT: Doom loop detected. Re-align with user before proceeding."
    return 1
  fi
}

Autonomous Branching Logic

# Full example: Pi test-and-branch pattern
pytest 2>&1 | jev-harness test-gate --json > /tmp/jev_result.json
JEV_EXIT=$?

if [ $JEV_EXIT -eq 0 ]; then
  # skip_llm=true → execute deterministic fix
  ACTION=$(jq -r '.recommendation' /tmp/jev_result.json)
  eval "$ACTION"
elif [ $JEV_EXIT -eq 1 ]; then
  # skip_llm=false → send filtered error to LLM
  FILTERED=$(jq -r '.recommendation' /tmp/jev_result.json)
  pi ask "Fix this error: $FILTERED"
fi

4. ⌨️ CommandCode

CommandCode is a terminal-centric autonomous coding assistant supporting MCP servers and pre-command execution hooks natively.

MCP Configuration (`.commandcode/config.json`)

{
  "mcpServers": {
    "jev-harness": {
      "command": "npx",
      "args": ["-y", "@ismaelsoilet/jev-harness", "mcp"],
      "env": {
        "JEV_API_KEY": "${JEV_API_KEY}"
      }
    }
  }
}

Alternative (Python CLI): Replace "command": "npx" and "args" with "command": "jev-mcp" and "args": [] if jev-harness is pip-installed globally.

COMMANDCODE.md Rules

# CommandCode Safety & Token Gate Rules

## On Every Non-Zero Exit Code
- Call MCP tool `jev_triage_test_failure` with the raw failure log.
- Adhere strictly to `skip_llm` verdicts to preserve frontier quota.
- If skip_llm=true: execute action_recommendation immediately. Do NOT deliberate.
- If skip_llm=false: pass ONLY the filtered action_recommendation to the model.

## On Second Consecutive Failure
- Call MCP tool `jev_abort_check` with the proposed next step and attempt history.
- If should_abort=true: HALT immediately. Report blocked trajectory to user.
- NEVER attempt a third identical action without user guidance.

## On Every Generation Step
- Call MCP tool `jev_modulate_reasoning_effort` with the step context.
- Inject the returned `provider_params` at root level into the API call.
- For mechanical tasks (git, file read, format): expect effort="low".
- For architecture and complex bugs: expect effort="high".

Pre-Execution Hook (`.commandcode/hooks.json`)

{
  "hooks": {
    "pre_command": {
      "enabled": true,
      "commands": [
        {
          "match": "^(pytest|npm test|cargo test|yarn test|pnpm test)",
          "pipe_to": "jev-harness test-gate",
          "on_exit_0": "apply_recommendation",
          "on_exit_1": "forward_to_llm"
        }
      ]
    }
  }
}

5. 🖱️ Cursor IDE

Cursor is a VS Code fork with deep MCP integration and an agent mode that can call registered MCP tools directly from the chat interface and Composer.

MCP Configuration (`.cursor/mcp.json`)

Place in your project root (project-scoped) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "jev-harness": {
      "command": "npx",
      "args": ["-y", "@ismaelsoilet/jev-harness", "mcp"],
      "env": {
        "JEV_API_KEY": "${JEV_API_KEY}"
      }
    }
  }
}

Python alternative: "command": "jev-mcp", "args": []

Quick Init via CLI

# Auto-generates .cursor/mcp.json in the current project
jev-harness init --cursor

# Verify the MCP server is discoverable by Cursor
npx @ismaelsoilet/jev-harness mcp --version

`.cursor/rules/jev.mdc` (Agent Rules)

---
description: Jev Harness Token Optimization Protocol for Cursor Agent
globs: ["**/*"]
alwaysApply: true
---

# Jev Harness Protocol

Before spending tokens on test or compilation failures:

1. Always pipe the test output through `jev-harness test-gate` or invoke
   the MCP tool `jev_triage_test_failure`.
2. If `skip_llm` is true, immediately execute the recommended action
   without querying the model. Zero deliberation.
3. If a task fails across 2 consecutive attempts, invoke `jev_abort_check`
   before proposing a third attempt.
4. If `should_abort` is true, halt execution and report the blocked
   trajectory to the user.
5. For every generation involving mechanical work, invoke
   `jev_modulate_reasoning_effort` and inject `provider_params` at root
   API level.

Alternative `.cursorrules` (Legacy Format)

# Jev Harness Token Governance

RULE 1 — TEST FAILURE TRIAGE
  Always call `jev_triage_test_failure` on non-zero exit codes.
  Never forward raw tracebacks >20 lines to the frontier model.
  skip_llm=true → execute action_recommendation. No model call.
  skip_llm=false → pass filtered recommendation to model only.

RULE 2 — DOOM LOOP PREVENTION  
  After 2 failed attempts at the same task:
  → Call `jev_abort_check` with proposed step and attempt history.
  → If should_abort=true: HALT. Report to user. Do not retry.

RULE 3 — REASONING MODULATION
  Before every generation, call `jev_modulate_reasoning_effort`.
  Inject returned `provider_params` at root level (not in messages[]).
  Git commands, reads, formatting → effort="low".
  Multi-file architecture → effort="high".

6. 🖥️ Claude Desktop

Claude Desktop is Anthropic's native desktop application with full MCP tool support. Configuration lives in the global MCP config file.

Configuration File Location

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/claude/claude_desktop_config.json`

`claude_desktop_config.json`

{
  "mcpServers": {
    "jev-harness": {
      "command": "npx",
      "args": ["-y", "@ismaelsoilet/jev-harness", "mcp"],
      "env": {
        "JEV_API_KEY": "${JEV_API_KEY}"
      }
    }
  }
}

Python alternative: "command": "jev-mcp", "args": []

Restart Required

After editing the config, fully quit and relaunch Claude Desktop. Verify the jev-harness hammer icon appears in the tool panel before starting a session.

Sample Claude Desktop Conversation Trigger

"Before we proceed with the refactoring, check this error with jev_triage_test_failure:
[paste traceback]"

Claude Desktop will automatically invoke the MCP tool and return a structured verdict without burning reasoning tokens.

7. 🌌 Google Antigravity IDE

Google Antigravity IDE is an agentic coding environment with native MCP support, PreInvocation hooks, and a composable skill system.

MCP Configuration (`mcp_config.json`)

{
  "mcpServers": {
    "jev-harness": {
      "command": "npx",
      "args": ["-y", "@ismaelsoilet/jev-harness", "mcp"],
      "env": {
        "JEV_API_KEY": "${JEV_API_KEY}"
      }
    }
  }
}

Python alternative: "command": "jev-mcp", "args": []

`hooks.json` — PreInvocation Hook

{
  "hooks": {
    "PreToolInvocation": [
      {
        "matcher": {
          "tool_name": "run_terminal_cmd",
          "command_pattern": "^(pytest|npm test|cargo test|yarn test|pnpm test|go test)"
        },
        "action": {
          "type": "pipe_output_to",
          "command": "jev-harness test-gate",
          "on_exit_0": {
            "behavior": "apply_recommendation",
            "skip_original_tool": true
          },
          "on_exit_1": {
            "behavior": "forward_recommendation_to_agent"
          }
        }
      }
    ],
    "PreGeneration": [
      {
        "action": {
          "type": "mcp_call",
          "tool": "jev_modulate_reasoning_effort",
          "arguments": {
            "context": "{{generation_context}}",
            "provider": "{{active_provider}}"
          },
          "inject_response": "provider_params"
        }
      }
    ]
  }
}

GEMINI.md / `.agents/rules/jev_protocol.md` Rules

# Token Economy & Gate Safeguards (Antigravity IDE)

## Mandatory Protocol
- ALWAYS triage compiler and test failures using `jev-harness test-gate`
  (CLI) or `jev_triage_test_failure` (MCP tool) before any model call.
- Adhere strictly to `skip_llm` verdicts to preserve frontier quota.
- Guard long-running trajectories against circular dead ends with
  `jev-harness abort-check` or `jev_abort_check`.

## Reasoning Modulation
- Call `jev_modulate_reasoning_effort` before every non-trivial generation.
- For mechanical bash operations (git, ls, cat, format): effort="low".
- For architectural design or multi-file race conditions: effort="high".
- Inject `provider_params` at root API payload level — never inside messages[].

8. 🌊 Windsurf

Windsurf (Codeium) is an IDE with integrated MCP server support and an agentic Cascade mode.

MCP Configuration (`~/.codeium/windsurf/mcp_config.json`)

{
  "mcpServers": {
    "jev-harness": {
      "command": "npx",
      "args": ["-y", "@ismaelsoilet/jev-harness", "mcp"],
      "env": {
        "JEV_API_KEY": "${JEV_API_KEY}"
      }
    }
  }
}

Python alternative: Replace "command" with "jev-mcp" and clear "args".

Project-Scoped Config (`<project-root>/.windsurf/mcp.json`)

{
  "mcpServers": {
    "jev-harness": {
      "command": "npx",
      "args": ["-y", "@ismaelsoilet/jev-harness", "mcp"]
    }
  }
}

`.windsurf/rules/jev-protocol.md` (Cascade Rules)

# Jev Harness Rules for Windsurf Cascade

- On any test/build failure: call MCP tool `jev_triage_test_failure` first.
- If skip_llm=true: run the action_recommendation shell command immediately.
- If skip_llm=false: pass the filtered recommendation to the model.
- Before any second retry: call `jev_abort_check`.
- Before every generation: call `jev_modulate_reasoning_effort` and inject
  the returned provider_params at root API payload level.

9. ⚡ Zed Editor

Zed is a high-performance code editor with native MCP context server support, configurable in its global settings.

`~/.config/zed/settings.json` — `context_servers` Block

{
  "context_servers": {
    "jev-harness": {
      "command": {
        "path": "npx",
        "args": ["-y", "@ismaelsoilet/jev-harness", "mcp"],
        "env": {
          "JEV_API_KEY": "${JEV_API_KEY}"
        }
      },
      "settings": {}
    }
  },
  "assistant": {
    "default_model": {
      "provider": "anthropic",
      "model": "claude-fable-5.1"
    }
  }
}

Python alternative: Set "path": "jev-mcp" and "args": [].

Per-Project Override (`.zed/settings.json`)

{
  "context_servers": {
    "jev-harness": {
      "command": {
        "path": "npx",
        "args": ["-y", "@ismaelsoilet/jev-harness", "mcp"]
      }
    }
  }
}

Zed Slash Command Integration

Once registered, invoke Jev tools directly from Zed's assistant panel:

/mcp jev-harness jev_triage_test_failure {"failure_log": "ModuleNotFoundError: No module named 'scipy'"}

10. 🟢 OpenCode

OpenCode is a terminal-based AI coding assistant with MCP support and a built-in free-tier provider (OpenCode Zen) powered by advanced open models.

MCP Configuration (`.opencode/config.json` or `opencode.json`)

{
  "mcp": {
    "servers": {
      "jev-harness": {
        "type": "local",
        "command": ["npx", "-y", "@ismaelsoilet/jev-harness", "mcp"],
        "env": {
          "JEV_API_KEY": "${JEV_API_KEY}"
        }
      }
    }
  }
}

Python alternative: "command": ["jev-mcp"]

Global Config (`~/.config/opencode/config.json`)

{
  "mcp": {
    "servers": {
      "jev-harness": {
        "type": "local",
        "command": ["npx", "-y", "@ismaelsoilet/jev-harness", "mcp"]
      }
    }
  },
  "provider": {
    "default": "opencode-zen"
  }
}

OpenCode Zen Free-Tier Integration

OpenCode Zen is OpenCode's built-in free provider. Jev Harness is fully compatible:

{
  "providers": {
    "opencode-zen": {
      "base_url": "https://zen.opencode.ai/v1",
      "api_key": "${OPENCODE_ZEN_API_KEY}"
    }
  },
  "mcp": {
    "servers": {
      "jev-harness": {
        "type": "local",
        "command": ["npx", "-y", "@ismaelsoilet/jev-harness", "mcp"]
      }
    }
  }
}

OPENCODE.md Rules

# OpenCode Jev Harness Token Gate Rules

- On every non-zero exit code: invoke `jev_triage_test_failure` before LLM.
- If skip_llm=true: auto-execute action_recommendation without model call.
- After 2 failed attempts: invoke `jev_abort_check`. Halt if should_abort=true.
- Before every generation: invoke `jev_modulate_reasoning_effort` and
  inject provider_params at root payload level.

🛠️ MCP Tool Inventory

All 5 MCP tools exposed by jev-harness mcp (JSON-RPC 2.0 over stdio):

Tool Name	Purpose	Key Inputs	Key Outputs
`jev_triage_test_failure`	Triages test traceback, compile error, or runtime failure using Jev System One. Returns whether to skip the frontier LLM and an exact action recommendation.	`failure_log: string`	`skip_llm: bool`, `category: string`, `recommendation: string`, `confidence: float`
`jev_abort_check`	Guards against doom loops and dead-ends. Evaluates the proposed next step against recent attempt history before burning tokens on a third attempt.	`proposed_step: string`, `recent_attempts_summary?: string`	`should_abort: bool`, `reasoning_summary: string`, `suggested_alternative: string`
`jev_route_task`	Routes a programming task to the minimum sufficient model tier (deterministic script, fast flash model, or heavy frontier model) to optimize cost and latency.	`task_description: string`	`selected_tier: string`, `recommended_model: string`, `complexity_score: float`
`jev_verify_completion`	Calibrated, evidence-based check of whether a step's acceptance criteria have been met. Prevents false-completion claims without launching expensive review loops.	`acceptance_criteria: string`, `produced_output: string`	`is_verified: bool`, `confidence: float`, `needs_rework: bool`
`jev_modulate_reasoning_effort`	Dynamically modulates per-generation reasoning effort (low / medium / high) and compiles provider-specific API parameters for OpenAI, Anthropic, DeepSeek, Gemini, Qwen, Kimi, and MiMo.	`context: string`, `provider?: string`, `model?: string`, `session_context_tokens?: int`	`effort: string`, `provider_params: object`, `is_reasoning_supported: bool`, `cache_safe_recommendation: string`

MCP Protocol Details

Transport:     stdio (JSON-RPC 2.0)
Protocol:      MCP 2024-11-05
Server name:   jev-harness
Version:       0.1.6
Entrypoint:    npx -y @ismaelsoilet/jev-harness mcp
               jev-mcp  (Python CLI)
               jev mcp  (Rust CLI)

Example Tool Call (Raw JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "jev_triage_test_failure",
    "arguments": {
      "failure_log": "ModuleNotFoundError: No module named 'scipy'\n  File 'test_analysis.py', line 3, in <module>\n    import scipy"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\n  \"category\": \"ENV_MISSING\",\n  \"confidence\": 0.97,\n  \"skip_llm\": true,\n  \"skip_llm_prob\": 0.96,\n  \"severity_score\": 1.0,\n  \"recommendation\": \"pip install scipy\",\n  \"is_mock\": false\n}"
    }],
    "isError": false
  }
}

🚦 Semantic Exit Codes

All CLI commands follow the Unix semantic exit code contract:

Exit Code	Name	Meaning	Agent Action
`0`	DETERMINISTIC_SAFE	`skip_llm = true`. Jev identified a deterministic fix (missing package, flaky transient, trivial assertion). The `action_recommendation` field contains the exact shell command to run.	Execute `action_recommendation` immediately. Do NOT call the frontier LLM.
`1`	LLM_REQUIRED / ABORT	`skip_llm = false` (deep logic defect), OR `should_abort = true` (doom loop detected). The frontier model is genuinely needed — or trajectory must be halted entirely.	Forward `action_recommendation` (filtered) to frontier model. OR halt and notify user.
`2`	INVOCATION_ERROR	Syntax error, missing required argument, or invalid CLI invocation.	Fix the jev-harness command syntax. Do not retry the original task.

Examples

# Exit 0: missing package — fix deterministically
pytest 2>&1 | jev-harness test-gate
# stdout: {"skip_llm": true, "recommendation": "pip install scipy", "category": "ENV_MISSING"}
# exit: 0

# Exit 1: deep logic bug — forward to LLM
pytest 2>&1 | jev-harness test-gate
# stdout: {"skip_llm": false, "recommendation": "Genuine recursion error in...", "category": "DEEP_LOGIC"}
# exit: 1

# Exit 1: doom loop detected — halt
jev-harness abort-check --plan "Retry migration" --history "Failed twice: FK constraint"
# stdout: {"should_abort": true, "reasoning_summary": "Identical plan failed 2 times"}
# exit: 1

# Exit 2: syntax error
jev-harness test-gate --invalid-flag
# stderr: Error: unknown option '--invalid-flag'
# exit: 2

🧠 Agent System Prompt Rules

Copy-paste these 3 rules directly into your agent's system prompt, AGENTS.md, CLAUDE.md, CODEX.md, or equivalent configuration file. They enforce token-optimal behavior across all supported agents.

╔══════════════════════════════════════════════════════════════════════════════╗
║          MANDATORY PROTOCOL — Jev Harness Token Governance v0.1.6           ║
╚══════════════════════════════════════════════════════════════════════════════╝

RULE 1 — ZERO-LLM TRIAGE ON FAILURES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Before calling ANY frontier LLM on a test, build, or compiler failure:

  → Run: jev-harness test-gate  (CLI)
    OR: call MCP tool jev_triage_test_failure

  IF skip_llm = true  (exit 0):
    Execute action_recommendation as a shell command. Immediately. Zero tokens.
  IF skip_llm = false (exit 1):
    Forward ONLY the filtered action_recommendation to the frontier model.
    NEVER pass the raw traceback (>20 lines) directly.

RULE 2 — CIRCUIT BREAKER ON REPETITIVE ACTIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If ANY operation fails TWICE in a row:

  → Run: jev-harness abort-check --plan "..." --history "..."
    OR: call MCP tool jev_abort_check

  IF should_abort = true (exit 1):
    HALT IMMEDIATELY.
    Explain the dead-end clearly to the user.
    Ask for directional guidance.
    NEVER attempt a 3rd identical action without explicit user approval.

RULE 3 — PER-GENERATION REASONING MODULATION (ASTRA-JEV)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Before every non-trivial LLM generation:

  → Call MCP tool jev_modulate_reasoning_effort
    Arguments: {context: "<next step description>", provider: "<your_provider>"}

  Inject the returned provider_params at ROOT API PAYLOAD LEVEL.
  NEVER inject into the messages[] array (breaks KV-cache).

  Mechanical steps  (git, ls, cat, format, rename): effort="low"  → saves ~$0.80/call
  Standard features (implement, test, review):       effort="medium"
  Architecture      (design, multi-file refactor):   effort="high"

Provider-Specific System Prompt Snippets

For Claude Code (`CLAUDE.md`)

# Jev Harness Protocol for Claude Code
- Triage test errors using `jev-harness test-gate` or MCP `jev_triage_test_failure`.
- When skip_llm=true: execute the deterministic command immediately. No deliberation.
- Prevent doom loops: run `jev_abort_check` before any second retry of a failed step.
- For mechanical bash operations: use `jev_modulate_reasoning_effort` with effort="low".

For OpenAI Codex / Astra-Codex (`CODEX.md` / `AGENTS.md`)

# Astra-Jev Dynamic Reasoning Protocol
- Modulate reasoning effort per turn via jev_modulate_reasoning_effort.
- reasoning_effort="low" for mechanical inspection; "high" for architecture.
- Keep message prefixes clean: pass provider params at root API level (KV-cache).
- Filter test failures with jev-harness test-gate before passing to GPT-6 Astra.

For Pi & Oh My Pi (`PI.md` / `~/.pi_rules`)

# Pi / Oh My Pi Frugal Rules
- Wrap all test runs: npm test 2>&1 | npx @ismaelsoilet/jev-harness test-gate
- If exit 0: auto-apply action_recommendation. No LLM call.
- If exit 1: summarize failure for frontier model only.
- NEVER pass raw tracebacks >20 lines to the model.

For CommandCode (`COMMANDCODE.md`)

# CommandCode Safety & Token Gate
- Call jev_triage_test_failure on all non-zero exit codes.
- Adhere to skip_llm verdicts to preserve quota.
- Abort repetitive loops when jev_abort_check returns should_abort=true.
- Modulate reasoning with jev_modulate_reasoning_effort before each generation.

For Cursor (`.cursor/rules/jev.mdc`)

---
alwaysApply: true
---
# Jev Token Optimization Protocol
1. Pipe test output through jev_triage_test_failure before spending tokens.
2. skip_llm=true → execute action_recommendation. No model call.
3. After 2 failures → jev_abort_check. should_abort=true → HALT and report.
4. Every generation → jev_modulate_reasoning_effort. Inject provider_params at root level.

For Google Antigravity IDE (`GEMINI.md` / `.agents/rules/`)

# Token Economy & Gate Safeguards — Antigravity IDE
- Always triage compiler and test failures using jev-harness test-gate.
- Adhere strictly to skip_llm verdicts to preserve frontier quota.
- Guard long-running trajectories with jev-harness abort-check.
- Modulate reasoning effort per generation with jev_modulate_reasoning_effort.

🌐 Provider Configuration

TypeSafe AI (Primary Provider)

TypeSafe AI's Jev System One is the native backend for all semantic decisions.

# Set API key (environment variable)
export JEV_API_KEY="your_typesafe_api_key_here"

# Or in .env file
JEV_API_KEY=your_typesafe_api_key_here

# Python SDK
from jev_harness import JevClient

client = JevClient(api_key="your_typesafe_api_key_here")
# Or: client = JevClient()  # reads JEV_API_KEY from environment

Pricing (verified 2026-09-22):

Tier	Input	Output	Latency
Jev System One	$0.042 / 1M tokens	$0.00 (non-autoregressive)	70–300ms

OpenCode Zen (Free Tier)

OpenCode Zen is OpenCode's built-in free model provider. Use it to run Jev gate evaluations at zero cost in development:

export JEV_PROVIDER=opencode-zen
export JEV_BASE_URL=https://zen.opencode.ai/v1
export JEV_API_KEY=your_opencode_zen_key

{
  "jev": {
    "provider": "opencode-zen",
    "base_url": "https://zen.opencode.ai/v1",
    "api_key": "${OPENCODE_ZEN_API_KEY}"
  }
}

OpenRouter Adapter

Use OpenRouter to route Jev evaluations through hundreds of models:

export JEV_PROVIDER=openrouter
export JEV_BASE_URL=https://openrouter.ai/api/v1
export JEV_API_KEY=your_openrouter_api_key

# Test the OpenRouter connection
jev-harness test-gate --log /dev/null --json

from jev_harness import JevClient

client = JevClient(
    provider="openrouter",
    base_url="https://openrouter.ai/api/v1",
    api_key="your_openrouter_api_key",
)

Offline / Air-Gapped Mode

Jev Harness runs entirely locally when no API key is set or when the network is unavailable:

# No API key required — local heuristic simulation activates automatically
# Latency: <500µs | Cost: $0.00 | CI-safe: never crashes
unset JEV_API_KEY
pytest 2>&1 | jev-harness test-gate

🔁 Mode 4: CI/CD & Git Hooks

GitHub Actions (`.github/workflows/ci.yml`)

name: CI with Jev Gate Guard

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: pip install jev-harness

      - name: Run Tests with Jev Gate Guard
        env:
          JEV_API_KEY: ${{ secrets.JEV_API_KEY }}
        run: |
          pytest 2>&1 | jev-harness test-gate
          # exit 0 → deterministic fix applied
          # exit 1 → genuine failure, CI correctly fails

Pre-Commit Hook (`.pre-commit-config.yaml`)

repos:
  - repo: https://github.com/ismaelsoilet/jev-harness
    rev: v0.1.6
    hooks:
      - id: jev-test-gate
        name: Jev Test Gate Guard
        description: Triage test failures before commit — block on deep logic bugs
        language: python
        stages: [pre-push]

Husky (Node.js projects)

{
  "husky": {
    "hooks": {
      "pre-push": "npm test 2>&1 | npx @ismaelsoilet/jev-harness test-gate"
    }
  }
}

Cargo Pre-Push (Rust)

# .cargo/config.toml — alias for convenience
[alias]
test-gate = "test 2>&1 | jev test-gate"

🔗 Related Pages

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
📦 SDK Reference	Python, TypeScript, and Rust API documentation
🔁 CI/CD & Git Hooks	Full CI/CD integration guide
📋 Changelog	Release notes and version history

jev-harness v0.1.6 — MIT License — GitHub · PyPI · npm · crates.io

Report a Bug | Discussions | AGENTS.md

⚡ Jev Harness

Navigation / Navegação

🇬🇧 English

🏠 Home

Getting Started

Gates Reference

Integrations

SDK Reference

CI/CD

📋 Changelog

🇧🇷 Português

🏠 Início

Começando

Referência dos Gates

Integrações

🔌 Todos os IDEs & Agentes

SDK

CI/CD

🔁 GitHub Actions

📋 Changelog

v0.1.6 — MIT License

Integrations

🔌 Integrations

⚡ Overview: 4 Integration Modes

1. 🤖 Claude Code (claude CLI by Anthropic)

MCP Registration (Recommended)

CLAUDE.md System Rules

How It Works Inside Claude Code

CLI Pipe Fallback

2. 🧠 OpenAI Codex / Astra-Codex

AGENTS.md / CODEX.md System Rules

Per-Generation Reasoning Modulation (CLI)

Python SDK Integration (Zero-Cache-Invalidation)

Per-Step Hooks in Astra-Codex

Test Failure Triage

3. 🐚 Pi & Oh My Pi

Pipe-First Integration

PI.md / ~/.pi_rules

oh-my-pi Shell Plugin (~/.config/oh-my-pi/plugins/jev.sh)

Autonomous Branching Logic

4. ⌨️ CommandCode

MCP Configuration (.commandcode/config.json)

COMMANDCODE.md Rules

Pre-Execution Hook (.commandcode/hooks.json)

5. 🖱️ Cursor IDE

MCP Configuration (.cursor/mcp.json)

Quick Init via CLI

.cursor/rules/jev.mdc (Agent Rules)

Alternative .cursorrules (Legacy Format)

6. 🖥️ Claude Desktop

Configuration File Location

claude_desktop_config.json

Restart Required

Sample Claude Desktop Conversation Trigger

7. 🌌 Google Antigravity IDE

MCP Configuration (mcp_config.json)

hooks.json — PreInvocation Hook

GEMINI.md / .agents/rules/jev_protocol.md Rules

8. 🌊 Windsurf

MCP Configuration (~/.codeium/windsurf/mcp_config.json)

Project-Scoped Config (<project-root>/.windsurf/mcp.json)

.windsurf/rules/jev-protocol.md (Cascade Rules)

9. ⚡ Zed Editor

~/.config/zed/settings.json — context_servers Block

Per-Project Override (.zed/settings.json)

Zed Slash Command Integration

10. 🟢 OpenCode

MCP Configuration (.opencode/config.json or opencode.json)

Global Config (~/.config/opencode/config.json)

OpenCode Zen Free-Tier Integration

OPENCODE.md Rules

🛠️ MCP Tool Inventory

MCP Protocol Details

Example Tool Call (Raw JSON-RPC)

🚦 Semantic Exit Codes

Examples

🧠 Agent System Prompt Rules

Provider-Specific System Prompt Snippets

For Claude Code (CLAUDE.md)

For OpenAI Codex / Astra-Codex (CODEX.md / AGENTS.md)

For Pi & Oh My Pi (PI.md / ~/.pi_rules)

For CommandCode (COMMANDCODE.md)

For Cursor (.cursor/rules/jev.mdc)

For Google Antigravity IDE (GEMINI.md / .agents/rules/)

🌐 Provider Configuration

TypeSafe AI (Primary Provider)

OpenCode Zen (Free Tier)

OpenRouter Adapter

Offline / Air-Gapped Mode

🔁 Mode 4: CI/CD & Git Hooks

GitHub Actions (.github/workflows/ci.yml)

Pre-Commit Hook (.pre-commit-config.yaml)

Husky (Node.js projects)

Cargo Pre-Push (Rust)

🔗 Related Pages

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

1. 🤖 Claude Code (`claude` CLI by Anthropic)

PI.md / `~/.pi_rules`

`oh-my-pi` Shell Plugin (`~/.config/oh-my-pi/plugins/jev.sh`)

MCP Configuration (`.commandcode/config.json`)

Pre-Execution Hook (`.commandcode/hooks.json`)

MCP Configuration (`.cursor/mcp.json`)

`.cursor/rules/jev.mdc` (Agent Rules)

Alternative `.cursorrules` (Legacy Format)

`claude_desktop_config.json`

MCP Configuration (`mcp_config.json`)

`hooks.json` — PreInvocation Hook

GEMINI.md / `.agents/rules/jev_protocol.md` Rules

MCP Configuration (`~/.codeium/windsurf/mcp_config.json`)

Project-Scoped Config (`<project-root>/.windsurf/mcp.json`)

`.windsurf/rules/jev-protocol.md` (Cascade Rules)

`~/.config/zed/settings.json` — `context_servers` Block

Per-Project Override (`.zed/settings.json`)

MCP Configuration (`.opencode/config.json` or `opencode.json`)

Global Config (`~/.config/opencode/config.json`)

For Claude Code (`CLAUDE.md`)

For OpenAI Codex / Astra-Codex (`CODEX.md` / `AGENTS.md`)

For Pi & Oh My Pi (`PI.md` / `~/.pi_rules`)

For CommandCode (`COMMANDCODE.md`)

For Cursor (`.cursor/rules/jev.mdc`)

For Google Antigravity IDE (`GEMINI.md` / `.agents/rules/`)

GitHub Actions (`.github/workflows/ci.yml`)

Pre-Commit Hook (`.pre-commit-config.yaml`)