jev-in-codex

Use Jev to rank capabilities and evidence inside an existing Codex workflow. A local MCP server exposes three tools; a companion skill explains when to use them.

Status: experimental MVP. Functional protocol and boundary tests are included. Ranking quality and time/token savings have not been benchmarked. This is an independent integration, not an official OpenAI or TypeSafe product.

What it does

Codex supplies the objective and makes the final decision. The server retrieves bounded candidates locally, asks Jev relevance questions, and returns original evidence. It neither executes selected capabilities nor intercepts arbitrary Codex tool calls. It does not replace Codex compaction or expose Codex's internal context/tool catalog.

Codex → MCP tool → local candidates → Jev relevance evaluation
                 ← ranked original evidence + coverage ←

The first triage version ranks passages and groups identical chunks. Semantic failure grouping and root-cause classification are future work.

Related MCP server: jev-mcp

Demo

Animated replay of actual MCP results using synthetic data and simulated TypeSafe responses. Playback is paced for readability; this is not a live Codex UI capture or a latency benchmark. Static preview.

Install

Give this prompt to your Codex session, opened in the project you want to use:

Install https://github.com/teempai/jev-in-codex for the current project using
its docs/INSTALL.md. Set up dependencies, the local Codex plugin, MCP connection,
and bundled skill. Add its docs/AGENTS.jev.md guidance to my project's persistent
Codex instructions so you know when and how to use Jev for tool/skill selection,
context search, and output triage. Preserve existing instructions and configuration.
Configure TypeSafe authentication privately and verify all three tools, reporting
whether Jev or local fallback is active. Complete the setup and tell me if you
need a private API-key entry or a Codex restart.

Jev uses a TypeSafe API key and sends selected code/log excerpts to TypeSafe. Codex handles setup; you may need to enter the key privately or restart Codex.

Install from source

Requires Node.js 22+, npm, and ripgrep (rg) on PATH.

git clone https://github.com/teempai/jev-in-codex.git
cd jev-in-codex
npm ci --ignore-scripts
npm run check

There is no published npm package yet. private: true prevents accidental npm publication; the source is publicly available under MIT.

Configure Codex MCP

Add an entry to your Codex config.toml, substituting both absolute paths:

[mcp_servers.jev]
command = "node"
args = ["/absolute/path/to/jev-in-codex/dist/index.js", "--root", "/absolute/path/to/your-project"]
env_vars = ["TYPESAFE_API_KEY", "JEV_MODEL"]
tool_timeout_sec = 90

Export TYPESAFE_API_KEY in the environment that launches Codex. Obtain the key from TypeSafe; don't put it in source control or a prompt. Optionally set JEV_MODEL to a pinned model name; the default is jev-latest.

The root is mandatory, so the server cannot silently scan an unintended working directory. Change --root for another project, or omit it and set JEV_WORKSPACE_ROOT and include that name in env_vars. An explicit --root takes precedence. Use an absolute Node executable path if your Codex launch environment cannot find node.

Without a TypeSafe key, all tools work in local fallback mode. This supports setup checks but does not demonstrate Jev's ranking quality. Normal Codex access and billing are unchanged. Jev requests use a separate TypeSafe API account; this integration does not route them through a Codex subscription.

See the Codex MCP documentation for configuration and server visibility in your client.

Add the companion skill

Copy skills/jev-assist into your coding project's .agents/skills/ directory (or your personal skills directory), then start a new Codex session. For example, from this repository:

mkdir -p /absolute/path/to/your-project/.agents/skills
cp -R skills/jev-assist /absolute/path/to/your-project/.agents/skills/

Review an existing skill directory before replacing it. The skill uses Jev only when selection or filtering is useful; simple exact searches stay with rg.

Optional plugin packaging

The repository includes a legacy-compatible .codex-plugin/plugin.json and .mcp.json bundling the same skill and MCP server. For local plugin development, run npm link after building so jev-in-codex is on PATH. Set JEV_WORKSPACE_ROOT to the coding project and export TYPESAFE_API_KEY in the Codex launch environment. The manifest forwards these variables to the server.

You can then add the clone to your own Codex plugin marketplace using the plugin authoring workflow. The direct MCP configuration above is the tested transport path. Plugin UI installation is not yet end-to-end verified, and a plugin install does not install Node, dependencies, or ripgrep. Choose one installation path to avoid duplicate tools/skills. This repository is not listed in the public plugin directory and does not modify your Codex configuration automatically.

Examples

Ask Codex: “Use Jev to select between these available capabilities for tracing why requests time out.” The MCP call can look like:

