Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

sync browser-use skill from browser-harness

Laith Weinbergerd73eea6329ef
diff --git a/.github/workflows/install-script.yml b/.github/workflows/install-script.yml
index 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: true
jobs:
+ 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.py
index 4d8e4ef65..fa8f18db7 100644
--- a/browser_use/cli.py
+++ b/browser_use/cli.py
@@ -7,6 +7,67 @@ from contextlib import redirect_stderr, redirect_stdout
from 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_command
diff --git a/browser_use/skills/browser-use/SKILL.md b/browser_use/skills/browser-use/SKILL.md
new file mode 100644
index 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.py
index bcf79174a..c354b54fd 100644
--- a/browser_use/skills/browser_use.py
+++ b/browser_use/skills/browser_use.py
@@ -3,6 +3,7 @@
from __future__ import annotations
from importlib import resources
+from pathlib import Path
def 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.toml
index 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.py
new file mode 100644
index 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.md
new file mode 100644
index 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.py
index 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')