browser

Category: Tools & Productivity | Uploader: browser-use | Downloads: 0 | Version: v1.0（Latest）

Direct browser control via CDP. Use when the user wants to automate, scrape, test, or interact with web pages. Connects to the user's already-running Chrome.

Changelog: Source: GitHub https://github.com/browser-use/browser-harness

Directory Structure

Current level: tree/main/

📁 .github/
- 📁 ISSUE_TEMPLATE/
  - 📄 bug-report.yml 1.4 KB
  - 📄 config.yml 395 B
  - 📄 feature-request.yml 909 B
- 📄 VOUCHED.td 406 B
📁 agent-workspace/
- 📁 domain-skills/
  - 📁 aa/
    
    📄 checkout.md 9.8 KB
  - 📁 agentlist/
    
    📄 discovery.md 5.9 KB
  - 📁 alaska/
    
    📄 checkout.md 5.6 KB
  - 📁 amazon/
    
    📄 product-search.md 8.5 KB
  - 📁 archive-org/
    
    📄 scraping.md 14.8 KB
  - 📁 articulate-rise/
    
    📄 code-blocks.md 9.4 KB
  - 📁 arxiv/
    
    📄 scraping.md 13.4 KB
  - 📁 arxiv-bulk/
    
    📄 scraping.md 13.7 KB
  - 📁 atlas/
    
    📄 overview.md 3.4 KB
  - 📁 bigbang-hr/
    
    📄 checkout.md 4.6 KB
  - 📁 bilibili/
    
    📄 navigation.md 11.1 KB
  - 📁 booking-com/
    
    📄 scraping.md 21.8 KB
  - 📁 BOSS-zhipin/
    
    📄 chat.md 12.6 KB
    
    📄 job-search.md 12.7 KB
    
    📄 navigation.md 2.6 KB
  - 📁 capterra/
    
    📄 scraping.md 18.3 KB
  - 📁 centilebrain/
    
    📄 generate-estimates.md 5.1 KB
  - 📁 claude-ai/
    
    📄 extract-share-transcript.py 2.7 KB
    
    📄 share-export.md 3.8 KB
  - 📁 coingecko/
    
    📄 scraping.md 14.3 KB
  - 📁 coinmarketcap/
    
    📄 scraping.md 16.5 KB
  - 📁 coursera/
    
    📄 scraping.md 13.1 KB
  - 📁 craigslist/
    
    📄 scraping.md 15.4 KB
  - 📁 crossref/
    
    📄 scraping.md 23.3 KB
  - 📁 ctrip/
    
    📄 hotels.md 10.1 KB
  - 📁 dev-to/
    
    📄 scraping.md 13.1 KB
  - 📁 duckduckgo/
    
    📄 scraping.md 15.5 KB
  - 📁 ebay/
    
    📄 scraping.md 16.6 KB
  - 📁 etsy/
    
    📄 scraping.md 18.5 KB
  - 📁 eventbrite/
    
    📄 scraping.md 15.3 KB
  - 📁 expedia/
    
    📄 automation.md 5.0 KB
  - 📁 facebook/
    
    📄 groups.md 10.0 KB
    
    📄 pages.md 13.4 KB
  - 📁 flipkart/
    
    📄 shopping.md 10.0 KB
  - 📁 framer/
    
    📄 editor.md 6.7 KB
  - 📁 fred/
    
    📄 scraping.md 19.2 KB
  - 📁 g2/
    
    📄 scraping.md 22.0 KB
  - 📁 genius/
    
    📄 scraping.md 19.7 KB
  - 📁 github/
    
    📄 repo-actions.md 3.4 KB
    
    📄 scraping.md 7.8 KB
  - 📁 glassdoor/
    
    📄 scraping.md 19.6 KB
  - 📁 gmail/
    
    📄 compose.md 5.5 KB
  - 📁 goodreads/
    
    📄 scraping.md 19.3 KB
  - 📁 gutenberg/
    
    📄 scraping.md 15.9 KB
  - 📁 hackernews/
    
    📄 scraping.md 8.5 KB
  - 📁 howlongtobeat/
    
    📄 scraping.md 21.7 KB
  - 📁 imdb/
    
    📄 scraping.md 12.4 KB
  - 📁 itch-io/
    
    📄 scraping.md 16.9 KB
  - 📁 job-boards/
    
    📄 indeed-glassdoor.md 35.7 KB
  - 📁 letterboxd/
    
    📄 scraping.md 14.7 KB
  - 📁 linkedin/
    
    📄 invitation-manager.md 4.5 KB
  - 📁 loom/
    
    📄 folder-enumeration.md 8.6 KB
  - 📁 ly-com/
    
    📄 hotels.md 10.3 KB
  - 📁 macrotrends/
    
    📄 scraping.md 20.5 KB
  - 📁 manus/
    
    📄 tasks.md 11.9 KB
  - 📁 medium/
    
    📄 article-hydration.md 5.5 KB
    
    📄 scraping.md 16.8 KB
  - 📁 metacritic/
    
    📄 scraping.md 20.2 KB
  - 📁 musicbrainz/
    
    📄 scraping.md 19.1 KB
  - 📁 nasa/
    
    📄 scraping.md 14.8 KB
  - 📁 news-aggregation/
    
    📄 multi-source.md 7.9 KB
  - 📁 open-library/
    
    📄 scraping.md 18.8 KB
  - 📁 openalex/
    
    📄 scraping.md 17.8 KB
  - 📁 openstreetmap/
    
    📄 scraping.md 20.5 KB
  - 📁 package-registries/
    
    📄 npm-pypi.md 16.3 KB
  - 📁 perplexity/
    
    📄 computer.md 16.0 KB
  - 📁 polymarket/
    
    📄 scraping.md 13.4 KB
  - 📁 producthunt/
    
    📄 scraping.md 11.1 KB
  - 📁 pubmed/
    
    📄 scraping.md 18.3 KB
  - 📁 quora/
    
    📄 scraping.md 16.2 KB
  - 📁 rawg/
    
    📄 scraping.md 13.4 KB
  - 📁 reddit/
    
    📄 scraping.md 8.3 KB
  - 📁 rest-countries/
    
    📄 scraping.md 9.7 KB
  - 📁 salesforce/
    
    📄 .gitkeep 0 B
  - 📁 sec-edgar/
    
    📄 scraping.md 15.6 KB
  - 📁 shopify-admin/
    
    📄 embedded-apps.md 2.5 KB
    
    📄 knowledge-base.md 4.2 KB
    
    📄 polaris-inputs.md 5.3 KB
    
    📄 README.md 2.1 KB
  - 📁 soundcloud/
    
    📄 scraping.md 13.9 KB
  - 📁 spotify/
    
    📄 scraping.md 14.5 KB
  - 📁 spreadshirt/
    
    📄 .gitkeep 0 B
  - 📁 stackoverflow/
    
    📄 scraping.md 18.2 KB
  - 📁 steam/
    
    📄 scraping.md 21.6 KB
  - 📁 substack/
    
    📄 scraping.md 11.9 KB
  - 📁 thetechgeeks/
    
    📄 pricing.md 2.6 KB
  - 📁 tiktok/
    
    📄 upload.md 3.8 KB
  - 📁 tradingview/
    
    📄 scraping.md 12.4 KB
  - 📁 trello/
    
    📄 boards-and-lists.md 3.5 KB
  - 📁 trustpilot/
    
    📄 scraping.md 13.6 KB
  - 📁 walmart/
    
    📄 scraping.md 16.7 KB
  - 📁 wayback-machine/
    
    📄 scraping.md 10.6 KB
  - 📁 weather/
    
    📄 scraping.md 16.5 KB
  - 📁 wehotel/
    
    📄 hotels.md 10.0 KB
  - 📁 wellfound/
    
    📄 scraping.md 20.8 KB
  - 📁 world-bank/
    
    📄 scraping.md 11.6 KB
  - 📁 xiaohongshu/
    
    📄 scraping.md 6.1 KB
  - 📁 youtube/
    
    📄 scraping.md 17.7 KB
  - 📁 zillow/
    
    📄 scraping.md 18.7 KB
