Installation and connection
1. What you need
| Item | Minimum version | Note |
|---|---|---|
| Chrome or Chromium | 116 | The extension uses the side panel |
| Node.js | 20 | Only used to build and to install the plugin |
| npm | ships with Node | — |
| OpenCode Terminal | v2 | It runs the models and the conversations |
The models are the same ones you already use in OpenCode: if your OpenCode works in the terminal, the extension works.
2. Install the extension
2.1 From the ready-made package (recommended)
Download the ZIP of the latest release and extract the files. The package includes the compiled extension, the plugin and the plugin installer; you do not need to run npm install or build the project.
- Open
chrome://extensionsand turn on developer mode; - click Load unpacked and select the
extension/folder from the ZIP; - in the terminal, inside the extracted package folder, run:
node scripts/install-plugin.mjs
opencode service restart
- open the side panel and click Connect; run
opencode pairin the terminal and paste the link shown into the panel.
2.2 From the project script
In the project folder:
./scripts/install.sh # Linux and macOS
.\scripts\install.ps1 # Windows (PowerShell 5.1+)
The script, in this order:
- checks for Node.js 20+, npm and OpenCode v2+ (it stops with a clear message if anything is missing);
- installs the dependencies (
npm install); - builds the extension (
npm run build) intodist/; - copies the plugin and the agent template to the OpenCode plugins folder (
npm run install:plugin); - restarts the OpenCode service (
opencode service restart); - waits for the plugin to answer at
http://127.0.0.1:8799/health.
If step 6 fails, the script itself warns you: open the extension panel and check.
install.shrestarts the OpenCode service. If you are using OpenCode in a terminal, the current session drops for a few seconds and reconnects — that is not an error.
2.3 Manually
npm install
npm run build
npm run install:plugin
opencode service restart
Then, in Chrome:
- open
chrome://extensions; - turn on developer mode (top right corner);
- click Load unpacked and choose the project's
dist/folder (not the root); - the OpenCode Browser icon appears in the toolbar.
2.4 After updating the code
Chrome keeps the service worker cached. Whenever you run npm run build again:
- open
chrome://extensions; - click Reload on the extension card.
Without this step, the old behavior stays live even with the new code.
3. Connect the extension to OpenCode (pairing)
- Open the panel: click the extension icon, or use the shortcut Ctrl+Shift+O (Command+Shift+O on macOS).
- The first time, the screen “Connect your browser to the OpenCode on your machine” appears.
- In the terminal, run:
bash opencode pair
- Copy the link shown (it is the same one that opens the OpenCode web interface) and paste it into the “
opencode pairlink” field. - Click “Connect to OpenCode”. When it finishes, the notice “Connected to OpenCode.” appears.
The link is single-use and expires in 5 minutes. If it expires, run opencode pair again. The previous token stays valid until you disconnect.
If pairing fails
| Message | What to do |
|---|---|
“Invalid link. Paste the full link shown by opencode pair.” | Copy the whole link, without cutting the final code |
| “The link must start with http:// or https://.” | You pasted only the code; paste the full URL |
| “The link does not contain /auth/connect/<code>.” | It is not a pairing link |
| “Could not reach OpenCode at … Is it running?” | The server is not up: run opencode serve |
“Link expired or already used. Run opencode pair again.” | Generate a new link |
| “The server did not return a session token.” | Incompatible OpenCode version: upgrade to v2 |
4. Install the tools plugin
The chat works with the API alone — for the agent to control Chrome, it needs the plugin:
npm run install:plugin
opencode service restart
The command copies, into the OpenCode plugins folder:
browser-relay.ts— the server that exposes the browser tools;opencode-browser.agent.md— the template of theopencode-browseragent.
and creates the default folder for browser conversations (~/.opencode-browser-extensions).
Check that everything is fine:
curl http://127.0.0.1:8799/health
In the panel, the composer footer shows “tools connected” when the plugin is active.
If the plugin does not connect
| Status | Meaning | What to do |
|---|---|---|
| “Plugin connected” | All good | — |
| “Plugin not found — install the plugin and restart OpenCode” | The plugin was not loaded | npm run install:plugin + opencode service restart |
| “Plugin refused the connection — check the extension ID” | The extension is not the expected one | Reload the extension or adjust OPENCODE_BROWSER_EXTENSION_ID |
| “Plugin stopped responding — restart OpenCode” | The plugin hung or the worker went to sleep | Restart OpenCode |
| “Plugin disconnected — restart OpenCode to reconnect” | The socket dropped | Restart OpenCode or use Reconnect plugin in the settings |
Keep a single copy of the plugin in the plugins folder. Two copies register the same plugin and one of them fails.