Browser Harness JS skill
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
- 493 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Attaches to your running Chrome and can read pages and cookies and type into sites where you are already logged in
- The agent calls any protocol method, including file uploads and downloads, network interception and page printing
- On first run installs the Bun runtime and keeps a background server on a local port until you stop it
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/browser-harness-jsDetects 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.
- Attaches to your running Chrome and can read pages and cookies and type into sites where you are already logged in
- The agent calls any protocol method, including file uploads and downloads, network interception and page printing
- On first run installs the Bun runtime and keeps a background server on a local port until you stop it
This is third-party code. Review the repository files before installing.
What it does
Browser Harness JS is the thinnest possible bridge between a language model and Chrome. The library is generated from the Chrome DevTools protocol definitions: it exposes 56 domains and 652 typed methods of the form `session.Page.navigate({url})`. There are no ready-made helpers such as `click()`, `goto()` or `upload_file()`: the authors argue every helper hides part of the protocol, so the agent writes the call itself, for example `Input.dispatchMouseEvent` or `DOM.setFileInputFiles`. It works through the `browser-harness-js` command-line program. On first run it starts a background Bun HTTP server holding one persistent `Session`, and later calls go to the same process. The connection, the chosen tab and global variables persist between calls. `session.connect()` with no arguments finds a running Chromium browser on its own: Chrome, Chromium, Edge, Brave, Arc, Vivaldi, Opera, Comet or Canary. The `interaction-skills/` folder holds short recipes for non-obvious mechanics: dropdowns, shadow DOM, iframes, uploads and downloads, dialogs, cookies, screenshots, print to PDF, scrolling and drag and drop.
Who it is for. For developers and agent enthusiasts who want direct, complete access to Chrome with no wrapper over the browser.
Good fit when
- You want an agent to look at all open tabs, group them by topic and screenshot the most interesting one
- The task needs a rarely used protocol call that wrappers lack: all 14 `Input.dispatchMouseEvent` parameters or network interception
- You need to attach to an already running browser with your session and act in it without a new window
- A page uses shadow DOM, nested iframes or unusual dropdowns, and you want proven pure-CDP recipes
- You need to save a page as PDF, download a file or handle dialogs through the protocol
Not a fit when
- You want simple commands such as «open a site and click a button» without knowing the protocol: a browser CLI with ready-made actions fits better
- The task must not touch your main browser with logged-in work accounts: the connection goes to the real session
- New software cannot be installed on the machine: the command installs Bun on first run if it is missing
- You need a non-Chromium browser: the skill attaches to Chrome, Edge, Brave and other browsers on that engine
Example request
Use the cdp skill to connect to my Chrome, list all open tabs, group them by topic and take a screenshot of the most interesting oneLimitations
A Chromium-based browser with remote debugging is required. If Chrome asks you to tick a remote-debugging checkbox, do it: that is how the agent attaches. For Chrome 144 and newer the port is read from the `DevToolsActivePort` file.
The `browser-harness-js` program does not land on PATH automatically: after `npx skills add` the skill sits in the agent's folder and you must create the symlink yourself, with paths for macOS and Linux given in SKILL.md. If Bun is missing the CLI installs it; set `BROWSER_HARNESS_SKIP_BUN_INSTALL=1` to opt out.
Multi-line snippets passed through stdin must return the result explicitly with `return`. The server port is 9876 by default and the log is `/tmp/browser-harness-js.log`; both are changed with the `CDP_REPL_PORT` and `CDP_REPL_LOG` variables.
How to disable. Stop the background server with `browser-harness-js --stop`. Then remove the `browser-harness-js` symlink from PATH and the cdp skill folder from the agent's skills directory, for example `~/.claude/skills/cdp`. In Chrome you can untick the remote-debugging box to close the connection.
FAQ
How do I install Browser Harness JS in Claude Code?
Run `npx skills add https://github.com/browser-use/browser-harness-js --skill cdp`. Then symlink `browser-harness-js` to `sdk/browser-harness-js` in a directory on PATH, because the install command does not put the CLI there. Or paste the ready-made prompt from the README and the agent does all the steps.
Why does the tool have no click or goto functions?
The authors treat every helper as a lossy layer over the protocol: `click(x, y)` hides 14 `Input.dispatchMouseEvent` parameters, and a trimmed wrapper limits the agent. So every CDP method is available as `session.<Domain>.<method>(params)` and the types serve as docs.
How do I attach to an already open Chrome?
Call `await session.connect()` with no arguments: the skill looks for running browsers through the `DevToolsActivePort` file in the profile and picks the most recently launched. To choose a specific one use `{ profileDir }` or `{ wsUrl }`. If Chrome asks to enable remote debugging, tick the box.
What persists between calls?
One connection to the browser, the active tab and values in `globalThis`. While the background Bun server runs, later `browser-harness-js` calls use the same `session`. `--restart` gives a clean state and `--stop` shuts it down.
What is in the interaction-skills folder?
Pure-CDP recipes for individual mechanics: connection, cookies, iframes and cross-origin iframes, dialogs, downloads, drag and drop, dropdowns, network requests, print to PDF, screenshots, scrolling, shadow DOM, tabs, uploads and viewport. New recipes are welcome, one per file.
Discussion
No questions or reviews yet.
Related
SkillsA skill and CLI from Browser Use: the agent drives your real Chrome over the DevTools Protocol, logged in as you, and writes any missing helper itself
A skill for Amp, Claude Code and Cursor: the agent drives your live Chrome with its open tabs and signed-in accounts through a single debugging toggle
A CLI, skill and MCP server for driving Chrome with short Puppeteer scripts, with tabs that keep state between calls
A Claude Code plugin that drives your Chrome over the DevTools Protocol: tabs, forms, page extraction and screenshots with no third-party dependencies
A local browser automation platform: MCP server, CLI and skills so an agent can drive Chrome, fill forms and pull data from pages
CLI, skill and Python library for browser control: the agent clicks, fills forms and reads pages over CDP
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Browser Harness JS (this entry) | yes | 493 | ||
| Browser Use | no | 118,910 | a Python CLI, skill and library with ready-made agent actions in the browser | |
| browser-use-mcp-server | no | API key | 848 | a Playwright-based MCP server with ready commands for opening pages, clicking and forms |
README in short
The README states the idea: the thinnest possible bridge from a language model to Chrome, with no ready-made helpers or rails, where the protocol is the API. It then gives one-command install and a ready prompt for an agent, a note about the debugging checkbox, a list of repository files and the reasoning for having no helpers. The exceptions are listed: `listPageTargets`, `resolveWsUrl`, `session.use` and `session.waitFor`. It ends with a request for new pure-CDP interaction recipes.
README badge
Original SKILL.md
---
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