browser-use

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: browser-use
description: "Direct browser control via CDP for web interaction: automation, scraping, testing, screenshots, and site/app work."
homepage: https://browser-use.com
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["browser-use"] },
        "install":
          [
            {
              "id": "uv",
              "kind": "uv",
              "package": "browser-use",
              "bins": ["browser-use"],
              "label": "Install Browser Use CLI (uv)",
            },
          ],
      },
  }
---

# Browser Use

Direct browser control via CDP. For task-specific edits, use `agent-workspace/agent_helpers.py`. For setup, install, or connection problems, read https://github.com/browser-use/browser-harness/blob/main/install.md.

## When Not to Use

A basic fetch of public information needs no browser. If a plain HTTP request can read it — a public page, an API, docs — use `curl` or your fetch tool, and leave the browser alone. Use browser-use when the task needs interaction (click, type, navigate), the user's logged-in session, JS rendering, or a bot-protected page. If a direct fetch fails or returns a shell page, then escalate to the browser.

Domain skills are off by default. Set `BH_DOMAIN_SKILLS=1` to enable them; see the bottom section.

**If `BH_DOMAIN_SKILLS=1` and the task is site-specific, read every file in the matching `$BH_AGENT_WORKSPACE/domain-skills/<site>/` directory before inventing an approach.**

## Usage

```bash
browser-use <<'PY'
print(page_info())
PY
```

- Invoke as `browser-use`. Use heredocs for multi-line commands.
- Helpers are pre-imported. `run.py` calls `ensure_daemon()` before `exec`.
- First navigation for a task is `new_tab(url)`, not `goto_url(url)`. The daemon
  preserves the attached tab across separate CLI invocations, so do not call
  `new_tab()` again in every script.
- Keep one working tab per task/site. Before opening another, inspect
  `current_tab()` and `list_tabs()` and use `switch_tab()` to reuse a matching
  tab. Do not leave duplicate tabs on the same URL or close tabs you did not
  create.
- `new_tab()` and `switch_tab()` attach and move the horse marker without
  changing Chrome's visible tab. Screenshots and normal CDP input work in the
  background; call `activate_tab(target)` only when the user explicitly asks
  or a page demonstrably pauses rendering while hidden.
- Set `BH_TAB_MARKER=0` before starting the daemon to leave page titles unchanged.
  The horse marker remains enabled by default.
- A timed-out `scroll(...)` on an attached background tab is evidence that the
  page needs to be visible. Call `activate_tab(current_tab())`, retry the same
  scroll once, then re-read the scroll position. This visibly switches tabs,
  so do not use it when the user has forbidden foreground changes. Do not
  invent a `Runtime.evaluate` scroll replacement or a cross-frame JS walker.
- The normal local flow attaches to the running Chrome/Chromium CDP endpoint. No browser ids or local profile selection.

## Local Chrome

If the daemon cannot connect, run diagnostics:

```bash
browser-use --doctor
```

If Chrome is not running at all, the harness launches it automatically and retries.

If Chrome is running but remote debugging is not enabled, the harness opens:

```text
chrome://inspect/#remote-debugging
```

On macOS, when local Chrome asks for remote-debugging permission, keep the
original browser command running and call `mac-approve` in another shell/tool
call. Preserve the exact daemon name: if the waiting command used
`BU_NAME=r7k2`, run:

```text
BU_NAME=r7k2 browser-use mac-approve
```

For the default daemon, omit the `BU_NAME` prefix. The original command resumes
when the helper returns `ready`; do not rerun it. If the helper reports
`accessibility-required`, ask the user once to grant the app launching
browser-use (for example Terminal, iTerm, or Codex) access in System
Settings > Privacy & Security > Accessibility, then call `mac-app