An alloy spine for your LLM, built with Jev.
Jump to: Examples · Sift / Loop / Long · Connect an agent · TUI · Providers · Docs
JevRev is an LLM + Jev system. Evolution gave animals a spine so they could make many decisions quickly and cheaply. JevRev applies the same split to a workflow: the LLM brings depth and range, while Jev brings very fast, low-cost decisions. Together they make the workflow more efficient.
The tool has three parts: JevSift, JevLoop, and JevLong.
At the start of a task, it lets the LLM spread out like an octopus. Each arm can reach for a different path, and weak or disappointing paths get cut away. That is JevSift. JevLoop audits and scores each round of work, then uses the result to decide what the agent should do next. Jev makes the workflow faster and cheaper, and the final result can be far better. We include concrete cases below. JevLong watches long, multi-round tasks for stalls, repeated failures, drift, tool-call problems, and budget risk.
Jev stays on the sidelines. It makes decisions, filters paths, and raises reminders. The LLM proposes and executes the work. JevRev communicates through a CLI and JSON protocol and leaves the session in the host agent's hands.
Here are a few examples that show what JevRev changes in practice.
Open the case: building TidalCity
The same model, ChatGPT-6-Sol-Ultra, ran the same prompt to build TidalCity, a city simulation that floods with the tide. Here is the benchmark version without Jev's involvement:
It has a few simple buildings, roads, and a basic rising-water simulation. The model is rough, the controls are limited, and the roads and buildings are placed as disconnected pieces without much structure.
Here is the result built with JevRev, including JevSift, JevLoop, and JevLong:
The city is larger and the environment is much more fully built out. It has distinct districts, and almost every building has its own name. You can change the time of day, switch camera views, and use WASD to walk through the city or swim through the water.
Open the case: processing 25,000 JSONL events
The task was to make a pure Node 20 JSONL ingester handle 25,000 production-shaped events while meeting four requirements:
- isolate malformed lines;
- preserve first-seen order;
- emit each duplicate event only once;
- reach at least twice a conservative baseline throughput.
The input was about 2.3 MB, with 184 malformed/schema-invalid lines and 258 duplicate IDs.
What JevSift did:
Six approaches entered the sift. JevSift kept two strict survivors and sent one more to review:
| Approach | Sift score | Result |
|---|---|---|
batch-index |
0.9243 | kept, sent to a real probe |
regex-shortcut |
0.9240 | kept, sent to a real probe |
state-scan |
0.7965 | cut off by the budget |
baseline-parse |
0.6100 | rejected, low execution value |
worker-shards |
0.6043 | review, not treated as approved |
external-index |
0.4931 | rejected, low execution value |
Both survivors ran a correctness check and seven benchmark runs:
| Metric | regex-shortcut |
batch-index |
|---|---|---|
| Correctness | failed, expected 184 / actual 65 | passed |
| Mean throughput (events/s) | 180,530.90 | 180,317.21 |
| Sample standard deviation (n-1) | 8,567.37 | 10,486.05 |
| Decide | rejected | winner |
A one-shot workflow would pick regex. It is fast on paper, but it misses most malformed lines. JevRev chose batch-index because it met the task contract.
What JevLoop did:
- Round 1: throughput passed, correctness failed; returned
fix_regression. - Round 2: fresh correctness and maintenance evidence passed; returned
verify. - Round 3: all criteria and the protected surface were submitted again on the same head; returned
completed.
Final state: completed, round 3, with 838 ms wall-clock time and 1,628 tokens in replay provider accounting.
What JevLong did:
- accepted 13 events on the first import; accepted 0 on the duplicate import and identified 13 duplicates;
- ran
long status, a multi-framelong watch, andlong loop-audit; - ended at sequence 14;
- reported a high-severity
failure_loopalert and a criticalprotocolalert; - The Loop reached
completedwhile Long'sprogress_indexremained 0.
The LLM writes several genuinely different proposal cards. JevSift uses Jev for narrow questions, then deterministic policy handles duplicates and hard-constraint risk and creates probe work orders with budgets and stop conditions for the candidates that remain.
Sift answers one question: which directions deserve your token budget? The host agent still writes the code, runs the tests, and runs the benchmark.
If it is unclear whether a task deserves a Sift round, start with shadow activation:
jevrev activation --input activation.json --format jsonIt compares the expected cost of taking a wrong path with the cost of a few bounded probes and returns stable reason codes. It currently runs in shadow mode: it does not call Jev and does not start or skip Sift for you. See the activation policy for the fields and the follow-up evaluation plan.
The agent moves the work forward each round. JevLoop checks the result, reading the commands, tests, metrics, and artifacts recorded by the recorder. It confirms the facts first, then asks Jev what the result still needs. The next action can be fix, verify, continue, replan, or human, and the loop stops when the goal is actually met.
Loop follows one result. The agent acts, Loop reviews, and Jev decides. It does not take over the session or rubber-stamp a result that merely looks good. Every completion must be backed by replayable evidence.
Long keeps reading the JSONL events written by the agent, records session progress, and detects stalls, repeated failures, drift, tool problems, and budget risk. It reports what happened, whether the session is still moving, and where attention is needed.
jevrev long watch --directory .jevrev/long
jevrev long status --directory .jevrev/long --format jsonJevRev connects to external agents through its CLI and JSON/JSONL contracts. Codex, Claude Code, OpenCode, CI workflows, and custom harnesses can all use the same protocol. Hosts with skill support can load the instructions; other hosts can call the CLI directly.
npm install
npm run build
node scripts/install-skill.mjs --target <codex|claude|agents|dsh>Choose one target for the host you use. OpenCode and other custom hosts can use --destination <host-skill-directory>.
Prompt example:
Use JevRev: complete this task with Sift, execute only selected approaches, record the evidence, run each round through Loop, and connect Long for long-running work.
Run the full example now:
npm run demo:workflowRun jevrev in an interactive terminal to open the cockpit; a Long store is not
required. Sessions lists JevRev component sessions and host sessions registered
from Codex, Claude Code, OpenCode, or another agent:
jevrev session register --host codex --session-id <id> --title "..." --goal "..."
jevrev session listRegistration stores session metadata, not private host transcripts. Select a session to open its Kanban / Monitor page. The Loop and Long switches persist for that session and show whether an observer store is available; they do not start an observer or steer the host agent.
| Page | What it shows |
|---|---|
| Sessions | Registered host sessions and JevRev component sessions |
| Kanban / Monitor | Work, evidence, risks, and the Loop / Long switches |
| Config | Auto-open, refresh interval, and terminal colors |
Use Up / Down to select a session, Enter to open it, and l / o plus Space
to change a monitor switch. Successful component commands can open the cockpit
focused on the updated session. Use jevrev --no-tui ... or JEVREV_NO_TUI=1
to suppress that automatic open. Without an interactive terminal, JevRev keeps
normal human/JSON output and emits no TUI control sequences.
Sift, Decide, and Loop audit use the same provider interface. You can connect to hosted Jev, local SemIf, or a replay file for offline runs. Keep credentials out of command arguments, campaign files, evidence, and source control.
In an interactive terminal, jevrev and provider-related commands show a setup
form when the selected hosted provider has no key. Choose jev, local, or
semif, enter the endpoint and (for Jev) a masked API key, then press Enter to
save. The key is saved as plaintext in your user configuration, not encrypted:
- Windows:
%APPDATA%/jevrev/config.json(falls back to~/AppData/Roaming). - macOS:
~/Library/Application Support/jevrev/config.json. - Linux:
$XDG_CONFIG_HOME/jevrev/config.json(falls back to~/.config).
JEVREV_CONFIG_PATH selects another file. Non-empty environment settings override
saved values; explicit CLI options override endpoint/provider defaults. For an
environment-only or replay workflow, use jevrev --no-tui ... or
JEVREV_NO_TUI=1 to skip the form. Piped commands and --help / --version do
not prompt. Esc closes the form without saving, then the requested command
continues and may fail if it still needs a key. See configuration and reset
instructions; the hosted examples below use environment
variables without saving a key.
macOS / Linux:
export JEVREV_JEV_API_KEY="..."
node dist/cli.js sift \
--input examples/parser-speedup.json \
--provider jev \
--output campaign.jsonWindows PowerShell:
$env:JEVREV_JEV_API_KEY = "..."
node dist/cli.js sift `
--input examples/parser-speedup.json `
--provider jev `
--output campaign.jsonFor a custom Jev API address, set JEVREV_JEV_URL or pass
--jev-url <api-root>. The CLI sends requests to /v1/systemone on that address.
Windows:
powershell -ExecutionPolicy Bypass `
-File scripts/start-semif.ps1 -Background
node dist/cli.js sift `
--input examples/parser-speedup.json `
--provider semif `
--output campaign.jsonSee docs/SEMIF_LOCAL.md for starting, checking, and stopping the local model.
- Project cockpit design
- Workflow
- Activation policy
- Protocol and JSON contracts
- Authority model
- JevLoop design
- JevLong design
- Acceptance record
JevRev is released under the MIT license.