/jev-browser-use

name: jev-browser-use
description: Use when driving a web page in a browser — clicking, typing, navigating, logged-in or JS-rendered pages. Jev picks each step from the elements observed, under a host allowlist and a step budget.
version: 0.1.0
license: MIT
metadata:
  hermes:
    tags: [jev, typesafe, browser-use, web-automation]
    related_skills: [jev-computer-use]

Browser use with Jev

If a plain HTTP fetch can read it, fetch it and leave the browser alone. This skill is for pages that need interaction.

Jev never writes selectors, code or coordinates. It picks one operation and one target from the list of elements your browser tool observed. There are two ways to run it.

A. Your own browser tool + `jev choose` (works everywhere)

Same loop as `jev-computer-use`, with page elements as regions:

1. **Observe.** Read the page as an element list (accessibility tree, `read_page`, a snapshot). Keep role and a short label per element; leave page text out. 2. **Build the table.** One row per action you would be willing to take now: `click-r12`, `type-email-r7`, `scroll-down`, `back`, plus the mandatory `reobserve` and `abstain`. Text to type is decided by you and lives in your row, not in the request. 3. **Ask:** `jev choose < request.json` (Hermes: `jev_choose_action`). Schema `jev.action_choice_request_v1`; see `jev-computer-use` for the shape. 4. **Do that one action, observe again, verify.** Never retry a browser mutation blindly: look first.

**A "goal reached" row needs a second check.** Jev sees labels, not page text, so it can only guess from the link it followed that the goal is met. When it picks that row, ask a Noul over the page's own text (`jev ask`, state = goal + URL + about 6,000 characters of main text): *"From this page the visitor can do what the goal asks, now, without waiting for another person."* Measured on a request-access page reached by "Request free access": the choice said done at 0.73; the Noul said 0.07, and "a person must approve first" 0.91.

**Reviewing a site as a visitor.** Run a few persona goals ("start free now", "find the plan for 5 systems") with navigation-only candidates (no typing, no submit). Each run's path, and where it stops, is the finding. A page where every step stays under the 0.65 floor is a page with no clear next step for that visitor. Log the top three probabilities with their labels, so you can see *what* it was torn between. Headless Playwright on a throwaway profile is enough for path A.

B. Jev Ultrafast (fastest, and the default on a managed fleet that names it)

[browser-use/jev-ultrafast](https://github.com/browser-use/jev-ultrafast) (MIT) is a purpose-built loop with one Jev call per step. It is a separate install with its own Chrome under CDP. Run it through the bundled runner, which adds the guard rails it does not have:

python3 <this skill>/scripts/jev_browser_agent.py \
  --url 'https://en.wikipedia.org/wiki/Main_Page' \
  --goal 'Open the Wikipedia article about the Rosetta Stone.' \
  --allow-hosts wikipedia.org --expect 'Rosetta Stone' --max-ticks 10 --json

Set `JEV_ULTRAFAST_REPO` to your checkout (default `~/jev-ultrafast`; run `uv sync` in it once). Keep it separate from a fleet's pinned sandbox copy (Hermes `fleet-jev` loads `<hermes root>/shared/fleet-jev/sources/jev-ultrafast` directly), so patching one never changes the other. Without a text helper the runner still browses read-only (it found a pricing page in 3 ticks, about 2 s) and fails only when Jev chooses to type. **The runner brings its own browser**: when no CDP endpoint is given (`--cdp`, or `BU_CDP_WS` in the environment), it launches a headless Chrome on a throwaway profile and closes it on exit, so the person's everyday browser is never attached to and never has remote debugging enabled. The result reports `"browser": "owned"` or `"attached"`. Use `--no-launch-chrome` when you require an already-attached browser instead, `--chrome-path`/`BH_CHROME_PATH` to name the binary.

Exit 0 only when `--expect` is found in the live title, heading or URL; 4 unverified; 5 left the allowlist; 2 refused to start. Jev picks *where* to type; a separate text helper writes *what* (Jev does not generate text). Choose it once per machine in `~/.config/jev/browser.json` (`TEXT_MODEL`, `TEXT_MODEL_BASE_URL`, optional `TEXT_MODEL_RESPONSE_FORMAT`, `TEXT_MODEL_REASONING`; no credentials in it). Environment variables override it. `"TEXT_MODEL_PROVIDER": "claude-cli"` with `"TEXT_MODEL": "claude-haiku-4-5"` asks the signed-in Claude Code CLI instead, with no key at all (about 6 s per field). Ultrafast supports it on a local branch; see the fleet notes. Otherwise any OpenAI-compatible server works. A local one (127.0.0.1 or localhost) needs no key; LM Studio needs `"TEXT_MODEL_RESPONSE_FORMAT": "json_schema"`, because it rejects `json_object` (supported by Ultrafast with that variable). A remote one takes `TEXT_MODEL_API_KEY`, or `OPENROUTER_API_KEY` from the Keychain. Known gaps: shadow roots, iframes, canvas, file uploads, pop-up tabs. Report the gap; do not invent a DOM workaround.

Writing the goal: give the END STATE, not the hops

Jev Ultrafast is an end-goal loop — its own instruction to Jev is *"advance the user's entire goal from the current page"*. Give it one sentence describing where you want to end up and let it drive. **Do not plan hop by hop.** Feeding it one stepping stone at a time is slower, and it throws away the thing the loop is good at.

What a goal needs is the end state **plus what counts as progress**. Without the second part it will stop early, and it is right to: its instructions say `BLOCKED` means no operation can make progress, so if nothing on the page visibly serves the goal, it stops.

Measured on Wikipedia, starting at *Pizza*, target *Roman Empire*, links only:

| goal as written | result | |---|---| | "Reach the Roman Empire article by clicking links only. Do not use the search box." | **BLOCKED on tick 1, ze