Jev Reflex

Small decisions. More room to think.

A portable decision sidecar for coding agents. Give Jev the bounded judgments around a task while your main model keeps the plan, the reasoning, and the tools.

New in 0.6: practical agent workflows. Progress monitoring, two-stage skill selection, worker-report triage, patch review, handoff checks, memory-conflict advice and conditional candidate decisions. Includes explicit host-event adapters, recoverable local source artifacts and offline calibration audits. See workflow schemas and integration limits.

Stateful reflex controllers. Keep an investigation direction or semantic signal across changing evidence, damp rapid switching, preserve explicit corrections and reject late results. Controllers read recorded Jev answers; updating them makes no model call. Available through MCP, JSON CLI, Python and the pi bridge. Try jev-reflex controller-demo for an offline walkthrough. See the controller contract and examples.

Works through stdio MCP, a JSON CLI, and a Python API. Includes a native pi extension and setup guides for Claude Code, Codex, OpenCode, and custom function-calling agents, including applications using DeepSeek.

Independent open-source project by Eternities. Not an official TypeSafe product. MIT licensed.

What you get

Seven versioned recipes, plus raw Choice and Noul batches. Uncertainty is a first-class result. Score is intentionally not exposed in this release.

Related MCP server: pi-delegate-mcp

Why another Jev integration?

Plenty of projects expose Jev as a tool. Reflex concentrates on what happens around the decision:

• Shared context, many questions. Send one state packet once. Defaults allow up to 256 independent questions per request, constrained by size rather than an eight-question ceiling.

• Bulk jobs up to 10,000 items. Automatic packing, bounded concurrency, durable progress, cancellation, and paginated results. Raw items, shared-state questions and recipes use the same accounting.

• Durable accounting before dispatch. Multiple local processes share a SQLite ledger and atomically reserve against host limits.

• Duplicate-call protection. Replaying an operation ID never starts it again. Changed inputs under the same ID refuse.

• Exact successful-result reuse. Opt in per recipe; source, input, recipe, provider/model and thresholds must match. Each reuse has a new receipt pointing to its origin.

• Source-bound context plans. Hashes the exact supplied text, pointers and goal. Required evidence stays visible even if Jev calls it irrelevant. No file scanning or automatic compaction.

• Inspectable evidence. Full bounded distributions, model/route, elapsed time, known token usage, reported versus conservatively reserved cost, and caller-reported downstream outcomes.

• No silent retries or provider fallback. Uncertain attempts remain visible and accounted.

• Offline shadow evaluation. Per-route confusion matrices, precision/recall, abstentions and confidence bins. Measure correctness separately from valid output and speed.

This is an engineering contract, not a promise of universal speed or accuracy gains. The evaluation guide explains how to measure the whole workflow.

Try it without a key

Python 3.11+. Clone the repository and install into an isolated environment:

git clone https://github.com/xnuonux/jev-reflex.git
cd jev-reflex
python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell instead: .\.venv\Scripts\Activate.ps1
python -m pip install ".[mcp]"
jev-reflex demo

The demo uses a fake provider and a temporary ledger. It demonstrates one dispatch, an exact replay, successful-result reuse, and mandatory context retention. It makes zero network calls and does not configure your account.

For a standalone executable on your PATH, install with pipx install ".[mcp]" from the clone. The CLI and Python API also work with pip install . without MCP dependencies. No PyPI or npm package is claimed by this repository; install from this source or its GitHub release.

Enable your provider

Choose one route. No automatic fallback.

Set your credential privately in the environment of the process that launches Reflex. Never paste it into an agent conversation or commit it in config. Client environment inheritance varies; see agent setup.

Create an explicit local budget:

jev-reflex init --daily-usd 2 --enable
jev-reflex doctor

init refuses to overwrite a policy or coexist with a preexisting quota override. The default is disabled. State lives at ~/.local/share/jev-reflex-public/; set JEV_REFLEX_HOME before launch to choose another host-owned directory. Agents sharing that directory share accounting. This public default is separate from the original personal plugin.

