opencode-browser-agent is an OpenCode plugin for agent-browser: browser automation for AI agents with persistent sessions, dev tools, cross-platform installers (Windows / Linux desktop / Linux VPS-headless), and a rewritten, policy-first skill.

Direct answer

It attaches to your already-running Chrome via --auto-connect (your logins and tabs stay), forbids killing or closing the browser, and ships one-command install/update scripts for Windows PowerShell and Linux/macOS. An optional, opt-in Obscura backend provides a lightweight local CDP engine; Chrome stays the default.

Why use it

Uses your real browser, not a throwaway one. Reuse your running Chrome — logins intact, no new profile.
Policy-first. A rewritten skill constrains how the agent drives the browser (no pkill, no hijacking unrelated tabs, privacy-respecting defaults) instead of leaving the model to improvise.
One-command install everywhere. Windows PowerShell, Linux desktop, and headless VPS, with a matching one-command update path.
Optional Obscura engine. Opt-in only, never automatic; see the docs.

Install

Prerequisites: OpenCode ≥ 2.0.0, agent-browser CLI (npm i -g agent-browser), Chromium (agent-browser install; on Linux add --with-deps).

From npm (easiest):

{ "plugins": ["opencode-browser-agent"] }

From a local build (Windows PowerShell):

powershell -ExecutionPolicy Bypass -File .\install.ps1        # first-time setup
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Update  # update

From a local build (Linux / macOS):

bash install.sh            # first-time setup
bash install.sh --update   # update

Linux VPS (headless):

npm i -g agent-browser
agent-browser install --with-deps
agent-browser doctor
bash install.sh

Then restart OpenCode — plugins load at startup.

Attach to your Chrome (CDP)

Chrome exposes CDP only when launched with --remote-debugging-port=9222, and that port belongs to one browser process (so it identifies the profile too).

agent-browser --auto-connect open <url>            # reuse running Chrome
agent-browser --auto-connect false --cdp 9222 open <url>  # attach by port

Known gotchas:

If ~/.agent-browser/config.json sets "autoConnect": true, every --cdp call fails with “Cannot use –auto-connect and –cdp together” — pair with --auto-connect false.
Recent Chrome can answer GET /json/version with 404/empty while CDP works fine — never diagnose attachment with /json*.
A stale DevToolsActivePort makes --auto-connect hang then fail with os error 10060 — check the port is really listening.
chrome://inspect “Target discovery settings” does not open a debugging port on local Chrome.

Read-only diagnostics: ss -ltnp | grep 9222 (Linux) / Get-NetTCPConnection -LocalPort 9222 (Windows).

Troubleshooting

“Browser not launched”: run agent-browser doctor first; on headless Linux/container use agent-browser install --with-deps and agent-browser open --args "--no-sandbox" <url>.
Console/cookies show empty: always use --json (agent-browser console --json).
Cookie banner not detected: agent-browser snapshot -i then click the matching @ref.
Session lost: do not run agent-browser close (it deletes cookies); navigate to new URLs or use --auto-connect.
Element not found: re-snapshot after navigation (agent-browser snapshot -i) for fresh @refs.

Limitations

CDP attach requires Chrome launched with --remote-debugging-port; --auto-connect only confirms a Chrome answered, not which profile/account. Verify identity (port, PID, tabs, visible account) before account-dependent actions.
Headless VPS has no GUI Chrome to attach to; --auto-connect is pointless there — start a fresh browser.
Login without a desktop: export cookies / restore auth.json / use --session-name.
Derived from opencode-agent-browser (MIT, Nicola Crotti); see NOTICE.

opencode-browser-agent plugin

Direct answer

Why use it

Install

Attach to your Chrome (CDP)

Troubleshooting

Limitations

Links

Direct answer

Why use it

Install

Attach to your Chrome (CDP)

Troubleshooting

Limitations

Links

Related expertise

Related writing

More projects