cdp
Drive Chrome via the DevTools Protocol from JavaScript. Run JS snippets through the `browser-harness-js` CLI — it auto-spawns a long-lived bun HTTP server holding a fully-typed CDP `Session`, and every call (`browser-harness-js 'await session.Page.navigate(...)'`) executes against the same persistent connection. Session, active target, and globals survive across calls. Use when the user wants to automate, script, or inspect a Chrome browser via CDP — single tab or multi-tab, attach to existing Chrome or to a new one launched with --remote-debugging-port.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/browser-use/browser-harness-js with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/browser-use/browser-harness-js'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/browser-use--browser-harness-js)HTML
<a href="/listings/browser-use--browser-harness-js"><img src="/api/listings/browser-use--browser-harness-js/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
npx skills add https://github.com/browser-use/browser-harness-js --skill cdp
Or paste this into your agent — it'll install the skill, put the CLI on your PATH, and run a first task:
Run `npx skills add https://github.com/browser-use/browser-harness-js --skill cdp`, then symlink `browser-harness-js` into a directory on my PATH, then use the cdp skill to drive my browser: look at all the tabs I have open, group them by topic, and screenshot the most interesting one.
(The CLI auto-installs [`bun`](https://bun.sh) on first run if it's missing. Set `BROWSER_HARNESS_SKIP_BUN_INSTALL=1` to opt out.)
If Chrome asks you to tick a remote-debugging checkbox, do it — that's how the agent attaches:
See [interaction-skills/](interaction-skills/) for recipes on the mechanics that are not obvious from the CDP method list alone.
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.
SKILL.md · Manifest · 250 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.
- ---
- name: cdp
- description: Drive Chrome via the DevTools Protocol from JavaScript. Run JS snippets through the `browser-harness-js` CLI — it auto-spawns a long-lived bun HTTP server holding a fully-typed CDP `Session`, and every call (`browser-harness-js 'await session.Page.navigate(...)'`) executes against the same persistent connection. Session, active target, and globals survive across calls. Use when the user wants to automate, script, or inspect a Chrome browser via CDP — single tab or multi-tab, attach to existing Chrome or to a new one launched with --remote-debugging-port.
- ---
- # CDP — `browser-harness-js` skill
- Custom codegen'd CDP SDK (every method from browser_protocol.json + js_protocol.json gets a typed wrapper) plus a tiny HTTP server that holds one persistent CDP `Session`. The `browser-harness-js` CLI auto-starts the server on first use and forwards JS snippets to it.
- The SDK lives in the skill's `sdk/` directory. In the rest of this doc, `<skill-dir>` refers to wherever `npx skills add` installed the skill (Claude Code: `~/.claude/skills/cdp`; Cursor: `~/.cursor/skills/cdp`; other agents vary). The CLI should be on PATH as `browser-harness-js`.
- ## Setup (once, first use)
- `npx skills add` drops the skill into your agent's skills directory but does NOT put the CLI on PATH. Before the first call, verify it's reachable and symlink it into any directory on your PATH if not:
- ```bash
- # macOS (Apple Silicon + Homebrew)
- command -v browser-harness-js >/dev/null || ln -sf <skill-dir>/sdk/browser-harness-js /opt/homebrew/bin/browser-harness-js
- # macOS (Intel) / most Linux — may need sudo
- command -v browser-harness-js >/dev/null || ln -sf <skill-dir>/sdk/browser-harness-js /usr/local/bin/browser-harness-js
- # Linux without sudo (ensure ~/.local/bin is on PATH)
- command -v browser-harness-js >/dev/null || { mkdir -p ~/.local/bin && ln -sf <skill-dir>/sdk/browser-harness-js ~/.local/bin/browser-harness-js; }
- ```
- The CLI auto-installs `bun` on first run if it's missing (the server is Bun-native). Set `BROWSER_HARNESS_SKIP_BUN_INSTALL=1` to opt out.
- ## How to use
- Just run `browser-harness-js '<JS>'`. The first call spawns the server in the background; subsequent calls hit the same process and so reuse the same `session`, the same WebSocket to Chrome, and any globals you set.
- ```bash
- browser-harness-js 'await session.connect()'
- browser-harness-js 'await session.Page.navigate({url:"https://example.com"})'
- browser-harness-js '(await session.Runtime.evaluate({expression:"document.title",returnByValue:true})).result.value'
- ```
- Output is the **raw result content** — no `{ok,result}` envelope.
- | Result type | stdout |
- |---|---|
- | string | bare text, no JSON quotes (e.g. `Example Domain`) |
- | number / boolean | `42`, `true` |
- | object / array (non-empty) | compact JSON (e.g. `{"frameId":"..."}`, `[1,2,3]`) |
- | `undefined` / `null` / `""` / `{}` / `[]` | empty (no output) |
- **Errors** go to **stderr**, exit code `1`. The CDP error message and JS stack are printed verbatim, e.g.:
- ```
- Error: CDP -32602: invalid params
- at _call (.../session.ts:117:33)
- ...
- ```
- Detect failure with `if browser-harness-js '...'; then ...; else handle_error; fi` or by checking `$?`.
- **Multi-line snippets via stdin (heredoc).** Important: a multi-statement snippet does NOT auto-return the last expression — write `return X` explicitly. Single-expression snippets passed as the first argument DO auto-return.
- ```bash
- browser-harness-js <<'EOF'
- const tabs = await listPageTargets();
- globalThis.tid = tabs[0].targetId;
- await session.use(globalThis.tid);
- return globalThis.tid;
- EOF
- ```
- ## CLI commands
- | Command | Behavior |
- |---|---|
- | `browser-harness-js '<js>'` | Auto-start server if needed, eval the JS, print result. |
- | `browser-harness-js <<EOF…EOF` | Same, code from stdin. |
- | `browser-harness-js --status` | Print health JSON (uptime, connected, sessionId) or exit 1 if down. |
- | `browser-harness-js --start` | Explicit start (no-op if already running). |
- | `browser-harness-js --stop` | Graceful shutdown. Drops session state. |
- | `browser-harness-js --restart` | Stop + start fresh. |
- | `browser-harness-js --logs` | `tail -f` the server log (`/tmp/browser-harness-js.log`). |
- Env vars: `CDP_REPL_PORT` (default `9876`), `CDP_REPL_LOG` (default `/tmp/browser-harness-js.log`).
- ## API surface inside snippets
- These globals are pre-loaded — no imports needed:
- - `session` — the persistent `Session`. Has every CDP domain mounted: `session.Page`, `session.DOM`, `session.Runtime`, `session.Network`, … 56 domains, 652 methods total.
- - `listPageTargets()` — list real page targets via CDP's `Target.getTargets` (works on Chrome 144+ too), with `chrome://` and `devtools://` URLs filtered out. No args — uses the connected session.
- - `detectBrowsers()` — scan OS-specific profile dirs for running Chromium-based browsers with remote debugging on. Returns `[{name, profileDir, port, wsPath, wsUrl, mtimeMs}]`, sorted by most recently launched.
- - `resolveWsUrl(opts)` — resolve a WS URL from `{wsUrl}` | `{port, host?}` | `{profileDir}`. For the no-args auto-detect flow, call `session.connect()` directly instead.
- - `CDP` — the generated namespaces (`CDP.Page`, `CDP.Runtime`, …) for type-name reference.
- ### Calling a CDP method
- Every method takes a single object argument matching the CDP wire params; it resolves to the typed return value (no `result` envelope, no `id` correlation — handled for you).
- ```js
- // no params
- await session.DOM.enable()
- // required params
- await session.Page.navigate({ url: 'https://example.com' })
- // all-optional params (object also optional)
- await session.Page.captureScreenshot()
- await session.Page.captureScreenshot({ format: 'png', quality: 80 })
- // returns are stripped to the typed shape
- const { root } = await session.DOM.getDocument()
- const { nodeId } = await session.DOM.querySelector({ nodeId: root.nodeId, selector: 'h1' })
- ```
- ### Connecting
- **Default: just call `session.connect()` with no args.** It auto-detects running Chromium-based browsers (Chrome, Chromium, Edge, Brave, Arc, Vivaldi, Opera, Comet, Canary) by scanning OS-specific profile dirs for a `DevToolsActivePort` file, ordered by most-recently-launched, and picks the first one whose WebSocket accepts. OS-agnostic — works on macOS, Linux, Windows.
- ```js
- await session.connect() // auto-detect
- ```
- Use `detectBrowsers()` first if you want to see what's available (or let the user pick) before connecting:
- ```js
- const found = await detectBrowsers()
- // [{ name: 'Google Chrome', profileDir, port, wsPath, wsUrl, mtimeMs }, ...]
- ```
- **Explicit forms** — use these only when auto-detect picks the wrong browser, or when you already know where to connect:
- | Form | When to use |
- |---|---|
- | `{ profileDir }` | Target a specific browser when several are running. Reads `<profileDir>/DevToolsActivePort` directly. |
- | `{ wsUrl }` | You already have `ws://…/devtools/browser/<uuid>` (e.g. piped from elsewhere). |
- ```js
- await session.connect({ profileDir: '/Users/<you>/Library/Application Support/Google/Chrome' })
- await session.connect({ wsUrl: 'ws://127.0.0.1:9222/devtools/browser/<uuid>' })
- ```
- Profile paths by OS — use these with `{ profileDir }`:
- - macOS: `~/Library/Application Support/<Browser>` (e.g. `Google/Chrome`, `Comet`, `BraveSoftware/Brave-Browser`, `Arc/User Data`)
- - Linux: `~/.config/<browser>` (e.g. `google-chrome`, `chromium`, `BraveSoftware/Brave-Browser`)
- - Windows: `%LOCALAPPDATA%\<Browser>\User Data` (e.g. `Google\Chrome`, `Microsoft\Edge`, `BraveSoftware\Brave-Browser`)
- Per-candidate WS-open timeout defaults to **5s** — live browsers answer with open/close within ~100ms, so 5s is already generous. The only case where 5s is too short is when Chrome is showing the **Allow** popup and waiting on the user to click. If you expect that, pass `timeoutMs: 30000`:
- ```js
- await session.connect({ profileDir: '/Users/<you>/Library/Application Support/Google/Chrome', timeoutMs: 30_000 })
- ```
- **If you see `No detected browser accepted a connection`** — the browsers have `DevToolsActivePort` files but none are currently serving WS. Most common cause: remote-debugging is enabled but the user hasn't clicked **Allow** on the prompt yet. Tell them to click Allow, then retry (or bump `timeoutMs`).
- ### Picking a target (tab)
- After `connect()`, call `session.use(targetId)` once; subsequent page-level calls (Page/DOM/Runtime/Network/etc.) auto-route to that target's sessionId. `Browser.*` and `Target.*` calls always hit the browser endpoint.
- ```js
- const tabs = await listPageTargets() // no args; uses the connected session
- const sid = await session.use(tabs[0].targetId)
- await session.Page.enable()
- await session.Page.navigate({ url: 'https://example.com' })
- ```
- `listPageTargets()` uses CDP's `Target.getTargets` (not `/json`), so it works on Chrome 144+ too. It already filters out `chrome://` and `devtools://` URLs. Equivalent raw call:
- ```js
- const { targetInfos } = await session.Target.getTargets({})
- const tabs = targetInfos.filter(t => t.type === 'page' && !t.url.startsWith('chrome://') && !t.url.startsWith('devtools://'))
- ```
- To switch tabs: `session.use(otherTargetId)`. To detach: `session.setActiveSession(undefined)`.
- ### Events
- ```js
- // Subscribe (returns an unsubscribe fn)
- const off = session.onEvent((method, params, sessionId) => { ... })
- // Or wait for a single matching event with optional predicate + timeout
- await session.Network.enable()
- const ev = await session.waitFor(
- 'Page.frameNavigated',
- (p) => p.frame.url.includes('example.com'),
- 10_000
- )
- ```
- ### Persisting state across calls
- Each snippet runs inside its own async wrapper, so its `let`/`const` declarations vanish when it returns. To carry data forward, attach to `globalThis`:
- ```bash
- browser-harness-js '(await listPageTargets()).forEach((t,i)=>globalThis["tab"+i]=t.targetId)'
- browser-harness-js 'await session.use(globalThis.tab0)'
- browser-harness-js 'await session.Page.navigate({url:"https://example.com"})'
- ```
- `session` itself, the active sessionId, and event subscribers are already preserved by the server — globals are only needed for ad-hoc data.
- ## Connecting to a running Chrome (chrome://inspect flow)
- When attaching to the user's already-running browser:
- 1. **Try `await session.connect()` first** (no args) — auto-detect handles every Chromium-based browser via `DevToolsActivePort`. If it returns, you're done.
- 2. **If auto-detect fails** with `No running browser with remote debugging detected`, the user needs to turn it on. Open the inspect page:
- ```bash
- # macOS — prefer AppleScript over `open -a` (reuses current profile, avoids the profile picker)
- osascript -e 'open location "chrome://inspect/#remote-debugging"'
- # Linux
- google-chrome 'chrome://inspect/#remote-debugging' # or: chromium, google-chrome-stable
- # Windows (PowerShell)
- Start-Process chrome 'chrome://inspect/#remote-debugging'
- ```
- Only macOS's AppleScript path avoids the profile picker; Linux/Windows may prompt the user to pick a profile first.
- 3. **Tick "Discover network targets"** in chrome://inspect, then click **Allow** when Chrome prompts.
- 4. **If auto-detect picks the wrong browser** (multiple running, you want a specific one): list them with `await detectBrowsers()`, then `await session.connect({ profileDir: <the one you want> })`.
- 5. **If `session.connect()` returns `No detected browser accepted a connection`**, the user has remote-debugging on but hasn't clicked **Allow** yet. Tell them to click it and retry, or pass `timeoutMs: 30000` to wait for the click.
- ## Working with targets (tabs)
- - **Filter Chrome internals.** `listPageTargets()` already drops `chrome://` and `devtools://` URLs. If you call `Target.getTargets()` directly, filter manually.
- - **CDP target order ≠ visible tab-strip order.** When the user says "the first tab I can see", use a screenshot or page title to identify it — `Target.activateTarget` only switches to a known targetId.
- ## Looking up a method
- The full typed surface is in `<skill-dir>/sdk/generated.ts` (~655 KB, only loaded if you read it). Each method has its CDP description as a JSDoc comment plus typed `*Params` / `*Return` interfaces in per-domain namespaces.
- ```bash
- grep -n "navigate" <skill-dir>/sdk/generated.ts | head
- ```
- ## Regenerating the SDK
- When the upstream protocol JSONs change, replace `sdk/browser_protocol.json` and/or `sdk/js_protocol.json` and re-run:
- ```bash
- cd <skill-dir>/sdk && bun gen.ts
- browser-harness-js --restart # pick up the new bindings
- ```
- ## Files
- All paths are relative to `<skill-dir>` (the install path — see top of this doc).
- - `/usr/local/bin/browser-harness-js` → `<skill-dir>/sdk/browser-harness-js` (the CLI)
- - `sdk/repl.ts` — HTTP server (`Bun.serve` on `127.0.0.1:9876`)
- - `sdk/session.ts` — `Session` class (transport, connect, target routing, events)
- - `sdk/generated.ts` — codegen output: every CDP method as a typed wrapper
- - `sdk/gen.ts` — codegen script
- - `sdk/{browser,js}_protocol.json` — upstream protocol (vendored)
README.md · README · 94 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.
- <img src="https://r2.browser-use.com/github/asbfgihsbfbaosfjla.png" alt="Browser Harness" width="100%" />
- > [!IMPORTANT]
- > **This repo is no longer the recommended path. Use [Browser Use](https://github.com/browser-use/browser-use).** Browser Use 1.0 is where this work continues: your coding agent drives Chrome over raw CDP with the browser-harness helpers, by piping Python to the `browser-use` CLI or through its MCP server.
- >
- > ```bash
- > uv tool install browser-use
- > browser-use <<'PY'
- > new_tab("https://example.com")
- > print(page_info())
- > PY
- > ```
- >
- > MCP server: `browser-use --cli-mcp`. This repo stays up as the JS/TS CDP bridge, for reference.
- # Browser Harness JS ♞
- The thinnest possible bridge from the LLM to Chrome. **No harness, no recipes, no rails** — just every CDP method as a typed JS call.
- One persistent WebSocket, 56 domains, 652 typed wrappers, zero wrapping of what Chrome already does.
- ```
- ● agent: wants to click a button
- │
- ● no click() helper, no upload_file(), no goto()
- │
- ● agent writes the CDP call itself await session.Input.dispatchMouseEvent({...})
- │ await session.DOM.setFileInputFiles({...})
- ✓ done — same pattern for all 652 methods
- ```
- **The protocol is the API.** If Chrome can do it, you can call it.
- ## Installation (legacy)
- For new setups use [Browser Use](https://github.com/browser-use/browser-use) (see the top of this page). To run this repo anyway:
- ```bash
- npx skills add https://github.com/browser-use/browser-harness-js --skill cdp
- ```
- Or paste this into your agent — it'll install the skill, put the CLI on your PATH, and run a first task:
- ```text
- Run `npx skills add https://github.com/browser-use/browser-harness-js --skill cdp`, then
- symlink `browser-harness-js` into a directory on my PATH, then use the cdp skill to drive
- my browser: look at all the tabs I have open, group them by topic, and screenshot the most
- interesting one.
- ```
- (The CLI auto-installs [`bun`](https://bun.sh) on first run if it's missing. Set `BROWSER_HARNESS_SKIP_BUN_INSTALL=1` to opt out.)
- If Chrome asks you to tick a remote-debugging checkbox, do it — that's how the agent attaches:
- <img src="docs/setup-remote-debugging.png" alt="Remote debugging setup" width="520" style="border-radius: 12px;" />
- See [interaction-skills/](interaction-skills/) for recipes on the mechanics that are not obvious from the CDP method list alone.
- ## Files
- - `SKILL.md` — day-to-day usage; how to connect, pick a tab, call methods, persist state
- - `sdk/browser-harness-js` — tiny CLI that auto-spawns the server and forwards snippets
- - `sdk/repl.ts` — Bun HTTP server holding one persistent `Session`
- - `sdk/session.ts` — the `Session` class: transport, connect, target routing, events
- - `sdk/gen.ts` — codegen: reads `browser_protocol.json` + `js_protocol.json` → typed wrappers
- - `sdk/generated.ts` — every CDP method as `session.<Domain>.<method>(params)` (generated)
- No helpers file. No `click()`, no `goto()`, no `upload_file()` — just the protocol, typed.
- ## Why no pre-baked helpers?
- Every helper is a lie about what CDP already gives you. `click(x, y)` hides `Input.dispatchMouseEvent` — which has 14 parameters the LLM might need (button, clickCount, modifiers, pointerType, force, tangentialPressure, …). A harness that exposes three of them quietly limits what the agent can do.
- - Types are the docs. `session.Page.navigate(` triggers autocomplete with the exact params — same JSDoc as the CDP reference.
- - No version drift. The SDK is regenerated from the upstream protocol JSON; new Chrome methods appear as soon as you swap the JSON.
- - No "helper doesn't handle my case" detours. If CDP can do it, the agent can call it — directly, typed, today.
- The only "helpers" you'll find are things CDP itself is missing:
- - `listPageTargets()` — filters `chrome://` / `devtools://` out of `Target.getTargets`
- - `resolveWsUrl({wsUrl|port|profileDir})` — reads `DevToolsActivePort` for Chrome 144+
- - `session.use(targetId)` / `session.waitFor(method, pred, timeout)` — the two routing primitives you genuinely need
- ## Contributing
- PRs welcome. The best way to help: **contribute a new interaction skill** under [interaction-skills/](interaction-skills/) when you figure out the CDP recipe for something non-obvious (a dropdown framework, a shadow-DOM trap, a network-wait pattern).
- - Keep recipes in **pure CDP** — `session.Domain.method(...)`, not wrapped helpers.
- - Lead with the shortest method call that works; add the workaround or trap afterwards.
- - Small and focused beats comprehensive. One mechanic per file.
- - Bug fixes, codegen improvements, and `session.ts` refinements are equally welcome.
- ---
- [Bitter lesson](https://browser-use.com/posts/bitter-lesson-agent-frameworks) · [Skills](https://browser-use.com/posts/web-agents-that-actually-learn)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.