Skip to main content
Glama
jevgrep

jevgrep

JevGrep

npm version Node.js 24+ MCP License: MIT

JevGrep finds code from a description of what it does. Ask something like "Where is session expiry handled?" and it returns the source lines that answer it, with file paths and line numbers. You can run it in a terminal or add it to Claude Code, Codex or another MCP client, so your coding agent can look things up instead of opening one file after another.

Why JevGrep

grep and rg work well when you know the name to search for. Often you only know what the code is supposed to do:

  • "Where do we check that a user can access this project?"

  • "What happens when a payment webhook arrives twice?"

  • "Which code decides whether a file is too big to index?"

JevGrep is built for that kind of question. Results are verbatim excerpts with path:start-end, so you or your agent can open the file and carry on from there. For an agent, one tool call stands in for a long walk through the repository, and the answer stays within a token budget you set. Every eligible UTF-8 text file is scored, configuration and tests included. Nothing is sent until you have authorized the repository and had the chance to check what would leave your computer.

Related MCP server: Fast Context MCP

How it compares

The recorded comparison used 55 real questions on six open-source repositories (21 in Python, 34 in Go and Rust). Mean evidence recall@5 (R@5) averages the fraction of each question's required evidence units covered by its first five results. Finding one of three required units gives 1/3 recall. Hit rate@5 counts questions with any required unit; complete-evidence success counts questions with every required unit. Those are separate metrics in new benchmark reports.

Tool

Evidence R@5 Python (21)

Evidence R@5 Go/Rust (all 34)

Go/Rust completed

Recorded cost / question

Recorded time / question

JevGrep, 8000 tokens + whole declarations

0.877

≈0.778

32/34 (94.1%)

$0.005

4 s

gpt-6.1-terra given the whole repository, medium

0.894

0.694

34/34

$0.12–0.23

12–15 s

gpt-6-luna given the whole repository, no reasoning

0.803

0.648

34/34

$0.01–0.02

3–4 s

CodeGraph query

0.491

0.319

34/34

free, needs an index

1 s

BM25

0.429

0.338

34/34

free

< 0.1 s

ripgrep

0.325

0.244

34/34

free

0.3 s

All 21 Python searches completed. The Go/Rust column counts JevGrep's two capped searches as zero: ≈0.778 is derived from the rounded completed-search recall 0.827 × 32/34, rather than a newly measured result. On the matching 32-question subset, Terra, Luna and JevGrep scored 0.737, 0.688 and 0.827 respectively.

JevGrep's row comes from the 2026-11-04 offline replay at 8000 response tokens with whole declarations; its original 4000-token live run scored 0.851/0.687 among completed Python/Go/Rust searches (Go/Rust 0.646 including the two failures). See the response budget, whole declarations, CodeGraph and models alone reports. Model-only arms returned up to ten ranges; returned context budgets were not matched. These historical quality figures have not been rerun for the current correctness, cache and response-refill changes.

A separate recorded study searched six repositories of 1 to 7.6 million tokens using 50 questions from real issues, with the held-out half frozen before the run:

Repository

Language

Tokens per scan

Evidence R@5

Recorded cost / question

Recorded time / question

prometheus

Go

1.1M

0.83

$0.05

6 s

hugo

Go

1.0M

0.86

$0.04

20 s

lombok

Java

1.0M

0.78

$0.04

30 s

nushell

Rust

2.1M

0.79

$0.09

—

ruff

Rust

3.6M

0.90

$0.14

27 s

lucene

Java

7.6M

0.88

$0.25

23 s

Times are through the Vercel AI Gateway at concurrency 16. prometheus, ruff and lucene were measured with the code used in that report (before the local batching, windowing and worker-pool fixes they took 20 s, 3 min and 7 min); hugo and lombok are from before those fixes; nushell was measured on a slower route only. Method, every number and the misses are in the hard set report.

We also kept JevGrep and swapped only the model that scores each fragment, on 65 searches. "No answer" is the share of questions with no answer in the repository where nothing is returned; false-premise coverage is the mean fraction of required counterevidence recovered for questions built on a wrong assumption.

Judge inside JevGrep

Evidence R@5

No answer (6 planned)

False-premise coverage (14 planned)

Recorded cost / search

Recorded time / search

Jev 1.13 / 1.14

0.91

100 %

100 %

$0.002

6–7 s

Luna Decisions

