---
title: "opencode-browser-agent plugin"
description: "OpenCode plugin for agent-browser: policy-first automation with persistent sessions, CDP auto-connect, devtools, and cross-platform installers."
author: "Mohammad-Pouya Ghourchiani"
canonical: "https://ghourchiani.ir/projects/opencode-browser-agent"
image: "https://ghourchiani.ir/og/mark-square.png"
updated: "2026-10-26"
lang: "en"
generated: "2026-11-02"
---
# opencode-browser-agent plugin

> **TL;DR:** OpenCode plugin for agent-browser — policy-first browser automation with persistent sessions, CDP attach, devtools, and cross-platform installers.

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):**

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

**From a local build (Windows PowerShell):**

```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
bash install.sh            # first-time setup
bash install.sh --update   # update
```

**Linux VPS (headless):**

```bash
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).

```bash
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.

## Links

- npm package: https://www.npmjs.com/package/opencode-browser-agent
- Repository: https://github.com/BTF-Kabir-2020/opencode-browser-agent
- Obscura backend docs: https://github.com/BTF-Kabir-2020/opencode-browser-agent/blob/main/docs/obscura.md