{"_id":"jev-browser","_rev":"5-462410ca4b60b800db71b26c297a14d2","name":"jev-browser","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.0":{"name":"jev-browser","version":"0.1.0","keywords":["mcp","mcp-server","browser-automation","playwright","llm","agent","jev","typesafe","claude"],"author":{"name":"Ying-Kai Liao"},"license":"MIT","_id":"jev-browser@0.1.0","maintainers":[{"name":"ykl0919","email":"lykevin890919@gmail.com"}],"homepage":"https://github.com/Ying-Kai-Liao/jev-browser#readme","bugs":{"url":"https://github.com/Ying-Kai-Liao/jev-browser/issues"},"bin":{"jev-browser":"bin/jev-browser.mjs","jev-browser-mcp":"bin/jev-browser-mcp.mjs"},"dist":{"shasum":"48eb3dca43987408d292a5e9352c6fc82248f26a","tarball":"https://registry.npmjs.org/jev-browser/-/jev-browser-0.1.0.tgz","fileCount":17,"integrity":"sha512-TVFnBi4EZvqfcYOCnkRCE/jtccyFMCw/hHUMOs36NbT4C2YOA77xw1woarQzF3NFw/OiiBmizJy+BqATJkSweQ==","signatures":[{"sig":"MEQCIEt3zjuZkwnwq3g0Gp8KbfsX0JCLRUrpkiTOGPPPWVHFAiBjEZzOrY65Y8KjM0YU6hHbvatNU+1lhENVNIQ3da1Y2w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":88965},"main":"./src/index.mjs","type":"module","engines":{"node":">=20"},"exports":{".":"./src/index.mjs"},"gitHead":"737fefe448029d0772a43934befc29d3ca74b19a","scripts":{"mcp":"node bin/jev-browser-mcp.mjs","test":"node --test test/*.test.mjs","bench":"node bench/run.mjs","setup":"npx playwright install chromium","test:e2e":"node test/mcp.e2e.mjs","bench:cost":"node bench/context-cost.mjs"},"_npmUser":{"name":"ykl0919","email":"lykevin890919@gmail.com"},"repository":{"url":"git+https://github.com/Ying-Kai-Liao/jev-browser.git","type":"git"},"_npmVersion":"12.0.2","description":"Browser automation where an LLM plans and Jev (Typesafe System One) makes every per-step decision. Library, CLI and MCP server.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^4.6.5","playwright":"^1.63.0","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/jev-browser_0.1.0_1789601692755_0.4098885850331184","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"jev-browser","version":"0.1.1","keywords":["mcp","mcp-server","browser-automation","playwright","llm","agent","jev","typesafe","claude"],"author":{"name":"Ying-Kai Liao"},"license":"MIT","_id":"jev-browser@0.1.1","maintainers":[{"name":"ykl0919","email":"lykevin890919@gmail.com"}],"homepage":"https://github.com/Ying-Kai-Liao/jev-browser#readme","bugs":{"url":"https://github.com/Ying-Kai-Liao/jev-browser/issues"},"bin":{"jev-browser":"bin/jev-browser.mjs","jev-browser-mcp":"bin/jev-browser-mcp.mjs"},"dist":{"shasum":"dec82bb07e9874fb45d6ffb66c1aa265a4a9feec","tarball":"https://registry.npmjs.org/jev-browser/-/jev-browser-0.1.1.tgz","fileCount":17,"integrity":"sha512-q7QpAG3JWpTnc7/Xg6tAb2F+UTVa+VlzOQ5+Zqxhfh1vJ58DiDuvEyM4Y36+fs9t4WCyBVvlcUpanYnUa27JAA==","signatures":[{"sig":"MEYCIQDtCN395hdl/FsZ+mu2kik1lXj3e8BRek++wuFtQi7SxQIhALhsnt3ha1DM7ckyhKbF8MlYFidZHHdeMlNW7+SyZ49n","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIFr2Quv2GDzs9BO8uzT59iitGQHXIY9CKF4Gjb2EQnW0AiEA7/bgCAi3z1kNIAw28d7BPP0y/1ILIvE3DJAXFJYyKgg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/jev-browser@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":94152},"main":"./src/index.mjs","type":"module","engines":{"node":">=20"},"exports":{".":"./src/index.mjs"},"gitHead":"ca4bc21226af0857f687c52cc3a3b0259a1e7c63","scripts":{"mcp":"node bin/jev-browser-mcp.mjs","test":"node --test test/*.test.mjs","bench":"node bench/run.mjs","setup":"npx playwright install chromium","test:e2e":"node test/mcp.e2e.mjs","bench:cost":"node bench/context-cost.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2e7ddae3-a04a-4482-99d2-b7c3410dc59b"}},"repository":{"url":"git+https://github.com/Ying-Kai-Liao/jev-browser.git","type":"git"},"_npmVersion":"12.0.2","description":"Browser automation where an LLM plans and Jev (Typesafe System One) makes every per-step decision. Library, CLI and MCP server.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.6.5","playwright":"^1.63.0","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/jev-browser_0.1.1_1789604095667_0.43730564823743445","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"jev-browser","version":"0.1.2","keywords":["mcp","mcp-server","browser-automation","playwright","llm","agent","jev","typesafe","claude"],"author":{"name":"Ying-Kai Liao"},"license":"MIT","_id":"jev-browser@0.1.2","maintainers":[{"name":"ykl0919","email":"lykevin890919@gmail.com"}],"homepage":"https://github.com/Ying-Kai-Liao/jev-browser#readme","bugs":{"url":"https://github.com/Ying-Kai-Liao/jev-browser/issues"},"bin":{"jev-browser":"bin/jev-browser.mjs","jev-browser-mcp":"bin/jev-browser-mcp.mjs"},"dist":{"shasum":"fca002d537355d512f40131368a6984475ddbd0d","tarball":"https://registry.npmjs.org/jev-browser/-/jev-browser-0.1.2.tgz","fileCount":20,"integrity":"sha512-tyU7Mxa2NV6aPjLdu0jDCUxxo5LZ1sjF9mEC+b2CD7o3ESmwZwMjeTGAaOQGD01mftW9mIJ5GPO/eDUmZMzIgQ==","signatures":[{"sig":"MEYCIQDPqHw9pDIfheVVjpLC77vLfP7bqEQBfgU2pDKD7UxLygIhANg3BL8O2ue3oR4f9aYiHD6wJjMPY0wKrW7XHzOpUEPO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIBVspbU6oP46QDCqYzO/pWoxYiwezxqdk+DbqgZFsQrIAiAnzngEDSPVw7yEVMWZD5tqC4wI2CAHaCaswmH07M4VtA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/jev-browser@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":165449},"main":"./src/index.mjs","type":"module","engines":{"node":">=20"},"exports":{".":"./src/index.mjs"},"gitHead":"84745e9059916ddf177e6abbe624d1659071e717","scripts":{"mcp":"node bin/jev-browser-mcp.mjs","cost":"node bin/jev-cost.mjs","test":"node --test test/*.test.mjs","bench":"node bench/run.mjs","setup":"npx playwright install chromium","test:e2e":"node test/mcp.e2e.mjs","bench:cost":"node bench/context-cost.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"2e7ddae3-a04a-4482-99d2-b7c3410dc59b"}},"repository":{"url":"git+https://github.com/Ying-Kai-Liao/jev-browser.git","type":"git"},"_npmVersion":"12.2.0","description":"Browser automation where an LLM plans and Jev (Typesafe System One) makes every per-step decision. Library, CLI and MCP server.","directories":{},"_nodeVersion":"22.23.3","dependencies":{"zod":"^4.6.5","playwright":"^1.63.0","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/jev-browser_0.1.2_1791482566789_0.7859671184880743","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"jev-browser","version":"0.2.0","keywords":["mcp","mcp-server","browser-automation","playwright","llm","agent","jev","typesafe","claude","claude-code-plugin"],"author":{"name":"Ying-Kai Liao"},"license":"MIT","_id":"jev-browser@0.2.0","maintainers":[{"name":"ykl0919","email":"lykevin890919@gmail.com"}],"homepage":"https://github.com/Ying-Kai-Liao/jev-browser#readme","bugs":{"url":"https://github.com/Ying-Kai-Liao/jev-browser/issues"},"bin":{"jev-browser":"bin/jev-browser.mjs","jev-browser-mcp":"bin/jev-browser-mcp.mjs"},"dist":{"shasum":"72787fe1921e1faf194edb7c19d082df723225f4","tarball":"https://registry.npmjs.org/jev-browser/-/jev-browser-0.2.0.tgz","fileCount":23,"integrity":"sha512-sdIRBdI6icM+Hd/xCMOaUaCx+kHGfwNoYxTILMQu+wc1jcc3jVIfuevSTb45+r98+YalKhxxNF4OZp+Ku2cuoQ==","signatures":[{"sig":"MEQCIHwbet5nVwrsJHjoyWKa0Vp9LmRneKM+SCU9X/Y98c0tAiBYx0Uos8kcIkj6KTrotE4fw7ON0RUhPObBNsvqU7mpsg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCa0JhfHJrCt/g390m+uh4Hlhw+NYTwhiEOWtkWrCaWWAIhANOARp8tGUwkfuvhYEcwUNn/8GJupZr2+bMZ9A54M8RL","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/jev-browser@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":213559},"main":"./src/index.mjs","type":"module","engines":{"node":">=20"},"exports":{".":"./src/index.mjs"},"gitHead":"31551c3b2fab328a21d2fdaac124602b373382f5","scripts":{"mcp":"node bin/jev-browser-mcp.mjs","cost":"node bin/jev-cost.mjs","test":"node --test test/*.test.mjs","bench":"node bench/run.mjs","setup":"npx playwright install chromium","version":"node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json .mcp.json","test:e2e":"node test/mcp.e2e.mjs","validate":"node scripts/sync-plugin-version.mjs --check && claude plugin validate . --strict","bench:cost":"node bench/context-cost.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"2e7ddae3-a04a-4482-99d2-b7c3410dc59b"}},"repository":{"url":"git+https://github.com/Ying-Kai-Liao/jev-browser.git","type":"git"},"_npmVersion":"12.2.0","description":"Browser automation where an LLM plans and Jev (Typesafe System One) makes every per-step decision. Library, CLI and MCP server.","directories":{},"_nodeVersion":"22.23.3","dependencies":{"zod":"^4.6.5","playwright":"^1.63.0","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/jev-browser_0.2.0_1791918813991_0.0018874771774690657","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"_id":"jev-browser@0.2.1","bin":{"jev-browser":"bin/jev-browser.mjs","jev-browser-mcp":"bin/jev-browser-mcp.mjs"},"bugs":{"url":"https://github.com/Ying-Kai-Liao/jev-browser/issues"},"dist":{"shasum":"e151e6009bc5992f340ffd7f8cb3fa25206e530e","tarball":"https://registry.npmjs.org/jev-browser/-/jev-browser-0.2.1.tgz","fileCount":23,"integrity":"sha512-m3mYzYZzzN+DJo5QVDji20pfDeTZxQbQ8b7Cm4vY7aIO0XI8ePYIqYkaylzAxDtrldX7gKnHQNsrcc0q2Yk8NA==","signatures":[{"sig":"MEUCIQD9k71ynDwvBfPul9Gdu0mSlrC1TQDPx7OuyWBU+TH+xQIgf4+s1tKCW/zu3Yg2KakbvnWOYpTHsaC0n7eTPBKDGSg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCnQPPyGERJ5YSb8NKzOoV6IxJa89eVSehHRLF1P0aBRAIhAInrPsk36IEfvt0vWLziEt/qQfUba1ChHIMQfqqoLoh4"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/jev-browser@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":223416},"main":"./src/index.mjs","name":"jev-browser","type":"module","author":{"name":"Ying-Kai Liao"},"engines":{"node":">=20"},"exports":{".":"./src/index.mjs"},"gitHead":"74592bac3fa78407ea1571b8233ead8540d531f3","license":"MIT","scripts":{"mcp":"node bin/jev-browser-mcp.mjs","cost":"node bin/jev-cost.mjs","test":"node --test test/*.test.mjs","bench":"node bench/run.mjs","setup":"npx playwright install chromium","version":"node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json .mcp.json","test:e2e":"node test/mcp.e2e.mjs","validate":"node scripts/sync-plugin-version.mjs --check && claude plugin validate . --strict","bench:cost":"node bench/context-cost.mjs"},"version":"0.2.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"2e7ddae3-a04a-4482-99d2-b7c3410dc59b"}},"homepage":"https://github.com/Ying-Kai-Liao/jev-browser#readme","keywords":["mcp","mcp-server","browser-automation","playwright","llm","agent","jev","typesafe","claude","claude-code-plugin"],"repository":{"url":"git+https://github.com/Ying-Kai-Liao/jev-browser.git","type":"git"},"_npmVersion":"12.2.0","description":"Browser automation where an LLM plans and Jev (Typesafe System One) makes every per-step decision. Library, CLI and MCP server.","directories":{},"maintainers":[{"name":"ykl0919","email":"lykevin890919@gmail.com"}],"_nodeVersion":"22.23.3","dependencies":{"zod":"^4.6.5","playwright":"^1.63.0","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/jev-browser_0.2.1_1792246004913_0.5319005661795795"}}},"time":{"created":"2026-09-16T23:34:52.566Z","modified":"2026-10-17T14:06:45.465Z","0.1.0":"2026-09-16T23:34:52.894Z","0.1.1":"2026-09-17T00:14:55.772Z","0.1.2":"2026-10-08T18:02:46.878Z","0.2.0":"2026-10-13T19:13:34.076Z","0.2.1":"2026-10-17T14:06:45.038Z"},"bugs":{"url":"https://github.com/Ying-Kai-Liao/jev-browser/issues"},"author":{"name":"Ying-Kai Liao"},"license":"MIT","homepage":"https://github.com/Ying-Kai-Liao/jev-browser#readme","keywords":["mcp","mcp-server","browser-automation","playwright","llm","agent","jev","typesafe","claude","claude-code-plugin"],"repository":{"url":"git+https://github.com/Ying-Kai-Liao/jev-browser.git","type":"git"},"description":"Browser automation where an LLM plans and Jev (Typesafe System One) makes every per-step decision. Library, CLI and MCP server.","maintainers":[{"name":"ykl0919","email":"lykevin890919@gmail.com"}],"readme":"# jev-browser\n\nBrowser automation where an LLM plans and **Jev** decides.\n\n> Unofficial project, not affiliated with TypeSafe. It calls the TypeSafe System One API\n> with your own API key.\n\nThe calling LLM (Claude, via MCP) says what outcome it wants, one step at a time, and hands\nover any text to type. For each round of a step, code describes the page. Then one ~300 ms\n[Typesafe System One](https://docs.typesafe.ai) request asks Jev several questions at once:\nwhich element, which action, which value, and is the step done / blocked / showing an error /\nabout to do something irreversible. Playwright performs the action. The LLM never reads page\nsnapshots unless it chooses to take over.\n\n```\nClaude ── browser_do(\"Log in\", {email, password}) ──▶ jev-browser\n                                                       │  loop until done / stuck / needs confirmation\n                                                       │   1. settle   (network + DOM quiet)\n                                                       │   2. describe (elements, labels, state, visible text, diff, counts)\n                                                       │   3. Jev      (done? error? irreversible? tool? target? value?)\n                                                       │   4. act      (Playwright)\nClaude ◀── { status: \"done\", url, actions[], done_score } ─┘\n```\n\nhttps://github.com/user-attachments/assets/2e688df9-4985-4854-8ebe-ba97c9d13d68\n\nWith [WebMCP](#webmcp-when-the-page-offers-its-own-tools), a page offers its own tools. Jev\nchooses between those and the page's buttons, and fills each argument by picking one of the\ncaller's `values` (`text: values.g1 → \"milk\"`), never by writing text:\n\nhttps://github.com/user-attachments/assets/fe309fb8-aada-4187-a91e-f18493a39526\n\nJev only answers with probability distributions: yes/no (`noul`), pick one option (`choice`)\nor a rating (`score`). It never writes text. So everything free-form comes from the caller as\ncandidates, and code turns disagreement or low confidence into a status the LLM can act on.\n\n## Results\n\n42 tasks in 16 categories on live sites (see [RESULTS.md](RESULTS.md)):\n\n- **40/42 correct in the latest run, 0 false \"done\" claims** (38/41 twice before the latest\n  fixes). Remaining misses: counting (\"add until 3\", flagged `likely_done`) and verifying a sort.\n- **~300 ms per Jev call**, 2–4 calls for most steps; a 5-step checkout takes ~14 s end to end.\n- **Pause before irreversible actions**: across ~200 rounds it flagged only saucedemo's\n  \"Finish\" (place order) button.\n- **Less page content for the LLM** than a Playwright-MCP-style loop on the same tasks\n  (estimate): median 5× per task, ≈8k vs ≈557k tokens in total. Big pages dominate the total:\n  a Wikipedia article is ~149k snapshot tokens. On tiny pages there is no saving. The page\n  reading moves to Jev.\n\nWorks on: forms, native and custom dropdowns, checkboxes and radios (including styled\nreplacements), dynamic loading, modals, JS dialogs, hover, right-click, drag and drop, key\npresses, file upload, iframes, shadow DOM, new tabs, pages with 2,000+ elements (two-stage\nselection), and non-English UIs.\n\nKnown limits, so write steps around them:\n- **Ordered sub-goals in one step** (\"add two todos, complete one, clear completed\") → split\n  into one outcome per step.\n- **Open-ended goals** (\"scroll to load more\") → make them measurable or check yourself.\n- **Judgements that compare many values** (is this table sorted, did exactly one thing change)\n  → verify with `browser_check` or `browser_snapshot`.\n\n## Quick start (Claude Code plugin)\n\n```\n/plugin install jev-browser --marketplace Ying-Kai-Liao/jev-browser\n```\n\nOn older Claude Code versions, add the marketplace first:\n\n```\n/plugin marketplace add Ying-Kai-Liao/jev-browser\n/plugin install jev-browser@jev-browser\n```\n\nClaude Code then asks for your TypeSafe API key (or an OpenRouter key), which goes to its secure credential store. It\nalso offers two optional settings: show the browser window, and a persistent profile directory\nso that logins survive restarts. The plugin runs the MCP server below, pinned to the same\nversion, and adds a skill that teaches Claude how to write steps and handle each status. The\nfirst browser call downloads Chromium for Playwright if it is missing (one time, about 30 s).\n\nData: see [Privacy](#privacy). Page content goes to the TypeSafe API (or OpenRouter); passwords and other\nsecrets you pass in `values` don't.\n\n## Quick start (MCP, from npm)\n\n```bash\nnpx playwright install chromium          # once (the server also does this on first use)\nclaude mcp add jev-browser -e TYPESAFE_API_KEY=your-key -- npx -y -p jev-browser jev-browser-mcp\n```\n\nAny MCP client works the same way: command `npx`, args `-y -p jev-browser jev-browser-mcp`,\nenv `TYPESAFE_API_KEY`. Add `JEV_BROWSER_HEADED=1` to watch it work.\n\nNo TypeSafe account? Jev is also on [OpenRouter](https://openrouter.ai/typesafe/jev-1.13): pass\n`-e OPENROUTER_API_KEY=your-key` instead, and calls are billed to your OpenRouter account. When both\nkeys are set, `TYPESAFE_API_KEY` wins, whether each comes from the environment or `.env`. `JEV_API_URL` and\n`JEV_MODEL` override the TypeSafe endpoint and model; they are ignored when the OpenRouter key is used.\n\n## Setup (from source)\n\n```bash\ngit clone https://github.com/Ying-Kai-Liao/jev-browser && cd jev-browser\nnpm install\nnpm run setup                    # downloads Chromium for Playwright\ncp .env.example .env             # add TYPESAFE_API_KEY or OPENROUTER_API_KEY\nnpm test                         # offline tests (no network, no key)\nnpm run test:e2e                 # MCP server end to end (network + key)\n```\n\n### Use from Claude Code (MCP, from source)\n\n```bash\nclaude mcp add jev-browser -- node /absolute/path/to/jev-browser/bin/jev-browser-mcp.mjs\n```\n\nFrom a source checkout the server reads `TYPESAFE_API_KEY` (or `OPENROUTER_API_KEY`) from the repo's `.env`.\n\n| tool | purpose |\n|---|---|\n| `browser_open(url, viewport?)` | navigate and wait for the page to settle; `viewport: \"390x844\"` resizes the window (e.g. to check a phone layout) and the size sticks for later calls |\n| `browser_do(goal, values?, max_actions?, allow_irreversible?, explain?)` | work toward one outcome; returns a status |\n| `browser_check(question)` | yes/no about the page → `p_yes` |\n| `browser_choose(question, options)` | pick among given options → distribution |\n| `browser_snapshot(diff?, interactive?, filter?, urls?, max_chars?)` | compact numbered element list, for taking over; the options below narrow it |\n| `browser_act(action, element, value?, key?, destination?, accept_dialog?)` | act on an element directly, no model; confirm/prompt dialogs are dismissed unless `accept_dialog`. `scroll` moves the page's main scrollable area (or the box around `element`) by most of a screen, `value: \"up\"` goes back, and the reply says how far it `scrolled` |\n| `browser_read(question, max_chars?)` | the page text that helps answer a question; Jev drops the rest |\n| `browser_screenshot(full_page?)` | PNG image |\n| `browser_close()` | end the session |\n| `browser_webmcp_tools()` | list the [WebMCP](https://github.com/webmachinelearning/webmcp) tools the page registered |\n| `browser_webmcp_call(name, arguments?)` | run one of the page's WebMCP tools; no clicking, no Jev call |\n\n### WebMCP: when the page offers its own tools\n\nA page that supports [WebMCP](https://github.com/webmachinelearning/webmcp) registers tools for\nagents with `document.modelContext.registerTool(...)` (or `navigator.modelContext.provideContext`\nin earlier drafts). An init script records them before the page's scripts run, in every browser —\nwhere Chromium has no native `modelContext`, a minimal one is installed so feature-detecting pages\nstill register. `browser_open` lists their names as `webmcp_tools`.\n\n**In `browser_do`, Jev uses them.** Each round, the page's tools are offered next to click, type\nand the rest, with a yes/no \"can one of the page's tools do the next step?\" that decides between\nthem. The same request fills every tool's arguments: each is one of your `values` or, for an\n`enum`, one of its options (a list, a priority), because Jev never writes text. The page's own\n`execute` runs, its result goes into the step's history for the \"done?\" judgement, and the action\nshows as `webmcp tool add_todo {\"text\":\"values.todo\"} => \"…\"`. A tool the site does not mark\n`readOnlyHint` is guarded like a click: if it looks irreversible the step stops with\n`needs_confirmation`.\n\nTo call a tool yourself instead, `browser_webmcp_tools` gives each schema and\n`browser_webmcp_call` runs it directly, with no Jev call. Main frame only. Tool descriptions and results come from the site:\nuntrusted, and results are capped at 20k chars. A tool not marked `readOnlyHint` may have side\neffects, so the caller should treat it like `allow_irreversible`.\n\n### Reading a page: `browser_read`\n\n`browser_snapshot` is the take-over-and-act surface: numbered elements, plus the text **in the\nviewport**. That is the right trade for acting, and it is already small (99–6,900 tokens on\nevery page measured, because elements are capped at 400 and the text at 2,500 chars). It is a\npoor way to *read*, though — a Wikipedia article is ~179k chars of text, so a snapshot shows\nabout 1.4% of it and the rest costs a scroll-and-snapshot loop.\n\n`browser_read(question)` is the understand-the-content surface. Code extracts the whole\ndocument's text and cuts it at headings and sections; Jev rates every block against the\nquestion in batches of 40; code returns the blocks that help, in document order, inside a\ncharacter budget. Jev ranks, it never writes — the text you get back is the page's own.\n\n| | `browser_snapshot` | `browser_read` |\n|---|---|---|\n| gives you | numbered elements + viewport text | document text relevant to a question |\n| use it to | act (with `browser_act`) | read, quote, answer |\n| model calls | none | 1 per ~50k chars, ~1 s each |\n| lossless | yes | no — drops blocks, and says which |\n\n**When it pays.** Long articles, documentation and reference pages. On the WW2 article,\n\"When and why did Japan surrender?\" returned 11.8k of 178.5k chars — 15× less — in 3.4 s over\n5 Jev calls, keeping the atomic-bomb and surrender paragraphs.\n\n**When it doesn't.** Short pages, apps and forms. Below a 8,000-char floor (and below your own\n`max_chars`) it returns the page whole and never calls Jev at all, because paying ~1 s to prune\na 2k-token page is a loss. Hacker News, a BBC front page and saucedemo all land under the floor.\n\nIt is **biased to keep**: a block Jev cannot rate — or a whole batch whose request failed — is\nkept, and whatever is left out is counted and marked in place with `[… N blocks dropped …]`.\nNothing is ever silently cut. Use `browser_snapshot` if you need the page as the caller\nnormally sees it.\n\n```bash\nnode examples/read-demo.mjs                                   # WW2 article, default question\nnode examples/read-demo.mjs \"https://…\" \"what do you want?\"   # needs a key\n```\n\n`browser_do` statuses:\n\n| status | meaning / what the caller should do |\n|---|---|\n| `done` | goal reached |\n| `likely_done` | the page looks done but Jev is unsure: verify before moving on |\n| `needs_login` | a sign-in wall and no credentials in `values`; log in yourself (headed + `JEV_BROWSER_PROFILE`) or pass credentials |\n| `needs_confirmation` | next action, or a confirm dialog it opened (then dismissed), looks irreversible (order, pay, send, delete); see `pending`, re-call with `allow_irreversible: true` only if the user wants it |\n| `error` | the page shows an error after the last action (e.g. wrong password); see `page_text` |\n| `stuck` / `max_actions` | no progress; see `info`, `page_text`, `candidates` |\n| `ambiguous` | low confidence in the target; pick from `candidates` with `browser_act` |\n| `blocked` | captcha, access denied, error page |\n\n`browser_snapshot` options. A snapshot is the one page the calling LLM reads in full, so every\noption narrows what gets rendered. All of them are pure formatting: nothing is collected\ndifferently and none of them costs a Jev call.\n\n| option | default | effect |\n|---|---|---|\n| `diff` | `false` | only what changed since the previous snapshot, using the same diff the `browser_do` loop feeds Jev. With no previous snapshot you get a full one and a note saying so. A diff carries no element numbers: take a full snapshot to act. |\n| `interactive` | `false` | drop the `visible text:` block; element lines and dialog/status text stay. The element list is interactive-only already, so this narrows the prose, not the elements. |\n| `filter` | — | keep only elements whose label, text, placeholder, name or href contains the substring, case-insensitive; the header says how many were hidden |\n| `urls` | `false` | print `href=` on element lines. **Off by default** — on a link-heavy page link targets are the largest single share of the output, and `browser_act` takes element numbers, not URLs. A link with nothing else to identify it keeps its href. |\n| `max_chars` | `10000` | size of the rendered snapshot, hard cap 20000. When it truncates, the last line says how many element lines and characters were dropped and which option would narrow it. |\n\nA typed password is never printed: `input:password` values render as `[redacted]`, in a snapshot\nand in a diff. Measured on a Wikipedia article (1,840 elements), a default snapshot went from\n26,919 to 9,926 characters (~6,700 → ~2,500 estimated tokens); `filter` brings it to ~800 and\n`diff` after a scroll to ~50.\n\nEnv: `JEV_BROWSER_HEADED=1` shows the browser, `JEV_BROWSER=chrome` runs your own browser\ninstead of Playwright's Chromium (`chrome`, `chrome-beta`, `msedge`, or the path to any\nChromium-based browser's executable, such as Brave), `JEV_BROWSER_PROFILE=/dir` keeps a persistent\nprofile (logins survive restarts; use a dedicated directory, since Chrome won't be automated with\nyour everyday profile), `JEV_BROWSER_LOG=1` prints per-round decisions to stderr,\nand `JEV_BROWSER_NO_INSTALL=1` turns off the Chromium download on first use. The MCP server\nreads `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY` from its environment, or from the `.env` of a source checkout, but\nnever from the `.env` of the directory it was started in.\n\n### Library\n\n```js\n// npm install jev-browser && npx playwright install chromium\nimport { JevBrowser } from \"jev-browser\";\n\nconst b = await JevBrowser.launch({ headed: true });\nawait b.open(\"https://www.saucedemo.com/\");\nawait b.do(\"Log in\", { values: { username: \"standard_user\", password: \"secret_sauce\" } });\nawait b.do(\"Add the Sauce Labs Backpack to the cart\");\nconst p = await b.check(\"Does the cart badge show 1 item?\");   // 0..1\nawait b.close();\n```\n\n### Watch it\n\n```bash\nnode examples/webmcp-demo.mjs        # headed: 9 plain goals on a planner; Jev picks page tools or clicks, ~25 s\nSTEP_MS=800 RECORD=demo.mp4 node examples/webmcp-demo.mjs   # same, paced, recorded at 2x (needs ffmpeg)\nnode examples/x-profile-demo.mjs     # headed, read-only x.com walkthrough with decision highlights\n```\n\nEach action is outlined in red with Jev's choice and scores before it happens (`highlight: true`,\non by default in the MCP server when `JEV_BROWSER_HEADED=1`). Some sites, x.com included, serve a\nblank page to headless Chromium: use headed mode there.\n\n### CLI\n\n```bash\nnode bin/jev-browser.mjs do https://the-internet.herokuapp.com/login \"Log in\" username=tomsmith 'password=SuperSecretPassword!'\nnode bin/jev-browser.mjs run examples/flows/todomvc.json --headed\n```\n\n## Writing good steps\n\n- One observable outcome per step: \"Log in\", \"Open the Pull requests tab\", \"Mark 'buy milk' completed\".\n- Every string goes in `values` with a meaningful key (`email`, `postal_code`, `file`).\n- Treat `likely_done`, `needs_confirmation`, `ambiguous` and `stuck` as your turn: check,\n  snapshot or ask the user, don't just retry.\n- After steps with side effects, `browser_check` what must *not* have changed.\n\n## Cost: what the caller pays and what Jev spends\n\n`bin/jev-cost.mjs` measures both sides of the trade this project claims to make, on a page you\nname. Every snapshot, every tool result and every Jev call is measured as it happens — nothing\nis measured once and multiplied.\n\n```bash\nnpm run cost                                              # the built-in saucedemo + wikipedia cases\nnpm run cost -- --url https://example.com/ --goal \"Log in\" --value user=ada --value pw=secret\nnpm run cost -- --json > run.json                         # machine-readable\nnpm run cost -- --report run.json                         # re-print the table from a saved run\nnode bin/jev-cost.mjs --help                              # every flag\n```\n\nPer scenario it reports **caller tokens** (the text crossing the MCP boundary: every tool result\nplus the arguments the caller had to write, at chars ÷ 4 — an approximation, and the report says\nso), **Jev tokens and calls** (the API's own `usage.input_tokens`, exact), and wall-clock\nseconds. The scenarios are run on the same page toward the same goal so they compare: a\nPlaywright-MCP-style baseline that takes a fresh `page.ariaSnapshot({ mode: \"ai\" })` after every\naction, `browser_do`, each `browser_snapshot` option against the default, and `browser_read`\nagainst dumping the whole document.\n\nThe `net` column is caller tokens saved minus Jev tokens spent, one for one, and it goes negative\nwhen a scenario loses — on a small page Jev's spend and latency can outweigh the saving, and the\ntool prints that as a loss. Measured numbers and what they say about the older estimate are in\n[RESULTS.md](RESULTS.md).\n\nA run needs network and `TYPESAFE_API_KEY`, and costs API credits. `npm test` stays offline: the\nledger arithmetic is pure and tested in `test/cost.test.mjs`.\n\n## Benchmark\n\n```bash\nnode bench/run.mjs --set all            # base, hard, guard (+ bench/tasks.local.mjs if present)\nnode bench/run.mjs --only ti-login,drag\nnode bench/context-cost.mjs bench/results/<run>.json   # older one-sided estimate; see npm run cost\n```\n\nPrivate sites and credentials go in `bench/tasks.local.mjs` (git-ignored), exporting `LOCAL`.\n\n## Layout\n\n```\nsrc/session.mjs      JevBrowser: settle, snapshot, decide (1 or 2 stages), resolve, act, do, check, choose\nsrc/page-script.mjs  runs in each frame: elements, labels, state, visible text, metrics, dialogs\nsrc/page-model.mjs   pure helpers: diff between pages, counts, compact rendering\nsrc/webmcp.mjs       init script recording the page's WebMCP tools; result formatting\nsrc/prune.mjs        pure helpers: split page text into blocks, batch, rank, reassemble\nsrc/jev.mjs          System One API client\nsrc/flow.mjs         JSON flow runner\nbin/                 CLI and MCP server\n.claude-plugin/      Claude Code plugin manifest and the repo's own marketplace\n.mcp.json            the plugin's MCP server: npx jev-browser@<version>, key from plugin settings\nskills/jev-browser/  skill the plugin adds: how to write steps and handle each status\nscripts/             keeps plugin.json and .mcp.json on package.json's version\nbin/jev-cost.mjs     two-sided token ledger: caller tokens vs Jev tokens, measured per scenario\nbench/               tasks with ground-truth checks, runner, context-cost estimate\ntest/                offline fixture tests, MCP end-to-end test\nNOTES.md             design notes: what works with Jev, what doesn't, and why\n```\n\n## Releasing\n\nCI runs the offline tests on every push and pull request. To publish, bump the version and push\nthe tag; `.github/workflows/release.yml` tests, publishes to npm with provenance and creates a\nGitHub release:\n\n```bash\nnpm version patch            # or minor / major: commits and tags vX.Y.Z\ngit push --follow-tags\n```\n\n`npm version` also sets the version in `.claude-plugin/plugin.json` and the pinned\n`jev-browser@X.Y.Z` in `.mcp.json`, so the plugin always launches the release it ships with.\nCI checks that the three agree and runs `claude plugin validate . --strict` (`npm run validate`\ndoes both locally). Plugin users get the new version when the marketplace repo updates; the\ndirectory listing picks it up from the tracked branch.\n\nPublishing uses npm trusted publishing, set up once with\n`npx npm@latest trust github jev-browser --file release.yml --repo Ying-Kai-Liao/jev-browser --allow-publish`.\n\n## Privacy\n\njev-browser runs locally. It has no server of its own and collects no telemetry. To decide\neach action it sends the following to the TypeSafe System One API (`api.typesafe.ai`), or to\nOpenRouter (`openrouter.ai`) when you use an OpenRouter key, using your key:\n\n- the current page's URL, title, visible text and interactive elements, as well as the text\n  blocks `browser_read` ranks;\n- the step's `goal`, recent action history, and your `browser_check` and `browser_choose`\n  questions;\n- the `values` you pass, **except** those whose key names a secret (`password`, `pw`, `token`,\n  `secret`, `otp`, `card`, `cvv`, `cvc`, `ssn`, `api_key`, `pin`). Those are shown by key only.\n  Values typed into password fields are also redacted, and so is a secret value the page\n  shows back (in its text or a WebMCP tool's result).\n\nPlaywright types the real values locally. TypeSafe's (and OpenRouter's) handling of this data\nis covered by their own terms. Screenshots and snapshots go only to your MCP client. See [PRIVACY.md](PRIVACY.md).\n\n## License\n\nMIT\n","readmeFilename":"README.md"}