# bluebug53/browser-use architecture

> Architecture diagram of the GitHub repository bluebug53/browser-use, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bluebug53/browser-use
- Repository: https://github.com/bluebug53/browser-use

## Overview

Browser Use is a Python AI browser-agent library, with related CLI, MCP, skills, and cloud-browser integrations. Its main workflow accepts a task, has an agent reason with a configurable language model and available tools, executes browser actions, and returns an answer or history. Browser sessions expose browser state and events; DOM extraction and filesystem support enrich the agent’s context and results. The graph preserves documented integrations and major capabilities, but source excerpts are partial, so some relationships rely on README statements or are omitted where implementation wiring is uncertain.

Main entry points: [`browser_use/agent/service.py`](https://github.com/bluebug53/browser-use/blob/main/browser_use/agent/service.py) (Agent loop), [`browser_use/browser/session.py`](https://github.com/bluebug53/browser-use/blob/main/browser_use/browser/session.py) (Browser session), [`browser_use/tools/service.py`](https://github.com/bluebug53/browser-use/blob/main/browser_use/tools/service.py) (Action tools), [`browser_use/config.py`](https://github.com/bluebug53/browser-use/blob/main/browser_use/config.py) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent workflow"]
  node_agent["Agent loop<br/>[service.py]"]
  node_messages["Prompt manager<br/>[service.py]"]
  node_llm["Model adapters<br/>[base.py]"]
  node_history["Run history<br/>[views.py]"]
end

subgraph group_browser["Browser runtime"]
  node_session["Browser session<br/>[session.py]"]
  node_events["Browser events<br/>[events.py]"]
  node_profile["Browser profile<br/>[profile.py]"]
  node_dom["DOM snapshots<br/>[service.py]"]
end

subgraph group_capabilities["Tools and capabilities"]
  node_actions["Action tools<br/>[service.py]"]
  node_registry["Tool registry<br/>[service.py]"]
  node_extraction["Structured extraction"]
  node_filesystem[("Agent files<br/>[file_system.py]")]
end

subgraph group_integrations["Integrations"]
  node_mcp["MCP interface<br/>[server.py]"]
  node_skills["Browser skills<br/>[browser_use.py]"]
  node_cloud["Cloud browser<br/>[cloud.py]"]
  node_gmail["Gmail actions<br/>[service.py]"]
end

subgraph group_support["Shared services"]
  node_tokens["Token accounting<br/>[service.py]"]
  node_telemetry["Product telemetry<br/>[service.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("Task author"))
node_actor(("Web browser"))
node_modelprovider(("Model provider"))

node_user -->|"submits task"| node_agent
node_agent -->|"builds prompts"| node_messages
node_agent -->|"requests completion"| node_llm
node_modelprovider -.->|"serves model"| node_llm
node_agent -->|"dispatches actions"| node_actions
node_agent -->|"controls browser"| node_session
node_agent -->|"records run"| node_history
node_agent -->|"accounts tokens"| node_tokens
node_actions -->|"resolves tools"| node_registry
node_actions -->|"reads page state"| node_dom
node_actions -->|"uses agent files"| node_filesystem
node_actions -->|"uses schemas"| node_extraction
node_session -->|"handles events"| node_events
node_session -->|"provides browser state"| node_dom
node_session -->|"uses profile"| node_profile
node_session -.->|"drives browser"| node_actor
node_session -->|"connects remotely"| node_cloud
node_mcp -->|"exposes tools"| node_actions
node_mcp -->|"offers browser access"| node_session
node_skills -.->|"guides automation"| node_agent
node_gmail -->|"reads settings"| node_config
node_agent -.->|"emits telemetry"| node_telemetry
node_tokens -->|"reads pricing config"| node_config
node_telemetry -->|"reads settings"| node_config

click node_agent "https://github.com/bluebug53/browser-use/blob/main/browser_use/agent/service.py"
click node_messages "https://github.com/bluebug53/browser-use/blob/main/browser_use/agent/message_manager/service.py"
click node_llm "https://github.com/bluebug53/browser-use/blob/main/browser_use/llm/base.py"
click node_history "https://github.com/bluebug53/browser-use/blob/main/browser_use/agent/views.py"
click node_session "https://github.com/bluebug53/browser-use/blob/main/browser_use/browser/session.py"
click node_events "https://github.com/bluebug53/browser-use/blob/main/browser_use/browser/events.py"
click node_profile "https://github.com/bluebug53/browser-use/blob/main/browser_use/browser/profile.py"
click node_dom "https://github.com/bluebug53/browser-use/blob/main/browser_use/dom/service.py"
click node_actions "https://github.com/bluebug53/browser-use/blob/main/browser_use/tools/service.py"
click node_registry "https://github.com/bluebug53/browser-use/blob/main/browser_use/tools/registry/service.py"
click node_extraction "https://github.com/bluebug53/browser-use/tree/main/browser_use/tools/extraction"
click node_filesystem "https://github.com/bluebug53/browser-use/blob/main/browser_use/filesystem/file_system.py"
click node_mcp "https://github.com/bluebug53/browser-use/blob/main/browser_use/mcp/server.py"
click node_skills "https://github.com/bluebug53/browser-use/blob/main/browser_use/skills/browser_use.py"
click node_cloud "https://github.com/bluebug53/browser-use/blob/main/browser_use/browser/cloud/cloud.py"
click node_gmail "https://github.com/bluebug53/browser-use/blob/main/browser_use/integrations/gmail/service.py"
click node_tokens "https://github.com/bluebug53/browser-use/blob/main/browser_use/tokens/service.py"
click node_telemetry "https://github.com/bluebug53/browser-use/blob/main/browser_use/telemetry/service.py"
click node_config "https://github.com/bluebug53/browser-use/blob/main/browser_use/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_messages,node_llm,node_history,node_actor toneBlue
class node_session,node_events,node_profile,node_dom toneAmber
class node_actions,node_registry,node_extraction,node_filesystem toneMint
class node_mcp,node_skills,node_cloud,node_gmail,node_user toneRose
class node_tokens,node_telemetry,node_config,node_modelprovider toneIndigo
```

## Components

### Agent workflow

- [Agent loop](https://github.com/bluebug53/browser-use/blob/main/browser_use/agent/service.py): `browser_use/agent/service.py`
- [Prompt manager](https://github.com/bluebug53/browser-use/blob/main/browser_use/agent/message_manager/service.py): `browser_use/agent/message_manager/service.py`
- [Model adapters](https://github.com/bluebug53/browser-use/blob/main/browser_use/llm/base.py): `browser_use/llm/base.py`
- [Run history](https://github.com/bluebug53/browser-use/blob/main/browser_use/agent/views.py): `browser_use/agent/views.py`

### Browser runtime

- [Browser session](https://github.com/bluebug53/browser-use/blob/main/browser_use/browser/session.py): `browser_use/browser/session.py`
- [Browser events](https://github.com/bluebug53/browser-use/blob/main/browser_use/browser/events.py): `browser_use/browser/events.py`
- [Browser profile](https://github.com/bluebug53/browser-use/blob/main/browser_use/browser/profile.py): `browser_use/browser/profile.py`
- [DOM snapshots](https://github.com/bluebug53/browser-use/blob/main/browser_use/dom/service.py): `browser_use/dom/service.py`

### Tools and capabilities

- [Action tools](https://github.com/bluebug53/browser-use/blob/main/browser_use/tools/service.py): `browser_use/tools/service.py`
- [Tool registry](https://github.com/bluebug53/browser-use/blob/main/browser_use/tools/registry/service.py): `browser_use/tools/registry/service.py`
- [Structured extraction](https://github.com/bluebug53/browser-use/tree/main/browser_use/tools/extraction): `browser_use/tools/extraction`
- [Agent files](https://github.com/bluebug53/browser-use/blob/main/browser_use/filesystem/file_system.py): `browser_use/filesystem/file_system.py`

### Integrations

- [MCP interface](https://github.com/bluebug53/browser-use/blob/main/browser_use/mcp/server.py): `browser_use/mcp/server.py`
- [Browser skills](https://github.com/bluebug53/browser-use/blob/main/browser_use/skills/browser_use.py): `browser_use/skills/browser_use.py`
- [Cloud browser](https://github.com/bluebug53/browser-use/blob/main/browser_use/browser/cloud/cloud.py): `browser_use/browser/cloud/cloud.py`
- [Gmail actions](https://github.com/bluebug53/browser-use/blob/main/browser_use/integrations/gmail/service.py): `browser_use/integrations/gmail/service.py`

### Shared services

- [Token accounting](https://github.com/bluebug53/browser-use/blob/main/browser_use/tokens/service.py): `browser_use/tokens/service.py`
- [Product telemetry](https://github.com/bluebug53/browser-use/blob/main/browser_use/telemetry/service.py): `browser_use/telemetry/service.py`
- [Configuration](https://github.com/bluebug53/browser-use/blob/main/browser_use/config.py): `browser_use/config.py`

### Other components

- **Task author**
- **Web browser**
- **Model provider**

## Connections

- Task author → Agent loop: submits task (evidence: `README.md`)
- Agent loop → Prompt manager: builds prompts (evidence: `browser_use/agent/service.py`)
- Agent loop → Model adapters: requests completion (evidence: `browser_use/agent/service.py`)
- Model provider → Model adapters: serves model (evidence: `README.md`)
- Agent loop → Action tools: dispatches actions (evidence: `browser_use/agent/service.py`)
- Agent loop → Browser session: controls browser (evidence: `browser_use/agent/service.py`)
- Agent loop → Run history: records run (evidence: `browser_use/agent/service.py`)
- Agent loop → Token accounting: accounts tokens (evidence: `browser_use/agent/service.py`)
- Action tools → Tool registry: resolves tools (evidence: `browser_use/tools/service.py`)
- Action tools → DOM snapshots: reads page state (evidence: `browser_use/tools/service.py`)
- Action tools → Agent files: uses agent files (evidence: `browser_use/tools/service.py`)
- Action tools → Structured extraction: uses schemas (evidence: `browser_use/tools/service.py`)
- Browser session → Browser events: handles events (evidence: `browser_use/browser/session.py`)
- Browser session → DOM snapshots: provides browser state (evidence: `browser_use/browser/session.py`)
- Browser session → Browser profile: uses profile (evidence: `browser_use/browser/session.py`)
- Browser session → Web browser: drives browser (evidence: `README.md`)
- Browser session → Cloud browser: connects remotely (evidence: `browser_use/browser/session.py`)
- MCP interface → Action tools: exposes tools (evidence: `browser_use/mcp/server.py`)
- MCP interface → Browser session: offers browser access (evidence: `browser_use/mcp/server.py`)
- Browser skills → Agent loop: guides automation (evidence: `README.md`)
- Gmail actions → Configuration: reads settings (evidence: `browser_use/integrations/gmail/service.py`)
- Agent loop → Product telemetry: emits telemetry (evidence: `browser_use/agent/service.py`)
- Token accounting → Configuration: reads pricing config (evidence: `browser_use/tokens/service.py`)
- Product telemetry → Configuration: reads settings (evidence: `browser_use/telemetry/service.py`)
