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
feat: install the Jevgrep skill through npx skills
David Zhang046158d29dc0
diff --git a/README.md b/README.mdindex 75311f5..1373356 100644--- a/README.md+++ b/README.md@@ -18,15 +18,17 @@ folders, files, and declarations. Your coding agent then implements and tests th```shnpm install -g @dzhng/jevgrepjg auth+npx skills add dzhng/jevgrep --skill jevgrep --agent codex --agent claude-codejg "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 agent skill — required for agent setup-Install the CLI above, then add the skill to the project where your agent works:+Installing the CLI alone does not teach your coding agent to use it. **Install+the skill as well**, from the project where your agent works:```shnpx skills add dzhng/jevgrep --skill jevgrep --agent codex --agent claude-code@@ -35,10 +37,34 @@ npx skills add dzhng/jevgrep --skill jevgrep --agent codex --agent claude-codeSelect 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 usereturned 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.+retrieval when the needed context is already known. The current repository skill+checks for `jg` and installs the CLI if it is missing; authentication still needs+your Gateway key. The skill installer itself does not configure credentials.++The next CLI release also provides a shortcut to the same installer:++```sh+jg skill # interactive agent selection+jg skill --agent codex --global # install for Codex across projects+```++`jg skill` delegates to `npx skills add dzhng/jevgrep --skill jevgrep` and needs+npm/npx plus network access. Add `--yes` for unattended installation. Published+0.1.0 still prints the bundled skill; use `npx skills` directly with that version.++### Upgrade++There is currently no `jg upgrade` command. Upgrade the CLI with npm:++```sh+npm install -g @dzhng/jevgrep@latest+jg --version+```-For manual skill export and authentication options, see the [package guide](apps/cli/README.md).+Update the installed skill separately by rerunning the `npx skills add` command+above. Updating the npm package does not+overwrite skill files in your projects. See the [package guide](apps/cli/README.md)+for authentication details.## Start with a question, leave with sourcediff --git a/apps/cli/README.md b/apps/cli/README.mdindex d594779..8c5f1dc 100644--- a/apps/cli/README.md+++ b/apps/cli/README.md@@ -26,6 +26,8 @@ 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:```sh@@ -35,19 +37,23 @@ npx skills add dzhng/jevgrep --skill jevgrep --agent codex --agent claude-codeSelect only the agent you use, or add `--global` for user-wide installation. Theseoptions come from the [skills CLI](https://github.com/vercel-labs/skills#install-a-skill).Installing the skill does not install the `jg` executable or configure its key.+The current repository skill installs a missing CLI when the agent first uses it;+published 0.1.0's bundled skill predates that setup step. Use the repository skill+installer above for the latest instructions.-You can also export the exact skill bundled with your installed `jg` into your-chosen agent skill directory. For example, set `skill_root` to that directory:+The next release's `jg skill` is a shortcut to that same installer. It supports+`--agent NAME` (repeatable), `--global`, and `--yes`; without options, the installer+prompts for settings. It requires npm/npx and network access. Published 0.1.0's+`jg skill` still prints text, so use `npx skills` directly with that version.-```sh-skill_root=/absolute/path/to/your/agent/skills-mkdir -p "$skill_root/jevgrep"-jg skill > "$skill_root/jevgrep/SKILL.md"-```--Jevgrep never edits agent configuration automatically. The skill directs the agent+Search does not install skills or edit agent configuration. Only an explicit+skill installation command invokes the installer. The skill directs the agentto read returned excerpts before further discovery, skip redundant searches whenthe 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 your `npx skills add` command to update+the agent's copy too.+See the [repository](https://github.com/dzhng/jevgrep) for architecture, officialbenchmark evidence and development. Jevgrep is MIT licensed.diff --git a/apps/cli/src/args.ts b/apps/cli/src/args.tsindex 6180e45..1debff3 100644--- a/apps/cli/src/args.ts+++ b/apps/cli/src/args.ts@@ -4,7 +4,8 @@ import { CliError } from "./errors";import { DEFAULT_MAX_SOURCE_BYTES } from "./render";export type Command =- | { kind: "help" | "version" | "doctor" | "skill" | "cache-clear" }+ | { kind: "help" | "version" | "doctor" | "cache-clear" }+ | { kind: "skill"; agents: string[]; global: boolean; yes: boolean }| { kind: "auth"; fromStdin: boolean }| {kind: "search";@@ -26,6 +27,9 @@ export function parseCommand(args: string[]): Command {help: { type: "boolean", short: "h" },version: { type: "boolean" },stdin: { type: "boolean" },+ agent: { type: "string", multiple: true },+ global: { type: "boolean" },+ yes: { type: "boolean" },"no-cache": { type: "boolean" },"max-source-bytes": { type: "string" },hidden: { type: "boolean" },@@ -49,7 +53,17 @@ export function parseCommand(args: string[]): Command {throw new CliError("Usage: jg auth [--stdin]");return { kind: "auth", fromStdin: values.stdin ?? false };}- if (first === "doctor" || first === "skill") {+ if (first === "skill") {+ const agents = values.agent ?? [];+ if (+ positionals.length !== 1 ||+ keys.some((key) => !["agent", "global", "yes"].includes(key)) ||+ agents.some((agent) => !/^[a-z][a-z0-9-]*$/.test(agent))+ )+ throw new CliError("Usage: jg skill [--agent NAME] [--global] [--yes]");+ return { kind: "skill", agents, global: values.global ?? false, yes: values.yes ?? false };+ }+ if (first === "doctor") {if (positionals.length !== 1 || keys.length)throw new CliError("This command takes no arguments.");return { kind: first };@@ -59,7 +73,12 @@ export function parseCommand(args: string[]): Command {throw new CliError("Usage: jg cache clear");return { kind: "cache-clear" };}- if (!first?.trim() || positionals.length > 2 || values.stdin)+ if (+ !first?.trim() ||+ positionals.length > 2 ||+ values.stdin ||+ keys.some((key) => ["agent", "global", "yes"].includes(key))+ )throw new CliError('Usage: jg "question" [root]. Run jg --help.');const rawBudget = values["max-source-bytes"];const maxSourceBytes = rawBudget === undefined ? DEFAULT_MAX_SOURCE_BYTES : Number(rawBudget);@@ -92,10 +111,18 @@ Root defaults to the current directory; use -- before a root beginning with -.Commands:auth [--stdin] Save a Gateway key (hidden prompt, or an explicit pipe)doctor Verify Jev access using a synthetic question- skill Print the bundled agent skill+ skill Install the agent skill via npx skills--help, -h Show usage--version Show the installed version+Skill installation options:+ --agent NAME Target an agent (repeat for multiple agents)+ --global Install for the current user instead of this project+ --yes Skip installer confirmation prompts++Skill installation requires npm/npx and network access. Without options,+the skills installer prompts for agents and installation settings.+Search options:--max-source-bytes N Source allocation; 0 means unlimited (default: ${DEFAULT_MAX_SOURCE_BYTES})--hidden Include hidden pathsdiff --git a/apps/cli/src/index.ts b/apps/cli/src/index.tsindex 017d6ed..9657c90 100644--- a/apps/cli/src/index.ts+++ b/apps/cli/src/index.ts@@ -6,7 +6,7 @@ import { renderResult } from "./render";import { homedir } from "node:os";import { join } from "node:path";import { version } from "../package.json";-import skill from "../../../skills/jevgrep/SKILL.md" with { type: "text" };+import { installSkill } from "./skill";globalThis.AI_SDK_LOG_WARNINGS = false;@@ -43,7 +43,8 @@ async function main() {case "version":return write(`${version}\n`);case "skill":- return write(skill);+ process.exitCode = await installSkill(command, controller.signal);+ return;case "auth":return authenticate(command.fromStdin, controller.signal);case "cache-clear": {diff --git a/apps/cli/src/skill.ts b/apps/cli/src/skill.tsnew file mode 100644index 0000000..d970ce0--- /dev/null+++ b/apps/cli/src/skill.ts@@ -0,0 +1,32 @@+import { spawn } from "node:child_process";+import type { Command } from "./args";+import { CliError } from "./errors";++export async function installSkill(+ command: Extract<Command, { kind: "skill" }>,+ signal: AbortSignal,+): Promise<number> {+ const args = ["--yes", "skills", "add", "dzhng/jevgrep", "--skill", "jevgrep"];+ for (const agent of command.agents) args.push("--agent", agent);+ if (command.global) args.push("--global");+ if (command.yes) args.push("--yes");+ signal.throwIfAborted();+ return new Promise((resolve, reject) => {+ const child = spawn("npx", args, {+ // Preserve installer prompts while keeping all CLI output on stdout.+ stdio: ["inherit", process.stdout, process.stdout],+ signal,+ killSignal: "SIGINT",+ });+ child.once("error", (error: NodeJS.ErrnoException) =>+ reject(+ error.code === "ENOENT"+ ? new CliError("Skill installation requires npx. Install npm, then run jg skill again.")+ : error,+ ),+ );+ child.once("close", (code, childSignal) =>+ resolve(code ?? (childSignal === "SIGINT" ? 130 : 1)),+ );+ });+}diff --git a/apps/cli/test/commands.test.ts b/apps/cli/test/commands.test.tsindex e3fca31..7618f2a 100644--- a/apps/cli/test/commands.test.ts+++ b/apps/cli/test/commands.test.ts@@ -1,41 +1,27 @@import { expect } from "bun:test";-import { readFile } from "node:fs/promises";import { fileURLToPath } from "node:url";import { version } from "../package.json";import { testInDocker, withCli } from "./cli";-testInDocker(- "built commands expose usage, version, and the canonical skill without authentication",- async () => {- await withCli(async ({ run }) => {- const help = await run(["--help"]);- expect(help).toMatchObject({ code: 0, stderr: "" });- expect(help.stdout).toContain('Usage: jg "question" [root]');- expect(await run(["--version"])).toEqual({ code: 0, stderr: "", stdout: `${version}\n` });- expect(await run(["skill"])).toEqual({- code: 0,- stderr: "",- stdout: await readFile(- new URL("../../../skills/jevgrep/SKILL.md", import.meta.url),- "utf8",- ),- });- const invalid = await run(["--accidentally-pasted-secret"]);- expect(invalid).toMatchObject({ code: 1, stderr: "" });- expect(invalid.stdout).not.toContain("accidentally-pasted-secret");- });- const sourceSkill = Bun.spawn(- ["bun", fileURLToPath(new URL("../src/index.ts", import.meta.url)), "skill"],- {- env: { ...process.env, AI_GATEWAY_API_KEY: "" },- stdout: "pipe",- stderr: "pipe",- },- );- expect(await new Response(sourceSkill.stdout).text()).toBe(- await readFile(new URL("../../../skills/jevgrep/SKILL.md", import.meta.url), "utf8"),- );- expect(await new Response(sourceSkill.stderr).text()).toBe("");- expect(await sourceSkill.exited).toBe(0);- },-);+testInDocker("built commands expose usage and version without authentication", async () => {+ await withCli(async ({ run }) => {+ const help = await run(["--help"]);+ expect(help).toMatchObject({ code: 0, stderr: "" });+ expect(help.stdout).toContain('Usage: jg "question" [root]');+ expect(await run(["--version"])).toEqual({ code: 0, stderr: "", stdout: `${version}\n` });+ const invalid = await run(["--accidentally-pasted-secret"]);+ expect(invalid).toMatchObject({ code: 1, stderr: "" });+ expect(invalid.stdout).not.toContain("accidentally-pasted-secret");+ });+ const sourceHelp = Bun.spawn(+ ["bun", fileURLToPath(new URL("../src/index.ts", import.meta.url)), "--help"],+ {+ env: { ...process.env, AI_GATEWAY_API_KEY: "" },+ stdout: "pipe",+ stderr: "pipe",+ },+ );+ expect(await new Response(sourceHelp.stdout).text()).toContain('Usage: jg "question" [root]');+ expect(await new Response(sourceHelp.stderr).text()).toBe("");+ expect(await sourceHelp.exited).toBe(0);+});diff --git a/apps/cli/test/package.test.ts b/apps/cli/test/package.test.tsindex dda3d5f..49066e5 100644--- a/apps/cli/test/package.test.ts+++ b/apps/cli/test/package.test.ts@@ -62,11 +62,12 @@ testInDocker(const help = await execute(binary, ["--help"], { cwd: scratch, env });expect(help.stderr).toBe("");expect(help.stdout).toContain('Usage: jg "question" [root]');- const skill = await execute(binary, ["skill"], { cwd: scratch, env });- expect(skill.stderr).toBe("");- expect(skill.stdout).toBe(- await readFile(new URL("../../../skills/jevgrep/SKILL.md", import.meta.url), "utf8"),- );+ expect(+ await readFile(+ join(prefix, "node_modules/@dzhng/jevgrep/dist/skills/jevgrep/SKILL.md"),+ "utf8",+ ),+ ).toBe(await readFile(new URL("../../../skills/jevgrep/SKILL.md", import.meta.url), "utf8"));const manifest = JSON.parse(await readFile(join(prefix, "node_modules/@dzhng/jevgrep/package.json"), "utf8"),);diff --git a/scripts/test-installed.sh b/scripts/test-installed.shindex 7eada81..20be0db 100755--- a/scripts/test-installed.sh+++ b/scripts/test-installed.sh@@ -41,6 +41,8 @@ if [[ -n "$package_input" ]]; thencp "$package_input" "$scratch/.package-input/jevgrep.tgz"cp "${JEVGREP_CANONICAL_SKILL:-$repo_root/skills/jevgrep/SKILL.md}" "$scratch/.package-input/canonical-skill.md"cp "$repo_root/test/installed.test.mjs" "$repo_root/test/runtime.Dockerfile" "$scratch/test/"+ mkdir -p "$scratch/test/fixtures"+ cp "$repo_root/test/fixtures/skill-installer.mjs" "$scratch/test/fixtures/"context_dir="$scratch"build_args=(--build-arg PACKAGE_STAGE=prebuilt)fidiff --git a/scripts/test-native.mjs b/scripts/test-native.mjsindex 9323333..37a7122 100644--- a/scripts/test-native.mjs+++ b/scripts/test-native.mjs@@ -130,7 +130,7 @@ try {"--test-reporter=tap","--test-concurrency=1","--test-name-pattern",- "^(installed local commands match the package without credentials|actual installed search parses Python and returns every relevant hierarchy branch)$",+ "^(installed local commands match the package without credentials|skill command delegates installation to npx without Gateway credentials|actual installed search parses Python and returns every relevant hierarchy branch)$",join(root, "test/installed.test.mjs"),],{ cwd: scratch, env: runtimeEnv, timeout: 120_000, maxBuffer: 8_000_000 },@@ -138,8 +138,8 @@ try {assert.equal(tested.stderr, "");assert.match(tested.stdout,- /^# pass 2$/m,- "Both native smoke journeys must execute; renamed selectors cannot silently pass",+ /^# pass 3$/m,+ "All native smoke journeys must execute; renamed selectors cannot silently pass",);console.log(tested.stdout.trimEnd());console.log(diff --git a/skills/jevgrep/SKILL.md b/skills/jevgrep/SKILL.mdindex 71076d1..e663562 100644--- a/skills/jevgrep/SKILL.md+++ b/skills/jevgrep/SKILL.md@@ -5,6 +5,21 @@ description: Find files for unfamiliar repository behavior and regression tests# Jevgrep+## Setup++Before the first search, check whether `jg` is on PATH (`command -v jg`). If it+is missing, check for Node.js 22+ and npm, then run+`npm install --global @dzhng/jevgrep@latest` and verify with `jg --version`.+If prerequisites are missing or installation fails, report the specific blocker+and use ordinary discovery; do not retry indefinitely or use sudo.++If a search reports missing credentials, have the user run `jg auth` in their+terminal or configure `AI_GATEWAY_API_KEY` through their secret manager. Never ask+them to paste a key into chat. Do not launch the interactive auth prompt in a+noninteractive agent shell. Continue with ordinary discovery until configured.++## Research+1. Run `jg "your research question"` through the shell. Describe the symptom,expected behavior, and useful reproduction clues. The CLI prints its file listand source or declaration locations to stdout; it creates no report files.diff --git a/specs/done/jevgrep/contracts.md b/specs/done/jevgrep/contracts.mdindex 684f4f4..38dd18a 100644--- a/specs/done/jevgrep/contracts.md+++ b/specs/done/jevgrep/contracts.md@@ -19,7 +19,7 @@ jg "question" [root] # root defaults to cwdjg auth [--stdin] # hidden interactive input or explicit pipejg doctor # synthetic Gateway connectivity/answer checkjg cache clear # idempotently clear Jevgrep cache-jg skill # print bundled SKILL.md to stdout+jg skill # invoke npx skills for explicit installationjg --helpjg --version```@@ -52,9 +52,18 @@ version/skill/cache-clear require no provider key. Bound auth stdin input.The canonical skill source is `skills/jevgrep/SKILL.md` in this repository,discoverable by the skills CLI installer. Ship that same file with the npm package;-do not maintain a second authored copy. `jg skill` makes installation-possible using ordinary redirection into the user's chosen agent skill directory;-do not silently write agent configuration. Document Codex and Claude installation.+do not maintain a second authored copy. The post-release `jg skill` command+invokes `npx --yes skills add dzhng/jevgrep --skill jevgrep`, forwarding explicit+agent, global and confirmation options. It installs the current repository skill,+not necessarily the packaged snapshot. Preserve the installer exit code and route+both output streams to stdout. Only this explicit command installs agent files;+search never does. npm/npx and network are required for installation, not search.+Published 0.1.0 retains its former print-only behavior. Document Codex and Claude+installation through the skills installer.+The repository skill now checks for a missing executable, installs the published+CLI with npm when prerequisites are available, and directs credential setup to+the user's terminal. This post-release setup addition does not alter the frozen+benchmark skill or its research instructions; 0.1.0's bundled copy remains unchanged.The skill chooses unfamiliar multi-file discovery, awaits the same invocation,reads included excerpts first, treats locations as optional leads, and uses normaltools to resolve remaining holes. It does not force retrieval for obvious knowndiff --git a/test/fixtures/skill-installer.mjs b/test/fixtures/skill-installer.mjsnew file mode 100755index 0000000..993ae06--- /dev/null+++ b/test/fixtures/skill-installer.mjs@@ -0,0 +1,6 @@+#!/usr/bin/env node+import { writeFileSync } from "node:fs";++writeFileSync("installed-skill.json", JSON.stringify(process.argv.slice(2)));+console.error("Installer completed.");+process.exitCode = Number(process.env.JEVGREP_INSTALLER_EXIT ?? 0);diff --git a/test/installed.test.mjs b/test/installed.test.mjsindex b8dab1d..fe58b21 100644--- a/test/installed.test.mjs+++ b/test/installed.test.mjs@@ -359,16 +359,61 @@ test("installed local commands match the package without credentials", async (t)const version = await fixture.run(["--version"], noCredentials);assert.equal(version.code, 0, version.stdout);assert.equal(version.stdout, `${metadata.version}\n`);- const skill = await fixture.run(["skill"], noCredentials);- assert.equal(skill.code, 0, skill.stdout);- assert.equal(skill.stdout, await readFile(expectedSkill, "utf8"));assert.equal(await readFile(join(packageDirectory, "dist/skills/jevgrep/SKILL.md"), "utf8"),- skill.stdout,+ await readFile(expectedSkill, "utf8"),);assert.equal(fixture.requests.length, 0, "Local commands must not contact Gateway");});+test("skill command delegates installation to npx without Gateway credentials", async (t) => {+ const fixture = await context(t);+ const bin = join(fixture.tree, "installer-bin");+ await mkdir(bin);+ await symlink(process.execPath, join(bin, "node"));+ const npx = join(bin, "npx");+ await symlink(new URL("./fixtures/skill-installer.mjs", import.meta.url), npx);+ const result = await fixture.run(+ ["skill", "--agent", "codex", "--agent", "claude-code", "--global", "--yes"],+ { PATH: bin, AI_GATEWAY_API_KEY: "" },+ );+ assert.equal(result.code, 0, result.stdout);+ assert.match(result.stdout, /Installer completed/);+ assert.deepEqual(JSON.parse(await readFile(join(fixture.tree, "installed-skill.json"), "utf8")), [+ "--yes",+ "skills",+ "add",+ "dzhng/jevgrep",+ "--skill",+ "jevgrep",+ "--agent",+ "codex",+ "--agent",+ "claude-code",+ "--global",+ "--yes",+ ]);+ assert.equal(fixture.requests.length, 0);+ const failed = await fixture.run(["skill"], {+ PATH: bin,+ AI_GATEWAY_API_KEY: "",+ JEVGREP_INSTALLER_EXIT: "7",+ });+ assert.equal(failed.code, 7, failed.stdout);+ assert.deepEqual(JSON.parse(await readFile(join(fixture.tree, "installed-skill.json"), "utf8")), [+ "--yes",+ "skills",+ "add",+ "dzhng/jevgrep",+ "--skill",+ "jevgrep",+ ]);+ await rm(npx);+ const unavailable = await fixture.run(["skill"], { PATH: bin, AI_GATEWAY_API_KEY: "" });+ assert.equal(unavailable.code, 1);+ assert.match(unavailable.stdout, /requires npx/);+});+test("actual installed search parses Python and returns every relevant hierarchy branch", async (t) => {const fixture = await context(t);const result = await fixture.run([query, fixture.tree, "--no-cache"]);diff --git a/test/reference/skill.test.ts b/test/reference/skill.test.tsindex 2df2853..5e64299 100644--- a/test/reference/skill.test.ts+++ b/test/reference/skill.test.ts@@ -1,10 +1,17 @@import { test, expect } from "bun:test";import { readFile } from "node:fs/promises";-test("production skill preserves the accepted instructions with only the executable renamed", async () => {+test("production skill preserves accepted research instructions after the installation preflight", async () => {const accepted = await readFile("test/reference/accepted-skill.md", "utf8");const canonical = await readFile("skills/jevgrep/SKILL.md", "utf8");- expect(canonical).toBe(- accepted.replace('Run `jevgrep "your research question"`', 'Run `jg "your research question"`'),+ const [header, research] = accepted.split("# Jevgrep\n\n");+ const sections = canonical.split("## Research\n\n");+ expect(sections).toHaveLength(2);+ expect(sections[0]).toStartWith(`${header}# Jevgrep\n\n## Setup\n\n`);+ expect(sections[1]).toBe(+ research!.replace(+ 'Run `jevgrep "your research question"`',+ 'Run `jg "your research question"`',+ ),);});diff --git a/test/runtime.Dockerfile b/test/runtime.Dockerfileindex 0c6fb60..d60892f 100644--- a/test/runtime.Dockerfile+++ b/test/runtime.Dockerfile@@ -36,6 +36,7 @@ FROM node:22-bookworm-slim AS runtimeCOPY --from=install /opt/jevgrep /opt/jevgrepCOPY --from=package /artifacts/canonical-skill.md /test/canonical-skill.mdCOPY test/installed.test.mjs /test/installed.test.mjs+COPY --chmod=755 test/fixtures/skill-installer.mjs /test/fixtures/skill-installer.mjsENV PATH=/opt/jevgrep/bin:/usr/local/bin:/usr/bin:/bin \JEVGREP_INSTALLED_BINARY=/opt/jevgrep/bin/jg \JEVGREP_INSTALLED_PACKAGE=/opt/jevgrep/lib/node_modules/@dzhng/jevgrep \