brw — Complete Chrome and Chromium control for agents

open source by Revitt

Control Chrome and Chromium completely. Quickly. With recipes.

brw gives any agent fast, inspectable control of real Chrome and Chromium. Stable refs replace pixel hunting, every action reports what changed, and deterministic recipes turn proven browser work into a two-call run.

Install brw See the proof

Latest release v0.13.5 · macOS · Linux · Windows

surface: 62 tools
fast path: 2-call recipes
clients: MCP + HTTP
licence: AGPL-3.0

The whole browser surface

More than clicks: tabs, groups, forms, files, console, network, responsive testing, downloads, artifacts and human hand-off — exposed as MCP and HTTP.

Fewer calls, smaller payloads

Stable refs, action observations, batched plans, bounded reads and on-demand tool disclosure remove repeat screenshots and unnecessary round-trips.

Teach it once. Run it exactly.

Turn stable browser work into immutable recipes with exact origins, declared risk and durable postconditions — then search and run in two calls.

Your real browser logins

Bridges to the installed, signed-in browser you already use — Chrome, Chromium, Edge, Brave, Vivaldi, Opera or Arc. The sites you're logged into, brw is too, and cookies and sessions stay on your machine.

Bind profiles to workspaces with MCPlexer →

ref

Find stable refs

Snapshot the actionable frontier or find one control by role, name, text or test id. brw returns stable refs like e17, not brittle selectors.

read

Act and read the change

Click, type, fill, select, drag, upload or commit. The action returns URL, focus and changed elements, so the agent does not spend another turn asking whether it worked.

observe

Promote the proven flow

Trace or draft the successful mechanics, validate the semantic targets and install an immutable recipe. Next time: search, pin and run.

known workflowtwo calls

01 / searchbrw_recipe_search { query, origin }

Returns id, version, digest, risk and score — never the private steps.

02 / runbrw_recipe_run { id, version, digest, inputs }

Returns status, attempts, timings and artifact handles.

Immutable identityAn id, semantic version and SHA-256 digest must all match.
Safe writesExact origins, one allowed actuation and durable postconditions.
Private by designRecipe bodies and credentials stay outside the public repo.

Semantic page control

The fast everyday surface, built around stable refs and small observations.

Snapshot and find interactive controls by role, name, text or test id
Read prose, headings, links, forms, tables, Open Graph and JSON-LD
Click, type, fill, select, press, scroll, hover, drag and upload
Wait and assert visibility, text, values and navigation outcomes
Discover and call WebMCP tools exposed directly by compatible web apps

Fast multi-step execution

Collapse browser work into fewer calls while preserving explicit checks.

Batch and plan many steps against one pinned tab
Pre-arm waits so fast page events are not missed
Cancel in-flight work and observe cheap page deltas
Trace a successful flow back into a replayable batch

Deterministic recipes

Move proven workflows out of prompts and into a private, reviewable runtime.

Semantic search over disclosure-safe recipe metadata
Immutable version and SHA-256 digest pinning
Exact-origin gates, declared inputs, risk and idempotency
Timers plus page, element, download, tab and network events

Profiles, tabs and isolation

The real browser stays visible, organised and under the operator's control.

Installed-profile bridge for existing logins and passkeys
One namespace per profile, plus tab leases and named tab groups
Background opens and pinned targets without stealing OS focus
Fresh incognito contexts on direct-CDP profiles

Debugging and evidence

See what the page, browser and server actually did.

Console messages, network resources and active request capture
Authenticated in-page request replay with mutation guards
Screenshots, element crops and Set-of-Marks overlays
Downloads, responsive device emulation and real window bounds

Browser-host artifacts

Large or sensitive evidence stays beside the browser until explicitly read.

Text, semantic JSON, screenshots, PDFs, downloads and short video
Opaque handles with bounded search, read, info and delete
TTL, per-item and total quotas, hashing and owner-only storage
Direct-CDP cookie controls for dedicated profiles; extension cookies stay blocked

Need the smallest possible prompt? Use --mcp-tools auto, core or minimal. Every tool remains discoverable and directly callable.

2.31×

faster event settling

Pre-armed semantic waits versus arming after a synchronous DOM reaction.

51.9×

less proxy transfer

A bounded browser-host read instead of hauling the full payload across HTTP.

6,332×

smaller capture result

A compact artifact handle instead of inline base64 for a 1.31 MB capture.

69.9%

less tool catalogue context

The default auto profile at startup versus advertising all 62 tools every turn.

Reproducible Apple M4 Max samples from September 2026. These are brw engineering probes, not Claude measurements. Methods and caveats →

brw vs Claude in Chrome

Infrastructure versus a finished assistant.

Claude in Chrome is polished and capable. brw wins when you need an open, agent-agnostic control layer, deterministic execution or an API you own. Here is the fair comparison.

