Drive Chrome via CDP for authenticated scraping and JS-heavy automation

Drives an existing, already-logged-in browser through the Chrome DevTools Protocol (CDP) for authenticated, visual, or interactive web automation - connecting to the user's running Chrome (or Brave, via the same brave://inspect/#remote-debugging mechanism) rather than launching a separate browser instance. It is invoked as browser-harness -c '<python>' (on $PATH, no cd/uv run needed), with helpers pre-imported and its daemon auto-starting; the first navigation in a session uses new_tab(url) rather than goto_url(url), since goto runs in the user's active tab and would clobber their work.

browser-harness -c '
new_tab("https://docs.browser-use.com")
wait_for_load()
print(page_info())
'

Its core working pattern is screenshot-driven: call capture_screenshot() to see the page, read a target's pixel coordinates off the image, click with click_at_xy(x, y), then screenshot again to verify - explicitly suppressing the "locate a selector first" reflex, since hit-testing happens in Chrome's browser process and clicks pass through iframes, shadow DOM, and cross-origin frames without extra work. It falls back to DOM reads via js(...) only when a target has no visible geometry, uses wait_for_load() after navigation, ensure_real_tab() to recover a stale or internal tab, and raw cdp("Domain.method", params) calls for anything the helpers don't cover. For login-walled content (X/Twitter articles, LinkedIn, paywalled sites) it navigates, waits for JS-heavy rendering, extracts text via js("document.querySelector('article').innerText"), and writes it to a temp file to avoid shell-escaping issues with large text - relying on the user's existing browser session for authentication rather than typing credentials.

For parallel or headless use it supports remote cloud browsers via start_remote_daemon, each isolated by a distinct BU_NAME, with optional named cloud profiles, a proxy country code, and a timeout, requiring BROWSER_USE_API_KEY; it prints (and, locally, auto-opens) a live URL so the user can watch, and remote daemons bill until they time out. Bulk static-page fetching uses http_get() with a thread pool instead of the browser. A set of interaction-skill reference files (connection, cookies, cross-origin iframes, dialogs, downloads, drag-and-drop, dropdowns, iframes, network requests, print-as-PDF, profile sync, screenshots, scrolling, shadow DOM, tabs, uploads, viewport) covers reusable UI mechanics. Optional, off-by-default per-site "domain skills" (enabled via BH_DOMAIN_SKILLS=1) capture durable, non-secret site quirks like stable selectors or URL patterns, never pixel coordinates or task narration.

Use it when a task needs a real logged-in browser, visible interaction, or JS-heavy page control that a static fetch can't provide. Route to a plain scrape API instead when the task needs no interaction and only page content is required. It is not for typing credentials found on a login screen - hitting an auth wall means stopping and asking the user - and any command, remote access, scheduling, or file-changing action needs explicit user approval with the target environment confirmed first.

Input is Python automation code passed via browser-harness -c, driving navigation, clicks, screenshots, and DOM/JS extraction against a connected browser. Output is page state (screenshots, page_info(), extracted text/DOM data) or the side effects of the interaction performed - a page navigated, a form filled, content extracted to a file.

Connects via CDP to the user's local Chrome or Brave, or to a Browser Use cloud browser (via its API and camelCase-keyed REST interface) for remote/parallel sessions; it is a companion to a deepapi scrape skill for non-interactive page fetches and to Hermes agent tooling (installed under ~/.hermes/skills/browser-harness/, requiring its frontmatter name be changed from the upstream browser to avoid shadowing Hermes's built-in browser toolset).

Agents and developers automating real, authenticated, or visually verified browser sessions - extracting content from login-walled sites, driving JS-heavy interactive flows, or supervising parallel remote browser sub-agents.