CodeVetter · Repo Unpack · Contributor handoff
browser-use/browser-use
Edit inside browser_use, keep examples and docs aligned only when behavior changes, and do not add sample scripts. The code style is tabs, single quotes, line length 130, Python 3.11+ unions, and Pydantic v2 models for action schemas. Before changing the agent loop, read Agent.step, BrowserSession.on_BrowserStartEvent, Tools.act, and Registry.execute_action. Run the focused tests/ci file plus pyright; the full matrix is ./bin/test.sh. Known traps are stale defaults in AGENTS.md, the external browser_harness CLI, the commented-out CrashWatchdog, and secret handling that is only domain-scoped when the caller uses the nested dict form.
- CLAUDE.md is the engineering contract: async Python, tabs not spaces, str | None rather than Optional, service.py for logic and views.py for Pydantic models, uuid7str for new ids, and runtime assertions at function boundaries. Logging helpers should be named _log_*.
- Safe first reads for any agent-loop change are browser_use/agent/service.py (Agent.__init__, step, run, multi_act), browser_use/browser/session.py (on_BrowserStartEvent, attach_all_watchdogs), browser_use/tools/service.py, and browser_use/tools/registry/service.py. BrowserProfile fields live in browser_use/browser/profile.py.
- Do not add new example files to show off a feature. AGENTS.md and CLAUDE.md both say to test inline in a terminal instead. Examples that already exist under examples/ should be updated when the API they demonstrate changes.
- Use uv, not pip. Local setup is uv venv --python 3.11, then uv sync. The CI-equivalent test command is ./bin/test.sh or uv run pytest -vxs tests/ci. A single file is uv run pytest -vxs tests/ci/<file>.py. Typecheck with uv run pyright. Format with uv run ruff format and uv run ruff check --fix. Pre-commit is uv run pre-commit run --all-files.
- Action signature trap: parameters injected by the registry must use the exact names in _get_special_param_types, and the function must not declare **kwargs. Custom tools that want the browser must annotate browser_session: BrowserSession. Using browser: Browser silently fails to inject.
- Indentation and formatter trap: ruff format uses indent-style tab and quote-style single, line length 130. A space-indented edit will fail pre-commit. E501 is ignored, so long lines are allowed.
- Default-value trap: trust Agent.__init__ and Agent.run, not the parameter tables copied into AGENTS.md. In this tree run(max_steps=500), max_actions_per_step=5, max_failures=5, step_timeout=180, use_vision=True, and a browser-use provider forces flash_mode.
- CLI trap: browser_use/cli.py is a compatibility shim. New browser commands belong in the browser_harness package, which this repo calls but does not vendor. Adding a subcommand whose name is in _LEGACY_HINTS will be swallowed as a migration error.
- Test trap: do not mock the browser, do not request https://example.com or other public hosts, and do not put new CI tests outside tests/ci or they will not be in the workflow matrix. LLM behavior is scripted with create_mock_llm in tests/ci/conftest.py.
- Secret and telemetry trap: do not log raw sensitive_data values; prompts are redacted but execution substitutes the real strings. Do not commit changes that flip ANONYMIZED_TELEMETRY or that print BROWSER_USE_API_KEY. The PostHog key in telemetry/service.py is a public project key, not a user secret, but device_id is persisted on disk.
- pyright will not catch mistakes in browser_use/beta/service.py, browser_use/llm/oci_raw, or the excluded llm tests. A green typecheck does not cover those files. Beta agent work needs tests/ci/test_beta_agent.py even though the implementation is excluded.
- Event-bus trap: BrowserSession handlers and watchdogs both listen on the same bus. Navigation security is enforced by raising from SecurityWatchdog.on_NavigateToUrlEvent, which depends on handler order. Adding a new navigation path that talks to CDP directly will bypass that check.