GitHub issue summary

JevRouter

Faster agent decisions. Models, subagents, skills, MCP tools, CLIs and plugins become one candidate set — Jev answers one typed Choice question, JevRouter enforces availability, permissions, risk and confirmation around it.

Website · Quickstart · Benchmark · Cookbook · Documentation · 中文

---

Why JevRouter

Agents waste reasoning tokens on a question a fast decision model answers better: which capability should handle this next? JevRouter puts Jev — a System One model that turns structured state into typed decisions with probability distributions — in front of your tools, while your reasoning model stays the execution and fallback layer.

The key contract is simple: Jev owns the decision probabilities; JevRouter owns availability, permissions, risk and confirmation. Router fields live under router, while the original probabilities, confidence, and complete provider response remain intact. Filtered candidates are never re-normalized.

• Decision-only by default — nothing executes implicitly; medium/high/critical capabilities require confirmation.
• One call or a plan — route answers one question; plan answers "which capability handles step 1..N" with serial, batch, and decomposed strategies.
• Every surface — models, subagents, Skills, MCP tools, CLIs, DSH plugins share one routing contract.
• Receipts by default — append-only decision/plan files with provenance hashes; what was decided, why, and at what confidence is always auditable.
• Capability trust is explicit — discovered and caller-supplied candidates carry verification status; strict projects can set require_verified_candidates to prevent unverified descriptions from being selected.

Benchmark

First-5 tool-call prediction on 10 Toolathlon tasks (real tool inventories from 9 live MCP servers, Jev typesafe/jev-1.13-20260917 vs DeepSeek V4.1 Flash):

Batch mode with beam sequence selection (--sequence beam) lifts position-wise hits 28% → 36% at zero extra provider calls. The same decompose+thread configuration scores 44% hits / 69% overlap on MCP-Atlas. This experiment measures ordered routing decisions, not end-to-end task completion; method and per-task data in issue #2, strategies in PR #9.

Quickstart

Node.js 20+ required. JevRouter accepts either the official Jev API or an OpenRouter key. The key is entered interactively when no matching environment variable is already exported.

Give your agent the router (installs the Skill + project instructions, checks Jev, launches the host):

npx --yes github:BillionsBobby/JevRouter agent start --agent codex

Choose typesafe for the official Jev API or openrouter at the prompt, then paste the corresponding key. The key stays in the current process environment and is never written to project files. For Claude Code use --agent claude, and for Cursor use --agent cursor. Setup automatically adds .jevrouter/ to .gitignore to keep local decision receipts from being accidentally committed. To install without launching a host, export TYPESAFE_API_KEY, JEV_API_KEY, or OPENROUTER_API_KEY first and use agent setup; to verify later, use agent doctor (--live adds a small paid probe):

npx --yes github:BillionsBobby/JevRouter agent setup          # Skill + project instructions only
npx --yes github:BillionsBobby/JevRouter agent doctor --live  # configuration + connectivity check

Route one decision (no registry needed — pass candidates inline):

OPENROUTER_API_KEY="your-key" npx --yes github:BillionsBobby/JevRouter route --provider openrouter \
  --request "Find original sources before summarizing" \
  --candidates '[{"name":"search_web","description":"Find web sources"},{"name":"summarize","description":"Summarize existing sources"}]'

Plan a multi-step task:

OPENROUTER_API_KEY="your-key" npx --yes github:BillionsBobby/JevRouter plan --provider openrouter \
  --request "Search sources about Jev, summarize them, save to notes.md" \
  --candidates-file candidates.json --steps 3 --mode serial

SDK:

npm install github:BillionsBobby/JevRouter

import { route, plan } from "jevrouter";

const decision = await route({ request, candidates: agentTools });
const planResult = await plan({ request, candidates: agentTools }, { steps: 3, mode: "batch", sequence: "beam" });

Try everything offline with the labelled demo provider (--provider demo) — no key required.

Cookbook

Task-oriented recipes, each with exact commands and expected output:

How it works

1. Choose the model. Route by capability, latency, cost, and context without rewriting your agent loop.
2. Every tool surface. Skill, MCP, or plugin — routed through the same Jev decision layer with permissions, risk, and confirmation intact.
3. Choose the specialist. Delegate research, coding, and focused work to the subagent built for the request.

Single decisions go through one Jev Choice call. When single_stage_max_candidates is exceeded, JevRouter keeps the coarse Top-K first, then asks Jev for a final Choice over the reduced set; both raw responses are preserved in raw_jev_stages.

Multi-step plans

route answers one question. plan answers "which capability should handle step 1..N of this request?":

• Serial (default): one full routing decisio