- 📄 agent_helpers.py 243 B
📁 docs/
- 📄 allow-remote-debugging.png 188.1 KB
- 📄 setup-remote-debugging.png 49.5 KB
📁 domain-skills/
- 📁 amazon/
  - 📄 cart.md 2.2 KB
  - 📄 orders.md 5.3 KB
📁 interaction-skills/
- 📄 connection.md 1.6 KB
- 📄 cookies.md 119 B
- 📄 cross-origin-iframes.md 165 B
- 📄 dialogs.md 2.3 KB
- 📄 downloads.md 160 B
- 📄 drag-and-drop.md 168 B
- 📄 dropdowns.md 193 B
- 📄 iframes.md 168 B
- 📄 network-requests.md 196 B
- 📄 print-as-pdf.md 171 B
- 📄 profile-sync.md 4.9 KB
- 📄 screenshots.md 1.0 KB
- 📄 scrolling.md 173 B
- 📄 shadow-dom.md 147 B
- 📄 tabs.md 2.1 KB
- 📄 uploads.md 10 B
- 📄 viewport.md 128 B
📁 src/
- 📁 browser_harness/
  - 📄 __init__.py 37 B
  - 📄 _ipc.py 5.8 KB
  - 📄 admin.py 24.9 KB
  - 📄 daemon.py 14.6 KB
  - 📄 helpers.py 19.9 KB
  - 📄 run.py 3.1 KB
