fastbrowse 0.5.0

A browser agent that picks instead of generating.

Jev chooses each action, an LLM plans and reads, and code owns verification, safety and secrets.

Warning
This project is highly experimental and not recommended for production use yet.

Why

fastbrowse indexes the page into candidates and has Jev, a choice model, pick one, so it cannot click something that was never on the page. Every claim in an answer cites a verbatim quote from the page.

Against Browser Use

Measured on 2026-09-21 with the build released as 0.5.0: the same 14 answer tasks (lookups, sign-ins, checkout, Google Flights), three passes each, on the same kind of cloud browser, with no dollar limit.

The whole suite cost $0.38 here and $18.62 there. Both hosted failures are Google Flights, where it read the page's HTML, found no results table and answered with no price. 0.4.1 scored 41/42 at a $0.0057 median.

Median cost ratios by category: 56x for lookups, 58x for checkout and 196x for sign-ins. Jev selects actions through classification; planning, field text and reading can still require LLM generation.

Task medians show where time went:

Lookup medians included pypi-version at 11.2s, arxiv-title at 15.0s and github-license at 16.5s, where hosted Browser Use is faster on some. Google Flights took 109.3s here, slower than 0.4.1's 71.7s.

Every run, what it cost, and how a failure is counted.

Why fastbrowse, against each kind of agent

• LLM agents that generate actions (Browser Use and similar): Jev picks each action from the controls that are on the page, so there is no invented selector to retry. A task costs a fraction as much (a lookup, $0.0060 against $0.3313 median across the lookup category), and every claim in the answer links to the page text it came from.
• Choice-model navigators (jev-ultrafast): the same core technique, with page reading, cited answers, scoped secrets and an authorization gate. On the six navigation tasks both can run, fastbrowse passed 18/18 against 11/18, and jev-ultrafast is cheaper on every task both finish.
• Scripts: there are no selectors to maintain. The same agent handles a date picker, a checkout and a search box it has never seen.

Try it

Needs uv and Chrome (not needed with --cloud); uv fetches Python itself (3.13 or newer).

export AI_GATEWAY_API_KEY=...   # or TYPESAFE_API_KEY, for Jev
export OPENROUTER_API_KEY=...   # for the LLM that plans and reads
uvx fastbrowse "What is the title of the top story right now?" --start https://news.ycombinator.com/

uvx runs the published package in an isolated cached environment. uv tool install fastbrowse keeps it on your PATH, and uv add fastbrowse puts it in a project. Service keys can live in a .env file in the working directory; .env.example shows the settings. Values named by --secret must be in the process environment.

To work on fastbrowse itself:

git clone https://github.com/agent-labs-dev/fastbrowse.git && cd fastbrowse
uv sync --all-extras   # the extras carry mcp and browser_use_sdk, which the tests and evals import
cp .env.example .env
uv run fastbrowse "What is the title of the top story right now?" --start https://news.ycombinator.com/

Steps go to stderr; the status, cost, step count and answer go to stdout. --json prints every step, the quotes behind the answer, and cost by component.

export SAUCE_PASSWORD=secret_sauce
uv run fastbrowse "Log in as standard_user with the saved password and add the backpack to the cart." \
  --start https://www.saucedemo.com/ --secret password=SAUCE_PASSWORD --authorize

Signed-in sites

Sign in once by hand in a profile of its own, then point runs at it:

google-chrome --user-data-dir="$HOME/.fastbrowse/amazon" https://www.amazon.com/   # sign in, then close Chrome
uv run fastbrowse "Add a UGREEN USB-A to USB-C cable, 2m, to my cart." \
  --start https://www.amazon.com/ --profile ~/.fastbrowse/amazon --headed

On a cloud browser the profile lives on the Browser Use Cloud account rather than on disk, and --cloud-profile ID runs as it. Whoever signed that profile in did so once, in a browser of their own; the run inherits the cookies and no model is shown a credential:

uv run fastbrowse "Add a UGREEN USB-A to USB-C cable, 2m, to my cart." \
  --start https://www.amazon.com/ --cloud --cloud-profile prof_1234

