OpenCode Browser

Browser automation plugin for OpenCode.

Control your real Chromium browser (Chrome/Brave/Arc/Edge) using your existing profile (logins, cookies, bookmarks). No DevTools Protocol, no security prompts.

https://github.com/user-attachments/assets/1496b3b3-419b-436c-b412-8cda2fed83d6

Why this architecture

This version is optimized for reliability and predictable multi-session behavior: - No MCP -> just opencode plugin - No WebSocket port → no port conflicts - Chrome Native Messaging between extension and a local host process - A local broker multiplexes multiple OpenCode plugin sessions and enforces per-tab ownership

Installation

Help me improve this!

bunx @different-ai/opencode-browser@latest install

https://github.com/user-attachments/assets/d5767362-fbf3-4023-858b-90f06d9f0b25

The installer will:

1. Copy the extension to ~/.opencode-browser/extension/
2. Walk you through loading + pinning it in chrome://extensions
3. Resolve a fixed extension ID (no copy/paste) and install a Native Messaging Host manifest
4. Update your opencode.json or opencode.jsonc to load the plugin

To override the extension ID, pass --extension-id <id> or set OPENCODE_BROWSER_EXTENSION_ID.

Configure OpenCode

Note: if you run the installer you'll be prompted to include this automatically. If you said "yes", you can skip this part.

Your opencode.json or opencode.jsonc should contain:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@different-ai/opencode-browser"]
}

Update

bunx @different-ai/opencode-browser@latest update

How it works

OpenCode Plugin <-> Local Broker (unix socket) <-> Native Host <-> Chrome Extension

• The extension connects to the native host.
• The plugin talks to the broker over a local unix socket.
• The broker forwards tool requests to the extension and enforces tab ownership.

Agent Browser mode (alpha)

This branch adds an alternate backend powered by agent-browser (Playwright). It runs headless and does not reuse your existing Chrome profile.

Enable locally

1. Install agent-browser and Chromium:

npm install -g agent-browser
agent-browser install

1. Set the backend mode:

export OPENCODE_BROWSER_BACKEND=agent

Optional overrides: - OPENCODE_BROWSER_AGENT_SESSION (custom session name) - OPENCODE_BROWSER_AGENT_SOCKET (unix socket path) - OPENCODE_BROWSER_AGENT_AUTOSTART=0 (disable auto-start) - OPENCODE_BROWSER_AGENT_DAEMON (explicit daemon path)

Tailnet/remote host

On the host (e.g., home-server.taild435d7.ts.net), run the TCP gateway:

OPENCODE_BROWSER_AGENT_GATEWAY_PORT=9833 node bin/agent-gateway.cjs

On the client:

export OPENCODE_BROWSER_BACKEND=agent
export OPENCODE_BROWSER_AGENT_HOST=home-server.taild435d7.ts.net
export OPENCODE_BROWSER_AGENT_PORT=9833

Per-tab ownership

• Each session owns its own tabs; tabs are never shared between sessions.
• If a session has no tab yet, the broker auto-creates a background tab on first tool use.
• browser_open_tab always creates and claims a new tab for the session.
• Claims expire after inactivity (OPENCODE_BROWSER_CLAIM_TTL_MS, default 5 minutes).
• Use browser_status or browser_list_claims for debugging.

Available tools

Core primitives: - browser_status - browser_get_tabs - browser_list_claims - browser_claim_tab - browser_release_tab - browser_open_tab - browser_close_tab - browser_navigate - browser_query (modes: text, value, list, exists, page_text; optional timeoutMs/pollMs) - browser_click (optional timeoutMs/pollMs) - browser_type (optional timeoutMs/pollMs) - browser_select (optional timeoutMs/pollMs) - browser_scroll (optional timeoutMs/pollMs) - browser_wait

Downloads: - browser_download - browser_list_downloads

Uploads: - browser_set_file_input (extension backend supports small files; use agent backend for larger uploads)

Selector helpers (usable in selector): - label:Mailing Address: City - aria:Principal Address: City - placeholder:Search, name:email, role:button, text:Submit - css:label:has(input) to force CSS

Selector-based tools wait up to 2000ms by default; set timeoutMs: 0 to disable.

Diagnostics: - browser_snapshot - browser_screenshot - browser_version

Roadmap

• [ ] Add tab management tools (browser_set_active_tab)
• [ ] Add navigation helpers (browser_back, browser_forward, browser_reload)
• [ ] Add keyboard input tool (browser_key)
• [x] Add download support (browser_download, browser_list_downloads)
• [x] Add upload support (browser_set_file_input)

Troubleshooting

Extension says native host not available - Re-run npx @different-ai/opencode-browser install - If you loaded a custom extension ID, rerun with --extension-id <id>

Tab ownership errors - Errors usually mean you passed a tabId owned by another session - Use browser_open_tab to create a tab for your session (or omit tabId to use your default) - Use browser_status or browser_list_claims for debugging

Uninstall

npx @different-ai/opencode-browser uninstall

Then remove the unpacked extension in chrome://extensions and remove the plugin from opencode.json or opencode.jsonc.