browser-use-heroku: Instructions file for Claude Code

Browser-Use is an async python >= 3.11 library that implements AI browser driver abilities using LLMs + playwright. We want our library APIs to be ergonomic, intuitive, and hard to get wrong.

Code Style

• Use async python
• Use tabs for indentation in all python code, not spaces
• Use the modern python >3.12 typing style, e.g. use str | None instead of Optional[str], and list[str] instead of List[str], dict[str, Any] instead of Dict[str, Any]
• Try to keep all console logging logic in separate methods all prefixed with _log_..., e.g. def _log_pretty_path(path: Path) -> str so as not to clutter up the main logic.
• Use pydantic v2 models to represent internal data, and any user-facing API parameter that might otherwise be a dict
• In pydantic models Use model_config = ConfigDict(extra='forbid', validate_by_name=True, validate_by_alias=True, ...) etc. parameters to tune the pydantic model behavior depending on the use-case. Use Annotated[..., AfterValidator(...)] to encode as much validation logic as possible instead of helper methods on the model.
• We keep the main code for each sub-component in a service.py file usually, and we keep most pydantic models in views.py files unless they are long enough deserve their own file
• Use runtime assertions at the start and end of functions to enforce constraints and assumptions
• Prefer from uuid_extensions import uuid7str + id: str = Field(default_factory=uuid7str) for all new id fields
• Run tests using uv run pytest -vxs tests/ci
• Run the type checker using uv run pyright

CDP-Use

We use a thin wrapper around CDP called cdp-use: https://github.com/browser-use/cdp-use. cdp-use only provides shallow typed interfaces for the websocket calls, all CDP client and session management + other CDP helpers still live in browser_use/browser/session.py.

• CDP-Use: All CDP APIs are exposed in an automatically typed interfaces via cdp-use cdp_client.send.DomainHere.methodNameHere(params=...) like so:
  • cdp_client.send.DOMSnapshot.enable(session_id=session_id)
  • cdp_client.send.Target.attachToTarget(params={'targetId': target_id, 'flatten': True}) or better: cdp_client.send.Target.attachToTarget(params=ActivateTargetParameters(targetId=target_id, flatten=True)) (import from cdp_use.cdp.target import ActivateTargetParameters)
  • cdp_client.register.Browser.downloadWillBegin(callback_func_here) for event registration, INSTEAD OF cdp_client.on(...) which does not exist!