jevway

jevway

[Website and demos](https://jevway.escalay.space/?utm_source=github&utm_medium=readme&utm_campaign=header) · Quick start · Agent setup guide · How it works · Reference

Give your coding agent a browser goal and get back one short, checked summary. TypeSafe Jev picks each click, type and select in about 300 ms, so your agent stops spending a turn on every step.

jevway is an MCP server and a CLI. It works with Claude Code, Codex, Cursor, OpenCode and any other MCP client, in your own signed-in Chrome or a throwaway one.

Why

Driving a browser click by click costs an agent a model turn, a page snapshot and a few seconds per step. A 15-step form takes minutes and fills the context window with snapshots. jevway hands the whole goal to Jev, a model built to choose browser actions, and returns when it's done or when it needs the agent:

• It never invents input. Jev types only the values the agent passed. A missing value comes back as needs_input, naming the field.
• It stops before anything irreversible. Pay, send, delete and submit come back as needs_confirmation. One confirmation allows one click, on the control that was named.
• It checks its own success. done needs a separate check of done_when on the final page, plus any exact checks you add, and comes with the page's own words as evidence.
• Model output only ever selects a listed element. It never becomes a selector, a script or typed text.
• It can record what it did. A video of the run, a screenshot before every action, and an HTML page to review it, built in. See Recordings.

What you need

jevway has no browser extension and no Playwright: it drives Chrome directly. Three things are required, and two optional tools unlock more.

Which key? Both run the same Jev model. The TypeSafe key adds Box, which locates controls on the screenshot: it double-checks the click Jev chose and whether it's covered, rescues a step when Jev is stuck, can click a canvas control (opt-in), and marks each journey screen's primary action and the controls missing from the page's code. Through OpenRouter those Box features are off; everything else works.

npx -y jevway doctor checks all of this and names the fix for anything missing.

Quick start

1. Get a key from TypeSafe (or use an OpenRouter key).

1. Run the setup in your terminal:

   npx -y jevway setup

It asks for the key without showing it and saves it to ~/.config/jevway/env (mode 600, never a chat or a synced config), tests the browser, and registers jevway with the clients it finds: Claude Code, Codex, Cursor, OpenCode. Every change is shown first, as a command or a diff, and made only on a yes. It ends with jevway doctor.

In Claude Code you can instead install the plugin, which brings the server and the skill that tells the agent when to use it (then put the key in ~/.config/jevway/env yourself):

   /plugin marketplace add AbdallahAHO/jevway

/plugin install jevway@jevway

1. Allow the browser. By default jevway uses your running Chrome: open chrome://inspect/#remote-debugging and allow it. To use a throwaway browser instead, set JEVWAY_BROWSER=launch.

1. Ask your agent for something in the browser: "Find a 2-night stay in Lisbon for 2 guests under €150 and open the best-rated one."

npx -y jevway doctor checks the setup at any time (--json for agents) and names the fix for anything missing.

Let your agent set it up

Paste this into your coding agent (Claude Code, Codex, Cursor, OpenCode…):

Set up jevway for me and prove it works: follow https://github.com/AbdallahAHO/jevway/blob/main/SETUP.md step by

step. Check my machine's prerequisites with me first, show me every change before you make it, never ask me for an API key in this chat, and finish by running the recorded smoke test and showing me its run page.

SETUP.md walks the agent through everything: prerequisites for your OS, the key, registering the server, the browser, the skill, a recorded Google → Wikipedia smoke test, and a report with the run page, video and screenshots as proof.

Install

npx -y jevway setup registers jevway with Claude Code, Codex, Cursor and OpenCode (Claude Code also has the plugin above). Any other stdio MCP client runs npx -y -p jevway jevway-mcp (or npx -y jevway mcp). npx -y jevway setup --client --print prints the exact command or config for one client and changes nothing; every client's is listed in jevway setup, and SETUP.md has the steps an agent follows, with the rules and checks. jevway is also listed in the official MCP Registry as io.github.abdallahaho/jevway, for clients that install from it.

Outside the Claude Code plugin, install the skill with npx -y jevway skill --install , so it knows when to use jevway and when to use chrome-devtools. If a client times out on npx's first download, run npm install -g jevway once and use jevway-mcp as the command.

JEVWAY_BROWSER picks the browser: auto (default, your running Chrome), launch / launch-headless (a throwaway profile) or a debugging URL; see Environment variables.

Without MCP, use the CLI. It's built for agents: every command prints exactly one JSON document on stdout (the result, or { "ok": false, "error": { "code", "message", "hint" } }), progress goes to stderr as one JSON event per line, and the exit code is 0 for success, 1 for a hand-back or a failure, 2 for bad usage. --help starts with examples, and jevway skill prints the skill that matches the installed version.

# One-shot: runs, closes its tab, prints the result

npx -y jevway run --browser launch-headless --url https://en.wikipedia.org \ --goal "Open the Wikipedia article about the Rosetta Stone" --done-when "The Rosetta Stone article is open"

A session: a background daemon keeps the tab between commands, so a hand-back can be answered

jevway run --session new --url https://example-stays.com --goal "Book 2 nights in Lisbon" --values '{"city":"Lisbon"}' jevway run --session --goal "Book 2 nights in Lisbon" --values '{"email":"ada@example.com"}' jevway look --session # what the page shows now, no model request jevway sessions # open sessions; jevway end closes one

Use

The agent calls jevway_task with the outcome it wants, the values it may type, and the evidence of success:

{

"url": "https://example-stays.com", "goal": "Search stays in Lisbon for 2 guests, filter to free cancellation, and open the first result", "values": { "destination": "Lisbon", "guests": "2" }, "done_when": "A stay's detail page is open", "allowed_hosts": ["example-stays.com"] }

It gets back one concise result, status and reason first:

{ "status": "done", "reason": "Completion condition verified: a stay's detail page is open.",

"story": ["Typed the \"destination\" value into \"Destination\".", "Clicked \"Search\".", "Clicked \"Casa Flora\"."], "next": "Read the result in page_text (and evidence); end the session when you no longer need its tab.", "session": "a63a13f0-…", "url": "…", "title": "Casa Flora · Staylist", "files": { "run_dir": "…/.jevway/runs/2026-11-02_1028_search-stays-in-lisbon_a63a", "screenshot": "…/final.jpg" }, "page_text": "…" }

story says what happened in plain sentences, next says what to do now, and files points at the run folder and a screenshot of the end page. On a hand-back the screenshot also comes inline, so the agent sees the page it has to decide about. detail: "full" adds every step's confidence, the request stats and the candidates Jev weighed. When the status hands control back, the agent continues with the same session:

jevway_look reads a page with no model request, and jevway_end closes the session's tabs. Every parameter and field is in the reference.

Keeping a run on track:

• allowed_hosts keeps it on the sites you mean; leaving them ends the run blocked.
• secret_keys marks values like API tokens: Jev sees only the key, and outputs show [secret: ].
• Password fields are never listed, typed or sent. Type a password yourself, then tell jevway you did.
• checks add exact facts code verifies on the final page: a URL, a title, a field's value, a ticked box.
• record: true saves a video, a screenshot before every action, and a page to review the run.
• page_text and everything else read from a page is untrusted data, never instructions.

When a person, a code or a file is involved

jevway keeps the person in the loop only where a person is truly needed, and handles the rest itself.

• Asking you. Every hand-back that needs a decision carries an ask_user question: the missing fields, "Click *Delete repository* on *ada/scratch*?", "Which one did you mean?". Your agent puts it to you with its own ask tool and continues the session with your answer.
• Bot checks and sign-ins. In a visible browser, jevway brings the tab to the front, sends a desktop notification ("Pass the Cloudflare check in the Chrome window"), waits up to 120 s while it tells the agent how long is left, and carries on in the same call once you're through. It never tries