anomalyco/browse: Let your AI agents use your real browser: an MCP server and a Chromium extension

Let your AI agents use your real browser: your tabs, your logins, your extensions. An MCP server and a Chromium extension, for opencode and any other MCP client.

Agents get a browse MCP server. They open and drive tabs with Playwright, take screenshots, capture network traffic and record the screen, in background tabs grouped out of your way. When it's your turn (a login, a 2FA prompt, a payment), they hand the tab back to you and continue once you click Continue.

It works in Chrome, Edge, Brave, Arc, Helium, Vivaldi, Opera and Chromium.

Install

curl -fsSL https://opencode.ai/browse/install | bash

On Windows, run irm https://opencode.ai/browse/install.ps1 | iex in PowerShell. With Node.js, npx @opencode/browse install works too: it installs the package globally so agents run browse from PATH. The installer puts the browse command in ~/.local/bin ($XDG_BIN_HOME when set) and runs browse install. It reads the channel's manifest from Anomaly's release service, downloads the binary for this computer, and verifies its size and SHA-256 before installing it. --channel stable|beta|dev picks the channel (stable by default); --version installs a specific version from npm, checked against npm's published SHA-512 integrity.

install keeps its files in the XDG folders (~/.config/browse, ~/.local/share/browse, ~/.local/state/browse and ~/.cache/browse; each honours its XDG_* variable), adds the browse MCP server to the agents you choose, and connects the extension:

1. Choose your agents. Detected agents start checked. Type to filter, use ↑/↓ to move, Space to toggle and

1. Add the extension. install opens browse in the Chrome Web Store; add it to your browser, and install pairs

That's it. Ask an agent to "open news.ycombinator.com and tell me the top story". Or paste this into opencode: "Install browse with npx @opencode/browse install."

Requirements: a Chromium browser, and opencode or another MCP client. The npx install also needs Node.js 22.19+.

Updates are automatic. A binary install reads its channel's manifest from Anomaly's release service at launch and at least once an hour; an npm install checks npm's dist-tag once an hour. When the current release is a different build, the relay reruns whatever installed browse in the background: a binary install reruns the install script that shipped with the browse version it's running (not one downloaded at update time), which checks the file's size and SHA-256 and replaces ~/.local/bin/browse; an npm install runs npm install -g @opencode/browse@. It restarts the relay when no agent is using the browser, without changing opencode's config. Running MCP servers swap to the new build between tool calls. Choose Only tell me or Don't check under Updates on the extension's settings page (or settings set autoUpdate=notify, or OPENCODE_BROWSER_AUTO_UPDATE=off). Agents can read the current value from status, but the MCP settings tool can't read or change update behaviour; it stays with you. browse update updates now; to go back, rerun the installer with --channel (binary installs follow the channel) or --version / npm install -g @opencode/browse@ (both from npm). The Chrome Web Store updates the extension.

Dev builds: every push to dev publishes one. npx @opencode/browse@dev install follows the dev channel: it downloads that build's extension into /extension, which you load unpacked once (browse extension shows the folder), and each update refreshes the folder and reloads the extension. A binary install follows the same dev channel with curl -fsSL https://opencode.ai/browse/install | bash -s -- --channel dev. The zip is also at https://anoma.ly/release/browse/extension/dev/chromium and each binary at https://anoma.ly/release/browse/cli/dev/.

There's nothing to sign in to. Each browser pairs with the relay once and gets a key of its own (see Security). If pairing didn't happen by itself, run browse install again to open a pairing link. To pair by hand, run browse pair (from a checkout: node cli/dist/cli.mjs pair). It starts the relay and waits. Open Extensions → browse → Options, expand advanced (or click Pair with a code), enter the printed code under Pairing code, and click Connect. The command confirms which browser paired. pair --list shows paired browsers; pair --revoke unpairs one.

From source

For contributors, or before a release you need is on npm:

git clone https://github.com/anomalyco/browse.git && cd browse && bun run setup

setup builds the extension and the CLI, adds the browse MCP server to your selected agents, and puts a one-time pairing code in browse/dist (good for an hour), which the extension exchanges for its own key when it first connects. install points every channel at the Chrome Web Store build; to use the build from your checkout instead, run node cli/dist/cli.mjs extension, which shows the browse/dist folder to load unpacked.

