browse README

README проекта с github.com/anomalyco/browse. Одним файлом markdown: 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)

Ищем в базе…

858 ·GitHub
Что это такое?Это позволяет вашим ИИ-агентам управлять вашим настоящим браузером Chromium, с вашими вкладками, входами в аккаунты и расширениями, через MCP-сервер browse и расширение для Chromium.
Это библиотека, с которой я работаю в коде, или приложение, которое я запускаю?Это инструмент, а не библиотека. Вы устанавливаете MCP-сервер browse, к которому обращается ваш агент, и расширение для Chromium, которое с ним связывается. Ничего не нужно импортировать в ваш собственный код.
Как это запустить?Выполните npx @opencode/browse install с Node.js 22.19+ или, в Windows, однострочник irm | iex в PowerShell. Установщик добавит browse в выбранных вами агентов и откроет страницу расширения в Интернет-магазине Chrome.
Что нужно сделать в первую очередь?Браузер на основе Chromium (Chrome, Edge, Brave, Arc, Vivaldi, Opera или Chromium) и opencode или другой MCP-клиент. Для варианта с npx также нужен Node.js 22.19+.
Есть какие-то подводные камни?Связывание происходит автоматически только после установки расширения из Интернет-магазина Chrome; в остальных случаях запустите browse pair вручную. Если браузер находится на другом компьютере, связь не шифруется самим browse, поэтому используйте приватную сеть.
Работает ли это в Windows, macOS и Linux?Да. В README описан однострочник PowerShell для Windows, а также указаны отдельные расположения конфигурации для macOS и Linux. Пути к конфигурации агентов различаются в зависимости от ОС.
Что агент на самом деле делает в моём браузере?Он открывает свои фоновые вкладки, сгруппированные так, чтобы не мешать вам, делает скриншоты, перехватывает сетевой трафик и записывает экран. Вкладки, к которым никто не обращается 10 минут, закрываются сами.
Могут ли агент и браузер работать на разных компьютерах?Да. Выполните browse set hostname 0.0.0.0 на машине агента и укажите расширению его адрес через приватную сеть, например Tailscale.
Работает ли это с агентами, кроме opencode?Да. Установщик может записать запись MCP для многих агентов, включая Claude Code, Cursor, Codex, Gemini CLI и режим агента VS Code Copilot.
Что происходит с вкладками агента при перезапуске ретранслятора?Они сохраняются. Сессия запоминает вкладки, которые открыл агент, поэтому перезапущенный ретранслятор снова их получает. Вкладка, которую вы одолжили, возвращается только в том случае, если она является страницей по умолчанию для сессии.
Какие есть похожие проекты?mcp-chrome, reticle, huashu-chrome, bb-browser, Endoplexity, api-anything, dev-browser, XActions
Автор
anomalyco
Размер
5.2 MB
Звёзды
858
Возраст
22 д
Коммиты · 90 дней