jev-classifier connects your coding agent to Jev, a model that predicts which tool to use next. Start by watching its suggestions. Then, where supported, let it choose the tool your agent calls. Every decision goes into a log you can review.

Keep using your agent's model and login. Configure a separate key for Jev during setup.

The original idea and inspiration for jev-classifier come from jev-eval-agent by vinilana. This project brings that approach to a local gateway and MCP tools for coding agents.

Codex Responses Lite records suggestions without forcing a tool. OpenCode supports API keys with its v1 configuration. Cursor and Antigravity choose when to ask Jev and whether to follow it.

Quick start

1. Install

Install Node.js 22 or newer, then install jev-classifier globally from npm:

npm install --global jev-classifier
jev-classifier --help

The global install makes jev-classifier available from every project and keeps desktop startup entries tied to a stable installation. No repository checkout or build step is required.

npm install --global jev-classifier@latest

jev-classifier stop
jev-classifier startup disable
npm uninstall --global jev-classifier

git clone https://github.com/felpsdev/jev-classifier.git
cd jev-classifier
npm ci
npm run build
node dist/cli.js setup

2. Configure

jev-classifier setup

Setup walks you through choosing a Jev provider, entering its key, and picking your agent. You don't need to set environment variables. Your choices are saved for all projects.

Choose Observe to watch Jev's decisions first. If you don't have a key yet, choose Offline test to check the connection without calling Jev. Review your settings, then save. Running jev-classifier without a command opens the interactive menu.

3. Connect an agent

For Codex, Claude Code, Grok Build, and OpenCode, run starts the gateway and opens your agent. If the gateway is already running, it uses that one. Connection settings apply to this session; your agent's configuration files stay as they are.

The gateway keeps running after you close the agent. Stop it with jev-classifier stop. To pass an option to the agent, put it after --:

jev-classifier run codex -- --no-alt-screen

For Cursor and Antigravity, open the editor and reload its MCP servers after connecting.

4. Check that it works

jev-classifier doctor --check
jev-classifier status
jev-classifier logs --follow

doctor --check sends a small request to Jev, which your provider may charge for. In status, watch the request and classification counts increase while your agent works.

For Cursor or Antigravity, ask the agent to call jev_status. To try a prediction, ask it to call jev_choose_next_tool with your task and available tools. Check logs --decisions for the result.

Agent integrations

Codex, Claude Code, and Grok Build

Pick Existing login in setup to use the account you're already signed into. Pick Provider API key to use a separate key for the agent's model. The agent handles sign-in and refreshes its own login. Jev's key is used only for classification.

For manual setup, run jev-classifier config <agent>. You can also expand the connection instructions in Reference. The Grok integration uses the official Grok Build CLI.

OpenCode

Run jev-classifier run opencode. Inside OpenCode:

1. Use /connect to add an OpenAI, Anthropic, or xAI API key.
2. Use /models to pick a model from that provider.
3. Run a task and check the opencode counts in jev-classifier status.

This connection supports OpenCode v1 with API keys. Subscription plugins may send requests directly to the provider and skip the proxy. Other providers and the v2 config format are not supported yet.

Cursor and Antigravity

Run jev-classifier connect cursor or jev-classifier connect antigravity, then open the editor and reload its MCP servers. The command adds jev-classifier to your global MCP config, keeps other servers, and backs up the file before changing it.

The editor starts jev-classifier when it needs the MCP tools. You don't need to run serve. It reads your saved Jev settings; your editor keeps its own login.

The agent decides when to ask Jev and whether to follow its suggestion. Jev sees only the context included in the call, which is sent to your chosen provider. It cannot watch the whole session or force the agent's next step.

Use logs --decisions to review suggestions under cursor or antigravity. Restart the editor's MCP server after changing Jev settings. This connection works with local agents; remote cloud agents cannot use the local process.

Run agents without Jev

Turn the proxy off for future run commands, or bypass it for one session:

jev-classifier proxy off
jev-classifier run claude
jev-classifier run codex
jev-classifier proxy on
jev-classifier run claude --no-proxy
jev-classifier proxy status

The main interactive menu also offers Turn Jev proxy on or off. The saved preference applies to Codex, Claude, Grok and OpenCode. Direct launches need no Jev key and do not start or contact its gateway. Agents manage their own authentication; --auth applies only to proxy launches. Codex uses its built-in openai provider in direct mode.

Restart your agent to switch an existing session. Disabling the proxy does not stop a running gateway or change desktop startup; use stop and startup disable for those separately. Cursor and Antigravity use MCP instead of the proxy; disable their Jev entry in the editor's MCP settings to stop using it.

Direct launches remove inherited Jev URLs from agent environment variables and OpenCode's inline provider settings, without changing the parent terminal. If you manually saved Jev URLs in Claude, Grok or OpenCode configuration files, remove those overrides there too. To launch Codex directly outside this wrapper, restore its model_provider from jev to openai in its configuration. Environment and explicit --env-file settings override the saved preference; --no-proxy always bypasses it for that launch.

Where Jev runs

Choose a Jev provider in setup. Your coding agent keeps using its own model provider.

OpenRouter and Vercel AI Gateway handle Jev's predictions only. They don't run your agent's coding model through this tool.

For proxy connections, choose how much control to give Jev:

