jevnav

jevnav

Page truth for browser agents — and decisions that replay, test and audit.

https://github.com/user-attachments/assets/502550ec-77d4-439e-b334-fe7007f946b9

jevnav is a browser layer for agents and tests. It reads a page as facts (structure, computed styles, the controls on screen), lets Jev — TypeSafe's model for structured questions — pick the element for an intent with a calibrated probability, gates risky or uncertain actions to a human, and records every decision in a trace that replay re-checks offline in CI.

• Page truth, not pixels. outline, styles and diff return what the browser resolved — font-size 32px → 28px between a mockup and the running app is something an agent can fix. No screenshots in the decision loop.
• Evidence, not confidence. Each decision carries its probability, the gate verdict and its cost. A site change that breaks a recorded decision makes replay exit 1 — no model call, no API key.
• Works where your agent works. CLI, Python/pytest, an MCP server for Claude Code, Cursor, Codex and friends, and a GitHub Action.

Why it exists — selector tests break when a label changes; LLM browser agents are confident, unauditable and occasionally wrong: docs/why.md.

Install

uv tool install jevnav          # or: pip install jevnav  (the MCP server is included)

playwright install chromium # one-time browser download

Requires Python 3.10+. Deciding (go, run, browse, goal) needs a TypeSafe API key in TYPESAFE_API_KEY or ~/.config/typesafe/apikey.txt. `replay`, `diff`, `outline` and `styles` need no key — that is the point.

Quickstart

1. Let Jev drive — state a goal and the outcome that proves it:

jevnav go --goal "sign in with the demo account and open the pricing page" \

--start https://app.example.com/login \ --context email=demo@example.com --context password="${ACME_PASSWORD}" \ --success "#pricing.visible" \ --report goal.md

status: done — outcome verified against the page steps: 5 — auto 4, review 0, blocked 0

One Jev request per step; every step is gated and traced. The loop stops when the goal is met, when nothing on the page can make progress (stuck), when the gate wants a human (review), when the page stops changing (no_progress), or at --max-steps. done is a claim — --success turns it into evidence (verified, or unverified and the run fails). --dry-run decides without acting.

2. Or script the flow and let Jev resolve each intent:

# flows/acme-login/flow.yaml

id: acme-login start: https://app.example.com/login steps:

• intent: "Sign in to the existing account" action: click
• intent: "Type the password" action: fill value: "${ACME_PASSWORD}" # read from the environment, never written to the trace
• intent: "Submit the login form" action: click

jevnav run flows/acme-login/flow.yaml --report run.md

3. Replay it in CI — offline, deterministic, no key:

jevnav replay acme-login.trace.jsonl            # re-resolve every recorded decision

jevnav replay acme-login.trace.jsonl --execute # also re-run the actions + check --success

steps 3 verdicts: ok 3

Change Sign in to Log in on the site and the same replay fails:

[01] changed   Sign in to the existing account

no element now has 'button|sign in' (was 'Sign in' / 'button')

Exit code 1, with the reason. That is the regression test.

Page truth for your agent

The facts a coding agent needs about a rendered page, without a screenshot: outline(selector) for a region's structure (tags, headings, text, boxes), styles(selector, props) for the computed values, page_state() for the controls jevnav can act on.

jevnav diff compares a mockup with the running app as facts and exits 1 on drift:

jevnav diff new-ui.html http://localhost:3000 --report ui-diff.md

The report also lists structure differences (missing, new and moved elements; boxes compared with a 4px --tolerance). The loop for "here is a new UI, update the codebase": the agent reads both pages with jevnav, edits the code itself, re-runs diff until it exits 0, then pins the outcome with goal(..., success=" ") so replay --execute keeps checking it. jevnav reports; it never edits your repository and never compares pixels.

Gates

Every decision gets one of three verdicts:

review and blocked never execute. Thresholds and risky patterns live in an optional gates.yaml; defaults ship for nine languages:

# flows/acme-login/gates.yaml

min_confidence: 0.9 # scripted flows: one question per step, well calibrated loop_min_confidence: 0.5 # goal loop: four questions at once, p runs lower risky:

