JevX

JEVX

Find where Jev fits in your codebase.

Regexes that guess what an error means. Keyword lists that guess what a customer wants. slice(0, 3) that guesses what's best. JevX finds these judgment calls hiding as rules, and hands them to Jev. The old rule stays as the fallback.

Install npm i -g @vij-sameerb5/jevx Add to Claude Read the docs

$ npx @vij-sameerb5/jevx --dry-run

ScanIndexes your repo on your machine. Free.
UnderstandYour AI reads the source, logic first.
ValidateAI, TypeSafe and patterns each score every spot.
PreviewRed/green diffs and scorecards.
ApplyStrong fits only. Old rule kept as the fallback.
TestYour tests run before and after. Breaks are reverted.

What is JevX

Some of your if-statements are really judgment calls.

Jev (TypeSafe) answers bounded questions about messy input: a yes/no (noul), a pick from a list (choice) or a rating (score). JevX is the tool that finds where your code should be asking one.

Before · a guess written as a rule

if (/User rejected|denied/i.test(msg)) {
  setError("You cancelled…");
} else if (/timeout/i.test(msg)) {
  setError("Not confirmed in time…");
} else if (/insufficient|balance/i.test(msg)) {
  setError("Not enough funds…");
}

Every wallet words its errors differently. Anything the regexes miss shows the raw error to the user.

After · Jev decides, the rule is the fallback

const kind = await failureKind(msg);
// choice: cancelled | timeout | funds | other

async function failureKind(msg) {
  try { return (await jev.systemOne(…)).answers.kind.choice; }
  catch { return legacyFailureKind(msg); }
}

New wordings are classified correctly. If Jev is unreachable, behaviour is exactly what it was.

How it works

Your AI reads. Three sources judge. Your tests decide.

Reads everything

Your AI reads the source files part by part: API routes and libraries first, UI last. Static analysis only sets the reading order. It never decides what gets read.

Scores three ways

Every spot gets a scorecard: your AI's opinion, TypeSafe's own opinion, and patterns learned from real Jev projects. If they disagree, JevX shows it instead of hiding it in an average.

Changes only strong fits

70% and up by default. It keeps the old rule as the fallback, updates callers, adds @typesafe-ai/sdk, and skips files you're still editing.

Proves it with your tests

Your test script and typecheck run before and after. A change that breaks something that passed is reverted on its own. jevx undo puts everything back.

AI61%

TypeSafe63%

Patterns69%

JEV FIT64% POSSIBLE

A real scorecard from a Next.js checkout. It's under 70%, so it's previewed, not written, unless you ask with --min-fit.

CLI

One command, with your own AI key.

JevX never ships a key. It uses xAI (Grok) or OpenRouter with your key, asks once before sending code, and never uploads your whole repo anywhere else.

# preview: nothing is written
jevx --dry-run

# change strong fits, run your tests
jevx

# put everything back
jevx undo

What a run costs

About 15–25 AI calls for a 50-file app, roughly $0.50–0.90 on your key with Grok 4.6. --budget caps it, and --fast reads with less reasoning.

When you want more

--min-fit 55 also writes fits from 55%. It warns you below 70% and never goes under 50%.

MCP · Claude Desktop · Claude Code · Cursor · VS Code · more

Or let the AI you already use do it.

JevX is also an MCP server with 11 tools. Your AI reads the code with its own tokens. JevX adds the Jev know-how, the scorecard, red/green diffs and a safe apply with your tests. You don't need an xAI key for this. Pick your app below.

1 · Install

Claude Desktop: double-click jevx.mcpb. Everything else: npm i -g @vij-sameerb5/jevx, then jevx mcp install.

2 · Restart

Quit the app fully and open it again. JevX's tools appear in the tools / MCP menu.

3 · Ask

Open your project and say "use jevx to find where Jev fits in this repo". Add "preview only" to change nothing.

Claude Desktop: the .mcpb extension

Download jevx-0.4.0.mcpb from GitHub releases.
Double-click it. Or go to Settings → Extensions → Advanced settings → Install extension… and choose the file.
Click Install. Pick your Project folder. You can add a TypeSafe API key too (optional).
Make sure JevX is switched on, then start a new chat.
Say "use jevx to find where Jev fits in my project".

You don't need a terminal, npm or config file. Claude Desktop keeps the TypeSafe key in its own settings, never in JevX.

"Not verified by Anthropic"? That's expected for any extension from outside Anthropic's directory. The code is open on GitHub, and the file is built by scripts/build-mcpb.mjs.

Asked to allow every tool? Choose Always allow for the read-only tools (see the table below). Keep jevx_apply on Allow once, because it changes files.

Another project? Name it in chat: "…in ~/code/other-app".

Claude Desktop: config file