Or from your vault, with the Bitwarden CLI unlocked. The item's saved URIs must match --start; values are then typed only on that origin, and models see only username and password:

export BW_SESSION="$(bw unlock --raw)"
uv run fastbrowse "Add a UGREEN USB-A to USB-C cable, 2m, to my cart." \
  --start https://www.amazon.com/ --bitwarden Amazon --profile ~/.fastbrowse/amazon --headed

Models

The LLM defaults to google/gemini-3.8-flash at low reasoning effort, with google/gemini-3.5-flash-lite for planning, proposing a direct address, typing field text and the done check's verdict. Override with FASTBROWSE_LLM_MODEL (every purpose), FASTBROWSE_LLM_MODEL_<PURPOSE> (PLAN, READ, FIELD_TEXT, SHORTCUT, RECOVER, COMPOSE, VERIFY) and FASTBROWSE_LLM_REASONING (low, medium, high).

Results

The exit code is 0 only for complete.

How it works

The LLM plans, reads and writes. Code owns the gates: irreversible actions stop without --authorize, secrets reach models by name only, and supported cookie banners are refused through autoconsent. More in docs/design.md.

How it compares

jev-ultrafast is Browser Use's navigation agent; fastbrowse shares its core techniques. Its column describes main as of 2026-09-18.

Embed it

uv add fastbrowse first, then:

import asyncio

from pydantic import BaseModel

from fastbrowse import run_task
from fastbrowse.models import Limits


class Release(BaseModel):
    package: str
    version: str


async def main() -> None:
    result = await run_task(
        "Find the httpx package and report its name and latest released version.",
        start="https://pypi.org/",
        output_schema=Release,
        limits=Limits(max_dollars=0.10),
    )
    print(result.status, result.data, f"${result.cost.known_dollars:.4f}")
    for evidence in result.evidence:
        print(f'  "{evidence.quote}" from {evidence.url}')


asyncio.run(main())

run_task(cdp_url=...) drives a browser that is already running, wherever it is, instead of starting one: the run opens its own tab and closes the tabs it owns. It leaves the browser and pre-existing tabs open; cookies and other changes made by the task can persist. Pass browser_api_key= to start a cloud browser; with neither argument, it runs local Chrome. Passing both is an error.

RunResult.citations is a tuple of Citation objects, also importable from fastbrowse. Each has id (the number in the answer), text (the Notes fact), requirement_id (or None), url, quote and deep_link. Each claim in result.answer carries numbered Markdown links to its supporting facts. Counts, totals and superlatives also cite the records they were derived from, including records read on earlier pages. Only verified Notes facts supply citation URLs and quotes; an answer citing an unknown reference fails the claim check, and the run falls back to an answer drafted from verified facts. Facts omitted from the answer have no citation, and citation numbers can have gaps.

Deep links follow the WICG Text Fragments syntax: url#existing-anchor:~:text=start. Text is percent-encoded, including hyphens, ampersands and commas. Whitespace is collapsed for the link; quote keeps the verbatim capture. Quotes over 120 characters with more than ten words use the first and last five words as text=start,end. An existing anchor is preserved; an old text directive is replaced. Pages that change or require a session may no longer show the quote.

To show a run as it happens, pass on_event=: a BrowserEvent arrives first with the live-view URL of a cloud browser, then a StepEvent per step. Config(step_frames=True) adds a PNG of the page each step acted on, for an interface that renders the run; a step whose page is showing a resolved secret sends no frame. StepEvent.step.facts (also StepResult.facts) holds only the facts added by that step: text, requirement id, quote, URL, deep link and reader (jev_choice or llm), with resolved secrets redacted before delivery. StepResult.note carries read outcomes, dispatch details, gate refusals or recovery guidance when available; it can be None for an ordinary successful action.

For continuous live images, pass an async on_frame handler accepting JPEG bytes. Frames follow the active tab and are acknowledged after delivery, with no fixed frame rate. Only the latest pending frame is kept. Handler failures are logged without stopping the run. Live frames and recordings are held back while a resolved secret may show on the page, as PNG step frames are. No handler means no live capture.

