Browser Harness

1. What is Browser Harness?

Browser Harness is a connector between an AI coding assistant (such as Claude Code or Codex) and the real Chrome browser on your computer. Once connected, the AI can open pages, click buttons, type, take screenshots, download files and more on your behalf, inside the Chrome you already use, with your accounts already signed in. What sets it apart, according to the project: when the AI is missing some ability (say, uploading a file), it writes a small piece of code for it and reuses it later.

It is free and open source (MIT license), made by the Browser Use team. It runs entirely on your machine; their "cloud browsers" are a separate, optional service.

Plainly: this is a developer tool, not an app with a window to click around in. You need an AI coding assistant already running in a terminal, and you give that assistant instructions in plain language. The project is at an early stage (Alpha). This guide takes you as far as a working connection and a first test.

Safety warning: an AI driving your real Chrome can see and act on whatever you are signed in to (mail, social media, banking...). Only use it if you trust your AI assistant, consider a separate Chrome profile for this, and do not let it do sensitive things such as moving money.

A good fit if:

• You already use Claude Code, Codex or a similar coding assistant and want it to act on the web for you.
• You need the AI to do things that require being signed in, or pages heavy on JavaScript that cannot be read with a plain download.

Not a fit if:

• You have no AI coding assistant and want a click-and-go tool. There is no standalone interface.
• You only need to read a public web page. The project's own documentation says a plain fetch (curl) is the right tool for public pages, no browser needed.

2. What you need

