# Contributor handoff — browser-use/browser-use

> Canonical page: https://codevetter.com/unpack/browser-use/agent-handoff

# Contributor handoff — browser-use/browser-use

Scanned commit d8110c5ff87ccba887aaa726cdb780f2f84bef8d (2026-09-15). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

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_*. — [CLAUDE.md](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/CLAUDE.md)
- 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. — [browser_use/agent/service.py#L134-L214](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/agent/service.py#L134-L214) [browser_use/browser/session.py#L1688-L1837](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/browser/session.py#L1688-L1837) [browser_use/tools/registry/service.py#L33-L73](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/tools/registry/service.py#L33-L73)
- 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. — [AGENTS.md](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/AGENTS.md) [CLAUDE.md](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/CLAUDE.md)
- 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. — [CLAUDE.md](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/CLAUDE.md) [bin/test.sh#L1-L9](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/bin/test.sh#L1-L9) [pyproject.toml#L120-L143](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/pyproject.toml#L120-L143)
- 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. — [browser_use/tools/registry/service.py#L57-L100](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/tools/registry/service.py#L57-L100) [AGENTS.md](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/AGENTS.md)
- 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. — [pyproject.toml#L120-L143](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/pyproject.toml#L120-L143)
- 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. — [browser_use/agent/service.py#L169-L243](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/agent/service.py#L169-L243) [browser_use/agent/service.py#L2503-L2508](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/agent/service.py#L2503-L2508) [AGENTS.md](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/AGENTS.md)
- 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. — [browser_use/cli.py#L185-L269](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/cli.py#L185-L269) [pyproject.toml#L49-L50](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/pyproject.toml#L49-L50)
- 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. — [tests/ci/conftest.py#L75-L80](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/tests/ci/conftest.py#L75-L80) [CLAUDE.md](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/CLAUDE.md) [.github/workflows/test.yaml#L51-L80](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/.github/workflows/test.yaml#L51-L80)
- 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. — [browser_use/telemetry/service.py#L21-L47](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/telemetry/service.py#L21-L47) [browser_use/agent/message_manager/service.py#L576-L591](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/agent/message_manager/service.py#L576-L591)
- 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. — [pyproject.toml#L160-L167](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/pyproject.toml#L160-L167)
- 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. — [browser_use/browser/watchdogs/security_watchdog.py#L35-L48](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/browser/watchdogs/security_watchdog.py#L35-L48) [browser_use/browser/session.py#L905-L910](https://github.com/browser-use/browser-use/blob/d8110c5ff87ccba887aaa726cdb780f2f84bef8d/browser_use/browser/session.py#L905-L910)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)