• "\\b(delete|remove|purchase|pay)\\b" # matched against intent + element name + role

intents: "delete the *": { min_confidence: 0.99 } truncated: review # the page had more than 255 candidates

The goal loop uses a lower threshold on purpose: measured correct loop decisions land at p 0.41–0.99 and wrong ones at 0.39–0.47, so its safety comes from deterministic checks instead — fill on a button is refused, a field with no context value is blocked, two steps that change nothing stop the run, risky patterns always go to review, and the outcome is verified against --success.

MCP server

claude mcp add --scope user jevnav -- uvx jevnav mcp

Or, for Cursor, Claude Desktop, VS Code and other clients:

{

"mcpServers": { "jevnav": { "command": "uvx", "args": ["jevnav", "mcp"], "env": { "TYPESAFE_API_KEY": "..." } } } }

No URL or flags needed: the agent opens pages with goto, one server serves every site, and each session writes an auditable jevnav-session.trace.jsonl (--no-trace opts out). The deciding tools are what no other browser MCP has:

Plus 28 acting and inspecting tools (forms, keys, uploads, tabs, console, network, styles, outline, emulation, tracing, Lighthouse), each with MCP annotations so the host knows which calls change state. A decision costs about $0.00004 and ~330ms, and the page never enters the LLM's context. Full tool reference, security flags and when to pick jevnav vs. Playwright or chrome-devtools-mcp: docs/mcp.md.

CI — GitHub Action

- uses: dtduc-git/jevnav@v0

with: trace: examples/local-demo/demo.trace.jsonl execute: "true" # also re-run the recorded actions report: replay.md

No model call, no API key, ~30 seconds. Fails when a recorded target changed, became ambiguous, or a recorded --success selector is no longer visible. Inputs: trace, report, execute, json, version (default latest from PyPI, or local for a checkout). @v0 floats; pin a release tag such as @v0.2.2 for fully reproducible CI.

pytest

The jev fixture ships with the package: an ordinary Playwright test gets Jev decisions, and every test writes a trace that replays in CI.

def test_sign_in(jev):

jev.goto("https://app.example.com/login") jev.fill("the email address", "demo@example.com") jev.fill("the password field", "${DEMO_PASSWORD}") jev.click("the sign-in button") jev.expect("#welcome")

DEMO_PASSWORD=... pytest --jev-trace-dir=traces

DEMO_PASSWORD=... jevnav replay --execute traces/test_sign_in.trace.jsonl # offline, no key

A review verdict fails the test before the action runs, ${VAR} values are recorded by name only, and jev.page is the real Playwright page for everything else. Runnable example with a committed trace: examples/pytest-interop/.

Your own browser

jevnav go --goal "..."                                          # fresh headless Chromium (default)

jevnav go --goal "..." --user-data-dir ~/.cache/jevnav-profile --headed # persistent profile jevnav go --goal "..." --cdp http://127.0.0.1:9222 # attach to a running Chrome

Log in once with --headed and every later run reuses the profile; --cdp drives the Chrome you already have open, keeps its own settings (so it refuses --user-data-dir, --locale, --timezone and --user-agent) and never closes it. Both work on run, go, replay and mcp, and so does --browser for firefox or webkit (plus --locale, --timezone, --user-agent). Profile paths and cookies never reach a trace.

Evidence

Small samples with a single annotator: read them as direction, not proof. jevnav's advantage is decision cost and evidence, not wall-clock speed on small pages. Method, caveats and the tool-level comparison: docs/evidence.md.

How it works

• A shortlist, not the page. Visible interactive elements from every frame and open shadow root, ranked by how likely a human would act on them and capped at 120 (--max-candidates, hard cap 254). Each carries role, accessible name, type, href, placeholder and a scope, so three "Email" fields stay distinguishable.
• One question per step. The shortlist plus none becomes a choice question; Jev answers with one element and its probability.
• Fingerprints, never positions. An element's identity is role|name. The trace stores every candidate's fingerprint as the model saw it, and actions and repla