0.93

67 %

75 %

$0.005

4.6 s

gpt-6-luna, no reasoning

0.95

100 %

77 %

$0.004

8 s

gpt-6-luna, medium

0.93

67 %

100 %

$0.004

13 s

gpt-6.1-terra, no reasoning

0.96

50 %

100 %

$0.042

12 s

gpt-6.1-terra, medium

0.96

33 %

100 %

$0.043

13 s

The OpenAI judges find slightly more, but they return code when the repository has no answer. Jev is the only judge that passes both checks, at 2 to 20 times lower recorded cost. These are small samples; incomplete searches were excluded from quality, including six searches with invalid JSON for Luna without reasoning. Historical request-time sums may omit retries and backoff; new benchmark reports record every attempt, wall time, and unknown usage separately.

The methodology, every number and the scripts to rerun them are in models alone, CodeGraph and judges. These are single runs on a modest question set, so treat small gaps as noise.

Getting started

You need Node.js 24 and an API key from one of the supported providers: TypeSafe AI, Vercel AI Gateway or OpenRouter.

1. Install

npm install -g @nassim-arifette/jevgrep

The unscoped jevgrep package on npm belongs to a different project. Install the scoped name above; the command is still jevgrep.

2. Add your provider key (once per computer)

jevgrep init --global                       # TypeSafe AI (default)
jevgrep init --global --provider vercel     # or Vercel AI Gateway
jevgrep init --global --provider openrouter # or OpenRouter

The key goes in your user configuration directory, never in a repository. Terminal key entry is hidden. To replace the stored key for the selected provider, run jevgrep init --global --replace-key; add --provider <name> to choose another provider. This prompts for a new key even when an old environment key exists. Environment variables still take precedence when searches run.

3. Authorize a project (once per repository)

cd path/to/my-project
jevgrep init

JevGrep asks before it sends anything:

Allow sending eligible source excerpts from this repository to Vercel AI Gateway? [y/N]

Answer y to start searching. If you would rather check first, press Enter and run jevgrep inspect to see which files would be sent (more in Privacy). Then rerun jevgrep init and answer y; tuned settings and the existing project provider are preserved.

4. Ask a question

jevgrep search --query "Where is session expiry handled?"

Each matching excerpt is printed with its location and a relevance score. Here is a real run on this repository:

$ jevgrep search --scope src --query "Where is filesystem access controlled, and what prevents path escapes?"
jevgrep: complete
coverage: scope src | files 45/45 eligible | 170 fragments | coverage complete

4 excerpts

src/source/authorization.ts:201-281 score 0.96
  #resolveWalk(normalized: string): Walk {
    this.assertCurrent();
    ...
      const canonical = fs.realpathSync.native(candidate);
      if (!contained(canonical, this.path)) return fail('outside_root', normalized);
    ...

src/cli-args.ts:57-108 score 0.95
...

Everyday use

# Look only in some folders
jevgrep search --query "How are permissions checked?" --scope src --scope tests

# Machine-readable JSON for scripts and agents
jevgrep search --query "Where is the cache invalidated?" --json

# Long, multi-line question
jevgrep search --query-file question.txt

# Check your setup without sending anything
jevgrep doctor

# See what a search would scan and roughly what it would cost
jevgrep inspect

You can run JevGrep from any folder inside an authorized project. Scores and file preparation are cached outside the repository, so repeated searches cost less and finish sooner; jevgrep cache clear resets the cache.

Choose the scope and work budget to match the question:

# Exhaustive: require every eligible fragment in this scope to be evaluated
jevgrep search --query "How are permissions checked?" --scope .

# Progressive: prioritize likely evidence and stop at the supplied work budget
jevgrep search --query "How are permissions checked?" --allow-partial --max-input-tokens 50000 --max-search-ms 10000 --json

# Continue the same query and scope with the returned continuation token
jevgrep search --query "How are permissions checked?" --allow-partial --max-input-tokens 50000 --max-search-ms 10000 --continuation '<token>' --json

# Focused: evaluate only files supplied by the caller
jevgrep search --query "How are permissions checked?" --scope src/auth.ts --scope tests/auth.test.ts

A focused search establishes coverage of the supplied files. Progressive results report what remains unevaluated; an empty partial answer does not establish absence. Operator caps still apply to exhaustive searches. Changing the question normally requires new provider evaluations, even when file preparation can be reused. Explicit scopes cannot reopen excluded files or directories, and Git negations cannot undo .jevgrepignore exclusions.

