Skip to content
Get packs

Guide · Open source

How to use browser-harness with Claude Code, Codex or Cursor

Updated · written with AI from the project's own documentation and checked against our catalogue data

Browser Harness is an open-source MIT-licensed project from Browser Use that lets a coding agent such as Claude Code, Codex or Cursor use your real Chrome browser, logged in as you. It opens pages, clicks, types, reads and downloads through the Chrome DevTools Protocol. This guide shows you how to set it up, connect it to your browser, and decide whether it fits your task.

Browser Harnessbrowser-use/browser-harness · ★ 18.8k · MIT

Quick start

  1. 1Check prerequisites. Make sure uv, Python 3.12 and Chrome 144 or newer are installed.
  2. 2Paste the setup prompt. Paste the setup prompt from the README into Claude Code or Codex, or add the MCP config for Cursor.
  3. 3Answer the recordings question. Choose whether local browser recordings are enabled. The default is no.
  4. 4Enable remote debugging. In chrome://inspect/#remote-debugging, tick the checkbox so the agent can connect.
  5. 5Approve the connection. Click Allow when Chrome asks to let the agent connect.
  6. 6Give the agent a task. Ask for a browser task in your own logged-in Chrome, such as downloading your own content.

What you need before you install

The README lists uv, Python 3.12 and Chrome 144 or newer. Chrome 144+ is needed for the remote debugging toggle that lets the agent connect to your running browser.

Because Browser Harness drives your whole running browser, it is worth knowing which logins are active before you start.

  • uv installed
  • Python 3.12
  • Chrome 144 or newer
  • A coding agent: Claude Code, Codex or Cursor

Install browser-harness with the setup prompt

The simplest route is to paste the setup prompt from the README into Claude Code or Codex. The prompt asks the agent to install or upgrade browser-harness with uv using Python 3.12, register the skill from browser-harness skill, and connect it to your browser.

The prompt also asks whether you want local browser recordings enabled. It defaults to no and keeps your existing preference on upgrades. If setup or connection fails, the prompt points the agent to install.md in the repository.

browser-harness skill

Turn on remote debugging in Chrome

The agent will open chrome://inspect/#remote-debugging. On first setup, tick the checkbox so the agent can connect to your browser. Chrome then asks you to click Allow.

Only approve this if you are comfortable letting the agent work inside that browser. The README's comparison table notes that this approval covers the whole browser, not a single site.

  • Open chrome://inspect/#remote-debugging if the agent does not do it for you
  • Tick the remote debugging checkbox
  • Click Allow when Chrome asks

Use browser-harness with Cursor through MCP

Cursor uses an MCP config instead of the setup prompt. Add the browser-harness server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project. The config uses uvx, so uv must be installed.

The server runs browser-harness-mcp over stdio and exposes the browser control helpers as MCP tools. The README points to docs/MCP.md for more setup and client configuration.

  • Project-only: .cursor/mcp.json in your project
  • All projects: ~/.cursor/mcp.json
{"mcpServers":{"browser-harness":{"type":"stdio","command":"uvx","args":["--from","browser-harness[mcp]","browser-harness-mcp"]}}}

Understand how the agent adds missing helpers

When the agent needs an action that no helper covers, it writes one in its local workspace, for example agent-workspace/agent_helpers.py, and then continues the task. The README says the core files in src/browser_harness/ stay protected while the agent writes reusable helpers.

The repository's main files are install.md, which connects the agent to your browser, and SKILL.md, which teaches it the browser workflow.

  • install.md: connects the agent to your browser
  • SKILL.md: the browser workflow the agent follows
  • src/browser_harness/: protected core code
  • agent-workspace/agent_helpers.py: where agent-written helpers go

Clone the repository

If you want the source locally, the README gives a git clone command for the repository. Use it when you want to read the code or follow the contributing guide.

git clone https://github.com/browser-use/browser-harness

What people use it for

  • Downloading your own videos or files from a site where you are signed in, as in the README's example of saving the latest 20 X video posts
  • Uploading a file through a website while using your existing logins
  • Letting Cursor, Claude Code or Codex drive your browser through the MCP server
  • Doing personal browser tasks that an agent would otherwise be blocked from because it has no access to your sessions

Frequently asked questions

Is browser-harness free?

Browser Harness is open source and MIT licensed, according to the README. The README does not list any paid tier for the project itself, though it mentions Browser Use Cloud as a separate option for running many browsers in parallel.

What are the requirements for browser-harness?

The README lists uv, Python 3.12 and Chrome 144 or newer for the remote debugging toggle. You also need a supported coding agent such as Claude Code, Codex or Cursor.

Is browser-harness safe to use with my personal logins?

The agent works in your running Chrome logged in as you, and the README's comparison table says the approval covers the whole browser. Use it only if you are comfortable with an agent having access to your personal logins.

How is browser-harness different from Playwright MCP?

Playwright MCP uses its own browser profile by default, while Browser Harness drives your running Chrome. The README recommends Playwright for isolated, repeatable CI tests in a clean browser with no personal logins.

Can I use browser-harness with Cursor?

Yes. The README describes an MCP config for Cursor that runs browser-harness-mcp through uvx. Add it to .cursor/mcp.json in a project or to ~/.cursor/mcp.json for all projects.

What should I do if setup fails?

The setup prompt tells the agent to follow install.md in the repository when setup or connection fails. You can also check that Chrome is version 144 or newer and that the remote debugging checkbox is ticked.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Browser Harness suits developers who already use Claude Code, Codex or Cursor and want the agent to act in their own logged-in Chrome for personal tasks. It is a poor fit for repeatable tests of your own app or for running many browsers at scale, where the README points to Playwright and Browser Use Cloud instead.

Install options & downloads