Capability	brw	Claude in Chrome
What it is	Open browser-control infrastructure for agents and automation systems.	Anthropic's end-user browser agent inside Claude products.
Who can drive it	Any MCP client or HTTP client — Claude, Codex, Cursor, pi, your own service.	Claude Code, Claude Cowork and the Claude side panel.
Browser support	Chrome and Chromium, plus Edge, Brave, Vivaldi, Opera and Arc — any Chromium build, named with one flag. Local, or a remote browser host over SSH.	Google Chrome; other Chromium browsers are not supported.
Signed-in browser	Yes — bridge into an installed profile, or use a dedicated direct-CDP profile.	Yes — works alongside the user's signed-in Chrome session.
Control contract	Stable semantic refs, bounded reads, observations after actions, assertions, batch, plan, cancel and trace.	Reads, clicks, types, navigates and fills forms; also exposes screenshots, console, network and DOM context.
Efficiency evidence	Public local probes: 2.31× faster event settling, 51.9× less proxy transfer, 6,332× smaller capture results and 69.9% less initial tool context.	No equivalent low-level benchmark is published in Anthropic's feature guide; private brw runs were directionally faster, not a numeric public claim.
Reusable work	Private schema-validated recipes pinned by id, version and digest, with origin/risk/postcondition gates.	Recorded workflows in the classic side panel, reusable shortcuts and scheduled tasks.
Large outputs	Browser-host artifacts for text, JSON, images, PDFs, downloads and video, read back in bounded windows.	No comparable public artifact-handle API is documented.
Ownership	Self-hosted, AGPL-3.0 source, local data path, optional commercial licence.	Proprietary Anthropic service; available on paid Claude plans.

Compared from public documentation checked 10 September 2026. Read Anthropic's current feature guide. Claude is an Anthropic product; brw is independent and is not affiliated with or endorsed by Anthropic.

start heremacOS and Linux

$ curl -fsSL https://brw.donworks.co.uk/install.sh | sh

That command runs a shell script fetched over the network, so read it first. install.sh is served from this site as plain text, with no caching, and is the same file the command executes.

Detects your platform, resolves the version and prints the whole plan — archive name, source URL, install directory — before it downloads anything.
Verifies the archive's SHA-256 and its GitHub build-provenance attestation. A mismatch aborts before anything is written to disk.
Installs under ~/Library/Application Support/brw on macOS or ~/.local/share/brw on Linux, and symlinks brwd, brwctl, brwcheck and brw-devtools-mcp into ~/.local/bin. No sudo, nothing outside your home directory.
Runs brwctl setup.

It reads no input, which is what makes the pipe safe. BRW_VERSION, BRW_INSTALL_DIR, BRW_BIN_DIR, BRW_BASE_URL, BRW_NO_SETUP and BRW_SKIP_ATTESTATION change what it does.

homebrewmacOS and Linux

brew install don-works/tap/brw installs the same tree into the formula prefix, which is then the app directory: brwctl doctor --app-dir "$(brew --prefix brw)". Run brwctl setup afterwards. The tap is bumped by the release workflow, so brew upgrade tracks releases.

Open the tap

macOS pkgAdmin and MDM installs

A universal .pkg that installs machine-wide under /usr/local. Take this route when you are deploying to someone else's machine, or when policy requires a package your MDM can ship. It needs administrator rights; the one-line installer does not.

Open releases

linux.deb and .rpm

brw_<version>_linux_amd64.deb and the arm64 and .rpm equivalents, for systems that expect packages to come from the package manager. Installs to /usr/share/brw/.

windows.msi

brw_<version>_windows_amd64.msi and an arm64 build. Puts the brw commands on PATH and the extension, tests and licence under C:\Program Files\brw\share\.

setupWhat brwctl setup does

Inside the pipe it is non-interactive: it prints the plan, performs it and exits. On a terminal it asks first. brwctl setup --dry-run lists every action without performing one. Nothing it writes is outside your home directory and no step uses sudo.

Writes a browser profile policy at ~/Library/Application Support/brw/browser-profiles.json on macOS and ~/.config/brw/browser-profiles.json on Linux, merging into an existing one rather than replacing it.
Installs a background daemon for your platform — a LaunchAgent on macOS, a systemd user unit on Linux, a logon task on Windows — bound to 127.0.0.1:17310 for control and 127.0.0.1:17311 for the bridge. If a service already drives that profile or holds those ports, it reports what it found and writes nothing.
Registers brw with Claude Code through claude mcp add. --mcp-client codex or both covers Codex; --mcp-client none prints the mcpServers block for you to paste.
Installs the bundled agent skill into ~/.claude/skills/brw, ~/.agents/skills/brw and ~/.codex/skills/brw.
On macOS, turns off App Nap for the browser so a backgrounded window does not drop the bridge.
Runs the doctor check and prints what is left for you to do.

thenConnect a browser

Loading the extension is the one step brwctl setup cannot do for you. The bridge drives a browser you are already signed into, so that browser needs the brw extension. One permanent extension id, trusted by the daemon with no configuration:

amocjcgddnoakjijfggdpnefdnboilpe

Chromium: drop one policy file and it force-installs from brw's self-hosted package and update manifest, then auto-updates. Linux needs no MDM: policy JSON into /etc/chromium/policies/managed/. macOS uses a configuration profile, Windows a .reg file or the matching GPO.
Chrome: load unpacked today. chrome://extensions → Developer mode → Load unpacked → the extension/ folder. A Chrome Web Store build is being prepared for review. No listing exists yet, so load-unpacked is the Chrome path until one does.
Either way, open the extension's Options page and click Enable local browser control. It attempts no connection before you do. What it handles, and what it refuses, is in the extension privacy policy.

