anomalyco/browser-control

Browser Control – A bridge that lets AI agents drive your real Chromium browser with Playwright

What it is

• A lightweight Node.js driver that runs a local relay and a browser‑extension. The relay receives Playwright snippets from an AI‑powered coding agent (or from the CLI) and executes them inside the user’s existing browser profile – keeping logged‑in sessions, cookies, extensions, etc.
• The project does not contain an LLM; it only provides the plumbing so an external agent can safely issue browser commands.

Key concepts

Concept	What it does
Relay	A tiny local server (127.0.0.1:19989) that talks to the extension via Chrome DevTools Protocol (CDP) and runs Playwright code on demand.
Extension	An unpacked Chrome/Brave/Edge/Arc extension shipped inside the npm package. It grants the relay the permissions needed to control tabs, capture media, and read cookies.
Session	A persistent sandbox that holds a single tab, JavaScript state (window), and a tiny journal (~/.browser‑control/sessions/<id>/journal.jsonl). Sessions survive across CLI calls; you can adopt an already‑open user tab.
Skill / MCP	Optional wrappers that expose the driver as a tool for agents that understand OpenAI‑style “skills” or the Multi‑Client‑Protocol (MCP).
Effect client	A TypeScript library (BrowserControlClient) that lets a program make authenticated fetch calls through the browser without running arbitrary Playwright scripts.

Main capabilities

• Run arbitrary Playwright snippets (browser-control execute …).
• Inspect pages safely with helpers like snapshot(), ariaSnapshot(), screenshotWithLabels(), and element refs that survive DOM changes.
• Human hand‑off (handoff(), demonstrate()) for CAPTCHAs, 2FA, or any step that requires a person.
• Read‑only sessions that block input commands while still allowing navigation and screenshots.
• Recordings – capture WebM/MP4 video of a tab, or a lightweight “flight‑recorder” buffer for debugging.
• Network capture – start a HAR‑style capture (browser-control network start …) that redacts secrets and writes a safe HAR file.
• Secret handling – the secrets sub‑command stores redacted values in a protected profile and lets downstream CLI tools run without ever seeing raw tokens.

Installation & first‑run

1. Node ≥ 22.19 and a Chromium‑family browser.
2. Install globally: npm install -g @opencode-ai/browser-control (adds browser-control and browser-control-mcp).
3. Load the unpacked extension from $(npm root -g)/@opencode-ai/browser-control/extension/dist via chrome://extensions → Developer mode → Load unpacked.
4. Test with a simple command, e.g.:

   browser-control execute 'await page.goto("https://example.com"); return {title: await page.title(), url: page.url()}'
   

   The CLI prints a session ID and a continuation command you can reuse.

Agent integration

• OpenCode plugin – opencode plugin add @opencode-ai/browser-control registers a @browser skill that automatically wires the skill, MCP entrypoint, and extension directory.
• Manual skill – npx skills add anomalyco/browser-control --skill browser-control -g makes the same workflow available to any agent that consumes the skills CLI.
• MCP – add a local MCP entry (browser-control-mcp) to your agent’s tool list if it prefers the MCP protocol.

Typical workflow

1. Create / adopt a session (browser-control session new myapp or session adopt …).
2. Execute Playwright (browser-control execute …).
3. Inspect (snapshot(), ref(), ariaSnapshot()).
4. Human step (await handoff("Solve CAPTCHA")).
5. Optionally record or capture network for later replay.
6. Close (browser-control session delete myapp).

Safety & limitations

• The extension requires broad permissions (debugger, tabCapture, etc.) and runs with the user’s full browser profile – it is intended only for trusted local use.
• Destructive CDP commands (clear cookies, close the whole browser) are blocked by the relay.
• The extension is currently distributed unpacked; a Chrome‑Web‑Store release is planned but not yet available.
• Playwright binaries are not bundled – the relay expects the host browser to be present.
• Video recording needs ffmpeg on the PATH and does not capture audio in CDP mode.
• The driver does not provide a remote, authenticated relay; it must run on the same machine as the browser.

Helpful commands

• browser-control doctor – sanity‑check the installation.
• browser-control status – shows whether the extension is connected.
• browser-control serve – run the relay in the foreground for debugging.
• browser-control journal --session <id> – view the JSON‑lines activity log.
• browser-control secrets … – manage redacted secret values for generated clients.

Bottom line Browser Control is a practical, open‑source bridge that lets AI coding agents (or any automation script) interact with a real user‑profile browser via Playwright, while giving developers fine‑grained controls for inspection, human hand‑off, recording, and secret‑safe network capture. It is a genuine tool in the AI‑agent‑automation space rather than a mere tutorial or curated list.