Jev Use

jev-use

English | [简体中文](README.zh-CN.md)

The best way for Claude Code, Codex, and pi to work with Jev: hand the tasks that need no text output to Jev — faster steps, fewer tokens, tasks done sooner and better.

It makes the LLM and Jev true collaborators: when content needs to be written, the LLM takes over; when a step just needs a fast decision, Jev executes it.

Demos — real runs, 1× speed

Directions task: Jev clicks, the LLM types — 10 decisions (p50 274 ms) · 4 writes; Jev rejects a wrong route, the LLM rewrites Context compaction — 200 messages judged in 7 calls, one LLM paragraph replaces the dropped pile; recall 3/3

Pong: ball speed = decision latency — 86 Jev decisions in 20 s vs 6 (haiku) and 3 (gemini) called the usual way; enum-constrain both and the gap is 3× Gate every shell command — dangerous ones denied in ~230 ms with a reason, zero LLM tokens

Every demo is a rerunnable script in [bench/examples/](bench/examples); all numbers, methodology, variance and caveats: [bench/RESULTS.md](bench/RESULTS.md) · third-party measurements: [docs/evidence.md](docs/evidence.md).

Install

npx -y jev-use install    # wires Claude Code, Codex, and pi — whichever it finds

Set one key in the environment your agent runs in (JEV_BACKEND=mock for a keyless dry run):

| Provider | Env var | | --- | --- | | TypeSafe direct | TYPESAFE_API_KEY | | OpenRouter | OPENROUTER_API_KEY | | Vercel AI Gateway | AI_GATEWAY_API_KEY |

npx -y jev-use doctor checks the wiring. Judged state goes to the provider you configure; JEV_BACKEND=mock stays local. Plugin form with the routing skill and the PreToolUse gate: [harness/claude-code](harness/claude-code/README.md) · [harness/codex](harness/codex/README.md).

Use as a library

npm i jev-use — zero runtime dependencies on the judgment path:

import { Jev, check, pick, rate } from "jev-use";

const jev = new Jev();

const { answers } = await jev.judge(state, {
  next: pick("Next action?", { merge: "all green", rerun: "looks flaky", hold: "needs attention" }),
  risk: rate("How risky?", ["routine", "worth a look", "incident"]),
  passed: check("Did the run fully succeed?"),
});
// answers.next → { answer: "merge", confidence: 0.93, confidenceFrom: "reported", escalate: false }

Anything Jev can't or shouldn't decide comes back with escalate: true and a typed reason. Tools, verdict shape, escalation contract, CLI: [docs/reference.md](docs/reference.md).

Small enough to read

| File | Job | | --- | --- | | [src/protocol.ts](src/protocol.ts) | Questions (check/pick/rate), verdicts, escalation reasons | | [src/dispatch.ts](src/dispatch.ts) | Pre-call routing: what never reaches Jev | | [src/judge.ts](src/judge.ts) | screen → backend → hand back what is unsure; gate | | [src/jev.ts](src/jev.ts) | The Jev client over that engine | | [src/backends/](src/backends) | TypeSafe, OpenRouter, Vercel, mock adapters | | [src/server.ts](src/server.ts) | The two MCP tools | | [src/cli.ts](src/cli.ts) | install, serve, hook gate, doctor | | [skills/jev-use/SKILL.md](skills/jev-use/SKILL.md) | The routing rules the agent follows |

Development

$ npm run typecheck && npm test    # unit tests incl. per-provider wire fixtures
$ npm run smoke                    # real MCP client ↔ built CLI over stdio
$ node bench/run.mjs               # micro-benchmarks, your key and region

Substantially written with Claude Code (AI-assisted).

MIT © shitianfang

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shitianfang
• Source: shitianfang/jev-use
• License: MIT
• Homepage: https://www.npmjs.com/package/jev-use

Install and usage instructions live in the source repository linked above.