JevX docs

Quick start

npm i -g @vij-sameerb5/jevx
export XAI_API_KEY=…         # your key (or OPENROUTER_API_KEY)
cd your-project
jevx --dry-run               # preview, writes nothing
jevx                         # change strong fits, run your tests
jevx undo                    # put everything back

After a real run, open VS Code or Cursor → Source Control. Every change is there in red/green. .jevx/report.html has every scorecard and diff.

Keys

JevX uses your AI key and never ships one. Anything inside an npm package can be extracted, so it never will.

• XAI_API_KEY (xAI / Grok) or OPENROUTER_API_KEY: required for the terminal version.
• TYPESAFE_API_KEY: optional. Adds Jev's own opinion to every scorecard. The code JevX writes also needs it at runtime, in your app's environment.

To keep keys in a file, put KEY=value lines in it and point to it once:

echo 'export JEVX_ENV_FILE="$HOME/path/to/.env"' >> ~/.zshrc
source ~/.zshrc

Anything you export in your shell always wins over the file. The run's header says where the keys came from, never what they are. Keep that file out of git.

What a run does

1. Index: functions, callers and types, on your machine. Free.
2. Read: your AI reads the source files in parts of about 23k tokens, API routes and libraries first, UI last. It names every spot where a rule looks like a judgment. Tests, .d.ts files, UI kits and configs are skipped.
3. Re-check: each spot is read again with its surrounding code (callers, types) and exact logic is dropped.
4. Score: AI + TypeSafe + patterns, averaged (see Scorecard).
5. Write: for fits at or above your minimum, the smallest change. The old rule becomes a named fallback, callers are updated (e.g. await), and @typesafe-ai/sdk is added.
6. Verify: your test script and tsc --noEmit run before and after. If a check that passed now fails, JevX re-applies the changes one at a time and reverts the ones that break it.

Files with your own uncommitted changes are never touched. Backups go to .jevx/backup/, and .jevx/ ignores itself in git.

Commands

Scorecard & fit

Every spot gets three independent scores from 0 to 100%:

• AI: your AI's confidence, after reading the code, that Jev improves this decision.
• TypeSafe: Jev's own opinion. Is it a judgment, are the outcomes bounded, and is exact code not the better tool?
• Patterns: how this spot compares with real Jev projects (8 features such as ambiguity and rule stability), blended with outcomes shared by other users once a pattern has at least 5 of them.

The bands are for people, not a proof. The three scores are always shown next to the average.

Lower fits, on purpose

Some teams want Jev even where the fit is 55–69%. That's fine, as long as it's your call:

jevx --dry-run --min-fit 55   # see exactly what would be written
jevx --min-fit 55             # write it

• Below 70, JevX prints a warning before writing.
• Below 50 it refuses. A fit under 50% means the sources think exact code is better.
• Your tests still run, breaks are still reverted, and jevx undo still works.

MCP: Claude Code, Claude Desktop & more

jevx mcp install

It finds and configures every supported app on your machine: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), Gemini CLI and Codex. Each config file is backed up once, and anything else in it is left alone. Restart the app, open a project and say "use jevx to find where Jev fits in this repo".

Claude Desktop: it has no open project, so name the folder ("…in ~/code/my-app"). Or install jevx.mcpb: double-click it, pick your project folder once, and optionally paste your TypeSafe key. Claude Desktop stores the key, not JevX. It can't edit files itself, so it uses jevx_apply, which backs up, runs your tests and reverts on failure.

Any other MCP app: the install output prints the command and arguments to paste.

Step-by-step setup for each app (the .mcpb, config snippets, Claude Code commands, the TypeSafe key, uninstall and fixes) is on the home page: Add JevX to Claude and other apps →

The AI uses these tools with its own tokens:

It changes strong fits by default. Say "use Jev where the fit is at least 55%" to go lower. It never goes under 50%.

Privacy & data

Sent to your AI

Your source files, with secrets scrubbed, sent to the provider's official address using your key. Never .env files, tests, builds or node_modules. JevX asks once per provider, and again when what it sends changes.

Stored by JevX: only with --share

One anonymous row per checked spot:

• The kind of code: e.g. error-message-regex-classifier, the input kind, the rule kind, the code shape in generic words, why Jev fits, and an invented example the rule gets wrong.
• The three scores, the verdict, your --min-fit, and what happened: changed, reverted by tests, undone, previewed or left.

Never stored: code, file or function names, identifiers, string literals, paths, your repo's name or your keys. The AI is asked to write generic text, and JevX also strips every name it finds in the spot's code before sending. The dataset only accepts inserts: nobody can read it with the key JevX uses.

That's how JevX learns which kinds of changes hold up. Outcomes feed back into the patterns score in later releases.

Configuration

Troubleshooting

• "No AI key found": the key isn't in this terminal. Exports only apply to the terminal you typed them in. Use JEVX_ENV_FILE or ~/.zshrc.
• "TypeSafe not set" although it's in your file: JEVX_ENV_FILE isn't set. The header line Keys should say from … + your shell.
• "No Jev opportunities found": the result box lists why each spot was left alone. The full answers are in .jevx/debug/. Many apps are mostly UI and plumbing, and zero is a valid answer.
• A part "could not be read (timed out)": each AI call gets 4 minutes. Try again, or set XAI_TIMEOUT_MS.
• "Stats not shared": JEVX_SUPABASE_URL / JEVX_SUPABASE_ANON_KEY aren't set in this run.
• Something changed you didn't want: jevx undo, or revert that one change in Source Control.

Versions