Browser Control CLI
A local Playwright driver for your everyday Chromium browser: the agent works in your live, logged-in profile through an extension and a relay
- 498 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The extension asks for broad permissions: `debugger`, `tabCapture` and a status script on all URLs
- The agent gets access to the logged-in sessions of your profile, including mail, banks and work dashboards
- Browser Control is not a sandbox: it runs the submitted code with access to the page and part of the Node.js API
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/browser-controlDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The extension asks for broad permissions: `debugger`, `tabCapture` and a status script on all URLs
- The agent gets access to the logged-in sessions of your profile, including mail, banks and work dashboards
- Browser Control is not a sandbox: it runs the submitted code with access to the page and part of the Node.js API
This is third-party code. Review the repository files before installing.
What it does
Browser Control lets a trusted agent drive your real Chromium browser (Chrome, Brave, Edge, Arc) through Playwright. The agent works in your profile with logged-in sessions and installed extensions, and no separate headless browser is launched. A request travels from the agent or CLI to a local relay, then the extension, then the browser. The driver runs locally and contains no model. The main interface is code. The `browser-control execute '...'` command takes a Playwright snippet and returns the result, logs, warnings and a summary of what changed. Sessions keep the page and a `state` variable between calls, and the journal sits in `~/.browser-control/sessions/<id>/journal.jsonl`. The `snapshot()` function returns a compact page description with references like `[ref=e12]`, which the agent clicks in the next call. Steps a person must complete, such as CAPTCHA, two-factor login or payment confirmation, go through `handoff()`. The script waits until you press the completion control on the page. An already open tab can be attached with `browser-control session adopt`. For applications there is a TypeScript client and secret profiles that substitute `BC_SECRET_N` into child processes without revealing values to the parent.
Who it is for. Developers of agents and automation who need pages behind a login in their own browser: accounts, internal dashboards, services with two-factor sign-in.
Good fit when
- The agent needs a page behind a login and you do not want to log in again in a separate headless browser
- A CAPTCHA or two-factor login appears and a person must pass that step through `handoff()`
- A tab is already open and logged in, and a script has to pick it up: `browser-control session adopt --target-url github.com`
- You want to record the traffic of an authenticated app into a HAR and later call it without a browser, injecting secrets through `secrets run`
Not a fit when
- Tests run in an isolated CI browser: there is no user profile or extension there
- The agent's code is untrusted: Browser Control runs it with access to the chosen page and its sessions
- The browser is not Chromium-based: Firefox and Safari are not supported
- You must drive a browser on another machine: there is no authenticated remote relay
Example request
Open my GitHub tab through Browser Control and return the page title and the list of open pull requestsLimitations
It needs Node.js 22.19 or newer and a Chromium-family browser. The extension is installed by hand as an unpacked extension through `chrome://extensions` in developer mode; it is not in the Chrome Web Store. Playwright downloads are unavailable because Chromium blocks the needed commands through `chrome.debugger`, so response bytes are written to a file with the `fs` module. CDP recording needs `ffmpeg`, activates the recorded tab and has no audio. The relay listens only on `127.0.0.1:19989`, so the tool is meant for trusted local use.
How to disable. Disable or remove the extension on `chrome://extensions`, then run `npm uninstall --global @opencode-ai/browser-control`. Session journals stay in `~/.browser-control/`; delete them if you wish.
FAQ
How do I install Browser Control in OpenCode?
Run `opencode plugin add @opencode-ai/browser-control`: the plugin registers the MCP entrypoint and the `browser` skill, called as `@browser`. Do not install the skill or MCP separately. The browser extension is loaded by hand.
How do I connect Browser Control to Claude Code?
Install the package and the skill, then optionally add MCP with `claude mcp add browser-control -- browser-control-mcp`. An agent that can run shell commands needs only the skill; MCP is for clients that prefer tools.
What happens to my cookies and cache?
The relay blocks browser-wide CDP commands that clear cookies, clear the cache or close the browser. This guards against accidents and is not a security boundary: a script sees the selected page and its logged-in state.
How do I check the install works?
Run `browser-control execute 'await page.goto("https://example.com"); return { title: await page.title(), url: page.url() }'`. A successful run returns the Example Domain title and a session ID, and `browser-control status` shows the extension as connected.
What should I do after an npm upgrade?
Reload the unpacked extension on the browser's extensions page. If a stale relay warning appears, finish recordings and raw CDP work and run `browser-control relay restart`: tabs and session identities persist while JavaScript state resets.
Discussion
No questions or reviews yet.
Related
CLI toolsAn MCP and CLI that let an agent control your real Chrome, with its own logins and extensions, through Playwright
Agent browser on direct CDP without Playwright: login profiles, a CLI, an MCP server and recording workflows into a skill
A local browser automation platform: MCP server, CLI and skills so an agent can drive Chrome, fill forms and pull data from pages
Turns any website into a CLI command and lets an agent drive the user's already logged-in browser via Playwright
CLI, skill and Python library for browser control: the agent clicks, fills forms and reads pages over CDP
The cdp skill: an agent drives your Chrome straight through the DevTools protocol, with 652 typed methods and no ready-made click or goto helpers
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Browser Control (this card) | no | 498 | ||
| Playwright MCP | yes | not required | 39,570 | Microsoft's official MCP server, which launches its own browser by default, while Browser Control attaches to your browser and profile through an extension |
| Browser Use | no | 120,809 | a library and CLI with its own agent loop, while Browser Control is a driver without an LLM and your agent makes the decisions |
README in short
The description opens with the agent, relay, extension and browser diagram and a quick start for OpenCode and other agents. It then covers sessions, attaching a tab, page inspection, handing control to a person, traffic capture with secrets, safety boundaries and upgrades, and ends with commands for developing and testing the project itself.