Start with Observe. Change modes in setup, or pass --shadow to observe for a run. Enforce is the default when no mode is configured. It adds a hint instead of forcing a tool when confidence is low.

jev-classifier keeps the full tool list in every request, so that part of the prompt cache stays valid. It also checks whether the requested work is done before accepting Jev's suggestion to respond. If classification fails, the original request continues to the model.

Codex Responses Lite always observes. Requests with duplicate tool names or previous_response_id also fall back to Observe. Check shadowReason in the decision log.

Gateway and startup

jev-classifier serve (or start) frees the original terminal and reuses an existing gateway. Use serve --foreground to keep the server in the current terminal.

Linux detects x-terminal-emulator, gnome-terminal, konsole, or xterm. If no display or usable terminal is available, the gateway continues in the background. On macOS/Linux, closing the log viewer leaves the gateway running; use stop to end it. On Windows, closing the gateway window also stops its process. Background console output is saved as gateway-console.log alongside the settings; routine activity and errors are also in the rotating event log.

Choose startup behavior in setup or use these commands:

jev-classifier startup               # interactive Enable / Disable menu
jev-classifier startup enable        # register for the next desktop sign-in
jev-classifier startup disable
jev-classifier startup status

Startup applies to your user account and needs no administrator access. It starts the gateway when you sign in to your desktop, using your saved settings. It does not run before login. Disabling startup leaves a running gateway active. Enable it again after moving this checkout or changing where Node is installed.

Monitoring

Terminal logs use aligned time, level, and agent columns. Event details use labeled fields such as chosen=Read, confidence=98%, and jev=124ms. Long messages wrap under the message column; narrow terminals show the details below the event header. Saved logs include the local date as well as the time. logs --json keeps the original machine-readable records.

Prefix commands with jev-classifier. Use --json with doctor, status, settings, logs, or startup for machine-readable output. --no-color or NO_COLOR disables colors. Output redirected to a file uses plain text. status --watch --json emits one JSON object per line.

doctor --check tests the settings loaded for that command. If a gateway is already running, it may still have older settings; doctor reports when the provider or model differs. Watch the classification count in status to confirm that requests are reaching Jev. For MCP suggestions, use logs, metrics, or the dashboard.

Gateway and MCP events are saved in gateway.jsonl beside the global settings. It rotates at 5 MB and retains one previous segment. Decision history lives in decisions.jsonl, unless customized. Detached macOS/Linux launches also save console output in gateway-console.log.

Invoke-RestMethod http://127.0.0.1:8080/__jev/health

Settings

Run jev-classifier setup to change preferences. Choices are saved globally:

Keys are saved as plain text in this file. On macOS/Linux, a new config file is readable and writable only by its owner. On Windows, it uses the user folder's permissions. Setup hides keys on the review screen, and settings --json hides their values too.

Logs live beside the config file by default. Set JEV_CONFIG_HOME to use a different folder.

Your saved settings work from any project. Before you save them for the first time, the CLI can load a local .env and import it during setup. After that, use --env-file .env if you want to load a project's settings.

When the same setting appears in several places, the first one in this list wins:

1. Command flags.
2. Existing environment variables.
3. An explicitly selected environment file.
4. Saved global preferences.

--global skips automatic .env loading. Restart the gateway or editor's MCP server after changing settings. The CLI trusts certificates installed on your computer when Node supports it; you can change that in advanced settings.

Reference

Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:ANTHROPIC_AUTH_TOKEN -ErrorAction SilentlyContinue
$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:8080/oauth/claude"
claude

model_provider = "jev" # top level, before any [table]

[model_providers.jev]
name = "jev-classifier"
base_url = "http://127.0.0.1:8080/oauth/codex"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

Remove-Item Env:XAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:GROK_MODELS_BASE_URL -ErrorAction SilentlyContinue
grok login # only if not already signed in
$env:GROK_CLI_CHAT_PROXY_BASE_URL = "http://127.0.0.1:8080/oauth/grok/v1"
grok

JEV_PROVIDER=openrouter
OPENROUTER_API_KEY=your-openrouter-key

{
  "ts": "2026-09-17T12:00:00.000Z",
  "agent": "anthropic",
  "model": "example-model",
  "session": "example-session",
  "mode": "enforce",
  "chosen": "Edit",
  "confidence": 0.82,
  "done": 0.1,
  "gated": false,
  "truncated": false,
  "top3": [
    {
      "name": "Edit",
      "p": 0.82
    }
  ],
  "jevMs": 180,
  "upstreamMs": 2400,
  "toolsCount": 14,
  "applied": true,
  "actual": "Edit",
  "match": true
}

Limits

• Jev accepts up to 255 choices, including respond_to_user. Larger catalogs are shortened for classification and marked truncated. The full tool list still goes to your agent's model.
• Each prediction takes time. Check jevMs in the log and the p95 timing in metrics to see how much delay Jev adds.

Development

npm install
npm run typecheck
npm test

CI is configured for Windows, macOS, and Linux with Node 22 and 24. Tests cover protocol forwarding, MCP stdio discovery and calls, configuration merging, process control, and startup-file generation. The new integrations were developed and tested on Windows; native macOS/Linux desktop launches and real Cursor/Antigravity sessions still require platform validation. OpenCode's configuration and mock upstream routing are tested separately from live provider inference.

License

MIT.