Skip to content
Back to search

browser-control

Local browser driver for trusted agents: control your existing Chromium browser through a small extension and local relay

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/anomalyco--browser-control/badge.svg)](/listings/anomalyco--browser-control)

HTML

<a href="/listings/anomalyco--browser-control"><img src="/api/listings/anomalyco--browser-control/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Browser Control requires Node.js 22.19 or newer and a Chromium-family browser such as Chrome, Brave, Edge, Arc, or Chromium.

Setup has three parts: install the npm package, install the agent skill, and load the included browser extension. Add MCP only when your agent prefers MCP tools over shell commands.

1. Install the CLI

npm install --global @opencode-ai/browser-control

This installs two commands:

- `browser-control` for CLI and skill-driven agents - `browser-control-mcp` for MCP clients

2. Connect your agent

The packaged skill teaches coding agents how to inspect before acting, preserve session identity, handle human-only steps, and recover from browser failures. Install it with the [skills CLI](https://skills.sh):

npx skills add anomalyco/browser-control --skill browser-control -g

Choose the agents you use when prompted. The global `-g` installation makes the skill available across projects.

Browser Control does not edit agent configuration itself. To inspect or install the skill manually, print the exact bundled text:

browser-control skill

Optional MCP server

The skill and MCP server do different jobs. The skill teaches the workflow; MCP exposes Browser Control as tools. Agents that can run shell commands need only the skill. Add MCP when your client prefers MCP tools.

For OpenCode:

// opencode.json
{
  "mcp": {
    "browser-control": {
      "type": "local",
      "command": ["browser-control-mcp"]
    }
  }
}

For Claude Code:

claude mcp add browser-control -- browser-control-mcp

CLI and MCP clients share the detached relay, but each execute session keeps its own default page and persistent JavaScript `state`. Restarting an MCP process does not stop the relay or interrupt an active CLI session.

MCP initialization, tool discovery, `skill`, and `session_current` do not contact or start the relay. The first operational call (such as `execute`, `session_new`, or `session_adopt`) starts it if needed. Relay-backed observational tools report an unavailable relay rather than starting one.

3. Load the extension

Browser Control currently ships its extension as an unpacked extension inside the npm package.

1. Print the extension directory:

   printf '%s\n' "$(npm root --global)/@opencode-ai/browser-control/extension/dist"

2. Open `chrome://extensions` or your browser's equivalent, such as `brave://extensions`. 3. Enable **Developer mode**. 4. Select **Load unpacked** and choose the printed directory. 5. Pin the Browser Control toolbar button.

4. Run your first browser command

Ask the configured agent to use Browser Control, or verify the installation directly:

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

The command starts a detached local relay when needed, opens a browser tab, and prints a readable session ID with the exact `--session` command needed to continue. The relay listens on `127.0.0.1:19989` and stays running between CLI calls.

A successful run returns the `Example Domain` title, a generated session ID, and a continuation command. `browser-control status` then reports the extension as connected.

Check the installation at any time with:

browser-control doctor
browser-control status

`doctor` and `status` are read-only. They report a stopped relay but never start one. Use `browser-control serve` only for foreground debugging.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 690 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Browser Control
  2. Browser Control lets trusted coding agents run Playwright against your existing
  3. Chromium-family browser. It uses your real browser profile, including logged-in
  4. sessions and installed extensions, instead of launching a separate headless
  5. browser.
  6. ```text
  7. Agent or CLI -> local relay -> browser extension -> your browser
  8. ```
  9. The driver runs locally and does not contain an LLM or make planning decisions.
  10. Its primary interface is code: an agent sends a Playwright snippet and receives
  11. the result, logs, warnings, and a summary of what changed.
  12. ## Quick Start
  13. Browser Control requires Node.js 22.19 or newer and a Chromium-family browser such
  14. as Chrome, Brave, Edge, Arc, or Chromium.
  15. OpenCode can install Browser Control as one managed plugin. Other agents use
  16. the manual CLI, skill, and optional MCP setup below. Every path still requires
  17. the user-approved browser extension.
  18. ### OpenCode plugin
  19. Install the package through OpenCode:
  20. ```bash
  21. opencode plugin add @opencode-ai/browser-control
  22. ```
  23. OpenCode installs the package and its dependencies in its managed cache,
  24. registers the packaged MCP entrypoint, and registers its bundled workflow as the
  25. `browser` skill. OpenCode's existing skill autocomplete then exposes `@browser`.
  26. Do not separately install the Browser Control skill or add an MCP configuration
  27. when using this path.
  28. ```text
  29. @browser Open example.com and return the page title.
  30. ```
  31. Selecting `@browser` attaches the complete bundled workflow through OpenCode's
  32. existing skill system. The Chromium extension remains a manual, user-approved
  33. installation. If it is not connected, ask:
  34. ```text
  35. @browser Check Browser Control setup and show me the extension directory.
  36. ```
  37. The registered skill supplies the exact unpacked-extension directory from
  38. OpenCode's managed package installation.
  39. ### Manual setup
  40. Manual setup has three parts: install the npm package, install the agent skill,
  41. and load the included browser extension. Add MCP only when your agent prefers
  42. MCP tools over shell commands.
  43. ### 1. Install the CLI
  44. ```bash
  45. npm install --global @opencode-ai/browser-control
  46. ```
  47. This installs two commands:
  48. - `browser-control` for CLI and skill-driven agents
  49. - `browser-control-mcp` for MCP clients
  50. ### 2. Connect your agent
  51. The packaged skill teaches coding agents how to inspect before acting, preserve
  52. session identity, handle human-only steps, and recover from browser failures.
  53. Install it with the [skills CLI](https://skills.sh):
  54. ```bash
  55. npx skills add anomalyco/browser-control --skill browser-control -g
  56. ```
  57. Choose the agents you use when prompted. The global `-g` installation makes the
  58. skill available across projects.
  59. Browser Control does not edit agent configuration itself. To inspect or install
  60. the skill manually, print the exact bundled text:
  61. ```bash
  62. browser-control skill
  63. ```
  64. #### Optional MCP server
  65. The skill and MCP server do different jobs. The skill teaches the workflow; MCP
  66. exposes Browser Control as tools. Agents that can run shell commands need only
  67. the skill. Add MCP when your client prefers MCP tools.
  68. For OpenCode installations that do not use the package plugin:
  69. ```jsonc
  70. // opencode.json
  71. {
  72. "mcp": {
  73. "browser-control": {
  74. "type": "local",
  75. "command": ["browser-control-mcp"]
  76. }
  77. }
  78. }
  79. ```
  80. For Claude Code:
  81. ```bash
  82. claude mcp add browser-control -- browser-control-mcp
  83. ```
  84. CLI and MCP clients share the detached relay, but each execute session keeps its
  85. own default page and persistent JavaScript `state`. Restarting an MCP process
  86. does not stop the relay or interrupt an active CLI session.
  87. MCP initialization, tool discovery, `skill`, and `session_current` do not contact
  88. or start the relay. The first operational call (such as `execute`, `session_new`,
  89. or `session_adopt`) starts it if needed. Relay-backed observational tools report
  90. an unavailable relay rather than starting one.
  91. ### 3. Load the extension
  92. Browser Control currently ships its extension as an unpacked extension inside
  93. the npm package.
  94. 1. Print the extension directory:
  95. ```bash
  96. printf '%s\n' "$(npm root --global)/@opencode-ai/browser-control/extension/dist"
  97. ```
  98. 2. Open `chrome://extensions` or your browser's equivalent, such as
  99. `brave://extensions`.
  100. 3. Enable **Developer mode**.
  101. 4. Select **Load unpacked** and choose the printed directory.
  102. 5. Pin the Browser Control toolbar button.
  103. ### 4. Run your first browser command
  104. Ask the configured agent to use Browser Control, or verify the installation
  105. directly:
  106. ```bash
  107. browser-control execute 'await page.goto("https://example.com"); return { title: await page.title(), url: page.url() }'
  108. ```
  109. The command starts a detached local relay when needed, opens a browser tab, and
  110. prints a readable session ID with the exact `--session` command needed to
  111. continue. The relay listens on `127.0.0.1:19989` and stays running between CLI
  112. calls.
  113. A successful run returns the `Example Domain` title, a generated session ID,
  114. and a continuation command. `browser-control status` then reports the extension
  115. as connected.
  116. Check the installation at any time with:
  117. ```bash
  118. browser-control doctor
  119. browser-control status
  120. ```
  121. `doctor` and `status` are read-only. They report a stopped relay but never start
  122. one. Use `browser-control serve` only for foreground debugging.
  123. ## TypeScript Client
  124. The package also exports an Effect client for applications that need structured
  125. browser-authenticated requests without executing generated JavaScript:
  126. ```ts
  127. import { BrowserControlClient } from "@opencode-ai/browser-control"
  128. import { Effect, Schema } from "effect"
  129. const program = Effect.gen(function* () {
  130. const client = yield* BrowserControlClient.make()
  131. const browserSession = yield* client.ensureSession({ id: "my-app" })
  132. const account = yield* browserSession.authenticatedOrigin({
  133. origin: "https://app.example.com",
  134. startUrl: "/account",
  135. })
  136. const sensitive = yield* account.json({
  137. path: "/api/session",
  138. method: "POST",
  139. body: {},
  140. response: Schema.Struct({ accessToken: Schema.String }),
  141. sensitive: true,
  142. })
  143. const credentials = BrowserControlClient.reveal(sensitive)
  144. const profile = yield* account.json({
  145. path: "/api/profile",
  146. response: Schema.Struct({ name: Schema.String }),
  147. })
  148. return { credentials, profile }
  149. })
  150. ```
  151. Requests use `window.fetch` in the session's current page, so ambient browser
  152. cookies stay in the browser. Paths must be same-origin, redirects are blocked,
  153. responses are bounded, and mutations are never retried automatically. Set
  154. `sensitive: true` to receive `Redacted<A>`; sensitive requests bypass execute
  155. journals and are rejected while session network capture is active. Reveal a
  156. sensitive result with `BrowserControlClient.reveal`; this keeps unwrapping in
  157. the same Effect runtime that created the redacted value, including when an
  158. application and Browser Control resolve separate Effect package instances.
  159. Client construction waits through a bounded extension reconnect window even
  160. when the matching relay was already running. A session summary reports
  161. `connected: true` only when its Playwright transport and live default page are
  162. both available.
  163. Use `resetSession(id)` to replace a persisted session generation that is no
  164. longer connected before creating a new authenticated-origin capability.
  165. Applications with a generated direct client can also consume a Secret Profile
  166. without requiring users to wrap the application in `browser-control secrets
  167. run`:
  168. ```ts
  169. import { SecretProfile } from "@opencode-ai/browser-control"
  170. import { Effect } from "effect"
  171. const result = await Effect.runPromise(SecretProfile.run({
  172. name: "github",
  173. command: process.execPath,
  174. args: ["./github-cli.js", "repositories"],
  175. }))
  176. process.stdout.write(result.stdout)
  177. process.stderr.write(result.stderr)
  178. process.exitCode = result.exitCode
  179. ```
  180. The trusted child receives `BC_SECRET_N` variables. The parent never receives
  181. their raw values, and known values are redacted from bounded child output. `status()`
  182. returns metadata only; the public SDK intentionally does not expose raw profile
  183. reads.
  184. ## Work in Sessions
  185. A bare `execute` creates a fresh session. Pass its ID to continue with the same
  186. page and `state`:
  187. ```bash
  188. browser-control session new docs
  189. browser-control execute --session docs 'await page.goto("https://example.com/docs"); state.visits = (state.visits ?? 0) + 1; return state.visits'
  190. browser-control execute --session docs 'return { url: page.url(), visits: state.visits }'
  191. browser-control journal --session docs
  192. ```
  193. The journal is a best-effort local activity record stored under
  194. `~/.browser-control/sessions/<id>/journal.jsonl`. It includes bounded script and
  195. result previews and remains after session deletion. Do not embed passwords,
  196. tokens, or other credentials directly in execute code.
  197. Single expressions return automatically, so this shorter form also works:
  198. ```bash
  199. browser-control execute --session docs 'await page.title()'
  200. ```
  201. Use `--file script.js` for longer programs and `--json` (anywhere on the command
  202. line) for a machine-readable result envelope. Exit codes follow the control-kit
  203. contract: 2 bad arguments, 4 relay or extension unreachable, 1 anything else.
  204. JSON failures also print one `browser-control: <message>` line on stderr.
  205. Delete the session when you finish:
  206. ```bash
  207. browser-control session delete docs
  208. ```
  209. Deletion is idempotent for an explicit session id, so cleanup can be safely
  210. retried when that session is already absent.
  211. ## Control an Existing Tab
  212. Relay-created pages are isolated from other Browser Control sessions. To use a
  213. tab that is already logged in:
  214. 1. Open the tab in your browser.
  215. 2. Click the Browser Control toolbar button to attach it.
  216. 3. Adopt it into a session using a unique URL substring:
  217. ```bash
  218. browser-control session new github
  219. browser-control session adopt --session github --target-url github.com
  220. browser-control execute --session github 'return { title: await page.title(), url: page.url() }'
  221. ```
  222. Adoption is exclusive to one Browser Control session. Resetting or deleting the
  223. session releases an adopted user tab without closing it.
  224. ## Inspect Before Acting
  225. Execute code receives normal Playwright `browser`, `context`, and `page`
  226. objects, plus Browser Control helpers. `snapshot()` is the compact default for
  227. reading a page before interaction:
  228. ```bash
  229. browser-control execute --session github 'return await snapshot()'
  230. ```
  231. Snapshot controls include refs such as `[ref=e12]`. Use a ref in the next call:
  232. ```bash
  233. browser-control execute --session github 'await ref("e12").click(); return await snapshot({ diff: true })'
  234. ```
  235. Compatible refs keep their ids across repeated same-document captures and become
  236. stale after navigation. They combine structural and accessible identity so DOM
  237. drift fails closed instead of silently targeting a different control.
  238. Use automatic deltas or semantic search when a full snapshot would be noisy:
  239. ```js
  240. return await snapshot({ delta: true })
  241. return await snapshot({ find: /checkout|payment/i, context: 2 })
  242. ```
  243. Other inspection helpers include:
  244. - `ariaSnapshot()` for a deeper accessibility-tree view with native text-control
  245. values, custom ARIA range values, and editable content omitted; await it
  246. separately from other operations on the same page
  247. - `screenshotWithLabels()` for an annotated screenshot and element metadata
  248. - `screenshotDiff({ baseline })` for changed-pixel metrics and a red-highlighted
  249. PNG against a saved baseline; capture both at the same CSS viewport scale
  250. - `fillInput()` and `fillInputs()` for input, textarea, and contenteditable
  251. fields when browser extensions interfere with Playwright's normal fill
  252. - `webmcp.list()` and `webmcp.call(name, input, { frame? })` for structured
  253. tools registered by WebMCP-enabled pages
  254. The agent skill gives the operating workflow and canonical examples; command
  255. `--help` output remains the source of truth for detailed options.
  256. ## Pause for Human-Only Steps
  257. Use `handoff()` for CAPTCHA, 2FA, payment confirmation, or another step that a
  258. person must complete:
  259. ```js
  260. await handoff("Complete 2FA, then use the in-page continue control")
  261. await page.getByRole("heading", { name: "Dashboard" }).waitFor()
  262. return page.url()
  263. ```
  264. If the click itself can block on native WebAuthn or payment UI, register the
  265. handoff before triggering it:
  266. ```js
  267. await handoff("Complete the security-key prompt, then continue", {
  268. timeoutMs: 600_000,
  269. start: () => page.getByRole("button", { name: "Use security key" }).click({ timeout: 600_000 }),
  270. })
  271. ```
  272. The page displays an accessible completion control and the script waits. Always
  273. verify the expected URL or element after the handoff; human acknowledgment does
  274. not prove that the requested step succeeded. Browser Control waits for the
  275. extension to acknowledge WAIT before calling `start`. If the handoff times out
  276. or its target disappears first, it disconnects that sandbox's Playwright
  277. connection before releasing the execute permit, preventing a still-pending
  278. prompt action from mutating the page later. Keep `start` limited to the bounded
  279. browser action that opens the native prompt.
  280. Use `demonstrate()` when a person can show a workflow faster than describing it.
  281. It records the exact-tab handoff as editable Playwright code:
  282. ```js
  283. return await demonstrate("Perform the workflow once, then continue")
  284. ```
  285. The result includes structured steps and generated code for clicks, edits,
  286. checkbox/select changes, and navigations. Password values are replaced with a
  287. secret-source comment. Add independent outcome assertions before replaying it.
  288. ## Use Read-Only Sessions
  289. Read-only sessions reject mouse and keyboard CDP commands while allowing
  290. navigation, inspection, and screenshots:
  291. ```bash
  292. browser-control session new inspect --read-only
  293. browser-control execute --session inspect 'await page.goto("https://example.com"); return await snapshot()'
  294. ```
  295. Read-only mode prevents accidental Playwright input. It is not a security
  296. sandbox: trusted code can still mutate a page with `page.evaluate()`.
  297. ## Record a Session
  298. ```bash
  299. browser-control recording start ./demo.webm --session github
  300. browser-control recording status --session github
  301. browser-control recording stop --session github
  302. ```
  303. Recording start/stop/status support `--json`. CDP quality receipts distinguish
  304. output fps from received/retained source frames and report coalescing, drops,
  305. dimensions, and screenshot fallback. These counters do not prove distinct motion.
  306. Explicit frame rates must be integers from 1 to 60; unsupported values are rejected.
  307. Visual comparison stays code-first:
  308. ```ts
  309. await page.screenshot({ path: "/absolute/before.png", scale: "css" })
  310. // Make the intended UI change, keeping the viewport unchanged.
  311. return await screenshotDiff({ baseline: "/absolute/before.png" })
  312. ```
  313. The result includes a diff image, `matches`, `changedPixels`, and `changedRatio`.
  314. Use `path` for a new absolute PNG output instead of inline media. `threshold`
  315. (default 0.1) controls pixel color tolerance, not allowed changed area. Different
  316. dimensions fail without resizing. Images are bounded to 32 MiB / 16 megapixels;
  317. existing output files are never overwritten. Review visible private content
  318. before sharing either screenshots or diffs.
  319. Automatic mode uses browser tab capture for user-owned tabs and CDP screencast
  320. for relay-created tabs. Tab capture writes WebM and can include audio. CDP mode
  321. writes WebM or MP4, requires `ffmpeg` on `PATH`, and does not capture audio.
  322. For intermittent failures, retain a rolling video window and save it afterward
  323. without stopping the buffer:
  324. ```bash
  325. browser-control flight-recorder start --session github --retention-ms 60000
  326. browser-control flight-recorder save-last ./failure.mp4 --session github --duration-ms 30000
  327. browser-control flight-recorder cancel --session github
  328. ```
  329. The bounded in-memory recorder reports retained frames, bytes, duration, and
  330. drops, and writes a JSON receipt next to each clip. Recording and flight-recorder
  331. lifecycle commands are also available over MCP.
  332. ## Derive a Direct Client
  333. Capture authenticated API exchanges across as many execute calls or human
  334. handoffs as the workflow needs:
  335. ```bash
  336. browser-control network start --session github --url /api/ \
  337. --resource-type fetch --resource-type xhr
  338. browser-control execute --session github --file ./perform-flow.js
  339. browser-control network stop --session github \
  340. --output ./github.har --secrets github
  341. ```
  342. Browser Control records normalized request/response exchanges itself; HAR is an
  343. interoperable export, not the internal capture model. Written artifacts replace
  344. cookies, authorization headers, CSRF tokens, API keys, and token-like query or
  345. body fields with stable `${BC_SECRET_N}` references. Lossless values are stored
  346. separately in a mode-`0600` profile under `~/.browser-control/secrets`.
  347. Bodies that cannot be reliably redacted, including binary and file-bearing
  348. multipart content, are omitted and reported as truncated.
  349. Unknown-length and compressed response bodies are also omitted so Browser
  350. Control never materializes them before it can enforce the configured budget.
  351. Generated clients read the referenced environment variables and run without
  352. printing or embedding the values:
  353. ```bash
  354. browser-control secrets status github
  355. browser-control secrets run github -- ./github-cli repositories
  356. browser-control secrets refresh github --session github
  357. ```
  358. `secrets refresh` reloads the session page and preserves references while
  359. updating values observed at the same source. If reauthentication requires a
  360. human flow, log in through the browser and repeat the capture with the same
  361. profile name instead. Child stdout and stderr are redacted before Browser
  362. Control returns them.
  363. ## Safety Boundaries
  364. Browser Control trusts the local agent code it executes. It is a driver, not an
  365. untrusted-code sandbox.
  366. The extension requires broad browser permissions, including `debugger`,
  367. `tabCapture`, and a status content script on all URLs. Attaching a user tab gives
  368. Browser Control access to that tab through your existing browser profile.
  369. The relay blocks destructive browser-wide CDP commands that clear cookies,
  370. clear cache, or close the browser. It also keeps session-owned tabs private from
  371. other Browser Control sessions. These guardrails reduce accidents, but scripts
  372. still have access to the selected page, its logged-in state, and a limited set
  373. of Node.js filesystem and network APIs.
  374. Current limitations:
  375. - The extension is installed unpacked; Chrome Web Store distribution is not
  376. available yet. The repository can produce the review artifact with
  377. `pnpm package:extension`; the first Store release will begin as an unlisted
  378. beta.
  379. - Playwright download artifacts are unavailable because Chromium blocks the
  380. required download commands through `chrome.debugger`. Fetch exposed response
  381. bytes and write them with the provided `fs` module instead.
  382. - CDP recording requires `ffmpeg`, activates the recorded tab, and has no audio.
  383. - Browser Control is intended for trusted local use. It does not provide an
  384. authenticated remote relay.
  385. ## Troubleshooting and Upgrades
  386. - **`browser-control: command not found`**: confirm npm's global binary
  387. directory is on `PATH`, then rerun the global install.
  388. - **Extension disconnected**: confirm the unpacked extension is enabled, then
  389. reload it from the browser's extensions page. The extension reconnects to a
  390. running relay automatically.
  391. - **After an npm upgrade**: reload the unpacked extension. Extension and relay
  392. versions may differ when they use the same reported protocol version.
  393. - **Stale relay warning**: ordinary commands never replace a running relay.
  394. Coordinate with other users, finish recordings and raw CDP work, then run
  395. `browser-control relay restart`. It drains accepted work and preserves tabs
  396. and durable session identity, but JavaScript state and snapshot refs reset.
  397. A busy/timeout result leaves the relay running. Legacy relays without safe
  398. shutdown protocol 2 need a one-time coordinated manual stop; the new CLI will
  399. not force-kill them or downgrade a newer relay.
  400. - **Who restarted the relay?** Inspect the private
  401. `~/.browser-control/relays/<port>/lifecycle.jsonl` records for requester, build,
  402. instance, and outcome metadata. Browser URLs and executed code are not recorded
  403. there.
  404. For PowerShell, print the unpacked extension path with:
  405. ```powershell
  406. Join-Path (npm root --global) "@opencode-ai/browser-control/extension/dist"
  407. ```
  408. ## Development
  409. ```bash
  410. git clone git@github.com:anomalyco/browser-control.git
  411. cd browser-control
  412. pnpm install
  413. pnpm typecheck
  414. pnpm test
  415. pnpm check:unused
  416. pnpm check:locals
  417. pnpm audit:duplicates
  418. # Fresh paths outside this checkout; parent directories must exist.
  419. mkdir -p "$HOME/.browser-control/builds" "$HOME/.browser-control/runtimes"
  420. pnpm runtime:prepare \
  421. --staging "$HOME/.browser-control/builds/candidate-1" \
  422. --install "$HOME/.browser-control/runtimes/candidate-1"
  423. # Select only after validation. This does not restart the relay.
  424. pnpm runtime:select \
  425. --install "$HOME/.browser-control/runtimes/candidate-1" \
  426. --active "$HOME/.browser-control/active"
  427. export PATH="$HOME/.browser-control/active/bin:$PATH"
  428. ```
  429. For occasional whole-codebase audits, `pnpm exec knip --production` excludes test
  430. usage. Review its findings rather than requiring a clean result: an export used
  431. only by tests can still have production callers inside its own module. Normal
  432. `pnpm check:unused` remains the CI gate.
  433. ### Gauntlet
  434. `pnpm gauntlet:isolated` builds this checkout and runs the gauntlet through a
  435. disposable Chromium profile, the real MV3 extension, and a private relay. It
  436. needs no installed Browser Control runtime and does not touch your browser.
  437. Install Chromium once with `pnpm exec playwright-core install chromium`.
  438. ```bash
  439. GAUNTLET_CASE=cross-origin-payment-iframe pnpm gauntlet:isolated
  440. GAUNTLET_WARMUP=1 GAUNTLET_REPEAT=9 pnpm gauntlet:isolated
  441. ```
  442. Each run prints its evidence directory with JSON results, timings, and logs.
  443. See [the reliability loop](docs/RELIABILITY.md) for options, CI lanes, evidence
  444. boundaries, and the next fault-injection work.
  445. `pnpm gauntlet` runs an adversarial suite of locally served hostile pages against
  446. the live relay and browser. Each case reproduces one real-world behaviour that
  447. has broken agents before (bot protection stalling the main world, typing that
  448. freezes a form, a cross-origin payment iframe that ignores autofill, a sign-in
  449. redirect during a handoff, click-through overlays, a heavy SPA bootstrapping
  450. after a navigation) and asserts two things: the outcome an agent should see (a
  451. successful read or a named diagnosis) and the tab-preservation invariants (the
  452. session still owns exactly one tab, on the fixture URL, never replaced with
  453. `about:blank`, no silent new page). Every case has a wall-time budget.
  454. ```bash
  455. pnpm gauntlet # all cases
  456. GAUNTLET_CASE=stalled-main-world pnpm gauntlet # comma-separated filter
  457. GAUNTLET_REPEAT=3 pnpm gauntlet # repeat for flake detection
  458. GAUNTLET_VERBOSE=1 pnpm gauntlet # print each case's return value
  459. GAUNTLET_CLI=/abs/path/dist/cli.js pnpm gauntlet
  460. ```
  461. The runner needs a running relay with the extension connected, like `pnpm smoke`.
  462. It drives Browser Control through the CLI the way a shell agent would, so it
  463. must use a CLI whose build matches the running relay: by default it tries the
  464. checkout's `src/cli.ts` and then the installed `browser-control` binary, and
  465. fails fast if neither matches. `GAUNTLET_CLI=source|installed|<path>` pins one.
  466. Fixtures are served on `127.0.0.1:19801` and `localhost:19802` (different sites
  467. allow OOPIF testing with Chromium site isolation); override with `GAUNTLET_PRIMARY_PORT` /
  468. `GAUNTLET_SECONDARY_PORT`. Sessions are created through bare `execute`, so the
  469. run never changes your current session.
  470. Exit status is non-zero for `fail`, `unexpected-pass`, or `budget-exceeded`.
  471. Cases marked `expectedFailure` document behaviour Browser Control does not
  472. deliver yet; only their exact named assertion can report `xfail`. Unrelated
  473. failures and cleanup leaks always fail. An unexpected pass prompts removal of
  474. the obsolete expectation. `GAUNTLET_REPORT=/absolute/report.json` saves results
  475. for this already-running-browser mode as well.
  476. To add a fixture: drop a self-contained `gauntlet/fixtures/<name>.html` (no
  477. external network; explain the hostile mechanism in a leading HTML comment; take
  478. tunables from the query string), add any dynamic route to `gauntlet/server.ts`,
  479. and add a `GauntletCase` to `gauntlet/cases.ts` whose `run` drives the CLI via
  480. `ctx.execute`, usually inside `withSession`, which asserts the session kept its
  481. original tab and target (or call `assertTabPreserved` directly). Cases that need a user-owned
  482. tab receive one as `page`; set `userTabCleanupGraceMs` if the fixture can leave
  483. that tab's renderer busy at cleanup time.
  484. ### App gauntlet
  485. `pnpm gauntlet:apps` evaluates browser agents end to end on two fake apps served
  486. from one loopback server: Junglemart (Amazon-style: search, filters, pagination,
  487. sponsored lookalikes, variants, out-of-stock sizes, a protection-plan upsell,
  488. address validation, paid shipping pre-selected, promo codes, card form) and
  489. Grubber (Uber Eats-style: address gate, membership modal, a closed restaurant,
  490. sold-out items, required option groups, a lazily loaded menu section, the
  491. one-restaurant cart rule, an add-on upsell, a pre-checked membership box,
  492. delivery or pickup). Data is fake, the only accepted card is
  493. `4242 4242 4242 4242`, and nothing leaves the machine: pages carry a same-origin
  494. CSP and the runner aborts every request outside the app origin.
  495. Each of the 10 tasks (`pnpm gauntlet:apps --list`) seeds its own run, isolated
  496. by a cookie, and is graded from the server's final state (the right cart or
  497. order with the right options), never from screenshots. Ordered milestones show
  498. where a failed run stalled. The runner uses headless Chromium with a throwaway
  499. context per run and writes JSONL plus a Markdown summary (success, steps, wall
  500. time, cost, stall point) to `artifacts/gauntlet-apps/`.
  501. ```bash
  502. pnpm gauntlet:apps # scripted reference policy; must pass 10/10
  503. pnpm gauntlet:apps --policy ./agent.ts --arms a,b --tasks eats --reps 3
  504. pnpm gauntlet:apps --report a.jsonl,b.jsonl # one summary over several runs
  505. node --import tsx gauntlet/apps/server.ts # browse the apps on :19830
  506. ```
  507. A policy module exports a `GauntletPolicy` (`gauntlet/apps/policy.ts`), an
  508. array or a record of them. It gets the task (goal, the only text it may type,
  509. step cap) and a Playwright `page`, and reports each action through `step()`.
  510. Use `bun` instead of `tsx` when the policy needs Bun APIs. To add a task, add it
  511. to `gauntlet/apps/tasks.ts` with a `grade` that fails on the untouched seed
  512. (`test/gauntlet-apps.test.ts` checks this) and a script in
  513. `gauntlet/apps/reference.ts`.
  514. `pnpm smoke:snapshot` runs native-role/ref, portal-dialog, and dense-list
  515. regressions against an isolated Chromium browser using the real snapshot code.
  516. Install its browser with `pnpm exec playwright-core install chromium` if needed.
  517. It does not connect to the user's relay. `pnpm repro:screenshot-zoom` is a
  518. separate standalone reproduction of stock Playwright's full-page clipping at
  519. 110% browser zoom; it intentionally fails while that upstream issue remains.
  520. Use the same `active/bin/browser-control-mcp` path in MCP configuration. Do not
  521. `bun link` the active tool into the checkout: changing dependencies or rebuilding
  522. `dist` would also change what other agents execute. Retain previous installation
  523. directories while existing processes may still load resources from them. Selecting
  524. an older installation does not authorize a daemon downgrade.
  525. `pnpm runtime:check-lifecycle --previous /absolute/install-a --candidate
  526. /absolute/install-b` checks two validated protocol-2 installations on a private
  527. temporary home and loopback port using a fake extension. The candidate must have
  528. a later build id. It verifies non-replacement by ordinary CLI/MCP clients,
  529. explicit restart attribution, synthetic adopted-target restoration, and downgrade
  530. refusal. It does not prove real-browser tab continuity or cross-release
  531. compatibility when both installations came from the same source revision.
  532. For a build-only check, `pnpm build:cli --outdir /absolute/fresh-external-directory`
  533. redirects bundles and declarations together. Candidate preparation never writes
  534. checkout `dist`, `node_modules`, or the loaded `extension/dist`. Explicitly run
  535. `browser-control relay restart` when ready to replace the active daemon.
  536. Extension source changes require `pnpm build:extension` and reloading the
  537. unpacked extension. Relay-only changes require rebuilding or restarting the
  538. relay, not reloading the extension.
  539. See [`PLAN.md`](./PLAN.md) for architecture and roadmap decisions,
  540. [`AGENTS.md`](./AGENTS.md) for contributor invariants, and
  541. [`skills/browser-control/SKILL.md`](./skills/browser-control/SKILL.md) for the
  542. complete agent workflow.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.