📁 tests/
- 📁 integration/
  - 📄 __init__.py 0 B
  - 📄 test_js.py 5.5 KB
- 📁 unit/
  - 📄 __init__.py 0 B
  - 📄 test_admin.py 9.8 KB
  - 📄 test_helpers.py 11.2 KB
  - 📄 test_run.py 2.1 KB
- 📄 __init__.py 0 B
- 📄 conftest.py 293 B
📄 .env.example 102 B
📄 .gitignore 66 B
📄 AGENTS.md 941 B
📄 install.md 9.6 KB
📄 LICENSE 1.0 KB
📄 pyproject.toml 598 B
📄 README.md 3.6 KB
📄 SKILL.md 7.1 KB

SKILL.md

---
name: browser
description: Direct browser control via CDP. Use when the user wants to automate, scrape, test, or interact with web pages. Connects to the user's already-running Chrome.
---

# browser-harness

Direct browser control via CDP. For task-specific edits, use `agent-workspace/agent_helpers.py`. For setup, install, or connection problems, read install.md.

Domain skills (community-contributed per-site playbooks under `agent-workspace/domain-skills/`) are off by default. Set `BH_DOMAIN_SKILLS=1` to enable them; see the bottom section.

## Usage

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

- Invoke as browser-harness — it's on $PATH. No cd, no uv run.
- First navigation is new_tab(url), not goto_url(url) — goto runs in the user's active tab and clobbers their work.

## Tool call shape

```bash
browser-harness -c '
# any python. helpers pre-imported. daemon auto-starts.
'
```

run.py calls ensure_daemon() before exec — you never start/stop manually unless you want to.

### Remote browsers

Use remote for parallel sub-agents (each gets its own isolated browser via a distinct BU_NAME) or on a headless server. BROWSER_USE_API_KEY must be set. start_remote_daemon, list_cloud_profiles, list_local_profiles, sync_local_profile are pre-imported.

```bash
browser-harness -c '
start_remote_daemon("work")                               # default — clean browser, no profile
# start_remote_daemon("work", profileName="my-work")      # reuse a cloud profile (already logged in)
# start_remote_daemon("work", profileId="<uuid>")         # same, but by UUID
# start_remote_daemon("work", proxyCountryCode="de", timeout=120)   # DE proxy, 2-hour timeout
# start_remote_daemon("work", proxyCountryCode=None)      # disable the Browser Use proxy
'

BU_NAME=work browser-harness -c '
new_tab("https://example.com")
print(page_info())
'
```

start_remote_daemon prints liveUrl and auto-opens it in the local browser (if a GUI is detected) so the user can watch along. Headless servers print only — share the URL with the user. The daemon PATCHes the cloud browser to stop on shutdown, which persists profile state. Running remote daemons bill until timeout.

Profiles (cookies-only login state) live in interaction-skills/profile-sync.md — covers list_cloud_profiles(), the chat-driven "which profile?" pattern, and sync_local_profile() for uploading a local Chrome profile.

## Interaction skills

If you start struggling with a specific mechanic while navigating, look in interaction-skills/ for helpers. They cover reusable UI mechanics like dialogs, tabs, dropdowns, iframes, and uploads. The available interaction skills are:
- connection.md
- cookies.md
- cross-origin-iframes.md
- dialogs.md
- downloads.md
- drag-and-drop.md
- dropdowns.md
- iframes.md
- network-requests.md
- print-as-pdf.md
- profile-sync.md
- screenshots.md
- scrolling.md
- shadow-dom.md
- tabs.md
- uploads.md
- viewport.md

