AnyBrowser

A browser-automation and agent runtime you can take apart. Three interfaces — the browser, the transport, the model — each with a registry and a conformance suite, so "implement your own" is something you can verify rather than hope for.

from anybrowser import open_engine

async with await open_engine("playwright") as engine:
    await engine.navigate("https://example.com")
    page = await engine.snapshot()
    await engine.click(page.elements[0])

Same code against Chrome attached to your own logged-in window, against Safari, or against a browser nobody has written a backend for yet.

Why this exists

Most browser automation assumes it owns the browser: a fresh profile, a clean window, a driver launched with the right flags. That assumption breaks the moment the job is to work in the browser a person actually uses — their tabs, their sessions, their logins, already open. You cannot ask them to log in again inside a throwaway profile, and you cannot attach WebDriver to a window that was not started for automation.

AnyBrowser assumes it does not own the browser. Every abstraction here comes from driving real Chrome and Safari windows in production, and every one of the three ideas below is a failure mode that cost someone a week.

Backends differ in kind, not quality. Safari has no CDP; Apple's Web Inspector protocol needs private entitlements. WebDriver cannot adopt your open window. So an engine declares what it can do and callers route around the gaps, instead of discovering them by catching an exception halfway through a task. See capabilities.

A no-op is not a success. The most common way an agent dies is a click that hit nothing, reported as "success", read back by the model as progress, and repeated forever. Every action returns changed alongside ok, and the conformance suite fails an engine that clicks dead space and calls it a change. See truthful outcomes.

The contract is executable. pytest --pyargs anybrowser_conformance --engine yours is the definition of a working backend.

Install

pip install anybrowser[playwright]      # the reference engine, easiest start
pip install anybrowser[chrome]          # attach to your own Chrome
pip install anybrowser[all]             # everything

Python 3.10+. import anybrowser pulls in no browser driver, no HTTP server and no LLM SDK — every backend is an extra.

The Playwright engine needs its browser binaries once, which pip cannot fetch for you:

playwright install chromium

Running a contract against something whose extra is missing skips rather than fails, and says which extra to install — so pip install anybrowser[all] is the shortcut if you would rather not think about it.

The three interfaces

Register with an entry point and yours is selectable by name everywhere:

[project.entry-points."anybrowser.engines"]
firefox = "my_package.engine:FirefoxEngine"

pytest --pyargs anybrowser_conformance --engine firefox     # the engine contract
pytest --pyargs anybrowser_conformance --transport grpc     # the transport one

Each flag selects a contract and skips the other. The suite is capability-gated. A backend that honestly declares it cannot drag is skipped, not failed. A backend that claims it can drag and then doesn't is failed — the suite tests truthfulness as hard as it tests function.

Full walkthrough: Writing an engine.

Engine status

The engine contract is 32 tests. The 4 skips are the capability gate working as intended: those tests assert the error an engine raises for something it does not declare, so they stand down for an engine that declares it. Run the whole suite directory and you will see more skips still — the transport and model contracts, idle because you passed neither --transport nor --model.

Pointing the engine contract at the remote engine grades the whole daemon stack — transport, protocol, codec, dispatch — and it scores the same 28 passed, 4 skipped over both the memory and websocket transports.

The Chrome engine has two pipes behind one interface. devtools talks to a browser started with --remote-debugging-port — standard, and the only mode that runs in CI. extension relays CDP through a browser extension and is the one that matters, because it attaches to the browser you already have open, with your tabs and your logins. Same engine either way; the connection reports which it is, and the declared attach_to_user_session capability is derived from that rather than asserted next to it.

Both Chrome pipes pass the contract. To drive the browser you already have open, see driving your own Chrome — note that --load-extension is silently ignored by Chrome stable, which is a memorable afternoon if nobody tells you.

Safari is implemented in both halves: a Swift helper for trusted background input and occlusion-proof capture, and a Web Extension for the DOM and pointer gestures. It needs a local build and a one-time Accessibility grant, so it skips rather than fails where that has not been done — see driving Safari.

Layout

src/anybrowser/
  core/          interfaces and value types — imports no backend
  engines/       chrome, safari, playwright
  perception/    turning a page into a snapshot, engine-agnostic
  daemon/        protocol, transports, the server that owns an engine
  agent/         planner, tools, executor, memory
  models/        LLM providers
conformance/     the executable contract
docs/            architecture, guides, ADRs

Docs

• Architecture overview
• Capabilities — why backends declare instead of raise
• Truthful outcomes — why changed exists
• Writing an engine
• Writing a transport
• Writing a model provider
• Driving your own Chrome
• Driving Safari
• ADRs — the decisions and what they cost

Contributing

Start with CONTRIBUTING.md. Good first issues are labelled good first issue; a new backend is the highest-value contribution there is, and the conformance suite means you can tell when it's done.

By participating you agree to the Code of Conduct. Security reports go to SECURITY.md, not the issue tracker.

License

Apache-2.0. See LICENSE and NOTICE.