jev-kit

Everything you need to run TypeSafe's Jev with Claude Code:
guard your agent's tool calls, right-size its sub-agents, and wire Jev into search, browsing, review and more.

Quickstart · Browser result · What is in the kit · How it works · Measured results · Safety · FAQ

Jev decides, Claude writes. With Jev choosing each click, the browser agent's Claude bill was 0.0008 USD a run against 0.1868 USD with Sonnet choosing, at the same 9/9 success. The numbers, and how they were taken.

What is Jev, and why a kit

Jev is a TypeSafe System One model. It does not return text. It returns a typed decision with a probability attached: yes or no, a choice, a score. That takes roughly 0.3 s and costs a fraction of a cent, so it fits inside an agent's loop as a judge rather than beside it as another chat.

A kit, because the judge is the easy part. The work is the places it pays off: which tool call to question, which sub-agent rung a task needs, what to redact before sending, and how to fail open when no answer arrives. This repository is that wiring, built and measured.

Quickstart

git clone https://github.com/jonathanavis96/jev-kit.git ~/code/jev-kit
cd ~/code/jev-kit
install/install.sh          # guard + session check + daemon + monitoring
                            # + filesearch + claude-update + belay,
                            # all under $HOME

On native Windows without WSL, that is not the install: the installer is Python, not bash. Follow docs/INSTALL-WINDOWS.md instead.

install.sh never runs sudo, never writes outside $HOME, and never edits a settings.json unless you pass --wire. Without --wire it prints the exact JSON to add and stops. --check-only prints the plan and installs nothing.

The one thing a human supplies is a TYPESAFE_API_KEY. Every component in the kit reads the same one, so it lives at a kit-level path:

mkdir -p ~/.config/jev-kit && chmod 700 ~/.config/jev-kit
touch ~/.config/jev-kit/env && chmod 600 ~/.config/jev-kit/env
$EDITOR ~/.config/jev-kit/env        # one line: TYPESAFE_API_KEY=...

Type it into the file with an editor. Never print it, never paste it into a session, never echo it back to confirm it. Without a key everything still installs and still fails open; only the code-only rules fire.

Prove it works

install/doctor.sh runs a real deny and a real allow through the actual hook process against a throwaway HOME. To see it with your own hands, pipe a fake PreToolUse event at the hook:

printf '%s' '{"session_id":"t","cwd":"/tmp","tool_name":"Bash","tool_input":{"command":"xdg-open https://example.com"}}' \
  | AIRLOCK_MODE=enforce python3 ~/.local/share/airlock/current/hooks/airlock.py

That prints JSON containing "permissionDecision": "deny". An ordinary command prints nothing at all:

printf '%s' '{"session_id":"t","cwd":"/tmp","tool_name":"Bash","tool_input":{"command":"echo hello"}}' \
  | AIRLOCK_MODE=enforce python3 ~/.local/share/airlock/current/hooks/airlock.py

Shadow first, then enforce

The default is shadow: the real rules table runs, the log records what enforce would have done, and nothing is blocked. Read the log for a while, then arm it.

python3 -m airlock.report                 # what shadow mode would have done
echo enforce > ~/.config/airlock/mode     # a deny now blocks
echo shadow  > ~/.config/airlock/mode     # back to log-only

Kill switch, which beats the mode entirely: export AIRLOCK_DISABLE=1 for this shell, or touch ~/.config/airlock/disabled for the machine.

Or tell your agent

Paste this into Claude Code:

"Install jev-kit from https://github.com/jonathanavis96/jev-kit. Follow docs/install.md, run install/install.sh --check-only first and show me the plan, ask me for the TYPESAFE_API_KEY rather than printing one, leave it in shadow mode, and prove a deny works before telling me it is done."

Full detail, flags, config file, WSL, rollback and the agent checklist: docs/install.md.

Jev as the decision-maker: the browser agent

A browser agent is where swapping the decision-maker shows up plainest. Same goals, same browser, same code. Only the model choosing each click changes.

Jev reached every goal Sonnet reached, two to four times faster per decision, for 233 times less Claude spend per run. The bill collapses because the language model is no longer asked to decide each click, only to write text into a field.

Method: 3 goals, 3 arms, 3 repetitions each (27 runs), one machine, one shared headless Chromium, 2026-09-19. Spend is goal 1, read from the CLI's own total_cost_usd. At n=3 a cell is directional, not significant. Full tables: docs/measurements.md.

A session reaches it through one MCP tool, browse, which browse/ serves over stdio. Give it a goal and it returns the final URL, the page text and whatever a CSS selector picked out.

The guard points at that tool. R11-browse-via-jev matches a Playwright MCP browsing call by its tool name and denies it with the one-line usage of browse. The match is code only: Jev is never asked and nothing is scored. Shell commands and Playwright scripts are never looked at, and the Playwright servers stay registered. See docs/rules.md.

What is in the kit

Airlock is the tool-call guard. It is one component of the kit, not the kit.

