You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Chrome automation plugin for OpenCode via WebSocket and Chrome Extension. Gives AI agents 165+ tools covering tabs, CDP debugging, network interception, visual clicking, session management, accessibility, advanced mouse/keyboard control, testing & mocking, profiling, stealth/anti-fingerprinting, proxy management, form automation, lighthouse audits, screencast recording, and more.
How it works
The system has two parts that talk to each other over a local WebSocket connection:
MCP Server — a Node.js process that OpenCode connects to via stdio. It exposes all tools to the AI agent and forwards commands over WebSocket to the extension.
Chrome Extension — a Manifest V3 service worker that receives commands from the MCP server and executes them inside the browser using Chrome APIs and CDP.
Click Load unpacked and select the extension/ folder.
4. Connect
Click the extension icon in the Chrome toolbar. The default endpoint is ws://localhost:3002. If the MCP server is running on a different machine or port, enter the correct address (e.g. ws://192.168.1.62:3002) and click Save Endpoint. The status indicator turns orange when connected.
5. Setup api & endpoint for Jev/Laya (Optional)
DECISION_ENDPOINT="https://api.typesafe.ai/v1/systemone"DECISION_API_KEY="sk_xxxxxx"# Model ConfigurationDECISION_MODEL="jev-latest"DECISION_TIMEOUT_MS=5000
Running locally from source
If you want to run the MCP server from a local clone instead of installing from npm:
git clone https://github.com/mytai20100/opencode-browser
cd opencode-browser/server
npm install
npm run build
Then point OpenCode at the local build by using the absolute path to dist/index.js in your config:
Replace /absolute/path/to/opencode-browser with the actual path where you cloned the repo. On macOS and Linux you can get it by running pwd inside the server/ folder. On Windows use the full path with backslashes, e.g. C:\\Users\\you\\opencode-browser\\server\\dist\\index.js.
After saving the config, restart OpenCode. The MCP server will start automatically whenever OpenCode launches.
For the extension, load the extension/ folder from the cloned repo the same way as the regular install: chrome://extensions > Developer mode > Load unpacked > select extension/.
Prompt tips
A few patterns that get the most out of the 165+ available tools:
Always start with the tool graph. Before any multi-step task, ask the agent to call chrome_get_tool_graph with a plain description of the goal. This gives it an ordered execution plan and tells it which tools to skip, saving unnecessary calls.
Use chrome_get_tool_graph with intent "fill in the login form and submit"
Use chrome_get_workflow_context before interacting with a page. It gives the agent a snapshot of all forms, inputs, and buttons so it can build accurate CSS selectors before clicking or typing anything.
Before clicking anything, call chrome_get_workflow_context to map the page first.
Attach the debugger early when working with APIs. If the task involves reading network traffic, attach CDP at the start so requests are captured from the beginning.
Attach the debugger to the current tab, then navigate to the page and capture all API calls.
Prefer chrome_get_content over chrome_get_html for reading pages. It returns clean visible text without markup, which is faster and uses fewer tokens. Only reach for chrome_get_html when you need the raw DOM structure.
Use chrome_find_text_on_screen + chrome_visual_click as a fallback. When a button has no reliable CSS selector, find its text on screen first, then click the returned coordinates.
Find the text "Submit Order" on screen and click it visually.
Save sessions to avoid re-logging in. After a successful login, call chrome_save_session with a name. Restore it at the start of future tasks to skip the authentication flow entirely.
Save the current session as "prod-login" after logging in.
Mock API responses for testing. Use chrome_intercept_request and chrome_mock_response together to inject fake data without touching the backend.
Intercept all requests to /api/orders and return a mocked empty array.
Tools reference
All tools are prefixed with chrome_. The agent can call chrome_get_tool_graph with a plain-text intent to get an optimized execution plan before starting any task — this prevents redundant calls and saves tokens.
Tabs — viewing and querying
Tool
Description
chrome_list_tabs
List all open tabs with id, title, url, active, pinned, muted, audible states
chrome_get_active_tab
Get info about the currently active tab
chrome_get_tab_info
Get detailed info about a specific tab by id
chrome_search_tabs
Search open tabs by title or URL keyword
Tabs — management
Tool
Description
chrome_navigate
Navigate a tab to a URL (defaults to active tab)
chrome_new_tab
Open a new tab, optionally with a URL
chrome_close_tab
Close a tab by id (defaults to active tab)
chrome_close_tabs
Close multiple tabs by id array
chrome_switch_tab
Focus a specific tab by id
chrome_duplicate_tab
Duplicate a tab
chrome_pin_tab
Pin or unpin a tab
chrome_mute_tab
Mute or unmute a tab
chrome_reload_tab
Reload a tab, optionally bypassing cache
chrome_move_tab
Move a tab to a different position or window
Windows
Tool
Description
chrome_list_windows
List all open windows with id, state, focused, tab count
chrome_new_window
Open a new browser window (supports incognito)
chrome_close_window
Close a browser window by id
Screenshot
Tool
Description
chrome_screenshot
Capture the visible area as a base64 PNG or JPEG
chrome_screenshot_element
Capture a specific element by CSS selector
chrome_screenshot_fullpage
Capture full page with scrolling and stitching
chrome_pdf_print
Save current page as PDF with custom options
Page interaction
Tool
Description
chrome_click
Click an element by CSS selector
chrome_double_click
Double click an element by selector or coordinates
chrome_right_click
Right click to open context menu
chrome_middle_click
Middle click (open in new tab)
chrome_drag_drop
Drag and drop from element A to B
chrome_type
Type text into an input element by CSS selector
chrome_hover
Hover over an element by CSS selector
chrome_select
Select an option in a <select> element
chrome_scroll
Scroll the page or a specific element by x/y pixels
chrome_scroll_to
Scroll an element into view
chrome_key_press
Dispatch a keyboard event (Enter, Escape, Tab, etc.)
Before starting any multi-step task, call chrome_get_tool_graph with a plain-text description of what you want to accomplish. It returns a ranked list of recommended tools, their cost (low / medium / high), prerequisites, suggested next steps, and tools to avoid. This is especially useful for agents that might otherwise make redundant or expensive calls.
intent: "capture network requests from the login page"
-> recommended: chrome_debug_attach -> chrome_navigate -> chrome_debug_get_network
-> avoid: chrome_screenshot, chrome_get_html
Requirements
Node.js 22 or later
Google Chrome (or a Chromium-based browser that supports Manifest V3)
OpenCode v1.18.31 or later
Troubleshooting
Connection lost
If you see connection errors:
Check extension status — verify the opencode-browser extension is enabled in Chrome.
Re-enable extension — if you disabled it, re-enable it and retry the browser action immediately.
Check browser is running — ensure Chrome or Edge is actually open.
Retry after readiness — the MCP server does not add extra backoff delay, so the next attempt can run right away.
Restart only if needed — restart OpenCode only if the browser stays unavailable after retrying.
The extension will display messages like [Opencode-browser] Connecting... in the popup while it attempts to reconnect.
Extension not loading
Check file location — ensure the extension/ folder is in the correct directory.
Check Developer mode — it must be enabled at chrome://extensions.
Check syntax — ensure the JavaScript files have no syntax errors.
Check logs — open the service worker DevTools from chrome://extensions and look for initialization errors.
Tools not available in OpenCode
Check MCP server status — ensure the MCP server started without errors (npx @mytai20100/opencode-browser).
Check config — verify your opencode.json has the correct MCP configuration.
Restart OpenCode — try restarting after any configuration change.
Check Node.js — run node --version to confirm Node.js 22 or later is installed.
Development
Building from source
git clone https://github.com/mytai20100/opencode-browser
cd opencode-browser/server
npm install
npm run build
To run locally during development:
npm run dev
To test changes to the extension, reload it at chrome://extensions after editing extension/background.js or extension/popup.js.