{
  "objective": "Trace the source of request timeouts",
  "candidates": [
    { "id": "read_logs", "kind": "tool", "description": "Read recent request logs with timestamps and errors" },
    { "id": "design_assets", "kind": "skill", "description": "Create visual assets for the interface" }
  ],
  "limit": 2
}

The caller must supply real available IDs and descriptions. The server cannot see Codex's complete tool or skill catalog automatically.

Search for implementation context:

{
  "question": "Where is retry backoff implemented for outgoing requests?",
  "scope": ["src"],
  "query_terms": ["retry", "backoff", "timeout"],
  "limit": 5
}

Triage output already saved inside the workspace:

{
  "question": "Which failures explain why the database integration tests failed?",
  "artifact_path": "test-output.txt",
  "limit": 4
}

For example, in Bash, capture a command's output without losing its status:

set -o pipefail
npm test 2>&1 | tee test-output.txt

The triage tool reads the artifact; it does not run the command. Use start_line and end_line to select a relevant range. Outputs preserve source locations so Codex can inspect surrounding evidence before acting.

Behavior and limits

• Ranking: independent Jev noul relevance questions, batched four candidates per request. Up to 24 candidates per operation, eight-second timeout per request, 28,000-byte request cap, no automatic retries. Capability recommendations require a Jev score of at least 0.5; this is a provisional heuristic, not calibrated.

• Fallback: absent key, provider errors, invalid answers, or a failed batch cause the entire ranking to use lexical overlap. method, score_kind, fallback_reason, and api_requests make this visible. Local scores are not model probabilities. Successful responses identify the provider's model when returned. Scores are advisory in both modes.

• Search: ripgrep file discovery respects ignore rules, then local lexical matching builds a shortlist of at most 24 excerpts. At most 500 eligible files and approximately 20 MiB are scanned per call (the final file may cross the byte threshold). Search is not a semantic index. Coverage reports unread, skipped, matched, and shortlisted data. Broaden query terms or narrow scope when recall is insufficient.

• Artifacts: regular UTF-8 text files up to 1 MiB; null bytes are rejected. Excerpts preserve complete lines, with at most 30 lines and 4,000 bytes each. Oversized lines are rejected during triage; such files are skipped in search. There is no chunk overlap, so read surrounding lines when evidence crosses boundaries. Line range selection happens after the 1 MiB file check.

• Triage: all chunks in the requested range are grouped by exact text. When more than 24 distinct chunks remain, lexical matching selects the shortlist. Counts disclose unexamined chunks. At most 20 occurrence locations per group are returned, alongside the full count and omitted-location count. Identical excerpts are not proof that two failures share a cause; unchanged originals remain on disk.

• Returned context: at most ten excerpts or capabilities per response. A truncated shortlist never establishes that omitted evidence is irrelevant.

• Scope: relative paths only; resolved paths must stay within the configured root. Common dependency/build directories and credential filenames are excluded. Explicit artifact reads may access gitignored files, while search respects ignore rules. Configure a narrow project root, not your home directory.

Data handling

With TYPESAFE_API_KEY configured, objectives, supplied capability descriptions, and shortlisted source/log excerpts are sent over HTTPS to https://api.typesafe.ai/v1/systemone. Search initially reads files locally; only its shortlist is sent. Triage reads and groups the requested range locally before sending its shortlist. No remote endpoint override is provided.

Filename exclusions are best-effort and do not detect secrets inside ordinary files. Only use the integration with content approved for TypeSafe. Retrieved content can contain prompt injection; ranking cannot establish that it is safe to execute. This server is a local convenience boundary, not a sandbox against concurrent malicious filesystem modification. It has no telemetry, persistent cache, or content logging of its own. TypeSafe's handling of API data is governed by its own service terms. Provider error bodies are not exposed in tool results.

Security review

The 2026-09-19 static security review found no confirmed reportable vulnerabilities in the initial implementation. The report records the reviewed commit, trust assumptions, hardening opportunities, and exclusions. It is not a security guarantee or a live dependency advisory scan.

Contributing

See CONTRIBUTING.md for development, local testing, and benchmarking guidance.

License and credits

MIT. This small integration uses a permissive license to make adoption and reuse straightforward. Apache-2.0 would add an explicit contributor patent grant and additional notice requirements; it is a reasonable alternative for a larger patent-sensitive project. See the MIT text and Apache-2.0 text.

Inspired by fast-jev-compaction and the TypeSafe Jev approach to bounded decisions. This repository implements its own integration; it does not include that project's compactor code.

References: TypeSafe API, MCP TypeScript SDK, Codex MCP.