Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.
TypeScript ai-sdkclaude-codeclicode-searchcodexcoding-agentscontext-retrievaldeveloper-toolsjevsemantic-searchtypescriptvercel-ai-gateway
docs: introduce public README with generated header and benchmark explainer
David Zhang487625e60dc2
diff --git a/README.md b/README.mdindex deff3ac..75311f5 100644--- a/README.md+++ b/README.md@@ -1,51 +1,116 @@++# jevgrep-Context retrieval for coding agents: ask a repository question and receive source-context that helps the agent act without a long sequence of searches and reads.-The production Node-only CLI is implemented and its installed package is verified-on macOS and Linux. The [implementation record](specs/done/jevgrep/README.md)-owns the rationale, invariants and evidence limits. The user accepted the documented-quality tradeoff after the corrected candidate failed its original benchmark gate;-the separately authorized identical-runtime repeat also failed that gate. It solved-7/10 tasks versus the saved baseline’s 8/10 while reducing total Sol cost by 40.70%.-Both complete cohorts remain separately reported in the implementation record.+[](https://www.npmjs.com/package/@dzhng/jevgrep)+[](LICENSE)+[](apps/cli/README.md)+[](https://github.com/dzhng/jevgrep/actions/workflows/publish.yml)++**Find code by asking what it does.**++Coding agents spend part of every unfamiliar task finding the right files.+Jevgrep gives them a place to start: ask a repository question, and `jg` returns+relevant files, reading leads, and verbatim source excerpts in one stdout response.+It uses [Jev](https://vercel.com/ai-gateway/models/jev) to judge relevance across+folders, files, and declarations. Your coding agent then implements and tests the change.++```sh+npm install -g @dzhng/jevgrep+jg auth+jg "How are telemetry events recorded and sent?" ./my-project+```++Requires **Node.js 22+**, **macOS or Linux**, and a **Vercel AI Gateway key**.+No separate Python, Bun, or ripgrep installation is required to use `jg`.++## Give your agent the skill++Install the CLI above, then add the skill to the project where your agent works:++```sh+npx skills add dzhng/jevgrep --skill jevgrep --agent codex --agent claude-code+```++Select just the agent you use, or add `--global` for a user-wide install. The+[skill](skills/jevgrep/SKILL.md) teaches the agent when to call `jg`, how to use+returned context, and when to fill gaps with its normal tools. It skips redundant+retrieval when the needed context is already known. Installing the skill does not+install the executable or configure an API key.++For manual skill export and authentication options, see the [package guide](apps/cli/README.md).++## Start with a question, leave with source++Use `jg` when you know the behavior you need to understand but not where it lives:++```sh+jg "Where is authentication checked before a request reaches a handler?" .+jg "How are database connections created, pooled, and closed?" ./src+jg "Which tests cover retry behavior when a request times out?" .+```++Jevgrep explores the repository hierarchy and follows qualifying branches. It+selects files using content previews, then identifies useful source units and+surrounding context. It keeps qualifying file locations even when it cannot+confidently return an excerpt; it does not force every search into a fixed top-two+list.++The summary comes first, followed by file locations, reading leads, and selected+source with line references. Python and TypeScript/JavaScript support declaration+parsing; other text uses a fallback. The output is evidence for the agent to use,+not a generated answer or a guarantee that every relevant file was found.+[See a recorded output example](specs/done/jevgrep/assets/stdout-example.txt).++When you already know an exact symbol or path, a direct read or `rg` search may be+all you need. Jevgrep is most useful for questions that span unfamiliar files.++## What we measured++++**About 40% lower coding-agent cost in one ten-task SWE-bench repeat.** Full Sol+cost fell from **$7.62 to $4.52**, including failed tasks and excluding Jev costs.+Solve rate was **7/10 with `jg`, versus 8/10 for the saved baseline**. This is a cost+reduction with a quality tradeoff, not evidence of equal or better solve quality.++The earlier run of the same corrected runtime solved 6/10 at $5.54. Both runs+remain separate; baselines were run once and reused, and outcomes were never+pooled. Both failed the original quality gate. The sample is a tuned Python+subset evaluated with Sol, so it does not establish general savings, faster+execution, or results for other coding agents.++The [full results and paired trace analysis](specs/done/jevgrep/assets/variance-repeat.md)+include exact costs, failed tasks, and separately observed Jev charges. See the+[evaluation guide](evals/README.md) for methodology.++## Source, credentials, and local state++Searches send eligible source content to Jev through Vercel AI Gateway. Default+filesystem filtering respects ignore files and excludes hidden, dependency/build,+binary, and obvious credential files. These filters are not a guarantee that all+sensitive information has been removed; choose a search root you intend to send.++`jg auth` saves your key in an owner-only config file. `AI_GATEWAY_API_KEY` takes+precedence when set; `jg doctor` checks the connection with synthetic input.+Evaluation answers are cached locally by default. The CLI writes its output to+stdout and does not create report files. Use `jg --help` for cache controls,+search overrides, and incomplete-result behavior.## Development-Uses Duet's Bun workspaces, shared TypeScript configuration, and Turborepo pattern.-Install with `bun install`, then run `bun run dev --help`. `bun run build` creates-a Node-compatible CLI at `apps/cli/dist/bin/index.js`; invoke it with Node during development.-Use the root typecheck, lint, test, and format-check scripts before handing off changes.--Run `bun run dev auth` to paste a hidden AI Gateway key, then `bun run dev doctor`-to exercise Jev using synthetic input. `auth --stdin` supports secret-manager pipes.-Credentials live in `$XDG_CONFIG_HOME/jevgrep/credentials.json`, falling back to-`~/.config/jevgrep/credentials.json`, with owner-only permissions. The environment-variable `AI_GATEWAY_API_KEY` takes precedence. Auth saves the key; doctor verifies it.--The CLI owns user interaction and credentials. [Core](packages/core/src/index.ts)-owns the Jev integration. AI SDK is pinned because its evaluation API is experimental.-Future providers should enter at that boundary when supported, rather than leak-provider concerns into repository traversal.--The architecture spike uses a pinned SWE-bench subset with Codex Sol.-The registered quality gate requires preserving baseline official solves while-reducing full task cost; the corrected candidate did not pass it. Jev usage is excluded. Claude and performance optimization are deferred. See [evaluations](evals/README.md) for the official benchmark-workflow and accounting rules. Older custom evals are deprecated and stay out of Git.--## Agent skill--See the [package guide](apps/cli/README.md) for installation, authentication and-Codex/Claude skill setup. The canonical [Jevgrep skill](skills/jevgrep/SKILL.md)-lives under `skills/` and is embedded unchanged in the installed CLI. Agent-configuration changes only when the user explicitly installs or exports it.--## Releases--The npm package is `@dzhng/jevgrep`; its executable is `jg`. The project uses the-[MIT license](LICENSE). [Release guidance](scripts/RELEASING.md) describes the-verified tarball and GitHub tag workflow. Version [0.1.0](https://www.npmjs.com/package/@dzhng/jevgrep/v/0.1.0) is published:-`npm install --global @dzhng/jevgrep`. The-[release record](specs/done/jevgrep/assets/release-0.1.0.md) owns artifact identity-and verification. The frozen benchmark archive remains `0.0.0`; publication does-not replace either measured cohort.+The repository uses TypeScript, Bun workspaces, and Turborepo. From a checkout:++```sh+bun install --frozen-lockfile+bun run dev --help+bun run verify+```++Verification includes Docker tests of the installed Node-only package. For the+reasoning behind retrieval, parsing, caching, and failure handling, start with the+[architecture](docs/architecture.md) and [implementation record](specs/done/jevgrep/README.md).+[Release guidance](scripts/RELEASING.md) covers tag-triggered npm publication and+verification of the exact public package.++[MIT](LICENSE). [Artwork and generation prompts](assets/README.md).diff --git a/assets/README.md b/assets/README.mdnew file mode 100644index 0000000..47d68a8--- /dev/null+++ b/assets/README.md@@ -0,0 +1,35 @@+# README artwork++Generated with the built-in image generation tool for the public README.+The cover illustrates discovery; it is not a literal file tree or CLI screenshot.+The explainer's example code is illustrative. Its benchmark claim comes from the+[retained repeat](../specs/done/jevgrep/assets/variance-repeat.md): 40.70% lower full+Sol cost across ten tasks, including failures, excluding Jev; 7/10 solves versus+8/10 baseline. The image rounds the reduction down to 40%. It does not claim+unchanged quality, faster execution, or general savings.++## Cover prompt++Create a finished wide landscape GitHub README hero image for an open-source developer CLI called "jevgrep", executable "jg". Aspect ratio about 2.4:1. Editorial technical illustration, refined print-like graphic design, warm ivory background, near-black ink, vibrant vermilion and muted blue accents. Strong typographic hierarchy, generous whitespace. Left half large crisp title exactly "jevgrep", smaller subtitle exactly "Find the context. Start coding." and a small terminal pill exactly "jg". Right half an elegant illustrated branching file tree: many small paper/code cards, a few highlighted coral branches leading to a neat small stack of source excerpts. Communicate semantic research through source files, grounded and calm. Flat shapes with slight paper grain, precise thin connectors, no gradients, no robots, no generic AI sparkle, no photos, no fake UI or charts. All text spelled exactly as given. Keep safe margins and very legible at GitHub README width. This is a project header image, not a web page screenshot.++### Final cover edit++Edit this Jevgrep README header while preserving its warm ivory/black/vermilion editorial style, large title, exact subtitle "Find the context. Start coding.", jg terminal pill, and wide composition. Simplify the right-hand file tree into elegant folder and document icons with code represented ONLY by abstract horizontal lines. Remove ALL tiny filename labels, all Rust code and .rs extensions, and replace the three rightmost source cards with clean abstract code lines (no words). Remove the bottom footer "SOURCE CODE × SEMANTIC SEARCH × FASTER PROGRESS" and the bottom-right italic extra tagline entirely. Do not add text. The ONLY text anywhere in the final image must be "jevgrep", "Find the context. Start coding.", and "jg". Keep the core idea: coral highlighted paths through a tree of folders and files flow into selected source cards. Avoid malformed connecting strokes; keep connectors crisp. Beautiful clear header at GitHub README width, no speed claims.++## Explainer prompt++Create a finished landscape explainer graphic for the open-source developer CLI "jevgrep" / "jg", aspect ratio about 1.6:1. Match a premium editorial technical print aesthetic: warm ivory paper, near-black ink, vermilion highlights, muted blue file cards, thin clean connectors, ample whitespace, crisp highly readable typography. Top left small brand "jevgrep". Top main text exactly "40% lower coding-agent cost". Below it smaller exact text "One 10-task SWE-bench repeat". Middle: a clear left-to-right three-step illustrated flow with exact labels "Ask a repo question" then "Jev finds relevant code" then "Agent implements + tests". Use a speech card, branching folder/file tree highlighting qualifying files, then a compact source/code card and checkmark. Below flow a simple text comparison (not a misleading chart): "Baseline $7.62" then "With jg $4.52". Directly below, prominent readable disclosure: "Task solves: 8/10 baseline → 7/10 with jg". Bottom two lines readable, not tiny: "Full Sol task cost, including failed tasks. Jev cost excluded." and "Single repeat on a tuned Python subset. Savings are not guaranteed." Do not claim faster runtime or equal quality. Render all requested text exactly, with clear spacing. Numbers must not be changed. This standalone shareable graphic should explain both what jg does and the scope of its observed cost reduction. No extra logos, no decorative fake text, no gradients, no robot imagery.++### Final explainer edit++Make a small final refinement to this Jevgrep explainer, preserving the entire layout, colors, headline, numbers, solve-rate disclosure, footnotes and all three stage headings exactly. Replace only the question bubble text with "Where is connection pooling configured? I need to add retries." in the same large readable monospaced style. Remove the tiny stray dark speck at the lower-left inside that bubble. In the right-hand example code card, simplify the body to just three large legible monospaced lines: "create_engine(", " pool_size=10,", ")" with the middle line highlighted pale green; preserve its src/db/connection.py header. Increase readability of the central tree's filename labels modestly if possible without overlap. No changes to the benchmark claims or other text.++## Visual review++Final semantic correction prompt: Edit ONLY the text inside the left speech bubble in this image. Replace it with exactly "Where is pooling configured? I need a pool of 10 connections." Keep the font large, monospaced and readable, wrapped naturally within the existing bubble. Remove the stray speck inside the bottom-left of the bubble. Preserve EVERY other pixel as closely as possible: all headings, diagrams, code showing pool_size=10, numbers, benchmark disclosures, colors and layout must remain unchanged.++An independent visual pass checked typography, layout, and benchmark disclosure.+The final edits simplified the example code for readability and matched the+requested pool size to the illustrated implementation. Fine file labels remain secondary at README+width; open the image for detail. The cover is an abstract discovery illustration,+not a literal filesystem. A tiny mark inside the speech bubble is cosmetic.diff --git a/assets/cover.png b/assets/cover.pngnew file mode 100644index 0000000..c0548aeBinary files /dev/null and b/assets/cover.png differdiff --git a/assets/how-it-works.png b/assets/how-it-works.pngnew file mode 100644index 0000000..261da2eBinary files /dev/null and b/assets/how-it-works.png differ