Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
sync browser-use skill from browser-harness
Laith Weinbergerd73eea6329ef
diff --git a/.github/workflows/install-script.yml b/.github/workflows/install-script.ymlindex ad63c4d38..8a6f407dc 100644--- a/.github/workflows/install-script.yml+++ b/.github/workflows/install-script.yml@@ -7,12 +7,18 @@ on:paths:- 'browser_use/cli.py'- 'browser_use/skills/**'+ - 'skills/browser-use/SKILL.md'+ - 'browser_use/skills/browser-use/SKILL.md'+ - 'scripts/sync_browser_harness_skill.py'- 'pyproject.toml'- '.github/workflows/install-script.yml'pull_request:paths:- 'browser_use/cli.py'- 'browser_use/skills/**'+ - 'skills/browser-use/SKILL.md'+ - 'browser_use/skills/browser-use/SKILL.md'+ - 'scripts/sync_browser_harness_skill.py'- 'pyproject.toml'- '.github/workflows/install-script.yml'workflow_dispatch:@@ -25,6 +31,18 @@ concurrency:cancel-in-progress: truejobs:+ check-browser-use-skill:+ name: browser-use skill sync+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4++ - name: Install uv+ uses: astral-sh/setup-uv@v6++ - name: Check generated Browser Use skill+ run: uv run --no-sync python scripts/sync_browser_harness_skill.py --check+test-pip-install:name: uv pip install (${{ matrix.os }})strategy:diff --git a/browser_use/cli.py b/browser_use/cli.pyindex 4d8e4ef65..fa8f18db7 100644--- a/browser_use/cli.py+++ b/browser_use/cli.py@@ -7,6 +7,67 @@ from contextlib import redirect_stderr, redirect_stdoutfrom io import StringIO+def _run_mcp_server() -> None:+ import asyncio+ import logging+ import os++ os.environ['BROWSER_USE_LOGGING_LEVEL'] = 'critical'+ os.environ['BROWSER_USE_SETUP_LOGGING'] = 'false'+ logging.disable(logging.CRITICAL)++ from browser_use.mcp.server import main as mcp_main++ asyncio.run(mcp_main())+++def _run_install_command(argv: list[str]) -> int:+ if any(arg in {'-h', '--help'} for arg in argv):+ print('usage: browser-use install')+ print()+ print('Install Chromium browser and system dependencies.')+ return 0++ import platform+ import subprocess++ print('Installing Chromium browser + system dependencies...')+ print('This may take a few minutes...\n')++ cmd = ['uvx', 'playwright', 'install', 'chromium']+ if platform.system() == 'Linux':+ cmd.append('--with-deps')+ cmd.append('--no-shell')++ result = subprocess.run(cmd)+ if result.returncode == 0:+ print('\nInstallation complete.')+ print('Ready to use. Run: uvx browser-use')+ return 0++ print('\nInstallation failed', file=sys.stderr)+ return result.returncode or 1+++def _run_init_command(argv: list[str]) -> int | None:+ from browser_use.init_cmd import main as init_main++ original_argv = sys.argv+ try:+ sys.argv = [original_argv[0], *argv]+ init_main()+ except SystemExit as exc:+ if exc.code is None:+ return 0+ if isinstance(exc.code, int):+ return exc.code+ print(exc.code, file=sys.stderr)+ return 1+ finally:+ sys.argv = original_argv+ return 0++def _as_browser_use_cli_text(text: str) -> str:return text.replace('Browser Harness', 'Browser Use').replace('browser-harness', 'browser-use')@@ -82,6 +143,15 @@ def browser_use_tui_main() -> int | None:def main() -> int | None:args = sys.argv[1:]+ if '--mcp' in args:+ _run_mcp_server()+ return 0+ if args and args[0] == 'install':+ return _run_install_command(args[1:])+ if args and args[0] == 'init':+ return _run_init_command(args[1:])+ if '--template' in args or '-t' in args:+ return _run_init_command(args)if args and args[0] == 'skill':from browser_use.skills.install import handle as handle_skill_commanddiff --git a/browser_use/skills/browser-use/SKILL.md b/browser_use/skills/browser-use/SKILL.mdnew file mode 100644index 000000000..b30a9767c--- /dev/null+++ b/browser_use/skills/browser-use/SKILL.md@@ -0,0 +1,127 @@+---+name: browser-use+description: "Direct browser control via CDP for web interaction: automation, scraping, testing, screenshots, and site/app work."+---++# 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-use/blob/main/install.md.++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 is `new_tab(url)`, not `goto_url(url)`.+- 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 remote debugging is not enabled, the harness opens:++```text+chrome://inspect/#remote-debugging+```++Ask the user to tick "Allow remote debugging for this browser instance" and click Allow if Chrome shows a permission popup. Then retry the same `browser-use` command.++## Remote Browsers++Use Browser Use cloud for headless servers, parallel sub-agents, or isolated work. Authenticate once:++```bash+browser-use auth login+```++Or import a key safely:++```bash+browser-use auth login --api-key-stdin+```++Pick a short made-up name; `r7k2` below is just a placeholder:++```bash+browser-use <<'PY'+start_remote_daemon("r7k2")+PY++BU_NAME=r7k2 browser-use <<'PY'+new_tab("https://example.com")+print(page_info())+PY+```++When the task is done and a cloud browser is still running, ask directly: "Should I close this browser now?" If yes, run `stop_remote_daemon(name)`. Remote daemons bill until they stop or time out.++Do not start a remote daemon and then keep using the default daemon. Use the same name for `BU_NAME`.++Cloud profile cookie sync reference: https://github.com/browser-use/browser-use/blob/main/interaction-skills/profile-sync.md.++## Page Workflow++- Screenshots first: use `capture_screenshot()` to understand visible state.+- Clicking: screenshot -> read pixel -> `click_at_xy(x, y)` -> screenshot again.+- After navigation, call `wait_for_load()`.+- If the current tab is stale or internal, call `ensure_real_tab()`.+- Use `js(...)` for DOM inspection or extraction when coordinates are the wrong tool.+- Login walls: stop and ask. Exception: use available SSO automatically when Chrome is already signed in; still stop for passwords, MFA, consent, or ambiguous account choice.+- Raw CDP is available with `cdp("Domain.method", ...)`.++## Interaction Skills++If you get stuck on a browser mechanic, check https://github.com/browser-use/browser-use/tree/main/interaction-skills.++- 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++## Design Constraints++- Coordinate clicks default. CDP mouse events pass through iframes/shadow/cross-origin at the compositor level.+- Keep the connection model simple: use the default daemon, `BU_NAME`, `BU_CDP_URL`, `BU_CDP_WS`, or `start_remote_daemon(...)`.+- Core helpers stay short. Put task-specific helper additions in `$BH_AGENT_WORKSPACE/agent_helpers.py`.++## Gotchas++- `chrome://inspect/#remote-debugging` must be enabled for local Chrome control.+- Chrome may show an "Allow remote debugging?" popup; wait for the user to click Allow.+- Omnibox popups are not real work tabs.+- CDP target order is not Chrome's visible tab-strip order.+- `BU_CDP_URL` is an HTTP DevTools endpoint; the daemon resolves it to WebSocket.+- Ask before leaving cloud browsers running; stop them with `stop_remote_daemon(name)` or `PATCH /browsers/{id} {"action":"stop"}`.++## Domain Skills++Only applies when `BH_DOMAIN_SKILLS=1`. Otherwise ignore domain skills.++When enabled, search `$BH_AGENT_WORKSPACE/domain-skills/<host>/` before inventing an approach. `goto_url(...)` returns up to 10 skill filenames for the navigated host.diff --git a/browser_use/skills/browser_use.py b/browser_use/skills/browser_use.pyindex bcf79174a..c354b54fd 100644--- a/browser_use/skills/browser_use.py+++ b/browser_use/skills/browser_use.py@@ -3,6 +3,7 @@from __future__ import annotationsfrom importlib import resources+from pathlib import Pathdef as_browser_use_skill(text: str) -> str:@@ -39,17 +40,25 @@ def as_browser_use_skill(text: str) -> str:)body = body.replace('# browser-harness', '# Browser Use', 1).replace('# Browser Harness', '# Browser Use', 1)- body = body.replace('`browser-harness`', '`browser-use`')body = body.replace('browser-harness <<', 'browser-use <<')body = body.replace('browser-harness --', 'browser-use --')body = body.replace('browser-harness auth', 'browser-use auth')body = body.replace('browser-harness doctor', 'browser-use doctor')+ body = body.replace('Browser Harness', 'Browser Use')+ body = body.replace('browser-harness', 'browser-use')frontmatter_text = '\n'.join(lines)return f'---\n{frontmatter_text}\n---\n{body}'def skill_text() -> str:- """Return the canonical Browser Use skill from the browser-harness package."""+ """Return the canonical Browser Use skill."""+ for skill_path in (+ Path(__file__).resolve().parent / 'browser-use' / 'SKILL.md',+ Path(__file__).resolve().parents[2] / 'skills' / 'browser-use' / 'SKILL.md',+ ):+ if skill_path.exists():+ return skill_path.read_text(encoding='utf-8')+try:text = resources.files('browser_harness').joinpath('SKILL.md').read_text(encoding='utf-8')except ModuleNotFoundError as exc:diff --git a/pyproject.toml b/pyproject.tomlindex ec661f8b9..9320e2a92 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -180,6 +180,7 @@ include = ["!browser_use/**/tests.py","browser_use/agent/system_prompts/*.md","browser_use/cli_templates/*.py",+ "browser_use/skills/**/*.md","browser_use/py.typed","browser_use/dom/**/*.js","!tests/**/*.py",diff --git a/scripts/sync_browser_harness_skill.py b/scripts/sync_browser_harness_skill.pynew file mode 100644index 000000000..374e0012e--- /dev/null+++ b/scripts/sync_browser_harness_skill.py@@ -0,0 +1,73 @@+#!/usr/bin/env python3+from __future__ import annotations++import argparse+import difflib+import sys+from pathlib import Path+from urllib.request import urlopen++ROOT = Path(__file__).resolve().parents[1]+DEFAULT_SOURCE_URL = 'https://raw.githubusercontent.com/browser-use/browser-harness/main/SKILL.md'+DEFAULT_REPO_OUTPUT_PATH = ROOT / 'skills' / 'browser-use' / 'SKILL.md'+DEFAULT_PACKAGE_OUTPUT_PATH = ROOT / 'browser_use' / 'skills' / 'browser-use' / 'SKILL.md'+++def _read_source(source: str) -> str:+ if source.startswith(('http://', 'https://')):+ with urlopen(source, timeout=30) as response:+ return response.read().decode('utf-8')+ return Path(source).read_text(encoding='utf-8')+++def _to_browser_use_skill(text: str) -> str:+ from browser_use.skills.browser_use import as_browser_use_skill++ return as_browser_use_skill(text)+++def _build_parser() -> argparse.ArgumentParser:+ parser = argparse.ArgumentParser(description='Sync the Browser Use skill from browser-harness/SKILL.md.')+ parser.add_argument('--source', default=DEFAULT_SOURCE_URL, help='Source SKILL.md path or URL.')+ parser.add_argument(+ '--output',+ type=Path,+ action='append',+ help='Output Browser Use SKILL.md path. May be passed more than once. Defaults to repo and package copies.',+ )+ parser.add_argument('--check', action='store_true', help='Fail if the output file is stale.')+ return parser+++def main(argv: list[str] | None = None) -> int:+ args = _build_parser().parse_args(argv)+ expected = _to_browser_use_skill(_read_source(args.source))+ output_paths = args.output or [DEFAULT_REPO_OUTPUT_PATH, DEFAULT_PACKAGE_OUTPUT_PATH]++ if args.check:+ stale = False+ for output_path in output_paths:+ actual = output_path.read_text(encoding='utf-8') if output_path.exists() else ''+ if actual == expected:+ continue+ stale = True+ diff = ''.join(+ difflib.unified_diff(+ actual.splitlines(keepends=True),+ expected.splitlines(keepends=True),+ fromfile=str(output_path),+ tofile=f'{output_path} (expected)',+ )+ )+ print(diff, file=sys.stderr)+ return 1 if stale else 0++ for output_path in output_paths:+ output_path.parent.mkdir(parents=True, exist_ok=True)+ output_path.write_text(expected, encoding='utf-8')+ print(f'Synced {output_path} from {args.source}')+ return 0+++if __name__ == '__main__':+ sys.exit(main())diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.mdnew file mode 100644index 000000000..b30a9767c--- /dev/null+++ b/skills/browser-use/SKILL.md@@ -0,0 +1,127 @@+---+name: browser-use+description: "Direct browser control via CDP for web interaction: automation, scraping, testing, screenshots, and site/app work."+---++# 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-use/blob/main/install.md.++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 is `new_tab(url)`, not `goto_url(url)`.+- 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 remote debugging is not enabled, the harness opens:++```text+chrome://inspect/#remote-debugging+```++Ask the user to tick "Allow remote debugging for this browser instance" and click Allow if Chrome shows a permission popup. Then retry the same `browser-use` command.++## Remote Browsers++Use Browser Use cloud for headless servers, parallel sub-agents, or isolated work. Authenticate once:++```bash+browser-use auth login+```++Or import a key safely:++```bash+browser-use auth login --api-key-stdin+```++Pick a short made-up name; `r7k2` below is just a placeholder:++```bash+browser-use <<'PY'+start_remote_daemon("r7k2")+PY++BU_NAME=r7k2 browser-use <<'PY'+new_tab("https://example.com")+print(page_info())+PY+```++When the task is done and a cloud browser is still running, ask directly: "Should I close this browser now?" If yes, run `stop_remote_daemon(name)`. Remote daemons bill until they stop or time out.++Do not start a remote daemon and then keep using the default daemon. Use the same name for `BU_NAME`.++Cloud profile cookie sync reference: https://github.com/browser-use/browser-use/blob/main/interaction-skills/profile-sync.md.++## Page Workflow++- Screenshots first: use `capture_screenshot()` to understand visible state.+- Clicking: screenshot -> read pixel -> `click_at_xy(x, y)` -> screenshot again.+- After navigation, call `wait_for_load()`.+- If the current tab is stale or internal, call `ensure_real_tab()`.+- Use `js(...)` for DOM inspection or extraction when coordinates are the wrong tool.+- Login walls: stop and ask. Exception: use available SSO automatically when Chrome is already signed in; still stop for passwords, MFA, consent, or ambiguous account choice.+- Raw CDP is available with `cdp("Domain.method", ...)`.++## Interaction Skills++If you get stuck on a browser mechanic, check https://github.com/browser-use/browser-use/tree/main/interaction-skills.++- 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++## Design Constraints++- Coordinate clicks default. CDP mouse events pass through iframes/shadow/cross-origin at the compositor level.+- Keep the connection model simple: use the default daemon, `BU_NAME`, `BU_CDP_URL`, `BU_CDP_WS`, or `start_remote_daemon(...)`.+- Core helpers stay short. Put task-specific helper additions in `$BH_AGENT_WORKSPACE/agent_helpers.py`.++## Gotchas++- `chrome://inspect/#remote-debugging` must be enabled for local Chrome control.+- Chrome may show an "Allow remote debugging?" popup; wait for the user to click Allow.+- Omnibox popups are not real work tabs.+- CDP target order is not Chrome's visible tab-strip order.+- `BU_CDP_URL` is an HTTP DevTools endpoint; the daemon resolves it to WebSocket.+- Ask before leaving cloud browsers running; stop them with `stop_remote_daemon(name)` or `PATCH /browsers/{id} {"action":"stop"}`.++## Domain Skills++Only applies when `BH_DOMAIN_SKILLS=1`. Otherwise ignore domain skills.++When enabled, search `$BH_AGENT_WORKSPACE/domain-skills/<host>/` before inventing an approach. `goto_url(...)` returns up to 10 skill filenames for the navigated host.diff --git a/tests/ci/test_browser_use_skill_install_docs.py b/tests/ci/test_browser_use_skill_install_docs.pyindex be45dbf4f..d157e509f 100644--- a/tests/ci/test_browser_use_skill_install_docs.py+++ b/tests/ci/test_browser_use_skill_install_docs.py@@ -47,42 +47,6 @@ def test_docs_install_browser_use_skill_from_package_alias():assert 'raw.githubusercontent.com/browser-use/browser-harness/main/SKILL.md' not in readme-def test_browser_use_repo_does_not_carry_a_copied_browser_harness_skill():- assert not (ROOT / 'skills' / 'browser-use' / 'SKILL.md').exists()- assert not (ROOT / 'scripts' / 'sync_browser_use_skill.py').exists()---def test_browser_use_skill_alias_reads_browser_harness_package(monkeypatch, tmp_path):- package_dir = tmp_path / 'browser_harness'- package_dir.mkdir()- (package_dir / '__init__.py').write_text('', encoding='utf-8')- (package_dir / 'SKILL.md').write_text(- (- '---\nname: browser-harness\ndescription: "Always use browser-harness."\n---\n\n'- '# browser-harness\n\n'- "```bash\nbrowser-harness <<'PY'\nprint(page_info())\nPY\n```\n\n"- '- Invoke as `browser-harness`.\n'- ),- encoding='utf-8',- )- monkeypatch.syspath_prepend(str(tmp_path))-- from browser_use.skills import browser_use_skill_text-- text = browser_use_skill_text()- assert text.startswith(- '---\n'- 'name: browser-use\n'- 'description: "Direct browser control via CDP for web interaction: automation, scraping, testing, screenshots, and site/app work."\n'- '---\n\n'- '# Browser Use\n'- )- assert "browser-use <<'PY'" in text- assert 'Invoke as `browser-use`' in text- assert "browser-harness <<'PY'" not in text- assert 'Invoke as `browser-harness`' not in text--def test_browser_use_cli_installs_browser_harness_package_skill(tmp_path):bin_dir = _fake_browser_harness_tools(tmp_path, '---\nname: browser-harness\n---\n\n# Browser Harness\n')