opencode browser Markdown PT

Installation and connection

1. What you need

ItemMinimum versionNote
Chrome or Chromium116The extension uses the side panel
Node.js20Only used to build and to install the plugin
npmships with Node—
OpenCode Terminalv2It 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.

  1. Open chrome://extensions and turn on developer mode;
  2. click Load unpacked and select the extension/ folder from the ZIP;
  3. in the terminal, inside the extracted package folder, run:
node scripts/install-plugin.mjs
opencode service restart
  1. open the side panel and click Connect; run opencode pair in 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:

  1. checks for Node.js 20+, npm and OpenCode v2+ (it stops with a clear message if anything is missing);
  2. installs the dependencies (npm install);
  3. builds the extension (npm run build) into dist/;
  4. copies the plugin and the agent template to the OpenCode plugins folder (npm run install:plugin);
  5. restarts the OpenCode service (opencode service restart);
  6. 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.sh restarts 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:

  1. open chrome://extensions;
  2. turn on developer mode (top right corner);
  3. click Load unpacked and choose the project's dist/ folder (not the root);
  4. 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:

  1. open chrome://extensions;
  2. 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)

  1. Open the panel: click the extension icon, or use the shortcut Ctrl+Shift+O (Command+Shift+O on macOS).
  2. The first time, the screen “Connect your browser to the OpenCode on your machine” appears.
  3. In the terminal, run:

bash opencode pair

  1. Copy the link shown (it is the same one that opens the OpenCode web interface) and paste it into the “opencode pair link” field.
  2. 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

MessageWhat 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:

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

StatusMeaningWhat to do
“Plugin connected”All good—
“Plugin not found — install the plugin and restart OpenCode”The plugin was not loadednpm run install:plugin + opencode service restart
“Plugin refused the connection — check the extension ID”The extension is not the expected oneReload the extension or adjust OPENCODE_BROWSER_EXTENSION_ID
“Plugin stopped responding — restart OpenCode”The plugin hung or the worker went to sleepRestart OpenCode
“Plugin disconnected — restart OpenCode to reconnect”The socket droppedRestart 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.