fastbrowse 0.3.1

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

Most browser agents generate each action from a screenshot. 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

The same 14 answer tasks (lookups, sign-ins, checkout, Google Flights), three passes each, on the same cloud browser with the same limits (30 steps, $0.25, 300s):

Every one of Browser Use's 28 failures ran past the $0.25 cap. In an earlier run with a $0.60 cap, it passed 6 of 8 such tasks at about 100s and $0.63 each. A later single pass of fastbrowse on current main passed all 21 tasks, answer tasks included (14/14, 21.5s median, $0.013). Tasks, method and per-category results.

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 thirty-fifth as much, and every claim in the answer cites a verbatim quote.
• Choice-model navigators (jev-ultrafast): the same core technique, plus everything a real task needs. fastbrowse reads pages and returns cited answers, signs in without showing a model the password, and stops before anything irreversible. On the six navigation tasks both can run, it passes 18/18 against 11/18.
• 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 3.14 itself.

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 without installing anything. uv tool install fastbrowse keeps it on your PATH, and uv add fastbrowse puts it in a project. Keys can live in a .env file in the working directory instead of the environment; .env.example lists every setting.

To work on fastbrowse itself:

git clone https://github.com/agent-labs-dev/fastbrowse.git && cd fastbrowse
uv sync
cp .env.example .env
uv run fastbrowse "What is the title of the top story right now?" --start https://news.ycombinator.com/

   0 read  -> executed
complete ($0.0071, 1 steps)
The top story on Hacker News is titled "...".

Steps go to stderr and the answer 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. Values are typed only on a site the item's saved URIs cover, 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 and typing field text. 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 cookie banners are refused before they paint. More in docs/design.md.

How it compares

jev-ultrafast is Browser Use's navigation agent (a measured 7.1s Google Flights run); 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())

complete {'package': 'httpx', 'version': '0.28.1'} $0.0114
  "httpx 0.28.1" from https://pypi.org/project/httpx/
  "pip install httpx" from https://pypi.org/project/httpx/

Jev comes from Typesafe directly or through the Vercel AI Gateway, whichever key is set (FASTBROWSE_JEV_SOURCE picks when both are, FASTBROWSE_JEV_BASE_URL adds a proxy). Any other source can be passed as run_task(jev=...), an object with one evaluate(state, questions) method; the LLM works the same way.

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.

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 and every request but GET /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. Before any button or submit, Jev is asked whether it commits something that cannot be undone. Without --authorize, a yes stops the run. 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. Every prompt says 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, under half a cent a task
uv run --extra browser-use python -m fastbrowse.evals.live   # live head-to-head; --arms fast skips hosted
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 docs src scripts tests

Grades come only from things the agent cannot write: requests the fixture server recorded, truth from a site's own API, or the URL the browser ended on. See docs/evals.md, docs/design.md, and docs/jev.md for every Jev assumption checked against Typesafe's documentation.

License

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