# setup prints this line with your workspace filled in
$ brwctl doctor --workspace brw-chrome-profile

# before the extension is loaded and the browser restarted,
# doctor reports it missing and exits non-zero. That is expected.

# then check it end to end
$ curl -s 127.0.0.1:17310/api/browser/open \
    -H 'content-type: application/json' \
    -d '{"url":"https://example.com"}'

# a visible tab opened; read its controls
$ curl -s 127.0.0.1:17310/api/page/snapshot | jq

# build from source instead
$ git clone https://github.com/Don-Works/brw.git
$ cd brw
$ make build
$ ./bin/brwd --mcp --http off

Remote browsers, multi-profile policies and SSH-first setups are in the install docs.

Capabilities of the brw extension bridge compared with the direct-CDP transport
Capability	Extension bridge	Direct CDP
The browser it drives	The Chrome, Chromium, Edge, Brave, Vivaldi, Opera or Arc you already have open and signed in.	A separate Chromium browser that brw launches, on a profile brw owns.
Where the logins come from	Sessions, cookies and passkeys that are already in that profile.	Sign in once with brwd --login; the profile keeps the session for later headless runs.
Chrome tab groups	Yes — chrome.tabGroups keeps the agent's tabs in one labelled group.	No. chrome.tabGroups is an extension API with no DevTools Protocol equivalent.
Incognito contexts	No.	Yes — brw_open_incognito opens an isolated context, brw_close_context disposes it.
Cookie tools	No. The extension refuses every cookie CDP method, HttpOnly included, to protect the signed-in profile.	Yes — brw_cookies lists, sets and deletes, HttpOnly cookies included.
Downloads	Files land in the browser's own download folder. Capturing the bytes as an artifact can need macOS Files & Folders consent; the metadata-only event does not.	Deterministic — files are staged in brw's private cache, no Downloads access needed.
Headless	No. --headless with --bridge is refused rather than ignored.	Yes, once the profile has been signed into.
How it starts	brwd --bridge, plus the extension loaded in that browser.	brwd --mcp --http off. No extension involved.

brw_identity reports which transport a namespace is on, so an agent can check before it assumes a capability. Read the auth model.

AGPL-3.0, all of it

Daemon, CLI and extension are in one public repository under one licence.

The extension ships unminified — every file in the package is a file in the repo
No telemetry, no analytics, no account, no Don Works service in the data path
Improvements flow back under the same licence; a commercial licence is available

Every artifact is attested

A checksum proves a file matches the release. An attestation proves which workflow and which commit built it.

GitHub build-provenance attestation is generated for every release artifact
SHA256SUMS.txt covers every installer, and install.sh checks both before it writes anything
Verifying needs gh 2.49 or newer, signed in — the bundle comes from the GitHub API

Code signing is not in place

No release artifact carries a platform code-signing signature today, on any operating system.

macOS packages are unsigned and not notarised; Windows packages carry no Authenticode signature
Linux .deb and .rpm are unsigned — there is no distribution GPG key to check them against
The signing pipeline is written and switches on when certificates are bought. No date is set

What a tag has to pass

A release builds only after the gate in the public workflow file.

Unit tests plus a deterministic real-browser functional suite
go vet, staticcheck and govulncheck for reachable vulnerabilities
A gitleaks scan of the full git history on every release

One permanent extension id

The daemon trusts that id with no configuration.

amocjcgddnoakjijfggdpnefdnboilpe, pinned by the public key in the manifest
Load-unpacked and self-hosted CRX builds resolve to the same id
A re-signed build gets a different id, and an unconfigured bridge will not accept it

What the extension cannot do

These refusals are implemented in the extension's service worker.

Cookie CDP methods are refused, HttpOnly cookies included
Storage, DOMStorage, IndexedDB, CacheStorage and Database domains are refused
Password, one-time-code and card fields are masked out of snapshots and reads

# the file matches the release
$ shasum -a 256 -c SHA256SUMS.txt

# the release came from this repository's workflow
$ gh attestation verify brw_<version>_macos_universal.pkg \
    --repo Don-Works/brw

Both checks run against artifacts from the releases page. The workflow that produces and attests them is in the repository.

safety

A normal browser, on a short leash

brw uses a normal visible browser and a persistent user profile. It does not add stealth code, CAPTCHA bypass, MFA bypass, fraud-check bypass or consent bypass. The installed-profile extension refuses HttpOnly cookie and bulk storage access; explicit cookie tools exist only for dedicated direct-CDP profiles, and the extension privacy policy lists every refusal. Browser-control HTTP binds to loopback by default, recipes declare their risk, and mutating requests are guarded. For remote use, prefer stdio MCP over SSH so the profile stays on the machine that owns it. Released under AGPL-3.0 — free to use, change and build on, with improvements shared back. If that doesn't fit your business, talk to Revitt about a commercial licence.

Browse the code