项目的 README,来自 github.com/anomalyco/browse。合并为一个 markdown 文件:README.md。
Let your AI agents use your real browser: your tabs, your logins, your extensions. A small native MCP server and a Chromium extension, for OpenCode, Claude Code, Codex, Cursor and any other MCP client.
Agents get a browse MCP server. They open tabs in the background, read pages, click, type, take screenshots,
capture network traffic and record the screen, in 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.
curl -fsSL https://opencode.ai/browse/install | bash
Or paste this into your agent: "Set up browse so you can use my Chrome: run
curl -fsSL https://opencode.ai/browse/install | bash". It sets browse up for the agent that ran it.
Other ways to install, all of which end in the same browse install:
| How | Command | Where browse lives, and what updates it |
|---|---|---|
| Install script (macOS, Linux) | curl -fsSL https://opencode.ai/browse/install | bash |
~/.local/bin/browse ($XDG_BIN_HOME when set); updates itself |
| Install script (Windows) | irm https://opencode.ai/browse/install.ps1 | iex in PowerShell |
%USERPROFILE%\.local\bin\browse.exe; updates itself |
| npx, bunx | npx @opencode/browse install |
copied to ~/.local/bin/browse once; updates itself from then on |
| npm | npm i -g @opencode/browse, then browse install |
npm's global browse; browse runs npm install -g to update |
| bun | bun add -g @opencode/browse, then browse install |
~/.bun/bin/browse; browse runs bun add -g to update |
| pnpm, yarn, volta | pnpm add -g / yarn global add / volta install @opencode/browse, then browse install |
that manager's browse; updated with the same manager |
There's always exactly one browse: a global package install is left to its package manager (nothing is copied next
to it, and a leftover ~/.local/bin/browse from an earlier install is removed), and agents run the same browse your
terminal does. If browse install finds another browse on your PATH it tells you which one and how to remove it.
The install script reads the channel's manifest from Anomaly's release service, downloads
the binary for this computer and checks its size and SHA-256 before installing it. --channel stable|beta|dev picks
the channel (stable by default); --version <version> installs a specific version from npm, checked against npm's
published SHA-512 integrity. With npm, @opencode/browse@dev is the dev channel. The npm package is a small Node
launcher (Node 22+) that runs the native binary npm installed for your platform.
browse install does~/.local/bin to your PATH when it copied browse there
(--no-modify-path skips that).browse install sets up itself. Without a terminal OpenCode is the
default. Edits keep the comments and formatting of each agent's config.Then ask your agent to "open news.ycombinator.com and tell me the top story". An agent that was already running needs a restart (or an MCP reload) to load browse.
browse install -a claude codex # these agents, without asking (--agent; names below)
browse install -a '*' # every supported agent, installed or not
browse install -y # every agent found on this computer
browse install --agent none # no agent: print the MCP entry to add by hand
CONFIG is $XDG_CONFIG_HOME or ~/.config. APP is ~/Library/Application Support on macOS, %APPDATA% on
Windows, or CONFIG on Linux. The paths below are defaults; a client's existing config or location override can apply.
| Agent (flag) | User config | Format / server key |
|---|---|---|
OpenCode (opencode) |
CONFIG/opencode/opencode.json or .jsonc |
JSONC · mcp.servers |
Claude Code (claude) |
~/.claude.json |
JSON · mcpServers |
Claude Desktop (claude-desktop) |
APP/Claude/claude_desktop_config.json |
JSON · mcpServers |
Cursor (cursor) |
~/.cursor/mcp.json |
JSON · mcpServers |
Codex (codex) |
~/.codex/config.toml |
TOML · mcp_servers |
VS Code, including Copilot agent mode (vscode) |
APP/Code/User/mcp.json |
JSONC · servers |
Windsurf (windsurf) |
~/.codeium/windsurf/mcp_config.json or existing CONFIG/devin/mcp_config.json (APP/devin on Windows) |
JSON · mcpServers |
Amp (amp) |
~/.config/amp/settings.json or .jsonc |
JSONC · literal amp.mcpServers |
Antigravity (antigravity) |
~/.gemini/config/mcp_config.json |
JSON · mcpServers |
Augment (Auggie CLI) (augment) |
~/.augment/settings.json |
JSON · mcpServers |
Cline (cline) |
~/.cline/data/settings/cline_mcp_settings.json; also recognizes the existing VS Code extension file in APP/Code/User/globalStorage/saoudrizwan.claude-dev/settings/ |
JSON · mcpServers |
CodeBuddy Code (codebuddy) |
~/.codebuddy/.mcp.json (or existing mcp.json) |
JSONC · mcpServers |
Cortex Code (cortex) |
~/.snowflake/cortex/mcp.json |
JSON · mcpServers |
DeepSeek Harness (dsh) |
$DSH_HOME/cordis.patch.yml (default ~/.dsh/cordis.patch.yml) |
YAML · insert patch row |
Factory Droid (droid) |
~/.factory/mcp.json |
JSON · mcpServers |
Gemini CLI (gemini) |
~/.gemini/settings.json |
JSON · mcpServers |
GitHub Copilot CLI (copilot) |
~/.copilot/mcp-config.json |
JSON · mcpServers |
Goose (goose) |
CONFIG/goose/config.yaml; Windows: APP/Block/goose/config/config.yaml |
YAML · extensions |
Grok Build (grok) |
~/.grok/config.toml |
TOML · mcp_servers |
Hermes Agent (hermes) |
~/.hermes/config.yaml |
YAML · mcp_servers |
Junie (junie) |
~/.junie/mcp/mcp.json |
JSON · mcpServers |
Kilo Code (kilo) |
CONFIG/kilo/kilo.json (also .jsonc, config.json) |
JSONC · mcp |
Kimi Code CLI (kimi) |
~/.kimi/mcp.json |
JSON · mcpServers |
Kiro (kiro) |
~/.kiro/settings/mcp.json |
JSON · mcpServers |
LM Studio (lm-studio) |
~/.lmstudio/mcp.json |
JSON · mcpServers |
Mistral Vibe (vibe) |
~/.vibe/config.toml |
TOML · [[mcp_servers]] |
Pi (pi) |
~/.pi/agent/mcp.json |
JSON · mcpServers |
Qoder CLI (qoder) |
~/.qoder/settings.json |
JSON · mcpServers |
Qwen Code (qwen-code) |
~/.qwen/settings.json |
JSON · mcpServers |
Roo Code (VS Code) (roo) |
APP/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json |
JSON · mcpServers |
Warp (warp) |
~/.warp/.mcp.json |
JSON · mcpServers |
Zed (zed) |
macOS: ~/.config/zed/settings.json; Linux: CONFIG/zed/settings.json; Windows: APP/Zed/settings.json |
JSONC · context_servers |
For any other stdio MCP client, run browse mcp:
{ "mcpServers": { "browse": { "command": "/home/you/.local/bin/browse", "args": ["mcp"] } } }
(browse install --agent none prints this with your path.) Re-running install updates the entries it wrote and
leaves servers named browse that it didn't write alone.
There's nothing to sign in to. Each browser pairs with browse once and gets a key of its own (see
Security). If pairing didn't happen by itself, run browse install again, or run browse pair: it
prints a one-time code (XXXX-XXXX, good for 10 minutes) and waits. Open Extensions → browse → Options, expand
advanced (or click Pair with a code), enter the code under Pairing code and click Connect. browse pair --list shows paired browsers; browse pair --revoke <browser> unpairs one.
When your agent runs on one machine and your browser on another (over Tailscale, say), browse runs next to the agent and the extension connects to it across the network:
browse install --remote (or browse set hostname 0.0.0.0 after installing). browse
then listens on every network, restarting the relay if it runs, and prints this machine's address and a pairing
code. Other computers reach only the extension link; the HTTP API answers on 127.0.0.1 only.The connection isn't encrypted by browse; use a network that is (Tailscale or WireGuard), not the open internet.
browse set hostname 127.0.0.1 goes back to this computer only.
Updates are automatic. The relay checks once at start and then hourly, and installs a new version when no agent is using the browser:
~/.local/bin/browse after checking its size and SHA-256;latest, or dev/beta for those builds) and run the package manager that
installed them (npm install -g, bun add -g, pnpm add -g, yarn global add, volta install) into the same
place.The relay restarts on the new version when it's idle; agent tabs stay open and come back. A running MCP server keeps
working with the newer relay until the agent restarts it. browse update updates now and browse update --check only
looks. Choose Tell me or Off under updates on the extension's options page, or run browse update --mode notify|off (OPENCODE_BROWSER_AUTO_UPDATE=off in the environment overrides both). To go back, rerun the install
script with --channel <channel> or --version <version>, or install @opencode/browse@<version> with your package
manager. The Chrome Web Store updates the extension.
Dev builds: every push to dev publishes one: curl -fsSL https://opencode.ai/browse/install | bash -s -- --channel dev, or npx @opencode/browse@dev install. The store extension works with dev builds. To try the dev
extension too, download https://anoma.ly/release/browse/extension/dev/chromium, unzip it, turn on Developer mode on
your browser's extensions page, click Load unpacked, pick the folder and run browse pair (browse extension
prints these steps on the dev channel). Remove the store extension first so only one browse runs in that profile.
browse uninstall
It removes browse from every agent config it was added to, stops the relay, deletes ~/.local/bin/browse (for the
install script and npx installs), the PATH line it added and browse's files. A global package stays with its package
manager: uninstall prints the command (npm rm -g @opencode/browse, bun remove -g @opencode/browse, ...). Remove the
extension from your browser to finish.
navigate without a tab opens a new background tab and returns its id; every other call
passes that tab. Agents use the tab ids they opened or were given, and leave other tabs alone unless you ask.
Tabs can be opened with options that stick: group (the tab group's title, and a handle to close them together),
allowedOrigins, readOnly, keepVisible and browser. Popups a page opens become agent tabs too.tabs with action: "new" and an id like work-mail opens
that tab once: asking again returns the same tab without navigating it, and every tool takes work-mail as tab.
The id lasts while the browser runs, through service-worker restarts. An extension update or reload keeps it only
for tabs in browse's agent group (grouping on); lent and ungrouped tabs get a new id then, and a browser restart
starts over. A tab opened this way is never closed as idle: only an agent or you close it. tabs lists each tab's
id, url, title, group, last use and whether a call is running in it.chrome-macbook); status lists them, and new
tabs open in the default browser unless browser names another.settings tool
when you ask them to.OpenCode, which composes tools in code mode, gets the plain tools. Every other MCP client gets execute, status and
tabs; execute runs JavaScript that can call all of them. The relay decides by the client's name
(OPENCODE_BROWSER_TOOLS=plain|execute|all on the relay overrides it).
| Tool | What it does |
|---|---|
navigate |
Open a page: without tab, in a new background tab whose id it returns |
snapshot |
A compact outline of the page with refs (e12) for the other tools, iframes included; scopes to the page's main area when there's exactly one and says what it left out |
click, fill, type, press, select, hover, drag, scroll |
Act on a ref, selector or point, with human-like input |
wait_for, dialog, upload, eval |
Wait for text, a URL or an element; answer dialogs; set files; run JavaScript in the page |
screenshot, screenshot_diff |
The viewport, full page, an element or a rectangle; compare with a baseline |
network, console |
Capture a tab's traffic (credentials redacted) or its console messages and errors |
recording |
Record a tab to a video file |
emulate, webmcp |
Viewport, color scheme, user agent, geolocation and more; tools a page offers through WebMCP |
tabs |
List, open or close tabs (group closes a whole group; an id names a tab for good, and opens it if it's missing) |
handoff, demonstrate |
Ask you to do something only a person can do; ask you to show a flow while it records your steps |
settings, status |
Read or change your settings when you ask; the relay, browsers, pairing state and what to do next |
execute |
For other clients: JavaScript with a Playwright-style page, snapshot(), ref(), handoff(), state and browse.<tool>(). Each result starts with the tab it ended in, to pass back as tab |
Everything is a CLI too: browse navigate https://example.com prints the new tab's id, then browse snapshot --tab <id>, browse click e12 --tab <id>, browse execute --file script.js. browse tools lists them and browse <tool> --help shows a tool's options.
The agent starts browse mcp, a small stdio proxy, which starts the relay on demand and forwards each call to it on
127.0.0.1:19988 (or the next free port from 19990–19997 when another program holds it). The extension connects to
the relay over a WebSocket and runs its commands in your browser through chrome.debugger.
browse serve, in rust/) keeps agent tabs, handoffs, recordings and network captures, talks the
Chrome DevTools Protocol to each tab, and runs execute scripts in an embedded JavaScript engine (QuickJS). It
exits when nothing uses it.src/) runs the relay's commands through chrome.debugger, keeps agent tabs in collapsed groups
by default (or their own window), closes idle ones, and shows the toolbar badge and the handoff card.Permissions: debugger, tabs, tabGroups, storage, alarms, scripting (to add the handoff card only to tabs
agents use), 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.
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.
~/.local/share/browse/relay-token (readable only by
you). The MCP server and CLI read it for you. The relay listens on 127.0.0.1 only (unless you open it with set hostname, and then only the extension link) and refuses cross-site browser requests and foreign Host headers.OPENCODE_BROWSER_EXTENSION_ORIGINS).execute is sandboxed, not a boundary. Scripts run in QuickJS inside the relay with CPU, memory and time
limits, no Node, network or file access beyond the file roots (temp folders and OPENCODE_BROWSER_FILE_ROOTS).
Treat code an agent runs as code running as you. The relay starts with an allowlisted environment, so your API keys
aren't in it.allowedOrigins limits navigations, top-level documents and the tabs and popups
an agent opens; requests a page makes itself (fetch, XHR, images, scripts, iframes) are not filtered. readOnly
refuses clicks, hover, drag, typing, key presses, filling, selecting, uploads and navigation commands after the tab
opens. Scrolling to an element or to the page's edges still works. eval and webmcp still run JavaScript in the
page: they can read everything the page can, make requests as the page, and change it (click, submit, navigate).
Snapshots, screenshots and the cookies the page itself can see stay readable. These keep an agent from wandering: for
pages you don't want an agent to read, don't open them in browse.fill hides values only for password and one-time-code fields. Snapshots leave out what's
typed in editable fields, but not other page text. Network capture redacts credentials by name and shape (auth and
API-key headers, cookie values, secret-named fields, token-like path segments), so a value under an ordinary name can
still come through. eval results, console messages, page text and screenshots are returned as they are.origin and results are
whatever a page supplies; browse doesn't verify them, and an annotation like readOnly is only the page's word. Treat
them like any other page text, not as instructions from the user.Escape hatches, set in the environment you start your agent from. The relay inherits OPENCODE_BROWSER_* variables
when it starts: it stops after 30 minutes without use, or run browse restart from a shell with the same variables:
| Variable | Effect |
|---|---|
OPENCODE_BROWSER_ALLOW_ALL_COOKIES=1 |
Let tabs read and write every cookie in the profile |
OPENCODE_BROWSER_ALLOW_ALL_STORAGE=1 |
Let tabs use every site's storage, and load resources from any host with your credentials |
OPENCODE_BROWSER_ALLOW_FOREGROUND=1 |
Allow bringing a tab's window to the front |
OPENCODE_BROWSER_ALLOW_FILE_URLS=1 |
Allow file: URLs |
OPENCODE_BROWSER_FILE_ROOTS |
More folders tools may read and write (path-list separated) |
OPENCODE_BROWSER_AGENT_WINDOW=separate |
Open agent tabs in a separate window (current: in yours), overriding the options page |
OPENCODE_BROWSER_HUMAN_INPUT=0 |
Send input at full speed; overrides the options page |
OPENCODE_BROWSER_AUTO_UPDATE=notify |
Only tell about new versions (off: don't check; on: install them, the default) |
OPENCODE_BROWSER_CHALLENGE_WAIT_MS=15000 |
How long to wait for a bot check the browser clears by itself |
OPENCODE_BROWSER_EXTENSION_TIMEOUT_MS=30000 |
How long the relay waits for the extension to answer a command |
OPENCODE_BROWSER_PING_TIMEOUT_MS=10000 |
How long a ping may go unanswered before the browser counts as asleep |
OPENCODE_BROWSER_PORT=20000 |
Pin the relay's port, with no fallback. The extension finds only browse's own ports (19988, 19990–19997) by itself, so enter localhost:<port> as its relay address when you pair |
OPENCODE_BROWSER_TOOLS=plain|execute|all |
Which tools every client gets |
browse status shows the install, the agents browse is set up in, updates, the relay, the extension and agent tabs,
and says what to do when the extension is missing, unpaired, closed or out of date. Agents get the same from the
status tool.browse install.OPENCODE_BROWSER_EXTENSION_TIMEOUT_MS and
OPENCODE_BROWSER_PING_TIMEOUT_MS.~/.local/state/browse/logs/relay.log.OPENCODE_BROWSER_PORT.browse install again, or browse pair and enter
the code in the extension's options.bun install && bun run dev # rebuilds the extension into dist/ on change; load it unpacked, reload to pick it up
bun run typecheck && bun test ./test
cd rust && cargo test --workspace && cargo run -p browse -- status
A build from a checkout (cargo run -p browse -- install) is used in place and never updates itself. The extension in
dist/ keeps the manifest key, so it loads with the unpacked ID the relay trusts; run browse pair to pair it.
RELEASING.md has the release flow (dev builds from every push to dev; stable releases only from the
Release workflow in GitHub Actions), and rust/PLAN.md the layout of the Rust crates. cli/ is the
earlier TypeScript implementation, kept as a reference.
We don't take pull requests. Open an issue describing the bug or idea, and our agents usually turn it around fast.