• A computer running Windows, macOS or Linux. The source code has handling for all three.
• Google Chrome (or a Chromium-based browser), installed and open. Download from https://www.google.com/chrome/ .
• An AI coding assistant, for example Claude Code (https://code.claude.com/docs/en/overview ) or Codex (https://github.com/openai/codex ). Those services have their own terms and pricing; check each official page. Browser Harness itself does not ask you to pay.
• uv (a tool that installs and runs Python programs, so you do not have to set Python up yourself). The project installs through uv. Official page: https://docs.astral.sh/uv/getting-started/installation/

The latest version at the time of writing is v0.1.13 (4 September 2026), which needs Python 3.11 or newer. The project's install command asks for Python 3.12; uv downloads it automatically if your machine does not have it.

No separate API key for Browser Harness. The project states that using local Chrome needs no Browser Use Cloud key.

3. Step-by-step installation

There are two routes. The easiest for a newcomer is Route A: ask your AI assistant to do the install.

Step 1: Install uv

Windows (open PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Or with Winget:

winget install --id=astral-sh.uv -e

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

On macOS you can also use Homebrew: brew install uv.

Afterwards, close and reopen your command window and check:

uv --version

What success looks like: a uv version number appears.

Step 2 (Route A): Let your AI assistant install it

Open Claude Code or Codex and paste a request like the one below. In essence: install or upgrade browser-harness with uv on Python 3.12, register its "skill", and connect it to your browser.

Install or upgrade browser-harness to the latest stable version with uv using Python 3.12, register the skill from `browser-harness skill`, and connect it to my browser. Ask me whether I want local browser recordings enabled (default: no). If setup or connection fails, follow https://github.com/browser-use/browser-harness/blob/main/install.md

The assistant runs the commands for you and opens Chrome's settings page. When it does, do Step 3.

Step 2 (Route B): Install it yourself

Run the install command (the same on all three systems):

uv tool install --python 3.12 --upgrade --force browser-harness

Check it:

browser-harness --version

What success looks like: a version number such as 0.1.13. For your AI assistant to know how to use the tool, it needs a "skill" named browser-harness, whose text comes from the browser-harness skill command, plus the trigger sentence the project recommends: "Always use browser-harness for any web interaction: automation, scraping, testing, or site/app work." Where skills are stored differs from one assistant to another, so the easiest way is still to have the assistant register the skill (Route A).

Step 3: Let the AI connect to Chrome

This is the one step only you can do; the AI does not click it for you:

1. Open Chrome and type chrome://inspect/#remote-debugging into the address bar, then press Enter.
2. Tick Allow remote debugging for this browser instance.
3. The first time the tool connects, Chrome may show one more dialog asking "Allow remote debugging?". Click Allow. Per the project's documentation this is a per-connection approval; it is expected, not an error.

On macOS, if that dialog gets stuck, the project has a helper command (it needs Accessibility permission for whichever app runs your terminal, under System Settings):

browser-harness mac-approve

Step 4: Check the connection

Ask your AI assistant: "Use browser-harness to print the current page info." Or run the diagnostic command yourself:

browser-harness --doctor

What success looks like: items such as "chrome running" and "daemon alive" pass. If something shows FAIL, see section 5.

About recording: Browser Harness can save screenshots and action traces on your machine. It is off by default. The project advises asking the user once, defaulting to no, because saved content may contain sensitive material. Check the current setting with:

browser-harness recordings

4. First use

Everything happens through your AI assistant. With Chrome open, start Claude Code or Codex and try a simple, low-risk request:

1. "Open https://example.com in a new tab and tell me the page title."
2. "Take a screenshot of that page and tell me where the image file is."

What success looks like: Chrome opens a new tab, marked with a small horse symbol at the start of its title (the sign that the tab is under AI control), the AI reports the page title and saves the screenshot.

Once comfortable, you can ask for longer jobs, like the project's own example: open your profile on a social network and download your latest videos. Remember the AI is using your real accounts.

Using it as an MCP server. If your assistant supports MCP (the standard that lets AI assistants use outside tools), the project provides this mode. With Claude Code:

claude mcp add browser-harness uvx --from 'browser-harness[mcp]' browser-harness-mcp

The tools it exposes have names starting with browser_, for opening tabs, clicking, typing and taking screenshots. Setup for Cursor and other apps is at https://github.com/browser-use/browser-harness/blob/main/docs/MCP.md

Note: commands of the form browser-harness <<'PY' ... PY in the documentation use bash syntax (a heredoc) that Windows PowerShell does not understand. You do not need to type them yourself, because the AI assistant runs them. To run them by hand on Windows, use Git Bash or WSL.

5. Common problems and fixes

Symptom	Cause	Fix
uv or browser-harness is not found	The command window was opened before installing and does not know the new path yet	Close and reopen Terminal/PowerShell and retry
page_info() reports permission-blocked or cannot connect	The remote debugging box is not ticked, or Allow was not clicked	Redo Step 3. If it is ticked but no dialog appears, untick and tick again
browser-harness --doctor shows "chrome running" FAIL	Chrome is not open	Open Chrome and run it again
--doctor shows "daemon alive" FAIL	Remote debugging permission is missing, Chrome was closed, or the connection port is unreachable	Open Chrome, redo Step 3 and run --doctor again
Linux: Chromium installed as a Snap, the AI cannot connect even though Chrome runs	Snap confines apps, so the browser's debugging port is not reachable	Install the official Google Chrome .deb package and set the BH_CHROME_PATH environment variable to its executable; details at https://github.com/browser-use/browser-harness/blob/main/docs/snap-linux-headless.md
The assistant picks an old "browser" skill instead of browser-harness	A stale skill installed earlier is still there	Delete that old skill folder by hand (as the project advises) and do not edit plugin cache folders
Mac: the Allow dialog keeps appearing	Chrome asks for approval on each new connection	Click Allow, or use browser-harness mac-approve as in Step 3. Avoid creating extra connections you do not need

If you are still stuck, the project's issue tracker is at https://github.com/browser-use/browser-harness/issues

6. Uninstalling and updating

Updating

Run the install command from Step 2 (Route B) again; it replaces the old version with the newest one. Or use the tool's own command:

browser-harness --update -y

Uninstalling

uv tool uninstall browser-harness

The tool's data (cloud sign-in if any, an anonymous identifier, the AI's workspace, logs, screenshots) lives in a .config/browser-harness folder under your home directory (on Windows, C:\Users\<your name>\.config\browser-harness, or whatever folder you set with the BH_HOME variable). Delete that folder to remove everything. If you registered a skill with your AI assistant earlier, delete that browser-harness skill folder as well.

To stop Chrome from accepting remote debugging connections, go back to chrome://inspect/#remote-debugging and untick the box you ticked in Step 3.

7. Frequently asked questions

Does it cost anything? Not when used with your own Chrome. Browser Harness is free and open source (MIT). The project also offers cloud browsers (parallel browsers, proxies, CAPTCHA solving...), a separate Browser Use service that is optional. The AI coding assistant you use alongside it may have its own fees.

Does it need the internet? You need a connection to install it and for your AI assistant to work. Driving local Chrome itself needs no Browser Use key.

Is my data sent anywhere? The code includes anonymous usage telemetry (sent to PostHog), on by default and possible to switch off. Turn it off with browser-harness telemetry disable; check the state with browser-harness telemetry status. Separately, the content of pages the AI looks at flows into your conversation with your AI assistant, so be careful around sensitive pages.

Will it run on a weak machine? The tool itself is light (a small Python program attached to Chrome). The practical limits are Chrome and whichever AI assistant you use.

Can I use it on a phone? No. It is a command-line tool for computers.