Jevgrep (jg)
Ask a repository question and get relevant file locations plus verbatim source excerpts. Jevgrep helps a coding agent begin unfamiliar multi-file work with useful context; the agent still owns implementation and verification.
Requires Node.js 22 or newer on macOS, Linux, or Windows. Install and authenticate:
npm install --global @dzhng/jevgrep
jg auth
jg doctor
jg "How are telemetry events recorded and sent?" ./my-project
auth asks you to choose a provider or a custom endpoint, then saves its key in an
owner-only config file. Run jg --help for the supported provider names. Searches
use that provider until you run auth again.
doctor verifies access with synthetic input and names the selected provider or
endpoint host.
When the provider rejects the request, doctor reports the HTTP status and its
error message, when available. A working key can still lack model access or paid
credits; follow the provider’s explanation before replacing the key. Saved keys
and raw response bodies are excluded from diagnostic output. If a provider echoes
a key with inserted separators, its message is omitted.
For unattended setup, pipe the key from your secret manager to:
jg auth --provider opencode --stdin
Both options are required for piped setup. To send traffic through your own
TypeSafe-compatible gateway, choose “Custom endpoint” in auth and enter its base
URL and model ID, or pass both explicitly:
jg auth --provider custom --base-url https://gateway.example.com/typesafe/v1 --model gateway/jev-2 --stdin
Custom endpoints must use https://; http://localhost and http://127.0.0.1
are accepted for a local proxy. Auth and doctor name only the endpoint host, never
the key. The saved endpoint and model are part of the cache identity, so custom
answers stay separate from the preset providers’ answers and from other endpoints.
A custom base URL must contain only the scheme, host, and optional path: no
embedded credentials, query string, or fragment. Jevgrep appends /systemone to
that base URL and sends the saved key as a Bearer token.
For gateway implementers, Jevgrep's boolean questions arrive as noul questions
without criteria. A minimal request and response are:
{
"model": "your-model",
"state": "source context",
"questions": { "q": { "type": "noul", "instructions": "Relevant?" } }
}
{ "answers": { "q": { "type": "noul", "noul": 0.9 } } }
Return an answer for every question ID, with a finite noul value between 0 and 1.
These answers need neither probabilities nor confidence. A server that demands
criteria.true and returns HTTP 422 is incompatible with these requests. Run
jg doctor against a custom gateway before searching a repository.
Credentials are saved under
$XDG_CONFIG_HOME/jevgrep/credentials.json, or ~/.config/jevgrep/credentials.json.
On Windows, config defaults to %APPDATA%\jevgrep and cache to %LOCALAPPDATA%\jevgrep.
XDG_CONFIG_HOME and XDG_CACHE_HOME override their respective locations independently
when set to absolute paths; relative values are ignored and platform defaults are used.
Windows ignores POSIX file modes, so these files rely on the user profile's access controls.
Existing saved records without a provider still mean Vercel, without a migration.
API-key, endpoint, and model environment overrides are ignored; users who only
configured an environment key must run auth. There is no automatic fallback or
per-search provider override. Searches send eligible source to the saved service.
Run jg files ./project first to see how many files and bytes that root makes
eligible and how many paths each filter skips; it needs no key and sends nothing.
Add --list to see the eligible relative paths, quoted and sorted. To remove a
path you did not intend to send, repeat the preview with --exclude and use the
same exclusions for the search. An incomplete preview lists only paths seen
before the limit or interruption; search-time content checks can exclude more.
Evaluation answers are cached locally; jg --help describes cache controls.
For a slow or unstable connection, try jg "question" ./project --concurrency 4
(or 1 to serialize requests). The default limit is 32 across all search stages,
including retries. Waiting for a slot does not consume the request timeout, and
queued source is revalidated before upload. This controls transport pressure,
not relevance thresholds or cache identity.
An incomplete search reports one sanitized, unrecovered provider error alongside
its issue counts, distinguishing HTTP failures, timeouts, and connection failures.
A batch failure that recovers through splitting is not used as the diagnostic. The
reported concurrency limit helps tune the next run. Only validated evaluation
answers are cached: provider errors and the final search result are never stored.
Rerunning after the connection recovers retries failed work while reusing valid
answers; --no-cache additionally bypasses those valid cached answers.
Bounded resource limits are a backstop for large or changing trees. They remain
visible as discovery incomplete and Issue: "resource_limit", but a result
containing only those issues exits successfully so shells and coding agents do
not mistake useful partial output for a failed command. Provider and other
operational issues retain the incomplete exit status.
The summary comes first, followed by file and declaration locations and selected
source. Locations are reading leads, not a checklist. Omitted excerpts are marked;
--max-source-bytes 0 includes all selected source. An incomplete result can still
be useful. Read what it supplies, then fill specific gaps with ordinary tools.
Application output goes to stdout; jg does not create a report file.
Agent skill
Installing the CLI is only half of agent setup: install the skill too.
Install the canonical skill into the project where your coding agent works:
jg skill
The installer detects your coding agents (Claude Code, Codex, OpenCode and
others) and asks where to install. jg skill also accepts --agent NAME
(repeatable), --global, and --yes; these options come from the
skills CLI, which it
delegates to. jg skill installs the jevgrep skill from this repository's
main branch with npm lifecycle scripts disabled and requires Node 22.20+ and
npm/npx with network access for the pinned installer. Rerun jg skill to refresh
the skill without waiting for a new npm release. Installer transitive
dependencies remain an external trust boundary.
Installing the skill does not configure the provider key.
Search does not install skills or edit agent configuration. Only an explicit skill installation command invokes the installer. The skill directs the agent to read returned excerpts before further discovery, skip redundant searches when the needed context is already known, and handle incomplete results honestly.
There is no built-in upgrade command. Use npm install --global @dzhng/jevgrep@latest
to upgrade the CLI, then rerun jg skill to update the agent's copy too. The
installer records the GitHub source and skill path in skills-lock.json. Rerun
jg skill on another machine or after changing your Node installation.
See the repository for architecture, official benchmark evidence and development. Jevgrep is MIT licensed.