Each provider call reserves $0.02 locally. This is a conservative envelope, not the price of a call. OpenRouter's validated reported cost can settle it downward. Direct TypeSafe retains the envelope because the API does not report USD cost. A local cap is not a provider billing cap; price changes, host changes or restoring old ledgers can invalidate assumptions. Accounting details.

Plug it into an agent

Once jev-reflex is on the host's PATH:

# Claude Code
claude mcp add --transport stdio jev-reflex -- jev-reflex serve

# Codex
codex mcp add jev-reflex -- jev-reflex serve

# Print configuration for another client without editing any files
jev-reflex config mcp

If using a virtual environment without activating it in the client, use the absolute path to that environment's jev-reflex executable. Copy the agent skill into your host's supported skill location, or ask the agent to read it. It explains when a reflex is useful and when direct reasoning is cheaper.

pi: load adapters/pi/jev-reflex.ts with pi --extension ./adapters/pi/jev-reflex.ts. The extension invokes the CLI without a shell, forwards cancellation, and does not install dependencies or intercept unrelated tools.

DeepSeek and other tool-capable models: the surrounding application runs the tool. Use jev_reflex.api.invoke or the JSON CLI; a model API itself is not an MCP host. See function-calling example.

See compatibility and verification for tested boundaries. An MCP round trip does not prove every named host's complete workflow.

One useful call

Send only selected, authorized text. On Windows PowerShell use Get-Content -Raw examples/context.json | jev-reflex call context.

jev-reflex call context < examples/context.json

{
  "project": "widget",
  "task": "fix-build",
  "request_id": "context-001",
  "privacy_namespace": "widget-selected-source",
  "goal": "Find the cause of the failing build",
  "chunks": [
    {
      "id": "failure",
      "text": "Type error: string is not assignable to number.",
      "source_ref": "build-output:lines-10-12",
      "mandatory_pinned": true
    }
  ]
}

The context tool generates the snapshot from the actual supplied packet. It returns a receipt and a visibility plan with source hashes and pointers, not rewritten source or an automatic context mutation. The caller keeps the originals and checks they are still current. Pointer values remain local; selected text and the goal reach the provider.

Tool surface

The 18-tool interface was tested from an installed wheel. See the v0.6 verification report for live workflow results, including abstentions and the limits of that small diagnostic.

Recipe schemas · Security and data handling · Evaluation · Research and related work · Verification

Shared state and bulk work

jev-reflex call shared < examples/shared.json
jev-reflex shadow-report < examples/shadow.json

Use shared when several questions inspect the same document: context appears once in the request, rather than repeated inside each item. Questions evaluate independently. Speculative questions can share a call if the host can discard irrelevant answers; an answer-dependent question needs a later step with explicit updated state.

For a large job, pass raw items, shared questions, or one recipe's items to bulk. It validates every item before inference, partitions by host capacity, then advances the job during a bounded foreground run. Inspect next_step: continue-same-input requires resubmitting the identical job later; paid children are never retried. No background worker is installed. Inspect results in pages without sending source text again. Schemas, lifecycle and examples.

Host-owned capacity.json configures count/concurrency/rate limits. Defaults: 256 questions per request, four concurrent calls, 60,000 request bytes and 30,000 bytes for state plus the longest question. These byte guards are conservative packing heuristics, not exact token counts or a promise of provider acceptance. Count alone never overrides size, disclosure, daily spending or provider limits.

Development

python -m unittest discover -s tests -v
node --test adapters/pi/bridge.test.mjs
python -m build

The test suite uses fake providers, real SQLite concurrency, real subprocesses, and an MCP client/server exchange. CI is configured for Windows, Linux and macOS. Read the current verification record for what has actually completed.

A subsequent live TypeSafe corpus stress test submitted 452 typed questions in 25 requests, up to 64 questions per request. The report preserves abstentions, an invalid provider response, independent review disagreements and the distinction between tariff estimates and bills.

Your host owns actions. Reflex helps decide where to spend attention.