Jev comes from Typesafe directly or through the Vercel AI Gateway, whichever key is set (FASTBROWSE_JEV_SOURCE=typesafe or gateway picks the first provider when both are set). With both keys, a retryable HTTP failure that exhausts retries switches the run to the other provider. A custom FASTBROWSE_JEV_BASE_URL or nondefault FASTBROWSE_JEV_MODEL disables that failover. Any other source can be passed as run_task(jev=...), implementing async evaluate(state, questions); run_task(llm=...) accepts an implementation of the LLMClient.generate(...) protocol in fastbrowse.llm.

Use it from an MCP client

fastbrowse-mcp serves one browse tool over MCP, so Claude Code, Claude Desktop, Cursor or any other MCP client can hand it a task. It returns the answer, typed fields if asked for, the quotes behind them, the status and what to do about it, and reports progress on every step. The answer contains numbered Markdown links. MCP's citations list contains quote and url from the run's evidence; it does not expose the Python Citation ids, requirement ids or deep-link fields.

claude mcp add fastbrowse -e OPENROUTER_API_KEY=... -e AI_GATEWAY_API_KEY=... \
  -- uvx --from 'fastbrowse[mcp]' fastbrowse-mcp --max-dollars 0.25

For a client configured by JSON, such as Claude Desktop:

{
  "mcpServers": {
    "fastbrowse": {
      "command": "uvx",
      "args": ["--from", "fastbrowse[mcp]", "fastbrowse-mcp"],
      "env": { "OPENROUTER_API_KEY": "...", "AI_GATEWAY_API_KEY": "..." }
    }
  }
}

The server's flags decide what a calling model may do; a call can ask for less, never more.

Over HTTP, set FASTBROWSE_MCP_TOKEN in the environment or .env and every request but /healthz needs Authorization: Bearer <token>. The server refuses to bind anything but loopback without one. A run takes seconds to minutes, so raise the client's tool timeout if it has one (MCP_TOOL_TIMEOUT in Claude Code).

Safety model

• Irreversible actions. Jev judges clicks, including links, Enter presses and acceptance of confirm, prompt or before-unload dialogs. Code-selected pagination is exempt, as are authorized actions with sufficient confidence. A refusal appears as a failed step with a reason: an unauthorized, confident action stops at needs_confirmation; an uncertain action goes to recovery. This is a classifier, not a guarantee: a page can word a harmful control to look harmless.
• Secrets. Models see secret names only. A value is resolved at the moment of typing, only for its declared origin, and redacted from everything the run returns. A password field is typed only from a stored secret, never generated.
• Page content is data. Reader and verifier prompts say so, and completion is judged against quotes and page state rather than the model's say-so.

Evals and development

uv sync --all-extras                                         # the hosted-arm SDK too, which ty checks
uv run pre-commit install                                    # ruff and ty before each commit
uv run python -m fastbrowse.evals.runner                     # local fixtures, about $0.005 a task
uv run --extra browser-use python -m fastbrowse.evals.live                     # live head-to-head, 8 at a time
uv run --extra browser-use python -m fastbrowse.evals.live --arms fast        # ours alone
uv run --extra browser-use python -m fastbrowse.evals.live --suite heldout   # the never-debugged split
uv run ruff format . && uv run ruff check . && uv run ty check && uv run pytest
uv run python scripts/no_slop.py && uv run vale sync && uv run vale README.md CHANGELOG.md AGENTS.md docs src scripts tests

Grades use recorded requests, API truth, final page state or captured quotes where the arm exposes them. Hosted Browser Use exposes answer text only, which is checked against task truth. See docs/evals.md, docs/design.md, and docs/jev.md for every Jev assumption checked against Typesafe's documentation.

Changelog

What changed in each release is in CHANGELOG.md, and every GitHub release publishes that version's entry.

License

MIT, copyright Agent Labs. Adapted third-party code is credited in NOTICE.