Easiest: run npm i -g @vij-sameerb5/jevx && jevx mcp install. It writes this entry for you, with the right paths.
By hand: go to Settings → Developer → Edit Config to open claude_desktop_config.json.
Add the jevx entry. Use absolute paths, because apps opened from the Dock don't see your shell's PATH.
Quit Claude Desktop fully (⌘Q / tray → Quit) and open it again.

The file lives at ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows.

{
  "mcpServers": {
    "jevx": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/opt/homebrew/lib/node_modules/@vij-sameerb5/jevx/dist/index.js", "mcp"],
      "env": {
        "JEVX_ROOT": "/Users/you/code/my-app",
        "JEVX_ENV_FILE": "/Users/you/.jevx/.env"
      }
    }
  }
}

# your two paths:
which node
echo "$(npm root -g)/@vij-sameerb5/jevx/dist/index.js"

JEVX_ROOT is the default project. JEVX_ENV_FILE points at the file that holds TYPESAFE_API_KEY=…, so the key never goes in this config.

Claude Code

Run jevx mcp install. It uses Claude's own CLI to add JevX for every project.
Or add it yourself with one of the commands on the right.
Open your project with claude. Type /mcp to see jevx · connected.
Say "use jevx to find where Jev fits in this repo". Claude edits files itself and runs your tests.

# installed globally
claude mcp add --scope user jevx -- jevx mcp

# or without installing
claude mcp add --scope user jevx -- npx -y @vij-sameerb5/jevx mcp

# with your TypeSafe key file
claude mcp add --scope user -e JEVX_ENV_FILE=$HOME/.jevx/.env jevx -- jevx mcp

claude mcp list   # check

Cursor

Run jevx mcp install. Or add the entry on the right to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (this project only).
Open Cursor Settings → MCP and check that jevx is on with 11 tools.
In Agent chat, say "use jevx to find where Jev fits in this repo".

{
  "mcpServers": {
    "jevx": { "command": "npx", "args": ["-y", "@vij-sameerb5/jevx", "mcp"] }
  }
}

Seeing "spawn npx ENOENT"? The app can't see your PATH. Run jevx mcp install instead: it writes absolute paths.

VS Code (GitHub Copilot)

Run jevx mcp install. Or open the Command Palette → MCP: Open User Configuration (or add .vscode/mcp.json to the project).
Add the entry on the right. VS Code uses servers, not mcpServers.
Open Copilot Chat in Agent mode and turn on the JevX tools in the tools menu.

{
  "servers": {
    "jevx": { "type": "stdio", "command": "npx", "args": ["-y", "@vij-sameerb5/jevx", "mcp"] }
  }
}

Windsurf

Run jevx mcp install. Or add the entry on the right to ~/.codeium/windsurf/mcp_config.json.
In Cascade, open the MCP servers panel and refresh.
Say "use jevx to find where Jev fits in this repo".

{
  "mcpServers": {
    "jevx": { "command": "npx", "args": ["-y", "@vij-sameerb5/jevx", "mcp"] }
  }
}

Gemini CLI

Run jevx mcp install. Or add the entry on the right to ~/.gemini/settings.json.
Start gemini in your project and type /mcp to see the JevX tools.
Say "use jevx to find where Jev fits in this repo".

{
  "mcpServers": {
    "jevx": { "command": "jevx", "args": ["mcp"] }
  }
}

OpenAI Codex CLI

Run jevx mcp install. Or add the block on the right to ~/.codex/config.toml.
Start codex in your project and say "use jevx to find where Jev fits in this repo".

[mcp_servers.jevx]
command = "jevx"
args = ["mcp"]

Any MCP app

JevX is a standard stdio MCP server. Point your app at it like this:

command	`jevx` or `npx`
args	`["mcp"]` or `["-y", "@vij-sameerb5/jevx", "mcp"]`
`JEVX_ROOT`	Default project folder (optional)
`JEVX_ENV_FILE`	File with `TYPESAFE_API_KEY=…` (optional)

# test it in a terminal (Ctrl+C to stop)
jevx mcp
# → jevx-mcp 0.4.0 ready (root: …)

For an app opened from the Dock or Start menu, use absolute paths. jevx mcp install prints the exact command for your machine.

What to say

use jevx to find where Jev fits in this repo

use jevx on ~/code/my-app. Preview only, don't change anything

use Jev where the fit is at least 60%

show me the JevX report

undo the JevX change

Without a fit you name, only STRONG fits (70%+) are changed. It never goes under 50%.

What each tool may do

READ-ONLY	`jevx_guide` `jevx_scan` `jevx_read` `jevx_related` `jevx_search` — safe to always allow
.JEVX ONLY	`jevx_scorecard` `jevx_preview_change` `jevx_report` — write only JevX's own git-ignored `.jevx/` folder
CHANGES FILES	`jevx_apply` `jevx_undo` — backup, your tests before and after, automatic revert
SENDS · OPT-IN	`jevx_share` — anonymous outcomes only, never code, names or paths

Add TypeSafe (optional)

