browse README

The project's README from github.com/anomalyco/browse. As one markdown file: README.md.

browse: let your AI agents use your real browser. An isometric desk computer whose screen shows a web browser with an agent's tab group, cabled to a small relay box.

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.

Install

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.

What browse install does

  1. Puts browse in place (see above) and adds ~/.local/bin to your PATH when it copied browse there (--no-modify-path skips that).
  2. Adds the browse MCP server to your agents. In a terminal you get a picker: OpenCode and the agents found on this computer start checked (your last choice next time). Type to search all supported agents, ↑/↓ to move, Space or Tab to toggle, Enter to confirm. An agent running browse install sets up itself. Without a terminal OpenCode is the default. Edits keep the comments and formatting of each agent's config.
  3. Connects the extension. If no browser has browse yet, install opens it in the Chrome Web Store; add it, and install pairs it once it's there. If a browser already has it, install opens its setup page with a one-time pairing code in the link, so it pairs without copying anything. Over SSH or without a display it prints a code instead.

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
Supported agents and their user-level config files

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.

Pairing

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.

Browser on another computer

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:

  1. On the agent's machine run 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.
  2. In the browser, open browse's setup page, choose Connect an agent on another computer and enter the address and code (or use Relay address and Pairing code under advanced on the options page).

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

Updates are automatic. The relay checks once at start and then hourly, and installs a new version when no agent is using the browser:

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.

Uninstall

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.

Using it

Tools

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.

How it works

Three machines on one bench, cabled in a line: the agent's terminal calling browse, the relay box in the middle, and the computer whose browser the agent drives.

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.

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.

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.

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

Troubleshooting

Development

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.

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

browse (anomalyco/browse)

Searching Database…

858 ·GitHub
What is this?It lets your AI agents drive your real Chromium browser, with your own tabs, logins and extensions, through a browse MCP server and a Chromium extension.
Is it a library I code against, or an app I run?It's a tool, not a library. You install a browse MCP server that your agent calls, plus a Chromium extension that pairs with it. You don't import anything into your own code.
How do I get it running?Run npx @opencode/browse install with Node.js 22.19+, or on Windows run the irm | iex one-liner in PowerShell. The installer adds browse to your chosen agents and opens the Chrome Web Store page for the extension.
What do I need first?A Chromium-based browser (Chrome, Edge, Brave, Arc, Vivaldi, Opera or Chromium) and opencode or another MCP client. The npx route also needs Node.js 22.19+.
Any gotchas?Pairing happens by itself only once the extension is installed from the Chrome Web Store; otherwise run browse pair by hand. If the browser sits on another machine, the link isn't encrypted by browse, so use a private network.
Does it work on Windows, macOS and Linux?Yes. The README covers a PowerShell one-liner for Windows, and it lists separate config locations for macOS and Linux. Agent config paths differ per OS.
What does the agent actually do in my browser?It opens its own background tabs grouped out of your way, takes screenshots, captures network traffic and records the screen. Tabs nobody touches for 10 minutes close by themselves.
Can the agent and the browser run on different computers?Yes. Run browse set hostname 0.0.0.0 on the agent's machine and point the extension at its address over a private network such as Tailscale.
Does it work with agents other than opencode?Yes. The installer can write the MCP entry for many agents, including Claude Code, Cursor, Codex, Gemini CLI and VS Code Copilot agent mode.
What happens to agent tabs when the relay restarts?They're kept. A session records the tabs the agent opened, so a restarted relay reclaims them. A tab you lent is reclaimed only when it's the session's default page.
Creator
anomalyco
Size
5.2 MB
Stars
858
Age
22d
Commits · 90 Days