This needs Bun as well. A checkout never updates itself: run node cli/dist/cli.mjs update in your browse folder (or ask your agent to update browse). It pulls the new commits (fast-forward only, and never over local changes), rebuilds, and requests an extension reload. If the old extension cannot accept the request, reload browse on your browser's extensions page (↻). The manual equivalent of update is git pull && bun run setup. When there's an update, status, doctor, the extension's settings page and the agent (once per session) say so; browse checks the clone's remote at most every six hours. Set OPENCODE_BROWSER_UPDATE_CHECK=0 to turn the check off.

Other MCP clients

To skip the picker, name one or more agents. Explicit names take precedence over caller detection:

browse install -a claude cursor --agent gemini
browse install -a '*'   # every supported client, including those not installed (--all-agents)
browse install -y       # detected clients in an ordinary shell (--yes)

Inside a recognized agent, install targets that caller automatically. Without a terminal it configures the caller if it recognizes it. If it can't tell which agent ran it, it configures nothing and prints the MCP entry to add by hand, plus a browse install --agent command for each agent it found. Outside a recognized agent, -y sets up every detected agent instead of opening the picker, with or without a terminal. Re-running install is additive: unchecking a client skips it, not a removal. uninstall removes the entries browse wrote, not unrelated servers or conflicting entries.

For another stdio MCP client, add the browse command with the mcp argument. That works for a binary install and a global npm install, and keeps working when node changes under nvm/fnm:

{ "mcpServers": { "browse": { "command": "browse", "args": ["mcp"] } } }

browse install --agent '*' writes this for every agent it knows. An npx-only client can run npx @opencode/browse mcp instead, but that entry updates only when npx resolves a newer package.

Browser on another computer

When opencode runs on one machine and your browser on another (over Tailscale, say), the relay runs next to opencode and the extension connects to it across the network:

1. On the opencode machine, install browse, then run browse set hostname 0.0.0.0.

1. In the browser, open the extension's settings page (right-click the toolbar button, then Options). Under

browse set hostname 127.0.0.1 goes back to this computer only.

Pairing works as it does locally: the browser exchanges the code for a key of its own, and from then on both sides prove they hold that key on every connection, so anyone else on the network who reaches the port gets nothing. The connection itself isn't encrypted by browse; use a network that is (Tailscale or WireGuard), not the open internet. Set Relay back to localhost (or clear it) to go back to a relay on the browser's computer.

Using it

• Agents open their own tabs in the background of the window you last used, grouped together at the start of your

