Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nassim-arifette--jevgrep/badge.svg)](/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

i

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.

  1. # JevGrep
  2. [![npm version](https://img.shields.io/npm/v/%40nassim-arifette%2Fjevgrep?logo=npm&label=npm)](https://www.npmjs.com/package/@nassim-arifette/jevgrep)
  3. [![Node.js 24+](https://img.shields.io/badge/node-%3E%3D24-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
  4. [![MCP](https://img.shields.io/badge/MCP-compatible-7C3AED?logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io/)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  6. JevGrep finds code from a description of what it does. Ask something like *"Where is
  7. session expiry handled?"* and it returns the source lines that answer it, with file
  8. paths and line numbers. You can run it in a terminal or add it to Claude Code, Codex
  9. or another MCP client, so your coding agent can look things up instead of opening
  10. one file after another.
  11. <p align="center">
  12. <a href="https://github.com/nassim-arifette/jevgrep/blob/main/docs/assets/jevgrep-demo.mp4">
  13. <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">
  14. </a>
  15. <br>
  16. <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>
  17. </p>
  18. ## Why JevGrep
  19. `grep` and `rg` work well when you know the name to search for. Often you only know
  20. what the code is supposed to do:
  21. - *"Where do we check that a user can access this project?"*
  22. - *"What happens when a payment webhook arrives twice?"*
  23. - *"Which code decides whether a file is too big to index?"*
  24. JevGrep is built for that kind of question. Results are verbatim excerpts with
  25. `path:start-end`, so you or your agent can open the file and carry on from there. For
  26. an agent, one tool call stands in for a long walk through the repository, and the
  27. answer stays within a token budget you set. Every eligible UTF-8 text file is scored,
  28. configuration and tests included. Nothing is sent until you have authorized the
  29. repository and had the chance to check what would leave your computer.
  30. ## How it compares
  31. The recorded comparison used 55 real questions on six open-source repositories
  32. (21 in Python, 34 in Go and Rust). **Mean evidence recall@5** (R@5) averages the
  33. fraction of each question's required evidence units covered by its first five
  34. results. Finding one of three required units gives 1/3 recall. Hit rate@5 counts
  35. questions with any required unit; complete-evidence success counts questions with
  36. every required unit. Those are separate metrics in new benchmark reports.
  37. | Tool | Evidence R@5 Python (21) | Evidence R@5 Go/Rust (all 34) | Go/Rust completed | Recorded cost / question | Recorded time / question |
  38. |---|---:|---:|---:|---:|---:|
  39. | JevGrep, 8000 tokens + whole declarations | 0.877 | ≈0.778 | 32/34 (94.1%) | $0.005 | 4 s |
  40. | `gpt-6.1-terra` given the whole repository, medium | 0.894 | 0.694 | 34/34 | $0.12–0.23 | 12–15 s |
  41. | `gpt-6-luna` given the whole repository, no reasoning | 0.803 | 0.648 | 34/34 | $0.01–0.02 | 3–4 s |
  42. | CodeGraph `query` | 0.491 | 0.319 | 34/34 | free, needs an index | 1 s |
  43. | BM25 | 0.429 | 0.338 | 34/34 | free | < 0.1 s |
  44. | ripgrep | 0.325 | 0.244 | 34/34 | free | 0.3 s |
  45. All 21 Python searches completed. The Go/Rust column counts JevGrep's two capped
  46. searches as zero: ≈0.778 is derived from the rounded completed-search recall
  47. 0.827 × 32/34, rather than a newly measured result. On the matching 32-question
  48. subset, Terra, Luna and JevGrep scored 0.737, 0.688 and 0.827 respectively.
  49. JevGrep's row comes from the 2026-11-04 offline replay at 8000 response tokens with
  50. whole declarations; its original 4000-token live run scored 0.851/0.687 among
  51. completed Python/Go/Rust searches (Go/Rust 0.646 including the two failures).
  52. See the [response budget](benchmarks/baselines/2026-11-04-response-budget.md),
  53. [whole declarations](benchmarks/baselines/2026-11-04-whole-declarations.md),
  54. [CodeGraph](benchmarks/baselines/2026-11-04-codegraph-comparison.md) and
  55. [models alone](benchmarks/baselines/2026-11-04-models-alone.md) reports.
  56. Model-only arms returned up to ten ranges; returned context budgets were not
  57. matched. These historical quality figures have not been rerun for the current
  58. correctness, cache and response-refill changes.
  59. A separate recorded study searched six repositories of 1 to 7.6 million tokens
  60. using 50 questions from real issues, with the held-out half frozen before the run:
  61. | Repository | Language | Tokens per scan | Evidence R@5 | Recorded cost / question | Recorded time / question |
  62. |---|---|---:|---:|---:|---:|
  63. | prometheus | Go | 1.1M | 0.83 | $0.05 | 6 s |
  64. | hugo | Go | 1.0M | 0.86 | $0.04 | 20 s |
  65. | lombok | Java | 1.0M | 0.78 | $0.04 | 30 s |
  66. | nushell | Rust | 2.1M | 0.79 | $0.09 | — |
  67. | ruff | Rust | 3.6M | 0.90 | $0.14 | 27 s |
  68. | lucene | Java | 7.6M | 0.88 | $0.25 | 23 s |
  69. Times are through the Vercel AI Gateway at concurrency 16. prometheus, ruff and
  70. lucene were measured with the code used in that report (before the local batching, windowing and
  71. worker-pool fixes they took 20 s, 3 min and 7 min); hugo and lombok are from before
  72. those fixes; nushell was measured on a slower route only.
  73. Method, every number and the misses are in the
  74. [hard set](benchmarks/baselines/2026-11-04-hard-set.md) report.
  75. We also kept JevGrep and swapped only the model that scores each fragment, on 65
  76. searches. "No answer" is the share of questions with no answer in the repository
  77. where nothing is returned; false-premise coverage is the mean fraction of required
  78. counterevidence recovered for questions built on a wrong assumption.
  79. | Judge inside JevGrep | Evidence R@5 | No answer (6 planned) | False-premise coverage (14 planned) | Recorded cost / search | Recorded time / search |
  80. |---|---:|---:|---:|---:|---:|
  81. | **Jev 1.13 / 1.14** | 0.91 | **100 %** | **100 %** | **$0.002** | 6–7 s |
  82. | Luna Decisions | 0.93 | 67 % | 75 % | $0.005 | 4.6 s |
  83. | `gpt-6-luna`, no reasoning | 0.95 | 100 % | 77 % | $0.004 | 8 s |
  84. | `gpt-6-luna`, medium | 0.93 | 67 % | 100 % | $0.004 | 13 s |
  85. | `gpt-6.1-terra`, no reasoning | 0.96 | 50 % | 100 % | $0.042 | 12 s |
  86. | `gpt-6.1-terra`, medium | 0.96 | 33 % | 100 % | $0.043 | 13 s |
  87. The OpenAI judges find slightly more, but they return code when the repository has
  88. no answer. Jev is the only judge that passes both checks, at 2 to 20 times lower
  89. recorded cost. These are small samples; incomplete searches were excluded from
  90. quality, including six searches with invalid JSON for Luna without reasoning.
  91. Historical request-time sums may omit retries and backoff; new benchmark reports
  92. record every attempt, wall time, and unknown usage separately.
  93. The methodology, every number and the scripts to rerun them are in
  94. [models alone](benchmarks/baselines/2026-11-04-models-alone.md),
  95. [CodeGraph](benchmarks/baselines/2026-11-04-codegraph-comparison.md) and
  96. [judges](benchmarks/baselines/2026-11-04-judge-comparison.md). These are single
  97. runs on a modest question set, so treat small gaps as noise.
  98. ## Getting started
  99. You need Node.js 24 and an API key from one of the supported providers:
  100. [TypeSafe AI](https://typesafe.ai), [Vercel AI Gateway](https://vercel.com/ai-gateway)
  101. or [OpenRouter](https://openrouter.ai/settings/keys).
  102. ### 1. Install
  103. ```bash
  104. npm install -g @nassim-arifette/jevgrep
  105. ```
  106. > The unscoped `jevgrep` package on npm belongs to a different project. Install the scoped name above; the command is still `jevgrep`.
  107. ### 2. Add your provider key (once per computer)
  108. ```bash
  109. jevgrep init --global # TypeSafe AI (default)
  110. jevgrep init --global --provider vercel # or Vercel AI Gateway
  111. jevgrep init --global --provider openrouter # or OpenRouter
  112. ```
  113. The key goes in your user configuration directory, never in a repository. Terminal
  114. key entry is hidden. To replace the stored key for the selected provider, run
  115. `jevgrep init --global --replace-key`; add `--provider <name>` to choose another
  116. provider. This prompts for a new key even when an old environment key exists.
  117. Environment variables still take precedence when searches run.
  118. ### 3. Authorize a project (once per repository)
  119. ```bash
  120. cd path/to/my-project
  121. jevgrep init
  122. ```
  123. JevGrep asks before it sends anything:
  124. ```text
  125. Allow sending eligible source excerpts from this repository to Vercel AI Gateway? [y/N]
  126. ```
  127. Answer `y` to start searching. If you would rather check first, press Enter and run
  128. `jevgrep inspect` to see which files would be sent (more in
  129. [Privacy](#privacy-what-leaves-your-computer)). Then rerun `jevgrep init` and
  130. answer `y`; tuned settings and the existing project provider are preserved.
  131. ### 4. Ask a question
  132. ```bash
  133. jevgrep search --query "Where is session expiry handled?"
  134. ```
  135. Each matching excerpt is printed with its location and a relevance score. Here is a
  136. real run on this repository:
  137. ```text
  138. $ jevgrep search --scope src --query "Where is filesystem access controlled, and what prevents path escapes?"
  139. jevgrep: complete
  140. coverage: scope src | files 45/45 eligible | 170 fragments | coverage complete
  141. 4 excerpts
  142. src/source/authorization.ts:201-281 score 0.96
  143. #resolveWalk(normalized: string): Walk {
  144. this.assertCurrent();
  145. ...
  146. const canonical = fs.realpathSync.native(candidate);
  147. if (!contained(canonical, this.path)) return fail('outside_root', normalized);
  148. ...
  149. src/cli-args.ts:57-108 score 0.95
  150. ...
  151. ```
  152. <p align="center">
  153. <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">
  154. </p>
  155. ## Everyday use
  156. ```bash
  157. # Look only in some folders
  158. jevgrep search --query "How are permissions checked?" --scope src --scope tests
  159. # Machine-readable JSON for scripts and agents
  160. jevgrep search --query "Where is the cache invalidated?" --json
  161. # Long, multi-line question
  162. jevgrep search --query-file question.txt
  163. # Check your setup without sending anything
  164. jevgrep doctor
  165. # See what a search would scan and roughly what it would cost
  166. jevgrep inspect
  167. ```
  168. You can run JevGrep from any folder inside an authorized project. Scores and file
  169. preparation are cached outside the repository, so repeated searches cost less and
  170. finish sooner; `jevgrep cache clear` resets the cache.
  171. Choose the scope and work budget to match the question:
  172. ```bash
  173. # Exhaustive: require every eligible fragment in this scope to be evaluated
  174. jevgrep search --query "How are permissions checked?" --scope .
  175. # Progressive: prioritize likely evidence and stop at the supplied work budget
  176. jevgrep search --query "How are permissions checked?" --allow-partial --max-input-tokens 50000 --max-search-ms 10000 --json
  177. # Continue the same query and scope with the returned continuation token
  178. jevgrep search --query "How are permissions checked?" --allow-partial --max-input-tokens 50000 --max-search-ms 10000 --continuation '<token>' --json
  179. # Focused: evaluate only files supplied by the caller
  180. jevgrep search --query "How are permissions checked?" --scope src/auth.ts --scope tests/auth.test.ts
  181. ```
  182. A focused search establishes coverage of the supplied files. Progressive results
  183. report what remains unevaluated; an empty partial answer does not establish absence.
  184. Operator caps still apply to exhaustive searches. Changing the question normally
  185. requires new provider evaluations, even when file preparation can be reused.
  186. Explicit scopes cannot reopen excluded files or directories, and Git negations
  187. cannot undo `.jevgrepignore` exclusions.
  188. If you already know the function name or the exact string, `rg` will be quicker.
  189. ## Connect your coding agent
  190. JevGrep includes a local [MCP](https://modelcontextprotocol.io/) server with two tools:
  191. `semantic_search_code` for one question and `semantic_search_code_many` for several
  192. questions that share one preparation of the repository. The agent gets the same
  193. excerpts the CLI would print, as text and as `structuredContent`, with progress
  194. notifications while a large repository is being scanned.
  195. Authorize the repository with `jevgrep init` first. It prints the absolute path of the
  196. project profile, which goes in the commands below. Each server handles one repository.
  197. <details open>
  198. <summary><b>Claude Code</b></summary>
  199. ```bash
  200. claude mcp add --transport stdio jevgrep -- jevgrep mcp --config "/absolute/path/to/config.json"
  201. ```
  202. Check it with `claude mcp get jevgrep`, or `/mcp` inside Claude Code.
  203. See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
  204. </details>
  205. <details>
  206. <summary><b>Codex</b></summary>
  207. Add to your Codex `config.toml`:
  208. ```toml
  209. [mcp_servers.jevgrep]
  210. command = "jevgrep"
  211. args = ["mcp", "--config", "/absolute/path/to/config.json"]
  212. tool_timeout_sec = 360
  213. ```
  214. See the [Codex MCP documentation](https://developers.openai.com/codex/mcp).
  215. </details>
  216. <details>
  217. <summary><b>Any other MCP client</b></summary>
  218. For clients that use an `mcpServers` JSON configuration:
  219. ```json
  220. {
  221. "mcpServers": {
  222. "jevgrep": {
  223. "command": "jevgrep",
  224. "args": ["mcp", "--config", "/absolute/path/to/config.json"]
  225. }
  226. }
  227. }
  228. ```
  229. On Windows, if the client cannot start the `jevgrep` command, use the absolute paths of
  230. `node.exe` and the installed `dist/cli.js`
  231. ([how](docs/install-guide.md#connect-an-mcp-client)).
  232. </details>
  233. On a large repository a search can take up to 5 minutes, so set the client's tool
  234. timeout to about 6 minutes. Keep API keys out of MCP configuration files. When the
  235. client runs as the same user, it picks up the key saved by `jevgrep init --global`.
  236. ## Privacy: what leaves your computer
  237. JevGrep reads your files locally. The provider you chose does the scoring, so each
  238. search sends it:
  239. - the eligible source fragments of the authorized repository;
  240. - your question;
  241. - repository-relative paths and the name of the enclosing symbol, when there is one.
  242. Line numbers stay on your machine: they are not needed to judge an excerpt, and
  243. leaving them out lets the cache keep the score of a function that only moved.
  244. JevGrep leaves out `.env` files, common credential files, dependencies, build output,
  245. generated and minified files, and files that look like they contain secrets. It
  246. follows `.gitignore`, plus a `.jevgrepignore` file it creates for your own
  247. exclusions. It does not follow links, and your API key never appears in a request
  248. body, a result or the cache.
  249. Secret detection will miss things sometimes. Run `jevgrep inspect` before your first
  250. search and add anything sensitive to `.jevgrepignore`. Whatever the provider receives
  251. is covered by its own privacy and retention policies.
  252. ## Providers
  253. | Provider | Setup | Model |
  254. | ----------------- | --------------------------------------------- | --------------------- |
  255. | TypeSafe AI | `jevgrep init --global --provider typesafe` | `jev-1.13.0` (pinned) |
  256. | Vercel AI Gateway | `jevgrep init --global --provider vercel` | `typesafe-ai/jev` |
  257. | OpenRouter | `jevgrep init --global --provider openrouter` | `typesafe/jev-1.13` |
  258. The environment variables `TYPESAFE_API_KEY`, `AI_GATEWAY_API_KEY` and
  259. `OPENROUTER_API_KEY` override saved keys, which is useful in CI. To move a project to
  260. another provider, run the global setup for that provider, then
  261. `jevgrep init --provider <name>` inside the project. The
  262. [reference](docs/reference.md#providers) lists each provider's validation status and
  263. API details.
  264. ## Troubleshooting
  265. | Message or symptom | What to do |
  266. | --- | --- |
  267. | `jevgrep: command not found` | check that npm's global `bin` folder is on your `PATH` |
  268. | `REMOTE_DISABLED` | you have not allowed remote evaluation yet: run `jevgrep inspect`, then rerun `jevgrep init` and answer `y` |
  269. | `CREDENTIAL_MISSING` | run `jevgrep init --global`, or set the provider's environment variable |
  270. | `PROVIDER_AUTH` | check model access; replace an expired key with `jevgrep init --global --replace-key` |
  271. | No result, `no_score_above_threshold` | rephrase the question or widen `--scope`; it does not prove the code is absent |
  272. | MCP tool times out | raise the client timeout to about 6 minutes |
  273. The [installation guide](docs/install-guide.md#troubleshooting) covers more cases.
  274. Exit codes: `0` complete, `2` invalid request or configuration, `3` partial result,
  275. `4` failure, `130` interrupted.
  276. ## Learn more
  277. - [Installation and configuration guide](docs/install-guide.md): manual profiles, limits, cost caps, retries and Windows notes
  278. - [Reference](docs/reference.md): providers, JSON output, cache policy, request batching and development
  279. - [Benchmarks](benchmarks/README.md): retrieval quality and performance
  280. - [Report an issue](https://github.com/nassim-arifette/jevgrep/issues)
  281. ## Contributing
  282. ```bash
  283. git clone https://github.com/nassim-arifette/jevgrep.git
  284. cd jevgrep
  285. npm ci
  286. npm run verify # type check, offline tests, build and smoke checks
  287. npm link # use your checkout as the global `jevgrep` command
  288. ```
  289. The test suite runs offline and needs no provider key.
  290. ## License
  291. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.