If you already know the function name or the exact string, rg will be quicker.

Connect your coding agent

JevGrep includes a local MCP server with two tools: semantic_search_code for one question and semantic_search_code_many for several questions that share one preparation of the repository. The agent gets the same excerpts the CLI would print, as text and as structuredContent, with progress notifications while a large repository is being scanned.

Authorize the repository with jevgrep init first. It prints the absolute path of the project profile, which goes in the commands below. Each server handles one repository.

claude mcp add --transport stdio jevgrep -- jevgrep mcp --config "/absolute/path/to/config.json"

Check it with claude mcp get jevgrep, or /mcp inside Claude Code. See the Claude Code MCP documentation.

Add to your Codex config.toml:

[mcp_servers.jevgrep]
command = "jevgrep"
args = ["mcp", "--config", "/absolute/path/to/config.json"]
tool_timeout_sec = 360

See the Codex MCP documentation.

For clients that use an mcpServers JSON configuration:

{
  "mcpServers": {
    "jevgrep": {
      "command": "jevgrep",
      "args": ["mcp", "--config", "/absolute/path/to/config.json"]
    }
  }
}

On Windows, if the client cannot start the jevgrep command, use the absolute paths of node.exe and the installed dist/cli.js (how).

On a large repository a search can take up to 5 minutes, so set the client's tool timeout to about 6 minutes. Keep API keys out of MCP configuration files. When the client runs as the same user, it picks up the key saved by jevgrep init --global.

Privacy: what leaves your computer

JevGrep reads your files locally. The provider you chose does the scoring, so each search sends it:

  • the eligible source fragments of the authorized repository;

  • your question;

  • repository-relative paths and the name of the enclosing symbol, when there is one.

Line numbers stay on your machine: they are not needed to judge an excerpt, and leaving them out lets the cache keep the score of a function that only moved.

JevGrep leaves out .env files, common credential files, dependencies, build output, generated and minified files, and files that look like they contain secrets. It follows .gitignore, plus a .jevgrepignore file it creates for your own exclusions. It does not follow links, and your API key never appears in a request body, a result or the cache.

Secret detection will miss things sometimes. Run jevgrep inspect before your first search and add anything sensitive to .jevgrepignore. Whatever the provider receives is covered by its own privacy and retention policies.

Providers

Provider

Setup

Model

TypeSafe AI

jevgrep init --global --provider typesafe

jev-1.13.0 (pinned)

Vercel AI Gateway

jevgrep init --global --provider vercel

typesafe-ai/jev

OpenRouter

jevgrep init --global --provider openrouter

typesafe/jev-1.13

The environment variables TYPESAFE_API_KEY, AI_GATEWAY_API_KEY and OPENROUTER_API_KEY override saved keys, which is useful in CI. To move a project to another provider, run the global setup for that provider, then jevgrep init --provider <name> inside the project. The reference lists each provider's validation status and API details.

Troubleshooting

Message or symptom

What to do

jevgrep: command not found

check that npm's global bin folder is on your PATH

REMOTE_DISABLED

you have not allowed remote evaluation yet: run jevgrep inspect, then rerun jevgrep init and answer y

CREDENTIAL_MISSING

run jevgrep init --global, or set the provider's environment variable

PROVIDER_AUTH

check model access; replace an expired key with jevgrep init --global --replace-key

No result, no_score_above_threshold

rephrase the question or widen --scope; it does not prove the code is absent

MCP tool times out

raise the client timeout to about 6 minutes

The installation guide covers more cases. Exit codes: 0 complete, 2 invalid request or configuration, 3 partial result, 4 failure, 130 interrupted.

Learn more

Contributing

git clone https://github.com/nassim-arifette/jevgrep.git
cd jevgrep
npm ci
npm run verify   # type check, offline tests, build and smoke checks
npm link         # use your checkout as the global `jevgrep` command

The test suite runs offline and needs no provider key.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI coding assistants to semantically search and retrieve relevant code patterns, documentation, and implementations from a codebase via MCP tools.
      8
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Exposes Cursor's semantic code search through MCP, enabling tools like codebase_search to query indexed repos.
      1
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables semantic code search across indexed codebases using natural language queries, with support for CLI and MCP interfaces.
      1
      MIT