browser-use/jev-ultrafast

What it is

Jev Ultrafast is an open‑source browser agent that lets a small language model (LLM) drive a web page to achieve a single natural‑language goal. It works by repeatedly taking a snapshot of the page, turning every visible control (buttons, comboboxes, text boxes, etc.) into a numbered table, and then asking an LLM to pick one operation (e.g., CLICK, TYPE_TEXT, SELECT) and one target element from that table. The chosen operation is executed in the browser, the next snapshot is taken, and the cycle repeats until the model returns DONE or the task is verified as complete.

The key novelty is the dynamic, indexed action space: instead of a fixed set of hand‑written selectors, the agent builds a fresh list of possible actions on every loop iteration, so it can adapt to page changes, loading delays, and UI animations with only one network round‑trip per decision.

How it works (high‑level)

Snapshot – A tiny JavaScript (snapshot.js) runs in Chrome via the Browser Harness protocol, reads the DOM atomically, and returns a list of UI elements with their type, label, and current value.
Prompt construction – The Python side (model.py) formats the snapshot and the user‑provided goal into a short prompt for a text‑only LLM (e.g., OpenRouter’s inception/mercury‑2.5).
LLM decision – The model returns a JSON object containing:
- operation – one of CLICK, TYPE_TEXT, SELECT, SCROLL_UP, SCROLL_DOWN, WAIT, DONE, BLOCKED.
- target – the index of the element that can accept that operation.
- (for TYPE_TEXT) the text to type.
Execution – The chosen operation is sent to Chrome via the harness. Before executing, the agent validates that the target is still present, not occluded, and matches the expected control type.
Loop – Steps 1‑4 repeat until DONE is returned and an optional verification step confirms the goal was met.

Because the snapshot includes only visible text and control metadata, the model never sees large page blobs, keeping the prompt short and the latency low.

Why it matters

Speed – The demo completes a full Google Flights search in ~7 seconds, using only ~100 browser‑protocol calls (vs. >1 000 in a naïve implementation). The design deliberately minimizes round‑trips.
Generality – No site‑specific scripts are baked into the policy. The same model can be reused for completely different tasks (flights, Wikipedia navigation, hotel search) simply by changing the goal string.
Safety – The agent never emits raw selectors, JavaScript, or shell commands. All model output must be valid JSON and is re‑validated against the current DOM before execution.
Transparency – An optional UI inspector shows the numbered element table, operation probabilities, and target probabilities, making the decision process observable and debuggable.

Quick start (Linux/macOS, Python 3.11+)

# 1. Clone the repo
git clone https://github.com/browser-use/jev-ultrafast.git
cd jev-ultrafast

# 2. Install dependencies with uv (or pip if you prefer)
uv sync          # creates a virtual env and installs Python deps
# Browser‑harness (Chrome remote debugging) is pulled in automatically

# 3. Configure API keys
cp .env.example .env
# Edit .env and add:
#   TYPESAFE_API_KEY=…   # for the TypeSafe policy service
#   TEXT_MODEL_API_KEY=… # OpenRouter (or compatible) key

# 4. Run the demo UI
uv run jev
# Open http://127.0.0.1:8766 in Chrome, enable remote debugging when prompted,
# then click “Start demo → Run automatically”.

Using the library in code

from jev_ultrafast import Agent

with Agent(
    "https://www.google.com/travel/flights?hl=en",
    "Find one‑way flights from Zurich to London on September 20, 2026, "
    "for one adult in economy. Stop when matching flight options are visible.",
) as agent:
    for state in agent.run():
        print(state["elapsed_ms"], state["status"])  # progress info

Run with the same uv run --env-file .env python your_script.py command used for the demo.

The repository also ships small example scripts (examples/run.py, examples/flights.py) that show how to change the start URL and goal without modifying the core agent.

Limitations (as documented)

Works only with standard HTML/ARIA controls; complex widgets such as custom canvas editors, file‑upload dialogs, pop‑up windows, or deep shadow‑DOM trees are not supported in this MVP.
The LLM is used only for text generation (TYPE_TEXT). All other decisions (which button to click, which option to select) are made by the policy model that receives the indexed element table.
Outcome verification (DONE) is still a separate step – the agent does not assume the model’s claim is correct without checking the page.
Performance numbers are based on a handful of runs on a single Chrome profile; they are not a guarantee of reliability across sites or browsers.

Where to look next

agent.py – the full decision loop and hand‑off to the text helper.
snapshot.js – the atomic DOM extraction logic.
browser.py – low‑level Chrome DevTools Protocol wrapper.
model.py – construction of the operation/target heads and the call to the text model.
performance.md – detailed timing breakdown and reproducibility notes.

TL;DR

Jev Ultrafast is a compact, open‑source system that lets a small LLM control a real web browser by repeatedly (1) reading the page into a numbered list of UI elements, (2) asking the model to pick one operation and one target, and (3) executing that action. The design keeps the prompt tiny, the network traffic low, and the whole loop fast enough to complete a realistic flight‑search task in under 8 seconds, while remaining fully inspectable and safe.