Application
Browser-use is a Python framework that enables AI agents (powered by LLMs like Anthropic Claude, OpenAI, Gemini, etc.) to autonomously control web browsers for task automation. It provides a full stack from DOM extraction and element interaction to agent orchestration, allowing an AI to see, reason about, and interact with web pages through CDP (Chrome DevTools Protocol) — essentially giving LLMs hands to browse the internet.
Key Features
- AI Agent Orchestration
- DOM Extraction & Serialization
- Actor Layer (Element, Mouse, Page)
- Browser Session Management
- Browser Watchdogs
- Multi-Provider LLM Support
- Tool & Action Registry
- Screenshot Annotation
- Code Generation Mode
- MCP Integration
- Interactive CLI & TUI
- Cloud API & Sync
- Sandbox Execution
- Skills System
Coding Conventions
Standards and patterns used in this codebase
Use __init__.py files to define the public API surface for each package, with lazy imports and explicit __all__ exports to control what is exposed.
Package init files re-export key classes/functions so consumers import from the package root rather than internal modules.Use a centralized configuration system that supports multiple sources (environment variables, JSON files) with automatic migration and backward compatibility.
browser_use/config.py provides a comprehensive config class that loads from env vars, JSON files, and supports migration between config versions.Use async/await as the primary execution model throughout the codebase, with asyncio patching at initialization to support nested event loops.
The package __init__.py patches asyncio (likely via nest_asyncio) to allow async code to run in various contexts including Jupyter notebooks.Follow a strict layered architecture: Agent (orchestration) → Controller (bridging) → Actor (browser primitives), with each layer having clear responsibilities and not bypassing intermediate layers.
Agent makes decisions, Controller translates them, Actor executes browser actions via CDP. Tools/Registry provides the action definitions.Use snake_case for modules and files, PascalCase for classes. Organize related functionality into descriptive sub-packages (e.g., browser/watchdogs/, dom/serializer/, llm/).
logging_config.py, init_cmd.py for modules; Element, Page, Mouse for classes in the actor package.Separate serialization, extraction, and execution into distinct modules. DOM serialization strategies are isolated from DOM extraction; LLM provider implementations are separate from the LLM abstraction layer.
DOM serializer strategies live in browser_use/dom/serializer/ separate from DOM extraction in browser_use/dom/. LLM providers are separate from base LLM classes.Use a custom logging configuration module with custom log levels, formatters, and handlers rather than relying on default Python logging.
browser_use/logging_config.py sets up structured logging that is initialized at package import time.Provide both interactive terminal UI and command-line interface modes, with template generation and GitHub-based resource fetching for project scaffolding.
cli.py provides interactive terminal UI for browser automation; init_cmd.py handles template generation with interactive selection.Use dedicated watchdog modules for health monitoring concerns (DOM changes, crashes, popups, permissions) rather than embedding monitoring logic in core browser code.
browser_use/browser/watchdogs/ contains separate watchdog implementations for different browser health concerns.Use provider/strategy patterns for extensible integrations: cloud browser providers, LLM providers, and DOM serialization strategies are all pluggable implementations behind abstract interfaces.
LLM providers implement a base class with provider-specific serializers; cloud browser providers are separate integrations behind a common interface.Centralize cross-cutting utilities (signal handling, decorators, environment checks, helper functions) in a dedicated utils module at the package root.
browser_use/utils.py provides signal handling, decorators, environment detection, and shared helper functions used across the codebase.Include dedicated modules for token counting, cost estimation, and pricing mappings to track and manage LLM usage costs as a first-class concern.
browser_use/tokens/ provides token counting and cost estimation with pricing mappings for different models.