Jev Decision

Fast, typed, budgeted TypeSafe Jev decisions for coding-agent harnesses: Command Code, Claude Code, Codex, Cursor, Gemini CLI, Antigravity, OpenCode, and any MCP or shell-capable client.

Jev is a "System 1" model: it returns typed probabilities for yes/no (Noul), multiple-choice (Choice), and rubric (Score) questions. This repository provides a portable client, a shared Python budget ledger, and optional harness and memory-system recipes. Quality, latency and net savings depend on the workload and need separate measurement.

Advice, never authority. Jev results never grant a permission, approve a command, or certify that a task is complete. Your harness's permission rules and your executed tests stay in charge. Any failure (no key, budget reached, timeout, provider error) returns an explicit unavailable result, and your workflow carries on as if Jev were absent.

Quickstart

1. Install

MCP support needs Python 3.10+; the core library and CLI run on 3.9+.

The v0.3 changes are currently reviewed in PR #1. These commands install that development branch; they do not install a published v0.3 release.

# Recommended: an isolated tool install that puts `jev` and `jev-mcp` on PATH
uv tool install "jev-decision[mcp,setup] @ git+https://github.com/Coding-Dev-Tools/jev-decision@codex/jev-harness-integration"

# Or into a virtual environment you manage
python -m venv .venv
# Activate on macOS/Linux: . .venv/bin/activate
# Activate on PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install "jev-decision[mcp,setup] @ git+https://github.com/Coding-Dev-Tools/jev-decision@codex/jev-harness-integration"

setup adds OS credential storage and timezone data. Generated harness entries point at this exact interpreter, so keep the environment in place after installing.

2. Configure a key and a daily budget

A fresh install makes no provider calls until you run setup.

jev setup            # interactive: key source, daily budget, workspace, harness
jev doctor --live    # one tiny budgeted request that checks authentication

jev setup stores the key in Windows DPAPI or the macOS/Linux keychain. It never writes the key to a config file. On headless machines, point setup at an environment variable name instead:

export TYPESAFE_API_KEY=...   # set this in the harness's launch environment
jev setup --non-interactive --credential-source env --daily-budget 1 --timezone UTC --workspace "$PWD"

A daily budget of 0 keeps requests disabled. Before each request the shared ledger reserves the worst-case cost of that request, so the cap holds across every harness that uses the same runtime.

3. Connect your harness

Preview the change, apply it, then reload the client:

jev harness install --target command-code --dry-run
jev harness install --target command-code --apply

Harness	--target	What gets installed
Command Code	command-code	jev MCP server plus the /jev-advice skill (guide)
Claude Code	claude-code	MCP server and skill
Codex	codex	[mcp_servers.jev] and skill
Cursor	cursor	MCP server and skill
Gemini CLI	gemini-cli	MCP server and skill
Antigravity CLI / IDE	antigravity, antigravity-ide	MCP server and skill
OpenCode	opencode	MCP server and skill
Claude Desktop, Crush	claude-desktop, crush	MCP server
Pi, Hermes, OMP, OpenClaude, Copilot	pi, hermes, omp, openclaude, copilot	CLI-based skill

Add --scope project --project-root /abs/project for a project-level configuration where the harness supports one. jev harness restore --target NAME --apply removes only what Jev added and reports any entries you changed yourself. File locations and verification status are in the integration matrix.

4. Optional: guard shell commands before they run

The optional pre-tool hook can assess a shell command before it runs:

jev hook config claude-code     # prints the exact JSON to merge into your settings

The hook is escalate-only. It can force the harness's normal approval prompt (Claude Code, Cursor), or block a flagged command with a reason (Command Code, Codex, Gemini CLI). By default it blocks only in sessions that run without approval prompts. It never approves anything. Simple read-only commands such as ls or git status skip the request. Any local failure leaves the harness unchanged, and JEV_HOOK=off turns the hook off. See docs/HOOKS.md.