With a TypeSafe key, every scorecard gets Jev's own opinion as a third score. Without one, jevx_scan says TypeSafe NOT configured and scorecards use two sources.

Claude Desktop (.mcpb): the TypeSafe API key field (Settings → Extensions → JevX)
Everything else: put TYPESAFE_API_KEY=… in a file and point JEVX_ENV_FILE at it

Remove it

# every app it was added to
jevx mcp uninstall

# Claude Code only
claude mcp remove --scope user jevx

The Claude Desktop extension: Settings → Extensions → JevX → Uninstall. Each config file is backed up once before its first change, as <file>.jevx-backup.

If something's off

No JevX tools: quit the app fully and reopen it. Then check that the config is valid JSON.
"… is not a project folder": name your project in chat, or set the Project folder / JEVX_ROOT.
spawn npx / node ENOENT: the app can't see your PATH. Run jevx mcp install, which uses absolute paths.
Still stuck: run jevx mcp in a terminal. It should print ready.

Installation

Up and running in a minute.

npm i -g @vij-sameerb5/jevx          # or use npx @vij-sameerb5/jevx
export XAI_API_KEY=…    # or OPENROUTER_API_KEY
export TYPESAFE_API_KEY=…  # optional
cd your-project
jevx --dry-run

Requirements

Node 20.10 or newer, and a TypeScript or JavaScript project. Works on macOS, Linux and Windows.

Keys in a file

Put KEY=value lines in a file and set JEVX_ENV_FILE to it once. Anything you export in your shell still wins.

Commands

Everything it does.

Command	What it does
`jevx`	Find, judge, change strong fits (70%+), run your checks
`jevx --dry-run`	Preview every fit from 50%, with diffs. Writes nothing
`jevx --min-fit <n>`	Write fits from n% (50–100). Warns below 70
`jevx --include-disagree`	Also write fits the three sources disagree on
`jevx undo`	Restore every file the last run changed
`jevx --fast`	Less AI reasoning while reading. Cheaper, may miss spots
`jevx --share`	Share anonymous outcomes to improve JevX (opt-in)
`jevx --report-json out.json`	Save the full result on your machine
`jevx mcp install`	Add JevX to every AI app on this machine (`uninstall` removes it)
`jevx --welcome`	Show the JEVX welcome again

Privacy

Your code goes to your AI, and nowhere else.

Sent to your AI (your key)

Your source files, with secrets scrubbed
Asked once per provider before anything is sent
Official provider addresses only

Shared with JevX (only with `--share`)

The kind of code, e.g. "regex on an error message"
Why Jev fits, the three scores, what happened
A random repo id, nothing else

Never leaves your machine

Code, file or function names, paths, string literals
.env files, tests, builds, node_modules
Your API keys. They come from your environment only

Examples

What it found on a real app.

GlobalCare is a Next.js medical-travel app with 53 files. xAI read all of it.

Spot	Verdict	Why
`checkout/page.tsx` wallet errors	64% POSSIBLE	Error text varies by wallet; regexes miss new wordings
`countryImages.ts` free-text lookup	49% disagree	Real, but cosmetic
`JourneyTicket.tsx` airport code	45% disagree	A real bug, but a proper airport lookup fixes it better
flights / hotels `slice(0, n)`	left alone	Google already ranks them, and there's no patient data to judge with
refunds · escrow · payments	never proposed	Money logic stays exact

In one line

What is JevX?

JevX finds the judgment calls hiding as hardcoded rules in your TypeScript or JavaScript code, and hands them to Jev.

Finds

Regexes guessing what an error means, keyword lists guessing intent, slice(0, 3) guessing what's best.

Proves

Every spot is scored three ways: your AI, TypeSafe and learned patterns. Only strong fits (70%+) change.

Stays safe

The old rule stays as the fallback. Your tests run before and after, and jevx undo puts everything back.

Use it from the terminal with your own AI key, or as an MCP server inside Claude, Cursor, VS Code and more. It's free and open source (MIT).

Install npm i -g @vij-sameerb5/jevx Add to Claude GitHub

Some of your if-statements are really judgment calls.

Your AI reads. Three sources judge. Your tests decide.

Reads everything

Scores three ways

Changes only strong fits

Proves it with your tests

One command, with your own AI key.

What a run costs

When you want more

Or let the AI you already use do it.

Claude Desktop: the .mcpb extension

Claude Desktop: config file

Claude Code

Cursor

VS Code (GitHub Copilot)

Windsurf

Gemini CLI

OpenAI Codex CLI

Any MCP app

What to say

What each tool may do

Add TypeSafe (optional)

Remove it

If something's off

Up and running in a minute.

Requirements

Keys in a file

Everything it does.

Your code goes to your AI, and nowhere else.

Sent to your AI (your key)

Shared with JevX (only with --share)

Never leaves your machine

What it found on a real app.

What is JevX?

Shared with JevX (only with `--share`)