browser-harness turns real Chrome into an agent-operable environment—a thin CDP layer, editable helpers, and domain skills for observe-act-reuse workflows.
What Is browser-harness?
browser-use/browser-harness is a browser control tool for AI agents. It connects LLMs to real Chrome or Chromium and uses CDP for browsing, clicks, screenshots, downloads, uploads, and form actions—so agents can handle web tasks closer to real work.
Project and docs:
Core Design
browser-harness is a browser runtime for agents—not a click-to-run extension for humans.
Core ideas:
- Connect directly to Chrome or Chromium.
- Operate pages over CDP WebSocket.
- Let agents combine screenshots, coordinate clicks, DOM, network state, and raw CDP.
- Store task-specific helpers in
agent-workspace/agent_helpers.py. - Persist site-level know-how in
agent-workspace/domain-skills/. - Keep the core thin—avoid becoming a heavy automation platform.
The project emphasizes a thin CDP harness, editable helpers, and domain skills. The goal isn’t prebuilt support for every site—it’s an operation layer close to a real browser so agents can fill gaps during tasks.
vs Traditional Browser Automation
Classic automation centers on Playwright, Selenium, or Puppeteer—deterministic scripts: open, locate, click, assert.
browser-harness targets open goals: the agent observes, decides, handles dialogs, adds helpers, and reuses site experience.
| Dimension | Playwright / Selenium / Puppeteer | browser-harness |
|---|---|---|
| Primary user | Human writes script; machine runs | Agent observes and acts |
| Task shape | Fixed flows, stable tests | Open goals, dynamic pages |
| Signals | Selectors, assertions, steps | Screenshots, DOM, CDP, network |
| Strength | Mature, stable E2E testing | Closer to autonomous web operation |
| Limit | Flow must be specified upfront | Higher permission and mis-click risk |
It’s not a Playwright replacement. Keep Playwright for stable E2E tests; use browser-harness to make real web UIs agent-operable.
Why Real Chrome Matters
Many browser-agent tools use isolated or headless browsers—easier to deploy, but they may not reuse daily login state, extensions, bookmarks, or profile context.
browser-harness can attach to local Chrome or Browser Use cloud browsers. Common local attachment paths:
- Enable remote debugging via
chrome://inspect/#remote-debugging. - Launch with
--remote-debugging-port=9222 --user-data-dir=...for an isolated profile.
Tradeoffs:
- Current Chrome: matches real workflows—logins, extensions, bookmarks—but sensitive permission boundaries.
- Isolated profile: better for unattended or long-running automation; more control, re-login required.
- Cloud browser: isolation and hosting; less alignment with the user’s daily machine.
Real browsers are powerful—and agents may reach mail, billing consoles, cloud admin, CRM, internal apps, and personal accounts. Pick connection mode by risk.
Editable Helpers and Domain Skills
browser-harness bakes “what the agent learned” into the repo layout.
agent_helpers.py
agent-workspace/agent_helpers.py holds helpers added during tasks—upload flows, download waits, table reads, dialog handling. When built-ins fall short, the agent can add a stable function for reuse.
domain-skills/
agent-workspace/domain-skills/ stores site-specific experience:
- Post-login navigation patterns.
- Dialogs that block main flows.
- Stable vs fragile selectors.
- Upload/download, iframes, shadow DOM, cross-origin widgets.
- Hidden waits and async states in a given admin UI.
Hard parts of web automation aren’t usually “click the button”—they’re these real-page details. Domain skills shorten the path on the next visit.
Good Fit Scenarios
browser-harness works well when you need to:
- Operate real web admin UIs for users.
- Repeat flows in systems without APIs.
- Handle login-dependent personal or enterprise pages.
- Use screenshots for complex interaction state.
- Let agents add tools and site knowledge mid-task.
- Run multiple sub-agents with separate browsers.
- Research browser-agent runtime design.
Examples: tidy web tables, submit internal forms, download bills/reports, upload files, expense workflows, order status checks, SaaS console configuration, extract data from authenticated pages.
Static scraping often doesn’t need a browser—HTTP may suffice. Reserve the browser for state, auth, and interaction.
Risks to Respect
Letting agents drive real Chrome is powerful and sensitive.
Permission boundaries
Mail, payments, cloud consoles, company systems, personal accounts—browser access is partial access to those surfaces.
Credentials
Don’t hand passwords, OTPs, payment data, or 2FA to the model. Agents can wait for human login/confirm steps—they should not read, store, or enter sensitive credentials.
Irreversible actions
Automation ≠ unsupervised trust. Expect fraud controls, mis-clicks, deletes, bulk submits, irreversible ops. Start read-only, low-risk, rollback-friendly flows.
Domain skill privacy
Skills can be saved—but don’t store accounts, internal URLs, customer data, one-off task details, or sensitive coordinate logs.
Connection choice
Daily login reuse favors current Chrome; long-running unattended jobs favor isolated profiles or cloud browsers.
What It Means for Agent Tooling
browser-harness is a pragmatic route: less platform, more real-environment interface.
Many agents stall between:
- Models that reason but can’t see real page state.
- Automation frameworks that need human-written flows upfront.
browser-harness bridges both: the browser holds world state; the agent observes, decides, acts, and extends tools.
“Self-improving harness” doesn’t mean sudden intelligence—it means reusable operational knowledge lands in the repo structure so the next similar site or flow doesn’t start from zero.
Recommendations
- Start low-risk: read pages, screenshot, extract information.
- After stable state recognition, try clicks, uploads, submits.
- Keep human confirmation for accounts, payments, deletes, sends, publishes.
- Run long-term automation in isolated profiles or cloud browsers.
- Redact domain skills—no personal or company secrets.
- Keep Playwright, Selenium, or Puppeteer for stable test suites.
Summary
browser-use/browser-harness matters not for feature bloat but for putting key browser-agent concerns in one design: real Chrome, CDP, screenshot-driven control, editable helpers, domain skill persistence, and permission boundaries.
For stable E2E testing, traditional automation remains mature. For Codex, Claude Code, and similar agents handling real web tasks, browser-harness is a closer fit to how agents actually work.
