Skip to content

README.md

Latest commit

 

History

History
72 lines (50 loc) · 2.81 KB

README.md

File metadata and controls

72 lines (50 loc) · 2.81 KB

OpenCode Chrome DevTools

Browser automation plugin for OpenCode using direct Chrome DevTools Protocol (CDP) connections.

This package now mirrors the browser tool example from OpenWork: no Chrome extension, no native messaging host, no local broker, and no hidden singleton browser state. Each tool call explicitly receives a browser_url, and tools can target a specific tab/window with target_id.

Why this architecture

  • Direct CDP keeps the package small and predictable.
  • browser_url makes the browser endpoint explicit and portable.
  • target_id supports multiple tabs/windows without per-session ownership state.
  • The same tools work with Chrome, Chromium, Electron, and remote/proxied CDP endpoints.

Configure OpenCode

Install or link the package, then add it to opencode.json or opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-chrome-devtools"]
}

Start A Browser

Start Chrome or Chromium with remote debugging enabled:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Then use http://127.0.0.1:9222 as browser_url.

For Electron apps, pass the app's exposed CDP endpoint as browser_url.

CLI Debugging

The CLI can list tools and run a tool directly after bun run build:

npx opencode-chrome-devtools tools
npx opencode-chrome-devtools tool browser_list --args '{"browser_url":"http://127.0.0.1:9222"}'
npx opencode-chrome-devtools tool browser_snapshot --args '{"browser_url":"http://127.0.0.1:9222"}'

If you omit browser_url in CLI calls, OPENCODE_BROWSER_URL is used, then http://127.0.0.1:9222.

Available Tools

  • browser_list: list page targets on a CDP endpoint.
  • browser_navigate: navigate a target to a URL.
  • browser_snapshot: get an accessibility tree snapshot with [uid] markers.
  • browser_click: click an element by snapshot UID.
  • browser_fill: fill an input by snapshot UID.
  • browser_eval: evaluate JavaScript in the page.
  • browser_screenshot: capture a PNG screenshot and return its saved path.

Typical Flow

  1. Run browser_list with a browser_url.
  2. Choose a target_id, or omit it to use the first page target.
  3. Run browser_navigate if needed.
  4. Run browser_snapshot to get UIDs.
  5. Use browser_click or browser_fill with a UID from the latest snapshot.
  6. Confirm results with browser_snapshot or browser_eval.

Troubleshooting

  • If browser_list fails, confirm the browser was started with --remote-debugging-port and that /json/list is reachable.
  • If browser_click or browser_fill says no snapshot is cached, call browser_snapshot first with the same browser_url and target_id.
  • If a proxied CDP endpoint returns localhost WebSocket URLs, the plugin rewrites them to the proxy host.