Browser Harness skill
A 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
- 18,581 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent drives your real Chrome and sees all open tabs, logins and cookies, not just one site
- Through CDP it runs arbitrary code on pages, presses buttons, types text and uploads files under your account
- With recordings on, screenshots and action traces with page content are saved to disk
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/browser-harnessDetects 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 agent drives your real Chrome and sees all open tabs, logins and cookies, not just one site
- Through CDP it runs arbitrary code on pages, presses buttons, types text and uploads files under your account
- With recordings on, screenshots and action traces with page content are saved to disk
This is third-party code. Review the repository files before installing.
What it does
Browser Harness lets Claude Code, Codex or Cursor drive a Chrome browser in which you are already signed in to your services. The `browser-harness` command attaches to a running Chrome over the DevTools Protocol (CDP) and takes short Python scripts through standard input. The scripts come with ready functions for tabs, clicks, typing, scrolling, screenshots, file uploads and arbitrary code on the page. If a needed function is missing, the agent writes it itself into `agent-workspace/agent_helpers.py`, while the `src/browser_harness/` folder stays protected from edits. The working order is described in `SKILL.md`. For simple public pages the agent uses `curl`, and turns to the browser when it needs clicks, your session, JavaScript rendering or a bot-protected page. It finds elements through the accessibility tree rather than screenshots, keeps one tab per task and closes extra tabs it created. At a login screen the agent stops and asks you, and it does not enter passwords, multi-factor codes or consents. On first connection Chrome asks you to allow remote debugging at `chrome://inspect/#remote-debugging`; on macOS the `browser-harness mac-approve` command helps with the prompt. The `browser-harness-mcp` command exposes the same functions as MCP tools with a `browser_` prefix: open a tab, click, type, take a screenshot, run code, upload a file, start and stop a recording. For parallel work the project has built-in access to Browser Use cloud browsers, which need a key and payment.
Who it is for. For developers and anyone who gives an agent work in web services under their own account: filling forms, exporting data, checking pages and downloading files.
Good fit when
- The agent has to do something in a service where you are already signed in and no separate login is set up for a bot
- A page is rendered by JavaScript and a plain request returns an empty shell
- You need to download a set of files or records from a personal account that has no API
- You want a record of the agent's actions to review what it did on a page
- You want to connect browser control to Claude Code, Cursor or another client as an MCP server
Not a fit when
- You only need to read a public page or call an API: the skill itself recommends `curl`, a browser is overkill
- Chrome has services open with payments, mail or work consoles the agent must not touch: it gets access to the whole browser, not one site
- The machine has no Python 3.11 or newer: the tool is written in Python
- You need isolation between several parallel tasks: tabs in local Chrome are shared, and the authors suggest Browser Use cloud browsers for isolation
- You need a setup for a remote machine with no display: without cloud browsers you need a local Chrome with remote debugging allowed
Example request
Open my store account in my Chrome, find the last ten orders and save their numbers and amounts to a tableLimitations
The project is in alpha: the package manifest shows version 0.1.13 and the classifier `Development Status :: 3 - Alpha`. Python 3.11 or newer is required, and the installer in `install.md` uses `uv` and Python 3.12.
Local connection works only with Chrome or Chromium where you have allowed remote debugging. On macOS Chrome shows a prompt with an Allow button for each new connection, and for the agent to press it the terminal needs access under Accessibility in system settings. One local daemon holds one current tab, so two agents switching tabs at the same time can mix them up.
Recording is off by default. After `browser-harness recordings enable`, screenshots and action traces are saved to disk and may contain page content. The site notes in `agent-workspace/domain-skills` (151 Markdown files) load only with the variable `BH_DOMAIN_SKILLS=1`.
Browser Use cloud browsers need a `BROWSER_USE_API_KEY` key or a login with `browser-harness auth login` and are billed until stopped. The license is MIT.
How to disable. Remove the program with `uv tool uninstall browser-harness` and the `browser-harness` skill file from the agent's skills folder. In Chrome clear the allow checkbox at `chrome://inspect/#remote-debugging`. Turn recordings off with `browser-harness recordings disable` and remove the MCP server with `claude mcp remove browser-harness`. If you started a cloud browser, stop it with `stop_remote_daemon(name)`.
FAQ
How is this different from launching a separate browser for the agent?
The agent attaches to your running Chrome and sees the same logins and cookies you do. No separate profile is created, and the sign-in under your account stays.
What does the agent do at a login page?
It stops and asks you. There is one exception: if Chrome is already signed in through single sign-on, the agent uses it automatically. It does not enter passwords, multi-factor codes or consents.
Which tools does the MCP server give?
Twenty-three tools with the `browser_` prefix, among them `browser_new_tab`, `browser_click`, `browser_type`, `browser_screenshot`, `browser_js`, `browser_cdp`, `browser_upload_file` and `browser_http_get`. Start it with `uvx --from 'browser-harness[mcp]' browser-harness-mcp`.
What are the site notes?
The `agent-workspace/domain-skills` folder with notes on specific sites, for example Amazon, Booking and arXiv. They stay off until the variable `BH_DOMAIN_SKILLS=1` is set; then the agent reads the files for the relevant site before it works.
Do I have to pay?
Local use is free: the package is under the MIT license. Only the Browser Use cloud browsers, which you need for parallel tasks and bot-protected sites, are paid.
Discussion
No questions or reviews yet.
Related
SkillsThe cdp skill: an agent drives your Chrome straight through the DevTools protocol, with 652 typed methods and no ready-made click or goto helpers
CLI, skill and Python library for browser control: the agent clicks, fills forms and reads pages over CDP
A local browser automation platform: MCP server, CLI and skills so an agent can drive Chrome, fill forms and pull data from pages
A separate browser for agents with a skill and MCP: Claude Code and Codex work in your logged-in accounts, and every session is recorded for replay
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 fast Rust CLI for agent browser automation: accessibility snapshots with element refs, an MCP server and skills
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Browser Harness (this entry) | no | 18,581 | |
| bb-browser | no | 6,249 | a CLI and MCP server through which an agent drives your real Chrome with saved logins |
| dev-browser | no | 6,694 | a CLI, skill and MCP for driving Chrome with short Puppeteer scripts, with tabs that keep state between runs |
| BrowserOS neo | no | 14,072 | a separate browser for agents with a skill and MCP |
README in short
The repository holds `SKILL.md` with the agent's working order, `install.md` with the quick install and a manual connection check, the `docs/MCP.md` document and an `interaction-skills` folder with tactics for common snags. The Python package with the core sits in `src/browser_harness/`, while the agent's own helpers live separately in `agent-workspace`, together with the site notes. The root contains `AGENTS.md` and `CLAUDE.md` for developing the project, a Claude Code plugin manifest and contribution rules.
README badge
Original SKILL.md
--- name: browser-harness description: "Control a real browser via CDP: clicking, typing, navigation, logged-in sessions, JS-rendered or bot-protected pages. Not for plain HTTP fetches of public content - use curl for those." --- # browser-harness Direct browser control via CDP. For task-specific edits, use `agent-workspace/agent_helpers.py`. For setup, install, or connection problems, read https://github.com/browser-use/browser-harness/blob/main/install.md. ## When Not to Use A basic fetch of public information needs no browser. If a plain HTTP request can read it — a public page, an API, docs — use `curl` or your fetch tool, and leave the browser alone. Use browser-harness when the task needs interaction (click, type, navigate), the user's logged-in session, JS rendering, or a bot-protected page. If a direct fetch fails or returns a shell page, then escalate to the browser. Domain skills are off by default. Set `BH_DOMAIN_SKILLS=1` to enable them; see the bottom section. ## Usage ```bash browser-harness <<'PY' print(page_info()) PY ``` - Invoke as `browser-harness`. Use heredocs for multi-line commands. - Helpers are pre-imported. `run.py` calls `ensure_daemon()` before `exec`. - First navigation for a task is `new_tab(url)`, not `goto_url(url)`.