Jev agent tools

jev-agent-tools

Six evidence-oriented tools for pi, omp and any MCP client, compatible with the Jev API format. Use them to navigate unfamiliar code, ask typed questions about repository evidence, review completed changes and select existing tests. They complement reading, searching and execution; they do not replace them.

Watch the launch video (74 s, MP4).

New here? Start with the getting-started guide; the documentation index maps every audience to its docs.

Install

Install through your host's package manager, or register the MCP server with an MCP client. The npm package is jev-agent-tools. pi and omp load its TypeScript sources directly; the MCP server ships prebuilt.

pi

pi install npm:jev-agent-tools@0.4.0

Project-local installation:

pi install -l npm:jev-agent-tools@0.4.0

omp

omp plugin install jev-agent-tools@0.4.0

Any MCP client

Since version 0.2.0, the package also ships jev-agent-tools-mcp, a stdio MCP server that exposes the same six tools to any MCP client: Claude Code, Claude Desktop, Kiro, Cursor, VS Code, Codex CLI and others. A typical mcpServers entry:

{

"mcpServers": { "jev": { "command": "npx", "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "/path/to/repository"], "env": { "JEV_TOOLS_URL": "${JEV_TOOLS_URL}", "JEV_TOOLS_API_KEY": "${JEV_TOOLS_API_KEY}" } } } }

On Windows most clients start commands without a shell, so use "command": "cmd" with "/c", "npx" at the start of args. The MCP setup guide has per-client files, CLI commands, variable interpolation, verification and troubleshooting. Releases are also listed in the official MCP Registry as io.github.NomenAK/jev-agent-tools. Add the agent instructions to CLAUDE.md, AGENTS.md or a Kiro steering file so the agent uses and reads the tools correctly.

The server reads the same environment variables as pi and omp and the configuration saved by /jev-setup. One server process is one session. MCP has no automatic run-end documentation hook; its absence does not require manual replacement calls. jev_ask is marked as not read-only while commands are enabled; set JEV_TOOLS_ALLOW_COMMAND=0 to remove command from its schema.

Requirements and compatibility

Requires Node.js 24 or later. Supported host baselines are pi 0.87.1 and omp 18.4.10. These are support baselines, not claims that every later version has been individually validated. omp uses its Bun runtime; Node.js is also required for Node-based project checks. Git and, for optional command evidence, Bash must be available. On Windows, command evidence uses Git for Windows bash (found next to git on PATH or under Program Files); the WSL bash.exe launchers are never used. Set JEV_TOOLS_BASH to the full path of another bash. Optional native parsers and file-search acceleration may be unavailable on some platforms; affected tools report their limitations.

The published jev-agent-tools@0.1.3 package was also checked with pi 1.0.0 on Linux under Node.js 24.15.0: npm installation, TypeScript checking against the host types, all six tools in the actual CLI, and reading-guide injection passed. The CLI smoke used a simulated conversation provider and Jev endpoint; it verifies host integration, not live model accuracy or every tool scenario.

pi 1.0.0 packaging warning: the package declares @sinclair/typebox in dependencies, while pi expects host-provided extension modules in peerDependencies with a "*" range. pi warns that separately installed copies can create duplicate runtime modules. The warning did not prevent the smoke from completing; it remains a packaging issue, not a claim of warning-free compatibility.

Configure

Interactive setup

In the main interactive terminal of pi or omp, a first launch without configuration offers Configure now / Later. Run /jev-setup at any time to change the endpoint, model or key. The key is typed in a masked field and is never passed as a command-line argument. Choose This session only (nothing is written) or Save for future sessions. Cancelling at any step changes nothing.

No dialog appears in print, JSON or RPC modes, or in sub-agents; configure those with the environment variables below. Changes apply immediately, without restarting the host.

Interactive setup waits for submission or cancellation, without a credential-entry timeout. The first-launch offer does not keep the host's startup event handler open while you find the endpoint or key.

Precedence per field: environment variable, then launch flag, then this session's setup, then saved configuration, then the default model openjev. A field set by the environment or a flag is shown as controlled and is never saved.

Saved configuration lives outside the repository at $XDG_CONFIG_HOME/jev-agent-tools/config.json (default ~/.config/jev-agent-tools/config.json), in a private directory (0700) with a private file (0600). On Windows, where mode bits do not exist, privacy is the folder's access list: saving restricts it to you, SYSTEM and Administrators, and loading refuses any other account with access. The key is stored in plaintext, not encrypted. Storage that is a symlink, accessible to other users, not owned by you or malformed is refused rather than overwritten. The MCP server also reads this file, after environment variables.

Environment variables

Set these before starting the host, using your own endpoint and credentials:

export JEV_TOOLS_URL="${YOUR_JEV_ENDPOINT}"

export JEV_TOOLS_API_KEY="${YOUR_JEV_API_KEY}"

Optional; already the default:

export JEV_TOOLS_MODEL="openjev"

YOUR_* placeholders are inputs you supply, not additional product settings. Environment variables are read when the extension loads and take precedence over everything else.

Without the endpoint or key, tools remain registered and explain the missing configuration; the automatic documentation check is disabled. There is no fallback to a chat model. Per-tool max_calls is separate from session limits. A model name echoed by the response does not establish which model was actually served.

Choose a tool

Use native read/search tools or code for exact source text, known symbols, filenames, line numbers, counts and arithmetic. Run commands yourself when you need their full output. Tool reference examples use fictional repository paths and are illustrative calls, not recorded executions.

Evidence root

All six tools accept optional root: string. Without it, the host's current directory or configured MCP server directory retains its existing behavior. An override must name exactly the initial repository's Git top-level or a registered live worktree with the same canonical Git common directory. Relative overrides resolve against the initial directory; absolute paths are accepted only for this parameter. Subdirectories, other clones/repositories, parent traversal and symlink components are refused before evidence collection, command execution, cache access or judgment. There is no fallback to a different checkout.

The admitted root governs files, base/diff, inventories, specification paths, runner plans and command cwd for that call only. It does not change another call or the automatic documentation hook. File arguments remain repository-relative and confined. A command still has ordinary shell permissions, not a sandbox. Check the reported authority, requested/effective root and resolved base before using a result.

Read the results

Each result begins with execution state: complete, partial, not_judged or refused. This describes processing, not correctness, safety or coverage. Items distinguish fresh or cached Jev judgments, static treatment and work never judged. Static selection and conservative fallback carry no invented probability. A judged line without an uncertainty mark is a verdict: a lead to check, not proof beyond the supplied evidence.

Ordinary boolean verdict bands are at or below 0.20 and at or above 0.80; category/level verdicts require a leading-option probability of at least 0.85 after applicable controls. Fixed checks and navigation tools have their own thresholds, described in their references and design.

Accounting separates HTTP attempts, questions sent, requested results (fresh/cache/static/not judged), cache probes, auxiliary controls and passage selection, current reported USD cost and elapsed time. These