jev-router – One Prompt Router for Claude Code, Codex & Antigravity

jev-router runs before every prompt you send to Claude Code, OpenAI Codex or Google Antigravity –
in every project, in the desktop apps and in remote sessions – and decides for that single request:

• which model and which reasoning effort to use,
• how many extra agents may work in parallel (strict token budget),
• which skill fits – from one shared folder that all three tools read,
• whether the request is irreversible (then the model must ask before acting),
• which language to answer in (the language of the prompt).

It also protects running work: a prompt sent while an earlier one is still being processed is
queued behind it and must not stop or overwrite it.

Decisions come from JEV (TypeSafe) when you configure a token. Without one, a built-in local
classifier with the same answer format decides – everything works out of the box.

🚀 Quick Start

Requirements: Python 3.10+ and at least one of Claude Code,
Codex CLI or Antigravity CLI.

git clone <this repository> jev-router
cd jev-router
python install.py

The installer walks you through five steps:

1. Detect which of Claude Code, Codex and Antigravity are installed and logged in, and tell you
   how to log in to the ones that are not.
2. JEV token – paste it, or press Enter to use the built-in local classifier.
3. Hooks + MCP server for every logged-in tool.
4. Shared skill folder ~/.skills – existing skills of every tool are moved there and linked
   back, so each tool sees all of them; worker agents are generated for every model × effort.
5. Optional extras – remote access from your phone, speech-to-text.

Every change is shown first, changed config files get a .bak copy, and re-running is safe.
Preview without changing anything: python install.py --dry-run.

One-time steps after installing: Codex runs a new hook only after you trust it (codex → /hooks).
For Claude desktop Chat/Cowork, restart the app and add to Settings → Profile → Personal preferences:
"Before answering any new request, call the jev-router route_prompt tool with my message and follow its instructions."

🧭 How It Works

prompt ─► hook / MCP tool ─► jev_router/core.route()
                               ├─ lang.detect()             answer language
                               ├─ is_destructive()          regex safety net (+ JEV verdict)
                               ├─ catalog.prefilter()       shared skill catalog → ≤ 8 candidates
                               ├─ classify()                JEV (token) or built-in classifier
                               ├─ decide()                  routes.json: task × difficulty → tier
                               └─ render()                  targets.json: tier → worker, model, effort
       + queue_state            earlier work still running? → "finish it first"
─► "[router] … Delegate to `opus-worker-xhigh` (opus, effort xhigh). Parallelism: none. Respond in English."

Model and effort are enforced, not suggested

No tool lets a hook switch the running model. jev-router therefore generates one worker agent per
(model, effort) pair – Claude subagents <model>-worker-<effort> (plus test-worker-<effort>),
Codex roles <model>-<effort> – and the router delegates to the right one. Antigravity has no
fixed-model agents, so its model choice is advisory (or enforced through the cli-bridge skill).

The ultra effort level is never offered, stripped from any answer and has no worker.

Parallel agents

Code-level clamps: one fewer when the answer is not confident, at most +1 unless the request is hard.

Queue protection

All three tools already queue messages typed while the agent is busy. jev-router adds the missing
context: the new prompt is told that earlier work in the same session is still running and must be
finished first – never stopped, restarted or overwritten. If another session works in the same
folder, the prompt is warned not to modify that session's files. State expires automatically, so a
crashed session never blocks anything.

Shared skills

~/.skills is the single skill folder. Claude Code and Codex see it through per-skill links
(junctions on Windows, symlinks elsewhere); Antigravity through its skills.json. Skills that tools
manage themselves (Claude desktop's synced skills, plugins, Codex built-ins) stay in place but are
indexed too, so the router can hand a skill of one tool to another ("read and follow <path>/SKILL.md").

Overrides

Claude #fable #sonnet #opus #codex #antigravity · Codex / Antigravity #fast #main #deep ·
#norouter / #privat: no routing, nothing is sent to TypeSafe (queue protection still applies).

Routing decision on demand

The hooks route each user prompt. To get a decision for a single sub-task – from a script, another
agent or another project – call the route command. It runs the same pipeline (core.route()) but
has no side effects: no queue state, no log.

python ~/.jev-router/bin/route.py --json "add a pagination parameter to the quotes API endpoint"
python install.py route [--provider claude|claude-chat|codex|antigravity] [--json] <text>   # no text: stdin

Without --json it prints the [router] … instruction. With --json it prints one object:
model (e.g. sonnet; null when the tier answers in-session), effort, agent (the worker to
delegate to, or null), tier, task, difficulty, extra_agents, destructive, skill,
verify, lang, backend, text and note. A #norouter / #privat prompt is not routed
(model: null, nothing is sent to TypeSafe). Exit codes: 0 success, 2 usage error (e.g. an
empty prompt), 1 unexpected error (only the exception type goes to stderr). The installer writes
the shim, so callers never need to know where the repository lives.

🎙️ Speech-to-Text

Dictate prompts into any app, in any language Whisper supports – offline and free.
See docs/speech-to-text.md for installation, model choice by hardware
and phone dictation.

📱 Remote Access

Control your computer from a phone or another device under one machine name, with every tool
starting its remote service at logon. See docs/remote-access.md.

⚙️ Configuration

📂 Repository Layout

install.py                 entry point: `python install.py [command]` (same as `python -m jev_router`)
pyproject.toml             package metadata, console script `jev-router`, pytest settings
jev_router/                the package
├── cli.py                 commands: setup, detect, models, remote, skills, doctor, uninstall, route
├── core.py                classification, decision, rendering, safety regex, JEV client + built-in classifier
├── lang.py                Hungarian / English detection
├── catalog.py             skill catalog and pre-filter
├── hooks.py               hook entry point for all three tools (python -m jev_router.hooks)
├── queue_state.py         queue protection
├── mcp_server.py          MCP server: route_prompt, list_skills, get_skill (python -m jev_router.mcp_server)
├── hub.py                 shared skill folder, links, worker generation
├── integrations.py        hook + MCP registration per tool, ~/.jev-router/bin shims
├── platforms.py           OS abstraction (paths, links, executables, detection)
├── remote.py              optional remote access
├── doctor.py              health report
├── config/                models.json (catalog + policy), routes.json (task → tier), targets.json (tier → worker)
├── templates/agents/      worker templates (rendered into ~/.claude/agents and ~/.codex/agents)
└── skills/                skills bundled with jev-router (cli-bridge)
tests/                     unit tests, model-policy test
eval/                      100 Hungarian + 100 English labelled prompts, evaluation script
docs/                      speech-to-text and remote-access guides

🧪 Development

pip install -e .[dev]              # optional: editable install, adds the `jev-router` command
python -m pytest tests -q          # unit tests incl. the model-policy check
python eval/eval_router.py         # full pipeline on the labelled prompts (exit 1 below target)

Evaluation targets: task accuracy ≥ 85 % per language, destructive-request recall 100 %,
false positives < 5 %, reply language 100 %. The test suite runs on Windows, macOS and Linux in CI.

See CHANGELOG.md for the release history and CLAUDE.md for contributor
conventions.

📄 License

MIT. Product names are trademarks of their respective owners.