Use it from code

from jev_decision import JevClient

client = JevClient()  # uses the saved `jev setup` runtime; fresh defaults stay offline
batch = client.evaluate(
    {"request": "Export needs a preview before downloading."},
    [{"id": "intent", "type": "choice", "instructions": "Classify the requested change.",
      "criteria": {"feature": "Adds new behavior", "bug": "Fixes broken existing behavior", "unclear": None}}],
)
if batch.status == "ok":
    print(batch.get_choice("intent").selected, batch.get_choice("intent").probabilities)
else:
    print(batch.status, batch.error_code)   # carry on without Jev

The native ID-keyed map ({"intent": {"type": "choice", ...}}) and the typed NoulQuestion/ChoiceQuestion/ScoreQuestion classes also work. Ready-made helpers include guard_bash_command, verify_turn_completion, assess_memory_relation, assess_memory_relevance, and prune_tool_output. Constructing JevClient(api_key=...) before any saved configuration explicitly opts in with the default $1/day cap on the shared ledger. Ambient environment keys do not enable fresh default clients or hooks; saved configuration always wins.

The memory-system guide and native JSON recipe cover scoped memory assessments and the optional Engraphis question bridge. Memory writes and evidence omission remain governed by the caller.

From a shell or any harness without MCP, run jev decide --file request.json (see examples). TypeScript users have an explicit-key client in ts/. It uses the same wire contract, but the Python budget ledger does not cover its calls.

MCP tools

Tool	Purpose
jev_decide	Batch of typed Noul/Choice/Score questions over one state
jev_guard_command	Risk category and probability for a shell command (advisory)
jev_verify_completion	Gaps between a goal and the supplied verification evidence
jev_read_evidence	Read a saved log page by page, with source hashes and line references
jev_prune_output	Relevance measurement for text already in context
jev_status	Local configuration and budget, with no network call

Getting good answers

Follow the provider's Jev 1.13 guidance:

• Batch related questions into one call. Extra questions add little latency.
• Describe every option. Give Choice labels and Score levels explicit meanings and boundary conditions.
• Send only the relevant state. Unrelated text acts as a distractor.
• Keep deterministic work in code: arithmetic, counting, date comparisons, parsing, and exit codes.
• Calibrate thresholds for each question on your own data. Don't reuse one question's threshold for another.

Evidence capture and selection

A large log only saves context tokens if it never enters the model's context. jev capture --directory /abs/new-dir -- pytest runs the command and saves stdout, stderr, hashes, and the exit status. It prints only a small reference. jev evidence / jev_read_evidence then pages through the saved file inside approved workspace roots, with secrets redacted and original line numbers preserved.

Evidence selection (dropping low-relevance log spans) is off by default. No workload ships qualified for automatic omission. shadow mode measures, and select requires a locally qualified profile built with the evaluation workflow. See docs/EVIDENCE.md. Savings depend on your logs, model, and harness, so this project makes no universal savings claim.

Safety and accounting

• The model (jev-1.13.0) and the official HTTPS endpoint are pinned. There is no proxy discovery and no redirect following.
• Each attempt reserves its worst-case cost in a SQLite ledger shared by every process with the same JEV_HOME. There is at most one transient retry within a single deadline.
• Keys live in DPAPI, the OS keychain, or an environment variable you name. Harness configs contain only variable references. Unexpanded ${NAME} placeholders are treated as missing keys.
• Question IDs, labels, and state are scanned for recognizable secrets and redacted before they leave the machine.

Development

python -m pip install -e ".[test,mcp,setup]" build
python -m pytest -q
python scripts/check_packages.py --output /abs/new-dir     # wheel/sdist installed outside the checkout
cd ts && npm ci && npm test && npm run check:package

CI runs Python 3.9–3.14 on Windows, macOS and Linux, plus Node 22 and 24. Migration from 0.2 · Runtime contract · Validation records · MIT license