## What actually works

- Screenshots first: use capture_screenshot() to understand the current page quickly, find visible targets, and decide whether you need a click, a selector, or more navigation.
- Clicking: capture_screenshot() → read the pixel off the image → click_at_xy(x, y) → capture_screenshot() to verify. Suppress the Playwright-habit reflex of "locate first, then click" — no getBoundingClientRect, no selector hunt. Drop to DOM only when the target has no visible geometry (hidden input, 0×0 node). Hit-testing happens in Chrome's browser process, so clicks go through iframes / shadow DOM / cross-origin without extra work.
- Bulk HTTP: http_get(url) + ThreadPoolExecutor. No browser for static pages (249 Netflix pages in 2.8s).
- After goto: wait_for_load().
- Wrong/stale tab: ensure_real_tab(). Use it when the current tab is stale or internal; the daemon also auto-recovers from stale sessions on the next call.
- Verification: print(page_info()) is the simplest "is this alive?" check, but screenshots are the default way to verify whether a visible action actually worked.
- DOM reads: use js(...) for inspection and extraction when the screenshot shows that coordinates are the wrong tool.
- Iframe sites (Azure blades, Salesforce): click_at_xy(x, y) passes through; only drop to iframe DOM work when coordinate clicks are the wrong tool.
- Auth wall: redirected to login → stop and ask the user. Don't type credentials from screenshots.
- Raw CDP for anything helpers don't cover: cdp("Domain.method", params).

## Design constraints

- Coordinate clicks default. Input.dispatchMouseEvent goes through iframes/shadow/cross-origin at the compositor level.
- Connect to the user's running Chrome. Don't launch your own browser.
- cdp-use is only for CDPClient.send_raw. Prefer raw CDP strings over typed wrappers.
- run.py stays tiny. No argparse, subcommands, or extra control layer.
- Core helpers stay short. Put task-specific helper additions in `agent-workspace/agent_helpers.py`; daemon/bootstrap and remote session admin live in the core package.
- Don't add a manager layer. No retries framework, session manager, daemon supervisor, config system, or logging framework.

## Gotchas (field-tested)

- Omnibox popups are fake page targets. Filter chrome://omnibox-popup... and other internals when you need a real tab.
- CDP target order != Chrome's visible tab-strip order. Use UI automation when the user means "the first/second tab I can see"; Target.activateTarget only shows a known target.
- Default daemon sessions can go stale. ensure_real_tab() re-attaches to a real page.
- Browser Use API is camelCase on the wire. cdpUrl, proxyCountryCode, etc.
- Remote cdpUrl is HTTPS, not ws. Resolve the websocket URL via /json/version.
- Stop cloud browsers with PATCH /browsers/{id} + {"action":"stop"}.
- After every meaningful action, re-screenshot before assuming it worked. Use the image to verify changed state, open menus, navigation, visible errors, and whether the page is in the state you expected.
- Use screenshots to drive exploration. They are often the fastest way to find the next click target, notice hidden blockers, and decide if a selector is even worth writing.
- Prefer compositor-level actions over framework hacks. Try screenshots, coordinate clicks, and raw key input before adding DOM-specific workarounds.
- If you need framework-specific DOM tricks, check interaction-skills/ first. That is where dropdown, dialog, iframe, shadow DOM, and form-specific guidance belongs.

## Domain skills (opt-in)

Only applies when `BH_DOMAIN_SKILLS=1`. Otherwise ignore — `agent-workspace/domain-skills/` is dormant and `goto_url` won't surface skill files.

When enabled, search `agent-workspace/domain-skills/<host>/` before inventing an approach. `goto_url` returns up to 10 skill filenames for the navigated host.

If you learn anything non-obvious — a private API, stable selector, framework quirk, URL pattern, hidden wait, or site-specific trap — open a PR to `agent-workspace/domain-skills/<site>/`. Capture the durable shape of the site (the map, not the diary). Don't write pixel coordinates (break on layout), task narration, or secrets — the directory is public.

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

browser

Directory Structure

SKILL.md

Report

Notice