Codex Jev MCP server

Codex Jev

Find the evidence. Keep your coding model.

Large repositories and noisy logs can fill a coding session with material it doesn't need. Codex Jev adds a retrieval layer: find candidate evidence locally, optionally rank sanitized excerpts with TypeSafe's Jev, and return bounded, source-addressed evidence with exact follow-up reads.

It does not replace your coding model, proxy inference, rewrite conversation history, or bypass Codex usage limits. Works without a Jev key in local-only mode.

Public beta. Offline safety and packaging tests pass; generalized Codex token, cost and speed savings are not yet established. Evidence-byte reduction is not an account-quota measurement. What is verified.

Why use it?

Capability	What you get
Focused investigations	Query-prioritized code, tests, configuration and log evidence
Progressive disclosure	Concise previews, source hashes, line ranges and exact reads
Recoverable omissions	List retained, omitted and unscored candidates; inspect what was left out
Controlled spending	Local-only by default; explicit paid activation, persistent caps and reservations
Recovery boundaries	Private Git checkpoints, corruption checks and owner-acknowledged resume
Honest measurements	Separate Jev, cache, bypass and fallback statistics; missing usage stays unknown

Best suited to multi-file investigations and large diagnostics. Precise file reads, small edits, patches and test commands should keep using native tools.

Quick start

Requirements: Node 22.13+, Python 3.11+, Git, ripgrep, and a Codex client with stdio MCP support. Recovery hooks additionally require a hook-capable Codex version. The tested deployment is a Linux execution host, including a remote host used from the macOS Codex app. Mac-local execution is unverified.

Run on the host where Codex actually reads your project. Use a permanent install directory outside the project; keep it after installation.

git clone https://github.com/Hyper-AI-Lab/codex-jev.git
cd codex-jev
git checkout v0.4.0-beta.1
npm ci
npm run build
python3 runtime/manage.py install \
  --node "$(command -v node)" \
  --workspace /absolute/path/to/your/git-project \
  --codex-home "${CODEX_HOME:-$HOME/.codex}" \
  --entrypoint dist

The installer preserves your model, reasoning effort, authentication and unrelated settings. It adds an owned MCP entry, concise global guidance and recovery hooks. Existing conflicting configuration is rejected, not overwritten.

Reconnect the execution host or reload your Codex client so it reads the new MCP configuration. Review the generated hooks in the native Hooks UI and authorize them there. Installation is not hook trust. Continue the same task afterward.

Ask Codex:

Check evidence_status. Use search_workspace_evidence to investigate how this
project loads configuration. Show source ranges, recover any relevant omissions,
and distinguish local results from actual Jev selection.

No paid requests occur from this quick start. To enable hosted ranking, follow the explicit key, spending-cap and retention-validation steps in Installation. The adapter is MIT-licensed; the hosted Jev service is separately billed.

Tools

MCP tool	Purpose
search_workspace_evidence	Scoped workspace investigation with bounded candidate selection
read_large_text_evidence	Query-related ranges from an eligible text or log file
list_evidence	Paginate candidate references, including omissions and unscored ranges
read_selected_evidence	Read exact bounded ranges after hash and access revalidation
evidence_status	Loaded build, selection mode, budget, reservations and measurement coverage

Selection currently bounds each request to 20 candidates, eight returned blocks and 48 KiB outbound. Critical overflow is recoverable through pagination and exact reads. Small packets bypass Jev; cache hits avoid a repeated paid call. Not selected does not mean nonexistent.

Safety and privacy

• Workspace authorization, Git exclusions, sensitive-path denial and local redaction apply before sending evidence. Source text remains untrusted data.
• Only bounded sanitized queries, requirements and excerpts go to TypeSafe, with opaque candidate identifiers, not full conversations or credential files.
• One in-flight Jev request, transactional reservations and conservative unknown charges protect shared budgets. Quota responses halt covered operations.
• Recovery verifies state before resuming; it never reapplies patches, repeats deployments or cancels unrelated processes automatically.
• Regex redaction is not perfect. Do not enable hosted ranking for data you cannot permit a third party to process. Provider retention is governed by TypeSafe's policy.

Hooks are partial guards, not a security sandbox or universal interception layer. Already-running commands and hard process failures need explicit reconciliation. See Security and Recovery.

Documentation

Installation and paid opt-in · Architecture · Recovery and rollback · Measurements and limitations · Contributing · Release notes

Development

npm ci
npm run check
python3 -m unittest discover -s runtime -p 'test_*.py' -q
python3 -m compileall -q runtime

The test suite uses synthetic fixtures and mocked providers; no API key, paid Jev call or native Codex inference is required. Packaging tests exercise isolated install, upgrade, rollback and uninstall without accessing real authentication.

Credits

Built by Hyper AI Lab, derived from James Cressler's Jev Codex Token Saver. Upstream MIT copyright is preserved. Full attribution. Independent project; not an official OpenAI or TypeSafe product.

Useful to your team? Share a reproducible, sanitized investigation or contribute a regression test. Correctness and transparent measurements matter more than headline compression percentages.