browser-use 0.2.0 → 0.4.0

package/README.md

@@ -1,228 +1,213 @@
-# browser-use
-
-![Node CI](https://github.com/webllm/browser-use/workflows/Node%20CI/badge.svg)
-[![npm](https://img.shields.io/npm/v/browser-use.svg)](https://www.npmjs.com/package/browser-use)
-![license](https://img.shields.io/npm/l/browser-use)
-
-> 🙏 **A TypeScript port of the amazing [browser-use](https://github.com/browser-use/browser-use) Python library**
->
-> This project is a faithful TypeScript/JavaScript implementation of the original [browser-use](https://github.com/browser-use/browser-use) Python library, bringing the power of AI-driven browser automation to the Node.js ecosystem. All credit for the innovative design and architecture goes to the original Python project and its creators.
-
-A TypeScript-first library for programmatic browser control, designed for building AI-powered web agents with vision capabilities and extensive LLM integrations.
-
-## Why TypeScript?
-
-While the original [browser-use Python library](https://github.com/browser-use/browser-use) is excellent and feature-complete, this TypeScript port aims to:
-
-- 🌍 Bring browser-use capabilities to the JavaScript/TypeScript ecosystem
-- 🔧 Enable seamless integration with Node.js, Deno, and Bun projects
-- 📦 Provide native TypeScript type definitions for better DX
-- 🤝 Make browser automation accessible to frontend and full-stack developers
-
-### Python vs TypeScript: Which Should You Use?
-
-| Feature             | Python Version                                                        | TypeScript Version                                          |
-| ------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- |
-| **Recommended for** | Python developers, Data scientists, AI/ML engineers                   | JavaScript/TypeScript developers, Full-stack engineers      |
-| **Ecosystem**       | PyPI, pip                                                             | npm, yarn, pnpm                                             |
-| **Type Safety**     | Optional (with type hints)                                            | Built-in (TypeScript)                                       |
-| **Runtime**         | Python 3.x                                                            | Node.js, Deno, Bun                                          |
-| **LLM Providers**   | 10+ providers                                                         | 10+ providers (same)                                        |
-| **Browser Support** | Playwright                                                            | Playwright (same)                                           |
-| **Documentation**   | ⭐ Original & Complete                                                | Port with TS-specific examples                              |
-| **Community**       | ⭐ Larger & More Established                                          | Growing                                                     |
-| **GitHub**          | [browser-use/browser-use](https://github.com/browser-use/browser-use) | [webllm/browser-use](https://github.com/webllm/browser-use) |
-
-**👉 If you're working in Python, we highly recommend using the [original browser-use library](https://github.com/browser-use/browser-use).** This TypeScript port is specifically for those who need to work within the JavaScript/TypeScript ecosystem.
-
-### Commitment to the Original
-
-We are committed to:
-
-- ✅ Maintaining feature parity with the Python version whenever possible
-- 🔄 Keeping up with upstream updates and improvements
-- 🐛 Reporting bugs found in this port back to the original project when applicable
-- 📚 Directing users to the original project's documentation for core concepts
-- 🤝 Collaborating with the original authors and respecting their vision
-
-This is **not** a fork or competing project—it's a respectful port to serve a different programming language community.
-
-### Upstream Parity Status
-
-This Node.js/TypeScript implementation is currently **strictly aligned** with the Python `browser-use` release
-[`v0.5.11`](https://github.com/browser-use/browser-use/releases/tag/0.5.11), published on **August 10, 2025**.
-
-- 📦 Core features and behavior are aligned against that upstream tag baseline.
-- ✅ Our test strategy is maintained to be as equivalent as practical to the Python coverage and behavior checks.
-- 🔄 We expect to move this parity baseline forward to the Python **January 2026** release line very soon.
-
-## Features
-
-- 🤖 **AI-Powered**: Built specifically for LLM-driven web automation with structured output support
-- 🎯 **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- 🌐 **Multi-Browser**: Support for Chromium, Firefox, and WebKit via Playwright
-- 🔌 **10+ LLM Providers**: OpenAI, Anthropic, Google, AWS, Azure, DeepSeek, Groq, Ollama, OpenRouter, and more
-- 👁️ **Vision Support**: Multimodal capabilities with screenshot analysis
-- 🛡️ **Robust**: Built-in error handling, recovery, graceful shutdown, and retry mechanisms
-- 📊 **Observable**: Comprehensive logging, execution history, and telemetry
-- 🔧 **Extensible**: Custom actions, MCP protocol, and plugin system
-- 📁 **FileSystem**: Built-in file operations with PDF parsing
-- 🔗 **Integrations**: Gmail API, Google Sheets, and MCP servers
-
-## Quick Start
+<p align="center">
+  <h1 align="center">🌐 Browser-Use</h1>
+  <p align="center">
+    <strong>Make websites accessible for AI agents — in TypeScript</strong>
+  </p>
+  <p align="center">
+    A TypeScript-first library for building AI-powered web agents that can autonomously browse, interact with, and extract data from the web using LLMs and Playwright.
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://github.com/webllm/browser-use/workflows/Node%20CI"><img src="https://github.com/webllm/browser-use/workflows/Node%20CI/badge.svg" alt="Node CI"></a>
+  <a href="https://www.npmjs.com/package/browser-use"><img src="https://img.shields.io/npm/v/browser-use.svg" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/browser-use"><img src="https://img.shields.io/npm/dm/browser-use.svg" alt="npm downloads"></a>
+  <img src="https://img.shields.io/npm/l/browser-use" alt="license">
+  <img src="https://img.shields.io/badge/TypeScript-first-blue" alt="TypeScript">
+</p>
+
+---
+
+> **TypeScript port** of the popular Python [browser-use](https://github.com/browser-use/browser-use) library — with a native Node.js experience, full type safety, and first-class support for all major LLM providers.
+
+## ✨ Features
+
+- 🤖 **Autonomous Browser Control** — AI-driven navigation, clicking, typing, form filling, scrolling, and tab management
+- 🧠 **10+ LLM Providers** — OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock, Groq, Ollama, DeepSeek, OpenRouter, Mistral, Cerebras, and custom providers
+- 👁️ **Vision Support** — Screenshot-based understanding for visual web interactions
+- 🔧 **45+ Built-in Actions** — Navigation, element interaction, scrolling, forms, tabs, content extraction, file I/O, and more
+- 🧩 **Custom Actions** — Extensible registry with Zod schema validation, domain restrictions, and page filters
+- 🔌 **MCP Server** — Model Context Protocol support for Claude Desktop and MCP-compatible clients
+- ⌨️ **CLI Tool** — Interactive and one-shot modes for quick browser tasks
+- 🔒 **Security First** — Sensitive data masking, domain restrictions, and Chromium sandboxing
+- 📊 **Observability** — Event system, telemetry, performance tracing, and session recording (GIF)
+- 🐳 **Docker Ready** — Configurable for containerized and CI/CD environments
+
+## 🚀 Quick Start
 
 ### Installation
 
 ```bash
 npm install browser-use
-# or
-yarn add browser-use
-# or
-pnpm add browser-use
+# Playwright browsers are installed automatically via postinstall
 ```
 
-Playwright browsers will be installed automatically via postinstall hook.
-
-Use only documented public entrypoints such as `browser-use` and
-`browser-use/llm/openai`. Avoid deep imports like `browser-use/dist/...`.
-
-### Basic Usage with Agent
-
-```typescript
-import { Agent } from 'browser-use';
-import { ChatOpenAI } from 'browser-use/llm/openai';
-
-async function main() {
-  const llm = new ChatOpenAI({
-    model: 'gpt-4',
-    apiKey: process.env.OPENAI_API_KEY,
-  });
-
-  const agent = new Agent({
-    task: 'Go to google.com and search for "TypeScript browser automation"',
-    llm,
-  });
-
-  const history = await agent.run();
-
-  console.log(`Task completed in ${history.history.length} steps`);
-
-  // Access the browser session
-  const browserSession = agent.browser_session;
-  const currentPage = await browserSession.get_current_page();
-  console.log('Final URL:', currentPage?.url());
-}
+### Set Up Your API Key
 
-main();
+```bash
+export OPENAI_API_KEY=sk-your-api-key
+# or ANTHROPIC_API_KEY, GOOGLE_API_KEY, etc.
 ```
 
-### Using Controller for Custom Actions
-
-Use `Controller` to register domain-specific actions, then pass it into `Agent`:
+### Run Your First Agent
 
 ```typescript
-import { Agent, Controller, ActionResult } from 'browser-use';
+import { Agent } from 'browser-use';
 import { ChatOpenAI } from 'browser-use/llm/openai';
-import { z } from 'zod';
-
-const controller = new Controller();
-
-controller.registry.action('Extract product info from the current page', {
-  param_model: z.object({
-    include_price: z.boolean().default(true),
-    include_reviews: z.boolean().default(false),
-  }),
-})(async function extract_product_info(params, { page }) {
-  const productData = await page.evaluate(() => ({
-    title: document.querySelector('h1')?.textContent ?? null,
-    price: document.querySelector('.price')?.textContent ?? null,
-  }));
-
-  return new ActionResult({
-    extracted_content: JSON.stringify({ ...productData, ...params }),
-    include_in_memory: true,
-  });
-});
 
 const agent = new Agent({
-  task: 'Open product page and extract product info',
+  task: 'Go to google.com and search for "TypeScript tutorials"',
   llm: new ChatOpenAI({
     model: 'gpt-4o',
     apiKey: process.env.OPENAI_API_KEY,
   }),
-  controller,
 });
 
-const history = await agent.run(10);
-console.log(history.final_result());
+const history = await agent.run();
+console.log('Result:', history.final_result());
+console.log('Success:', history.is_successful());
 ```
 
-### CLI Usage
+```bash
+npx tsx example.ts
+```
+
+### Use the CLI
 
 ```bash
-# Interactive mode (when running in a TTY)
+# Interactive mode
 npx browser-use
 
 # One-shot task
-npx browser-use -p "Go to example.com and extract the page title"
-
-# Positional task mode
-npx browser-use "Search for TypeScript browser automation"
-
-# Pick model/provider by model name
-npx browser-use --model claude-sonnet-4-20250514 -p "Summarize latest AI news"
-
-# Pick provider explicitly (uses provider default model)
-npx browser-use --provider anthropic -p "Summarize latest AI news"
+npx browser-use "Go to example.com and extract the page title"
 
-# Headless + custom browser profile settings
-npx browser-use --headless --window-width 1440 --window-height 900 -p "Check dashboard status"
+# With specific model
+npx browser-use --model claude-sonnet-4-20250514 -p "Search for AI news"
 
-# Restrict navigation to trusted domains (recommended with secrets)
-npx browser-use --allowed-domains "example.com,*.example.org" -p "Log in and fetch account info"
-
-# Connect to existing Chromium via CDP
-npx browser-use --cdp-url http://localhost:9222 -p "Inspect the active tab"
+# Headless mode
+npx browser-use --headless -p "Check the weather"
 
 # MCP server mode
 npx browser-use --mcp
 ```
 
-Interactive mode commands:
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Browser-Use                      │
+├─────────────────────────────────────────────────────┤
+│  Agent ← MessageManager ← LLM Providers             │
+│    ↓                                                │
+│  Controller → Action Registry → BrowserSession      │
+│                                      ↓              │
+│                                  DomService         │
+└─────────────────────────────────────────────────────┘
+```
+
+| Component          | Description                                                            |
+| ------------------ | ---------------------------------------------------------------------- |
+| **Agent**          | Central orchestrator — runs the observe → think → act loop             |
+| **Controller**     | Manages action registration and execution via Registry                 |
+| **BrowserSession** | Playwright wrapper — browser lifecycle, tab management, screenshots    |
+| **DomService**     | Extracts interactive elements with indexed mapping for LLM consumption |
+| **MessageManager** | Manages LLM conversation history with token optimization               |
+| **LLM Providers**  | Unified `BaseChatModel` interface across 10+ providers                 |
+
+### How It Works
+
+1. **Agent** receives a natural language task
+2. **DomService** extracts the current page state (interactive elements + optional screenshot)
+3. **LLM** analyzes the state and returns actions to take
+4. **Controller** validates and executes actions through the **Registry**
+5. Results feed back to the LLM for the next step
+6. Loop continues until `done` action or `max_steps`
+
+## 🔌 LLM Providers
+
+| Provider          | Import                       | Vision | Notes                                         |
+| ----------------- | ---------------------------- | ------ | --------------------------------------------- |
+| **OpenAI**        | `browser-use/llm/openai`     | ✅     | Default provider, reasoning models (o1/o3/o4) |
+| **Anthropic**     | `browser-use/llm/anthropic`  | ✅     | Prompt caching support                        |
+| **Google Gemini** | `browser-use/llm/google`     | ✅     | Extended thinking support                     |
+| **Azure OpenAI**  | `browser-use/llm/azure`      | ✅     | Enterprise deployment                         |
+| **AWS Bedrock**   | `browser-use/llm/aws`        | ✅     | Claude via AWS                                |
+| **Groq**          | `browser-use/llm/groq`       | ❌     | Fastest inference                             |
+| **Ollama**        | `browser-use/llm/ollama`     | ❌     | Local/self-hosted models                      |
+| **DeepSeek**      | `browser-use/llm/deepseek`   | ❌     | Cost-effective                                |
+| **OpenRouter**    | `browser-use/llm/openrouter` | Varies | Multi-model routing                           |
+| **Mistral**       | `browser-use/llm/mistral`    | Varies | Mistral models                                |
+| **Cerebras**      | `browser-use/llm/cerebras`   | ❌     | Fast inference                                |
+
+<details>
+<summary>Provider examples</summary>
 
-- `help`: show interactive usage
-- `exit`: quit interactive mode
+```typescript
+// OpenAI
+import { ChatOpenAI } from 'browser-use/llm/openai';
+const llm = new ChatOpenAI({
+  model: 'gpt-4o',
+  apiKey: process.env.OPENAI_API_KEY,
+});
 
-Security notes:
+// Anthropic
+import { ChatAnthropic } from 'browser-use/llm/anthropic';
+const llm = new ChatAnthropic({
+  model: 'claude-sonnet-4-20250514',
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
 
-- Prefer `--allowed-domains` whenever tasks involve credentials or sensitive data.
-- `--allow-insecure` disables domain-lockdown enforcement for sensitive data and is unsafe for production.
+// Google Gemini
+import { ChatGoogle } from 'browser-use/llm/google';
+const llm = new ChatGoogle('gemini-2.5-flash');
 
-## Advanced Usage
+// Ollama (local)
+import { ChatOllama } from 'browser-use/llm/ollama';
+const llm = new ChatOllama('llama3', 'http://localhost:11434');
 
-### Vision/Multimodal Support
+// OpenAI Reasoning Models
+const llm = new ChatOpenAI({ model: 'o3-mini', reasoningEffort: 'medium' });
+```
 
-Enable vision capabilities to let the AI analyze screenshots:
+</details>
 
-```typescript
-import { Agent } from 'browser-use';
-import { ChatGoogle } from 'browser-use/llm/google';
+## 🎯 Code Examples
 
-const llm = new ChatGoogle('gemini-2.5-flash');
+### Data Extraction
 
+```typescript
 const agent = new Agent({
-  task: 'Describe what you see on this page and identify main visual elements',
+  task: `Go to amazon.com, search for "wireless keyboard",
+         extract the name, price, and rating of the first 5 products as JSON`,
   llm,
   use_vision: true,
-  vision_detail_level: 'high', // 'auto' | 'low' | 'high'
 });
 
-const history = await agent.run(5);
+const history = await agent.run(30);
+console.log(history.final_result());
 ```
 
-### Custom Actions with Controller Registry
+### Form Filling with Sensitive Data
+
+```typescript
+const agent = new Agent({
+  task: 'Login to the dashboard',
+  llm,
+  sensitive_data: {
+    '*.example.com': {
+      username: process.env.SITE_USERNAME!,
+      password: process.env.SITE_PASSWORD!,
+    },
+  },
+  browser_session: new BrowserSession({
+    browser_profile: new BrowserProfile({
+      allowed_domains: ['*.example.com'],
+    }),
+  }),
+});
+```
 
-Extend the agent's capabilities with custom actions:
+### Custom Actions
 
 ```typescript
 import { Controller, ActionResult } from 'browser-use';
@@ -230,588 +215,212 @@ import { z } from 'zod';
 
 const controller = new Controller();
 
-controller.registry.action('Extract product information', {
+controller.registry.action('Save screenshot to file', {
   param_model: z.object({
-    include_price: z.boolean().default(true),
-    include_reviews: z.boolean().default(false),
+    filename: z.string().describe('Output filename'),
   }),
-})(async function extract_product_info(params, { page }) {
-  const productData = await page.evaluate(() => ({
-    title: document.querySelector('h1')?.textContent ?? null,
-    price: document.querySelector('.price')?.textContent ?? null,
-  }));
-
+})(async function save_screenshot(params, ctx) {
+  const screenshot = await ctx.page.screenshot();
+  fs.writeFileSync(`./screenshots/${params.filename}`, screenshot);
   return new ActionResult({
-    extracted_content: JSON.stringify({ ...productData, ...params }),
-    include_in_memory: true,
+    extracted_content: `Screenshot saved as ${params.filename}`,
   });
 });
-```
 
-### FileSystem Operations
-
-Built-in file system support with PDF parsing:
-
-```typescript
-import { Agent } from 'browser-use';
-import { ChatOpenAI } from 'browser-use/llm/openai';
-
-const agent = new Agent({
-  task: 'Download the PDF and extract text from page 1',
-  llm: new ChatOpenAI(),
-  file_system_path: './agent-workspace',
-});
-
-// FileSystem actions are available:
-// - read_file: Read file contents (supports PDF)
-// - write_file: Write content to file
-// - replace_file_str: Replace text in file
+const agent = new Agent({ task: '...', llm, controller });
 ```
 
-### Browser Profile Configuration
-
-Customize browser behavior with profiles:
+### Vision Mode & Session Recording
 
 ```typescript
-import { BrowserProfile, BrowserSession } from 'browser-use';
-
-const profile = new BrowserProfile({
-  window_size: { width: 1920, height: 1080 },
-  disable_security: false,
-  headless: true,
-  chromium_sandbox: true, // Keep enabled by default in production
-  args: ['--disable-blink-features=AutomationControlled'],
-  wait_for_network_idle_page_load_time: 3, // seconds
-  allowed_domains: ['example.com', '*.google.com'],
-  cookies_file: './cookies.json',
-  downloads_path: './downloads',
-  highlight_elements: false, // Visual debugging
-  viewport_expansion: 0, // Expand viewport for element detection
-});
-
-const browserSession = new BrowserSession({
-  browser_profile: profile,
+const agent = new Agent({
+  task: 'Navigate to hacker news and summarize the top stories',
+  llm,
+  use_vision: true,
+  vision_detail_level: 'high', // 'auto' | 'low' | 'high'
+  generate_gif: './session.gif',
 });
-
-await browserSession.start();
 ```
 
-If Chromium launch fails with `No usable sandbox` (common in restricted Linux CI),
-`BrowserSession` automatically retries once with `chromium_sandbox: false` and logs
-a warning. For deterministic CI behavior, set `chromium_sandbox: false` explicitly.
-
-### MCP (Model Context Protocol) Integration
-
-Connect to MCP servers for extended capabilities:
+### Multi-Tab Workflows
 
 ```typescript
-import { MCPController } from 'browser-use';
-
-const mcpController = new MCPController();
-
-// Add MCP server
-await mcpController.addServer('my-server', 'npx', [
-  '-y',
-  '@modelcontextprotocol/server-filesystem',
-  '/path/to/data',
-]);
-
-// MCP tools are automatically available to the agent
-const tools = await mcpController.listAllTools();
-console.log('Available MCP tools:', tools);
-```
-
-### Gmail Integration
-
-Built-in Gmail API support:
-
-```typescript
-import { GmailService } from 'browser-use';
-
-// Gmail actions are automatically available:
-// - get_recent_emails: Fetch recent emails
-// - send_email: Send email via Gmail API
-
 const agent = new Agent({
-  task: 'Check my last 5 emails and summarize them',
-  llm: new ChatOpenAI(),
-  // Gmail credentials loaded from config files (or explicit GmailService options)
+  task: `Compare "Sony WH-1000XM5" prices:
+    1. Open amazon.com and search for the product
+    2. Open bestbuy.com in a new tab and search
+    3. Provide a comparison summary`,
+  llm,
+  use_vision: true,
 });
 ```
 
-## Configuration
-
-### Environment Variables
-
-```bash
-# LLM Configuration (provider-specific)
-OPENAI_API_KEY=your-openai-key
-ANTHROPIC_API_KEY=your-anthropic-key
-GOOGLE_API_KEY=your-google-key
-AWS_ACCESS_KEY_ID=your-aws-key
-AWS_SECRET_ACCESS_KEY=your-aws-secret
-AZURE_OPENAI_API_KEY=your-azure-key
-AZURE_OPENAI_ENDPOINT=your-azure-endpoint
-GROQ_API_KEY=your-groq-key
-DEEPSEEK_API_KEY=your-deepseek-key
-
-# Browser Configuration
-BROWSER_USE_HEADLESS=true
-BROWSER_USE_ALLOWED_DOMAINS=example.com,*.trusted.org
-IN_DOCKER=true
-
-# Logging Configuration
-BROWSER_USE_LOGGING_LEVEL=info  # debug, info, warning, error
-
-# Telemetry (optional)
-ANONYMIZED_TELEMETRY=false
-
-# Observability (optional)
-LMNR_API_KEY=your-lmnr-key
-```
-
-### Agent Configuration
-
-```typescript
-interface AgentOptions {
-  // Vision/multimodal
-  use_vision?: boolean;
-  vision_detail_level?: 'low' | 'high' | 'auto';
-
-  // Error handling
-  max_failures?: number; // default: 3
-  retry_delay?: number; // seconds, default: 10
-  max_actions_per_step?: number; // default: 10
-
-  // Persistence / output
-  save_conversation_path?: string | null;
-  file_system_path?: string | null;
-  validate_output?: boolean;
-  include_attributes?: string[];
-
-  // Runtime limits (seconds)
-  llm_timeout?: number; // default: 60
-  step_timeout?: number; // default: 180
-}
-
-// Max step count is configured per run call:
-await agent.run(100);
-```
-
-## Supported LLM Providers
-
-### OpenAI
+### Event System
 
 ```typescript
-import { ChatOpenAI } from 'browser-use/llm/openai';
+const agent = new Agent({ task: '...', llm });
 
-const llm = new ChatOpenAI({
-  model: 'gpt-4o', // or 'gpt-4', 'gpt-3.5-turbo'
-  apiKey: process.env.OPENAI_API_KEY,
-  temperature: 0.1,
-  maxTokens: 4096,
+agent.eventbus.on('CreateAgentStepEvent', (event) => {
+  console.log('Step completed:', event.step_id);
 });
-```
 
-### Anthropic Claude
-
-```typescript
-import { ChatAnthropic } from 'browser-use/llm/anthropic';
-
-const llm = new ChatAnthropic({
-  model: 'claude-3-5-sonnet-20241022', // or other Claude models
-  apiKey: process.env.ANTHROPIC_API_KEY,
-  temperature: 0.1,
-});
+await agent.run();
 ```
 
-### Google Gemini
-
-```typescript
-import { ChatGoogle } from 'browser-use/llm/google';
-
-const llm = new ChatGoogle('gemini-2.5-flash');
-// Configure GOOGLE_API_KEY in env. Optional:
-// GOOGLE_API_BASE_URL / GOOGLE_API_VERSION
-```
+## ⚙️ Configuration
 
-### AWS Bedrock
+### Agent Options
 
 ```typescript
-import { ChatAnthropicBedrock } from 'browser-use/llm/aws';
-
-const llm = new ChatAnthropicBedrock({
-  model: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
-  region: 'us-east-1',
-  max_tokens: 4096,
+const agent = new Agent({
+  task: 'Your task',
+  llm,
+  use_vision: true, // Enable screenshot analysis
+  max_actions_per_step: 5, // Actions per LLM call
+  max_failures: 3, // Max retries on failure
+  generate_gif: './recording.gif', // Session recording
+  validate_output: true, // Strict output validation
+  use_thinking: true, // Extended thinking prompts
+  llm_timeout: 60, // LLM call timeout (seconds)
+  step_timeout: 180, // Step timeout (seconds)
+  extend_system_message: 'Be concise', // Custom prompt additions
 });
-```
 
-### Azure OpenAI
-
-```typescript
-import { ChatAzure } from 'browser-use/llm/azure';
-
-const llm = new ChatAzure('gpt-4o');
-// Configure AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION in env.
-```
-
-### DeepSeek
-
-```typescript
-import { ChatDeepSeek } from 'browser-use/llm/deepseek';
-
-const llm = new ChatDeepSeek('deepseek-chat');
+const history = await agent.run(50); // Max 50 steps
 ```
 
-### Groq
+### Browser Profile
 
 ```typescript
-import { ChatGroq } from 'browser-use/llm/groq';
-
-const llm = new ChatGroq('mixtral-8x7b-32768');
-```
-
-### Ollama (Local)
-
-```typescript
-import { ChatOllama } from 'browser-use/llm/ollama';
-
-const llm = new ChatOllama('llama3.1', 'http://localhost:11434');
-```
-
-### OpenRouter
+import { BrowserProfile, BrowserSession } from 'browser-use';
 
-```typescript
-import { ChatOpenRouter } from 'browser-use/llm/openrouter';
+const profile = new BrowserProfile({
+  headless: true,
+  viewport: { width: 1920, height: 1080 },
+  user_data_dir: './my-profile', // Persistent sessions
+  allowed_domains: ['*.example.com'], // Domain restrictions
+  highlight_elements: true, // Visual debugging
+  proxy: { server: 'http://proxy:8080' },
+});
 
-const llm = new ChatOpenRouter('anthropic/claude-3-opus');
+const session = new BrowserSession({ browser_profile: profile });
+const agent = new Agent({ task: '...', llm, browser_session: session });
 ```
 
-## Available Actions
-
-The AI agent can perform these actions:
-
-### Navigation
-
-- **search_google** - Search query in Google (web results only)
-- **go_to_url** - Navigate to a specific URL (with optional new tab)
-
-### Element Interaction
-
-- **click_element** - Click buttons, links, or clickable elements by index
-- **input_text** - Type text into input fields and textareas by index
-
-### Dropdown/Select
-
-- **dropdown_options** - Get available options from a dropdown
-- **select_dropdown** - Select option from dropdown by index
-
-### Scrolling
-
-- **scroll** - Scroll page up/down by pixels or direction
-- **scroll_to_text** - Scroll to text content on page
-
-### Tabs
-
-- **switch_tab** - Switch to different browser tab by index
-- **close_tab** - Close current or specific tab
-
-### Keyboard
-
-- **send_keys** - Send keyboard input (Enter, Tab, Escape, etc.)
-
-### Content Extraction
-
-- **extract_structured_data** - Extract specific data using LLM from page markdown
-
-### FileSystem
-
-- **read_file** - Read file contents (supports PDF parsing)
-- **write_file** - Write content to file
-- **replace_file_str** - Replace string in file
-
-### Google Sheets
-
-- **sheets_range** - Get cell range from Google Sheet
-- **sheets_update** - Update Google Sheet cells
-- **sheets_input** - Input data into Google Sheet
-
-### Gmail
-
-- **get_recent_emails** - Fetch recent emails from Gmail
-- **send_email** - Send email via Gmail API
-
-### Completion
-
-- **done** - Mark task as completed with optional structured output
+### Environment Variables
 
-## Examples
+| Variable                      | Description                                    |
+| ----------------------------- | ---------------------------------------------- |
+| `OPENAI_API_KEY`              | OpenAI API key                                 |
+| `ANTHROPIC_API_KEY`           | Anthropic API key                              |
+| `GOOGLE_API_KEY`              | Google API key                                 |
+| `BROWSER_USE_HEADLESS`        | Run browser headlessly (`true`/`false`)        |
+| `BROWSER_USE_LOGGING_LEVEL`   | Log level: `debug`, `info`, `warning`, `error` |
+| `BROWSER_USE_ALLOWED_DOMAINS` | Comma-separated domain allowlist               |
+| `ANONYMIZED_TELEMETRY`        | Enable/disable anonymous telemetry             |
 
-See the `/examples` directory for detailed examples:
+> See [Configuration Guide](./docs/CONFIGURATION.md) for the full list.
 
-- `examples/simple-search.ts` - Basic web search automation
-- `examples/search-wikipedia.ts` - Wikipedia navigation with vision
-- `examples/test-vision.ts` - Vision/multimodal capabilities demo
-- `examples/test-filesystem.ts` - File operations and PDF parsing
-- `examples/openapi.ts` - Complex API documentation extraction
+## 🔌 MCP Server (Claude Desktop)
 
-### Running Examples
+Browser-Use can run as an [MCP](https://modelcontextprotocol.io/) server, exposing browser automation as tools for Claude Desktop:
 
 ```bash
-# Set your API key
-export OPENAI_API_KEY=your-key
-# or for Google
-export GOOGLE_API_KEY=your-key
-
-# Run an example
-npx tsx examples/simple-search.ts
+npx browser-use --mcp
 ```
 
-## Error Handling
-
-The library includes comprehensive error handling:
-
-```typescript
-import { Agent, AgentError } from 'browser-use';
-
-try {
-  const agent = new Agent({ task: 'Your task', llm });
-  const history = await agent.run(10); // max 10 steps
-
-  // Check completion status
-  const lastStep = history.history[history.history.length - 1];
-  if (lastStep?.result.is_done) {
-    console.log('Task completed:', lastStep.result.extracted_content);
-  } else {
-    console.log('Task incomplete after max steps');
-  }
-} catch (error) {
-  if (error instanceof AgentError) {
-    console.error('Agent error:', error.message);
-    console.error('Failed at step:', error.step);
-  } else {
-    console.error('Unexpected error:', error);
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "browser-use": {
+      "command": "npx",
+      "args": ["browser-use", "--mcp"],
+      "env": {
+        "OPENAI_API_KEY": "your-api-key"
+      }
+    }
   }
 }
 ```
 
-## Development
-
-### Building from Source
-
-```bash
-git clone https://github.com/webllm/browser-use.git
-cd browser-use
-yarn install  # Automatically installs Playwright browsers
-yarn build
-```
-
-### Running Tests
-
-```bash
-# Run all tests
-yarn test
-
-# Run specific test
-yarn test test/integration-advanced.test.ts
-
-# Watch mode
-yarn test:watch
-
-# Validate published package exports
-yarn test:pack
-```
-
-### Code Quality
+Available MCP tools: `browser_run_task`, `browser_navigate`, `browser_click`, `browser_type`, `browser_scroll`, `browser_get_state`, `browser_extract`, `browser_screenshot`, `browser_close`.
 
-```bash
-# Lint
-yarn lint
-
-# Format
-yarn prettier
-
-# Type check
-yarn typecheck
-```
+> See [MCP Server Guide](./docs/MCP_SERVER.md) for more details.
 
-## Architecture
+## 🔒 Security
 
-The library follows a modular, layered architecture:
-
-```
-┌──────────────────────────────────────────┐
-│            Agent (Orchestrator)          │
-│  - Task execution & planning             │
-│  - LLM message management                │
-│  - Step execution loop                   │
-└─────────┬────────────────────────────────┘
-          │
-┌─────────▼────────────────────────────────┐
-│           Controller (Actions)           │
-│  - Action registry & execution           │
-│  - Built-in actions (30+)                │
-│  - Custom action support                 │
-└─────────┬────────────────────────────────┘
-          │
-┌─────────▼────────────────────────────────┐
-│        BrowserSession (Browser)          │
-│  - Playwright integration                │
-│  - Tab & page management                 │
-│  - Navigation & interaction              │
-└─────────┬────────────────────────────────┘
-          │
-┌─────────▼────────────────────────────────┐
-│         DOMService (DOM Analysis)        │
-│  - Element extraction                    │
-│  - Clickable element detection           │
-│  - History tree processing               │
-└──────────────────────────────────────────┘
-
-Supporting Services:
-┌──────────────────────────────────────────┐
-│  - LLM Clients (10+ providers)           │
-│  - FileSystem (with PDF support)         │
-│  - Screenshot Service                    │
-│  - Token Tracking & Cost Calculation     │
-│  - Telemetry (PostHog)                   │
-│  - Observability (LMNR)                  │
-│  - MCP Protocol Support                  │
-│  - Gmail/Sheets Integration              │
-└──────────────────────────────────────────┘
-```
-
-### Key Components
-
-- **Agent**: High-level orchestrator managing task execution, LLM communication, and step-by-step planning
-- **Controller**: Action registry and executor with 30+ built-in actions and custom action support
-- **BrowserSession**: Browser lifecycle manager built on Playwright with tab management and state tracking
-- **DOMService**: Intelligent DOM analyzer extracting relevant elements for AI consumption
-- **MessageManager**: Manages conversation history with token optimization and context window management
-- **FileSystem**: File operations with PDF parsing and workspace management
-- **ScreenshotService**: Captures and manages screenshots for vision capabilities
-- **Registry**: Type-safe action registration system with Zod schema validation
-
-## Token Usage & Cost Tracking
-
-The library automatically tracks token usage and calculates costs:
+- **Sensitive Data Masking** — Credentials are automatically masked in logs and LLM context
+- **Domain Restrictions** — Lock browser navigation to trusted domains
+- **Domain-scoped Secrets** — Credentials are only injected on matching domains
+- **Hard Safety Gate** — `sensitive_data` requires `allowed_domains` by default
+- **Chromium Sandbox** — Enabled by default for production security
 
 ```typescript
-import { TokenCost } from 'browser-use';
-
-const agent = new Agent({ task: 'Your task', llm });
-const history = await agent.run();
-
-// Get token statistics
-const stats = history.stats();
-console.log(
-  'Total tokens:',
-  stats.total_input_tokens + stats.total_output_tokens
-);
-console.log('Steps:', stats.n_steps);
-
-// Calculate cost (if pricing data available)
-const cost = TokenCost.calculate(history);
-console.log('Estimated cost: $', cost.toFixed(4));
-```
-
-## Screenshot & History Export
-
-Generate GIF animations from agent execution history:
-
-```typescript
-import { create_history_gif } from 'browser-use';
-
-const history = await agent.run();
-
-await create_history_gif('My automation task', history, {
-  output_path: 'agent-history.gif',
-  duration: 3000, // ms per frame
-  show_goals: true,
-  show_task: true,
-  show_logo: false,
+const agent = new Agent({
+  task: 'Login and fetch invoices',
+  llm,
+  sensitive_data: {
+    '*.example.com': {
+      username: process.env.USERNAME!,
+      password: process.env.PASSWORD!,
+    },
+  },
+  browser_session: new BrowserSession({
+    browser_profile: new BrowserProfile({
+      allowed_domains: ['*.example.com'],
+    }),
+  }),
 });
-
-console.log('Created agent-history.gif');
 ```
 
-## Observability
+> See [Security Guide](./docs/SECURITY.md) for production deployment best practices.
 
-Built-in observability with LMNR (Laminar) and custom debugging:
+## 📚 Documentation
 
-```typescript
-import { observe, observe_debug } from 'browser-use';
+| Document                                 | Description                          |
+| ---------------------------------------- | ------------------------------------ |
+| [Quick Start](./docs/QUICKSTART.md)      | Get started in 5 minutes             |
+| [Architecture](./docs/ARCHITECTURE.md)   | System design and component overview |
+| [API Reference](./docs/API_REFERENCE.md) | Complete API documentation           |
+| [Configuration](./docs/CONFIGURATION.md) | All configuration options            |
+| [LLM Providers](./docs/LLM_PROVIDERS.md) | Provider setup and comparison        |
+| [Actions](./docs/ACTIONS.md)             | Built-in and custom actions          |
+| [MCP Server](./docs/MCP_SERVER.md)       | MCP integration guide                |
+| [Security](./docs/SECURITY.md)           | Security best practices              |
+| [Examples](./docs/EXAMPLES.md)           | More code examples                   |
+| [Contributing](./docs/CONTRIBUTING.md)   | Contribution guidelines              |
 
-// Automatic tracing (if LMNR_API_KEY set)
-// All agent operations are automatically traced
+## 🛠️ Development
 
-// Custom debug observations
-@observe_debug({ name: 'my_custom_operation' })
-async function myFunction() {
-  // Function execution is logged and timed
-}
-```
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## Support
-
-- 📚 [Documentation](https://github.com/webllm/browser-use)
-- 🐛 [Issue Tracker](https://github.com/webllm/browser-use/issues)
-- 💬 [Discussions](https://github.com/webllm/browser-use/discussions)
-
-## Acknowledgments
-
-### Original Project
-
-This TypeScript implementation would not exist without the groundbreaking work of the original **[browser-use](https://github.com/browser-use/browser-use)** Python library:
-
-- 🎯 **Original Project**: [browser-use/browser-use](https://github.com/browser-use/browser-use) (Python)
-- 👏 **Created by**: The browser-use team and contributors
-- 💡 **Inspiration**: All architectural decisions, agent design patterns, and innovative approaches come from the original Python implementation
-
-We are deeply grateful to the original authors for creating such an elegant and powerful solution for AI-driven browser automation. This TypeScript port aims to faithfully replicate their excellent work for the JavaScript/TypeScript community.
-
-### Key Differences from Python Version
-
-While we strive to maintain feature parity with the Python version, there are some differences due to platform constraints:
-
-- **Runtime**: Node.js/Deno/Bun instead of Python
-- **Type System**: TypeScript's structural typing vs Python's duck typing
-- **Async Model**: JavaScript Promises vs Python async/await (similar but different)
-- **Ecosystem**: npm packages vs PyPI packages
+```bash
+# Install dependencies
+pnpm install
 
-### Technology Stack
+# Build
+pnpm build
 
-This project is built with:
+# Run tests
+pnpm test
 
-- [Playwright](https://playwright.dev/) - Browser automation framework
-- [Zod](https://zod.dev/) - TypeScript-first schema validation
-- [OpenAI](https://openai.com/), [Anthropic](https://anthropic.com/), [Google](https://ai.google.dev/) - LLM providers
-- And many other excellent open-source libraries
+# Lint & format
+pnpm lint
+pnpm prettier
 
-### Community
+# Type checking
+pnpm typecheck
 
-- 🌟 **Star the original Python project**: [browser-use/browser-use](https://github.com/browser-use/browser-use)
-- 🌟 **Star this TypeScript port**: [webllm/browser-use](https://github.com/webllm/browser-use)
-- 💬 **Join the community**: Share your use cases and contribute to both projects!
+# Run an example
+pnpm exec tsx examples/simple-search.ts
+```
 
-## Related Projects
+## Requirements
 
-- 🐍 [browser-use (Python)](https://github.com/browser-use/browser-use) - The original and official implementation
-- 🎭 [Playwright](https://playwright.dev/) - The browser automation foundation
-- 🤖 [LangChain](https://www.langchain.com/) - LLM application framework
-- 🦜 [Laminar](https://laminar.run/) - LLM observability platform
+- **Node.js** >= 18.0.0
+- **LLM API Key** — At least one supported provider
+- **Playwright** — Installed automatically as a dependency
 
-## License
+## 📄 License
 
-MIT License - see [LICENSE](LICENSE) for details.
+[MIT](./LICENSE) © Web LLM