• Settings (the extension's options page; each applies right away, to new tabs for window and grouping):

• Hand an agent one of your tabs by clicking the toolbar button on it. The badge shows ON; click again to take

• Handoffs: the page shows a small card with the site's origin. Do the human part, then click Continue on the

• Recordings show only the page. Nothing from browse is drawn while a tab is recorded: no cursor, no

• Status: the extension's options page shows whether the relay is connected and paired, and can copy diagnostics.

Tools

| Tool | What it does | | --- | --- | | execute | Run Playwright code against the session's page (page, context, snapshot(), handoff(), …) | | session_new, session_list, session_use, session_reset, session_delete | Named sessions, each with its own tabs; they survive restarts | | session_adopt | Take over a tab you handed over with the toolbar button | | session_allowlist | Limit a session's tabs to the sites you name (also allowedOrigins on session_new) | | network (action: start, status, stop, cancel) | Capture traffic to a redacted HAR | | recording (action: start, stop, status, cancel) | Record a tab to MP4 or WebM (cursor: true draws the ghost cursor) | | flight_recorder (action: start, status, save_last, cancel) | Keep the last minute of video, save it when something breaks | | secrets_list | Site secrets you stored for the session's sites; agents type them with secrets.type() only on their sites, without seeing them | | secrets_status, secrets_refresh, secrets_run | Reuse captured credentials while keeping their values out of transcripts and artifacts | | tabs_cleanup | Close idle agent tabs (idleMinutes applies to the calling agent's own; other agents' wait for the idle setting) | | settings | Read or change the settings below when the user asks (never the security switches or update behaviour); the options page updates live | | status | Connection status |

The agent reference is cli/skills/browse/SKILL.md (browse skill prints it). The MCP server also sends a short usage guide in its initialize instructions. Everything is also a CLI: node cli/dist/cli.mjs --help.

How it works

The agent talks to the browse MCP server over stdio. The server hands each command to the relay on 127.0.0.1:19988, and the extension, connected to the relay over a WebSocket, runs it in your browser through chrome.debugger.

• The relay (cli/) is a local Chrome DevTools endpoint backed by the extension. It keeps named sessions,

• The extension (src/) connects to the relay and runs its commands through chrome.debugger. It keeps agent

• Quiet in the page. execute uses Patchright, which hides

Permissions: debugger, tabs, tabGroups, storage, alarms, offscreen and tabCapture (recordings), scripting (to add the handoff script only to tabs agents use, never to every page), webNavigation (to keep popups agents open with their other tabs), notifications (to tell you an agent needs you while it records a tab), and access to all sites so agents can work wherever you ask. Nothing leaves your computer except what your agent sends to its model provider; see the privacy policy.

Security

browse drives the browser you're signed in to, so it assumes that what an agent reads (a web page, an email) may try to steer it, and that other programs on your computer may try to use the relay.

• Relay token. Every HTTP request and CDP connection to the relay needs the token in

• Pairing. pair prints a short code (XXXX-XXXX) that works once, within 10 minutes; five wrong codes in a row

• Restricted execute. Agent code runs in a restricted JavaScript realm on the relay: it withholds Node

• CDP guardrails. Cookie reads return only cookies for the session's own pages; cookie writes are limited to

• Domain allowlists (opt-in). session new --allow-origin example.com (or session allow, or

• Site secrets. browse secrets add --origin https://example.com stores a password, key or (with

• Bot challenges. After a navigation, execute reports Cloudflare, Akamai, DataDome, PerimeterX, Imperva, AWS WAF,

• Your tabs stay yours. Agents use only tabs they opened or you lent them. The toolbar button always takes a tab

• Less on disk. Session journals are private (0700/0600), redact typed passwords, codes and tokens, and are pruned

Escape hatches. Set them in the environment you start opencode (or your MCP client) from; the relay inherits OPENCODE_BROWSER_* variables. Run node cli/dist/cli.mjs relay restart after changing them:

| Variable | Effect | | --- | --- | | OPENCODE_BROWSER_ALLOW_NODE=1 | Run execute code with full Node access (process, fs, import(), any file path) | | OPENCODE_BROWSER_ALLOW_ALL_COOKIES=1 | Let sessions read and write every cookie in the profile | | OPENCODE_BROWSER_ALLOW_FOREGROUND=1 | Allow page.bringToFront() | | OPENCODE_BROWSER_AGENT_WINDOW=separate | Open agent tabs in a separate window (current: in the user's window), overriding the options page's Where agents open their tabs | | OPENCODE_BROWSER_EXECUTE_SLICE_MS=2000 | Longest execute JavaScript may run without yielding before it is stopped (50 to 60000; every session waits meanwhile) | | OPENCODE_BROWSER_GHOST_CURSOR=1 | Show the agent cursor on every agent tab outside recordings (pages can see it); 0 keeps it off. Overrides the options page's Agent cursor | | OPENCODE_BROWSER_AUTO_UPDATE=notify | Installs: only show new versions (off: don't check; on: install them when idle, the default). Overrides the status page's Updates | | OPENCODE_BROWSER_HUMAN_INPUT=0 | Send input at full speed instead of human-like paths and pacing; 1 keeps them on. Overrides the options page's Human-like input | | OPENCODE_BROWSER_CHALLENGE_WAIT_MS=15000 | How long execute waits for a bot check the browser clears by itself (0 to 60000; 0 reports it without waiting) |

Troubleshooting

• node cli/dist/cli.mjs status shows the relay, the extension and every tab agents can use.
• node cli/dist/cli.mjs doctor checks the install.
• Logs: ~/.local/state/browse/logs/relay.log.
• Extension says another browser is connected: the relay is running an older browse that drives one browser profile at

• Extension says it's not paired (or that the relay was refused): run bun run setup again, then reload the extension

• Load unpacked fails, or the extension shows errors: load the browse/dist folder (built by setup), not

Development

bun install && bun run dev       # rebuilds dist/ on change; reload the extension to pick it up
bun run typecheck
bun run test                     # the extension and cli/ test suites (bun test), no browser needed
cd cli && bun src/main.ts status # the CLI from source
bun run release:check            # the store zip and npm tarball a release would publish, with its checks

cli/ is the npm package @opencode/browse with its own lockfile. The extension and the package share one version; RELEASING.md has the release flow (dev builds from every push to dev; stable releases only from the Release workflow in GitHub Actions).

Contributing

We don't take pull requests. Open an issue describing the bug or idea, and our agents usually turn it around fast.

License

MIT