Exercised means unit tests, a labelled eval, a measured bench and real daily use on at least one machine. Experimental means unit tests and hand-runs only: no labelled corpus, no measured numbers, no sustained use.

Per-component detail, exposure and install flags: docs/components.md. The rules themselves: docs/rules.md.

The guard's steer toward graphify query instead of a raw recursive grep only exists where the search root carries a graph (graphify-out/graph.json). With no graph the branch is inert, which covers most users.

How it works

The hook is registered for every tool. What filters a call is not the matcher but the rules table, and the cheap paths come first: most calls never reach the network, and a call no rule covers costs nothing and logs nothing.

flowchart TD
    A["Tool call, any tool"] --> B{"Code pre-filter, airlock/rules.py"}
    B -->|"no rule could apply"| Z1["Allow. Nothing sent, nothing logged, microseconds"]
    B -->|"a rule might apply"| C["Scope decided in code: what is at stake, what is already known"]
    C --> D{"Can a deny still be reached?"}
    D -->|"no"| Z2["Allow. Jev call skipped. 5 percent sampled so tuning still sees traffic"]
    D -->|"yes"| E["Redact, then ask Jev one typed question. About 0.3 s warm"]
    E --> F{"Confidence at least 0.8 and margin at least 0.4?"}
    F -->|"no"| Z3["Allow, silently"]
    F -->|"yes"| G["Allow, warn, block, or rewrite"]
    E -.->|"error, timeout, budget, or no key"| Z4["Fail open. Allow"]

The tier guard runs the same way on an Agent dispatch. It asks Jev what kind of task this really is, maps that to a rung on your ladder, and acts on the gap:

flowchart LR
    A["scout-find"] --> B["scout"] --> C["workerS"] --> D["workerO"] --> E["claude, Plan, Explore"] --> F["fable"]

The ladder is yours: ~/.config/airlock/tiers.json overrides the built-in one, because agent type names differ per machine. Rewrite mode, which edits the dispatch instead of advising, exists and is off by default for a reason set out in docs/rules.md.

Measured results

Every number below was measured in this repository, on a stated date, by a stated command, on a 4 vCPU cloud VM in Europe (Ubuntu, 8 GB RAM, Python 3.14). Nothing is extrapolated.

Read that last row as a backstop, not a tax. Thirty sessions of ordinary agent work produced nothing worth blocking, because agents already pick the right tool almost every time. The bench shows the guard is cheap and stays out of the way. It does not show that the guard has saved anything yet, and that is why the guard now skips the Jev call when the code-computed facts make a deny unreachable.

Full tables, methods and the known limits: docs/measurements.md.

Safety model

• Fail open, everywhere. Any error, timeout, missing key or unreachable daemon means the tool call is allowed. A broken guard can never block or slow a tool call.
• A time budget. Enforce mode gives a judgement a hard budget; past it, the call runs.
• An override stamp. [airlock-ok: <reason>] in a call's description gets past any deny, with the reason recorded.
• Loop protection. The same call is never denied twice in ten minutes.
• A kill switch that beats the mode. AIRLOCK_DISABLE=1, or ~/.config/airlock/disabled, or echo off > ~/.config/airlock/mode.
• Confidence bars. Where Jev decides, a deny needs confidence of at least 0.8 and a margin of at least 0.4 over the runner-up. Rewrite mode needs 0.9 and 0.5.
• What leaves the machine. Redacted summaries of the ambiguous fraction of tool calls, and nothing else, unless you opt into a component whose row above says otherwise. Never a raw tool result: every string passes through airlock/redact.py first, and truncation happens after redaction so a secret straddling the boundary is not half-leaked. Compaction is the one large exposure, which is why it is never installed for you.
• This is not a security control. It is a cost and hygiene guard that fails open by design. A control that depends on an agent choosing to obey it is not a control. If something must not happen, restrict it at the platform.

Platforms

What "supported" means on native Windows

FAQ

(cd ~/.local/share/airlock/current && python3 -m airlock.headless merge ~/.config/airlock/rules.json)

Roadmap

What is known to be missing or unfinished, with nothing promised to a date: ROADMAP.md.

Credits

The ported patterns, the community projects they came from and the published work cited along the way: docs/CREDITS.md.

Contributing

Issues and pull requests are welcome.

• python3 -m unittest discover -s tests must pass. It is fully mocked, so it needs no key and makes no network calls.
• python3 tools/check_docs.py must pass: it resolves every relative link in the README and docs/, and checks every Mermaid block.
• python3 tools/check_prose.py README.md must pass. It flags machine-writing phrases, em dashes, long sentences, flat rhythm and walls of text; add --fix-hints for a plainer form where a mechanical one exists.
• A rule change needs labelled cases in eval/. No real data in an eval case: no real paths, hostnames, usernames, tokens or customer names. Write the shape, not the incident.
• A rule with any false deny on its eval cases ships as warn, not deny.
• Everything fails open. A change that can raise in the hot path is a bug, even if it is correct.
• Measured claims carry their method and their date, or they do not go in.

Licence

MIT. See LICENSE, and NOTICE for the third-party components this kit clones or patches.