jevgrep
Jev-powered semantic code search for coding agents — find behavior across repositories via CLI or MCP, with exact source excerpts and line numbers.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nassim-arifette/jevgrep with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nassim-arifette/jevgrep'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/nassim-arifette--jevgrep)HTML
<a href="/listings/nassim-arifette--jevgrep"><img src="/api/listings/nassim-arifette--jevgrep/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Install the public package from npm:
npm install -g @nassim-arifette/jevgrep jevgrep --version
The unscoped package name `jevgrep` belongs to a different project. Use the complete scoped name above when installing. The installed command is still `jevgrep`.
Package: [@nassim-arifette/jevgrep](https://www.npmjs.com/package/@nassim-arifette/jevgrep)
To install a development checkout instead:
git clone https://github.com/nassim-arifette/jevgrep.git cd jevgrep npm ci npm run build npm link jevgrep --version
`npm link` makes the `jevgrep` command available from any directory on the computer.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 379 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # JevGrep
- [](https://www.npmjs.com/package/@nassim-arifette/jevgrep)
- [](https://nodejs.org/)
- [](https://modelcontextprotocol.io/)
- [](LICENSE)
- 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.
- <p align="center">
- <a href="https://github.com/nassim-arifette/jevgrep/blob/main/docs/assets/jevgrep-demo.mp4">
- <img src="https://raw.githubusercontent.com/nassim-arifette/jevgrep/main/docs/assets/jevgrep-demo.gif" alt="Animated JevGrep demo: a plain-English question returns the exact source lines, paths and scores" width="900">
- </a>
- <br>
- <sub><a href="https://github.com/nassim-arifette/jevgrep/blob/main/docs/assets/jevgrep-demo.mp4">Full-quality video (44 s)</a>. The results in it come from a real search on this repository.</sub>
- </p>
- ## 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.
- ## 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](benchmarks/baselines/2026-11-04-response-budget.md),
- [whole declarations](benchmarks/baselines/2026-11-04-whole-declarations.md),
- [CodeGraph](benchmarks/baselines/2026-11-04-codegraph-comparison.md) and
- [models alone](benchmarks/baselines/2026-11-04-models-alone.md) 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](benchmarks/baselines/2026-11-04-hard-set.md) 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](benchmarks/baselines/2026-11-04-models-alone.md),
- [CodeGraph](benchmarks/baselines/2026-11-04-codegraph-comparison.md) and
- [judges](benchmarks/baselines/2026-11-04-judge-comparison.md). 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](https://typesafe.ai), [Vercel AI Gateway](https://vercel.com/ai-gateway)
- or [OpenRouter](https://openrouter.ai/settings/keys).
- ### 1. Install
- ```bash
- 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)
- ```bash
- 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)
- ```bash
- cd path/to/my-project
- jevgrep init
- ```
- JevGrep asks before it sends anything:
- ```text
- 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](#privacy-what-leaves-your-computer)). Then rerun `jevgrep init` and
- answer `y`; tuned settings and the existing project provider are preserved.
- ### 4. Ask a question
- ```bash
- 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:
- ```text
- $ 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
- ...
- ```
- <p align="center">
- <img src="https://raw.githubusercontent.com/nassim-arifette/jevgrep/main/docs/assets/jevgrep-result.png" alt="The top excerpt: src/source/authorization.ts lines 201 to 281, score 0.96, with the path containment check highlighted" width="900">
- </p>
- ## Everyday use
- ```bash
- # 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:
- ```bash
- # 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](https://modelcontextprotocol.io/) 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.
- <details open>
- <summary><b>Claude Code</b></summary>
- ```bash
- 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](https://code.claude.com/docs/en/mcp).
- </details>
- <details>
- <summary><b>Codex</b></summary>
- Add to your Codex `config.toml`:
- ```toml
- [mcp_servers.jevgrep]
- command = "jevgrep"
- args = ["mcp", "--config", "/absolute/path/to/config.json"]
- tool_timeout_sec = 360
- ```
- See the [Codex MCP documentation](https://developers.openai.com/codex/mcp).
- </details>
- <details>
- <summary><b>Any other MCP client</b></summary>
- For clients that use an `mcpServers` JSON configuration:
- ```json
- {
- "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](docs/install-guide.md#connect-an-mcp-client)).
- </details>
- 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](docs/reference.md#providers) 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](docs/install-guide.md#troubleshooting) covers more cases.
- Exit codes: `0` complete, `2` invalid request or configuration, `3` partial result,
- `4` failure, `130` interrupted.
- ## Learn more
- - [Installation and configuration guide](docs/install-guide.md): manual profiles, limits, cost caps, retries and Windows notes
- - [Reference](docs/reference.md): providers, JSON output, cache policy, request batching and development
- - [Benchmarks](benchmarks/README.md): retrieval quality and performance
- - [Report an issue](https://github.com/nassim-arifette/jevgrep/issues)
- ## Contributing
- ```bash
- 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](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.