Help and reference
13. Notices and signals
| Signal | What it means |
|---|---|
| “!” badge on the icon | Pairing still needs to be configured |
| Badge with a number | How many conversations have news (at most 9) |
| Green/red/amber dot in the header | API online, offline or connecting |
| Connection banner | Explains the failure and offers Try again, Reconnect or Open settings |
| Status strip below the chat | Reconnection attempts and backend messages |
| Blue border on the page | The agent is acting on that tab; it has a Stop button |
| “tools connected” / “tools offline” | Plugin state in the composer footer |
| Sound + notification | Something happened with the panel closed (run finished, permission, question) |
| Temporary notice in the footer | Confirmation or error from one of your actions |
14. Common problems
| Symptom | Likely cause | What to do |
|---|---|---|
| The panel says OpenCode is not responding | Server stopped | Run opencode serve and click Try again |
| “OpenCode token invalid or expired” | Token revoked or replaced | Run opencode pair and paste the new link in the settings |
| “OpenCode took too long to respond” | Server stuck | Restart OpenCode |
| Tools offline | Plugin not installed or an old service still in memory | npm run install:plugin + opencode service restart |
| “Plugin refused the connection” | Extension ID different from the expected one | Reload the extension; if it persists, adjust OPENCODE_BROWSER_EXTENSION_ID |
The agent cannot find browser_tabs_close | Name reserved by another plugin | Use browser_tabs_close_tab and reschedule the tools |
| Code changes do not show up | Service worker cached | Reload in chrome://extensions |
| “Could not prepare the page…” | chrome:// page, Chrome Web Store or a blank tab | Open a normal page and try again |
| “DevTools is open on this tab…” | DevTools interferes with the automation | Close DevTools on that tab |
| “Ref … is inside an iframe…” | Coordinate-based action on an iframe element | Ask for the action by reference (click/fill in) |
| “Ref … not found” | The page changed after it was read | Ask the agent to read the page again |
| “Only http(s) tabs can be attached.” | Internal browser tab | Use a regular page |
| “The tab is in another window…” | The group belongs to another window | Open a tab from the conversation or move the tab to another window |
| “The file … exceeds the ~5 MB limit.” | Upload too large | Shrink the file |
| “No frames recorded…” | GIF without start | Ask to start the recording first |
| “Failed to generate the GIF (offscreen unavailable).” | The offscreen document did not start | Reload the extension |
403 error on the tools | Outdated relay token | Delete ~/.cache/opencode-browser/relay.json (or under $XDG_RUNTIME_DIR/opencode-browser/) and restart OpenCode |
15. Limits and privacy
- Everything is local: the extension talks to
127.0.0.1; the plugin listens only on loopback (ports 8799–8802) and requires a “hello” from the extension before serving. - The panel is a single view: two open windows show the same conversation.
- The conversation↔group bond does not survive closing Chrome completely.
- Up to 4 conversations with detailed state in memory at the same time.
- One streaming reply at a time, but several conversations can run in parallel.
- Automatic group creates one blank tab per conversation; groups of conversations deleted outside the extension are only released on the next browser start.
- The permission card is modal: while a request is open, the panel is covered — answer it (or use Esc) to continue.
16. Quick reference
Paths
| What | Where |
|---|---|
| Extension build | dist/ (it is the folder to load in Chrome) |
| Plugin and agent | ~/.config/opencode/plugins/ |
| Browser conversations | ~/.opencode-browser-extensions |
| Agent screenshots | ~/.cache/opencode-browser/capturas/ |
| Relay token and port | $XDG_RUNTIME_DIR/opencode-browser/relay.json or ~/.cache/opencode-browser/relay.json |
Useful commands
npm run build # generates dist/
npm run install:plugin # copies plugin and agent
opencode service restart # reloads plugin and agent
opencode pair # generates the pairing link
curl http://127.0.0.1:8799/health
Requests that work well
- “Open example.com and tell me the page title.”
- “Read the current page and list the menu links.”
- “Fill in the contact form with test data and show me a screenshot before submitting.”
- “Investigate why the Save button does not respond: check the console and the network.”
- “Look up the price of this product in three stores and put it in a table.”
- “Record a GIF showing the login step by step.”