![\"OpenBrowser\"](\"docs/logo/icon.svg\"){kind=icon}
\n\n \n
AI browser automation, powered by code.
\n\n---\n\n**Cloud dashboard for saved cookies and scheduled tasks is available in the hosted version. Join the waitlist for early access: https://openbrowser.me** :\n\nhttps://github.com/user-attachments/assets/b17f97f3-f9f8-4707-8e39-abbbbe1a693b\n\n**Automating Walmart Product Scraping:**\n\nhttps://github.com/user-attachments/assets/c517c739-9199-47b0-bac7-c2c642a21094\n\n**OpenBrowserAI Automatic Flight Booking:**\n\nhttps://github.com/user-attachments/assets/632128f6-3d09-497f-9e7d-e29b9cb65e0f\n\n**OpenBrowserAI Automatic Form Filling:**\n\nhttps://github.com/user-attachments/assets/16f7ef1a-beb1-45e2-a733-9592536e0ef7\n\n\n[](https://pypi.org/project/openbrowser-ai/)\n[](https://pepy.tech/projects/openbrowser-ai)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/billy-enrizky/openbrowser-ai/actions)\n[](https://codecov.io/gh/billy-enrizky/openbrowser-ai)\n\n\n\n**AI-powered browser automation using CodeAgent and CDP (Chrome DevTools Protocol)**\n\nOpenBrowser is a framework for intelligent browser automation. It combines direct CDP communication with a CodeAgent architecture, where the LLM writes Python code executed in a persistent namespace, to navigate, interact with, and extract information from web pages autonomously.\n\n## Table of Contents\n\n- [Documentation](#documentation)\n- [Key Features](#key-features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Supported LLM Providers](#supported-llm-providers)\n- [Claude Code Plugin](#claude-code-plugin)\n- [Codex](#codex)\n- [OpenCode](#opencode)\n- [OpenClaw](#openclaw)\n- [MCP Server](#mcp-server)\n- [Benchmark: Token Efficiency](#benchmark-token-efficiency)\n- [CLI Usage](#cli-usage)\n- [Project Structure](#project-structure)\n- [Backend and Frontend Deployment](#backend-and-frontend-deployment)\n- [Testing](#testing)\n- [Research: Reinforcement Fine-Tuning for Browser Agents](#research-reinforcement-fine-tuning-for-browser-agents)\n- [Contributing](#contributing)\n- [License](#license)\n- [Contact](#contact)\n\n## Documentation\n\n**Full documentation**: [https://docs.openbrowser.me](https://docs.openbrowser.me)\n\n## Key Features\n\n- **CodeAgent Architecture** - LLM writes Python code in a persistent Jupyter-like namespace for browser automation\n- **Raw CDP Communication** - Direct Chrome DevTools Protocol for maximum control and speed\n- **Vision Support** - Screenshot analysis for visual understanding of pages\n- **15 LLM Providers** - OpenAI, Anthropic, Google, Groq, AWS Bedrock, Azure, Ollama, DeepSeek, Cerebras, OpenRouter, OCI, and more\n- **MCP Server** - Model Context Protocol for Claude Desktop, Claude Code, Codex, OpenCode, and other AI assistants, with reusable saved login sessions\n- **CLI Daemon** - Persistent browser daemon with `-c` flag for direct code execution from Bash, saved login state, and 10-minute auto-shutdown\n- **Workflow Recording** - Record, replay, and export browser sessions to Jupyter notebooks or API crawler code\n- **Video Recording** - Record browser sessions as video files with ffmpeg\n- **Cloud Platform** - Full-stack web UI with real-time VNC streaming, saved logins (KMS-encrypted), scheduled workflows (EventBridge + SQS), and email notifications (SES)\n- **Plugin System** - Claude Code plugin with 6 guided skills (web scraping, form filling, e2e testing, page analysis, accessibility audit, file download)\n\n## Installation\n\n### Quick install (macOS / Linux)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh\n```\n\n### Quick install (Windows PowerShell)\n\n```powershell\nirm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex\n```\n\nDetects `uv`, `pipx`, or `pip` and installs OpenBrowser automatically.\n\nInstall to `~/.local/bin` without sudo:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh -s -- --local\n```\n\n### Homebrew (macOS / Linux)\n\n```bash\nbrew tap billy-enrizky/openbrowser\nbrew install openbrowser-ai\n```\n\n### pip\n\n```bash\npip install openbrowser-ai\n```\n\n### uv (recommended)\n\n```bash\nuv pip install openbrowser-ai\n```\n\n### uvx (zero install)\n\nRun directly without installing -- `uvx` downloads and caches the package automatically:\n\n```bash\n# MCP server mode\nuvx openbrowser-ai --mcp\n\n# CLI daemon mode\nuvx openbrowser-ai -c \"await navigate('https://example.com')\"\n```\n\n### pipx\n\n```bash\npipx install openbrowser-ai\n```\n\n### From source\n\n```bash\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git\ncd openbrowser-ai\nuv pip install -e \".[agent]\"\n```\n\n### Optional Dependencies\n\n```bash\npip install openbrowser-ai[agent] # LLM agent support (langgraph, langchain, litellm)\npip install openbrowser-ai[all] # All LLM providers\npip install openbrowser-ai[anthropic] # Anthropic Claude\npip install openbrowser-ai[groq] # Groq\npip install openbrowser-ai[ollama] # Ollama (local models)\npip install openbrowser-ai[aws] # AWS Bedrock\npip install openbrowser-ai[azure] # Azure OpenAI\npip install openbrowser-ai[video] # Video recording support\n```\n\n> **No separate browser install needed.** OpenBrowser auto-detects any installed Chromium-based browser (Chrome, Edge, Brave, Chromium) and uses it directly. If none is found and `uvx` is available, Chromium is installed automatically on first run. To pre-install manually (requires `uvx`): `openbrowser-ai install`\n\n## Quick Start\n\n### Basic Usage\n\n```python\nimport asyncio\nfrom openbrowser import CodeAgent, ChatGoogle\n\nasync def main():\n agent = CodeAgent(\n task=\"Go to google.com and search for 'Python tutorials'\",\n llm=ChatGoogle(model=\"gemini-3-flash\"),\n )\n\n result = await agent.run()\n print(f\"Result: {result}\")\n\nasyncio.run(main())\n```\n\n### With Different LLM Providers\n\n```python\nfrom openbrowser import CodeAgent, ChatOpenAI, ChatAnthropic, ChatGoogle\n\n# OpenAI\nagent = CodeAgent(task=\"...\", llm=ChatOpenAI(model=\"gpt-5.2\"))\n\n# Anthropic\nagent = CodeAgent(task=\"...\", llm=ChatAnthropic(model=\"claude-sonnet-4-6\"))\n\n# Google Gemini\nagent = CodeAgent(task=\"...\", llm=ChatGoogle(model=\"gemini-3-flash\"))\n```\n\n### Using Browser Session Directly\n\n```python\nimport asyncio\nfrom openbrowser import BrowserSession, BrowserProfile\n\nasync def main():\n profile = BrowserProfile(\n headless=True,\n viewport_width=1920,\n viewport_height=1080,\n )\n \n session = BrowserSession(browser_profile=profile)\n await session.start()\n \n await session.navigate_to(\"https://example.com\")\n screenshot = await session.screenshot()\n \n await session.stop()\n\nasyncio.run(main())\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Google (recommended)\nexport GOOGLE_API_KEY=\"...\"\n\n# OpenAI\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Anthropic\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# Groq\nexport GROQ_API_KEY=\"gsk_...\"\n\n# AWS Bedrock\nexport AWS_ACCESS_KEY_ID=\"...\"\nexport AWS_SECRET_ACCESS_KEY=\"...\"\nexport AWS_DEFAULT_REGION=\"us-west-2\"\n\n# Azure OpenAI\nexport AZURE_OPENAI_API_KEY=\"...\"\nexport AZURE_OPENAI_ENDPOINT=\"https://your-resource.openai.azure.com/\"\n```\n\n### BrowserProfile Options\n\n```python\nfrom openbrowser import BrowserProfile\n\nprofile = BrowserProfile(\n headless=True,\n viewport_width=1280,\n viewport_height=720,\n disable_security=False,\n extra_chromium_args=[\"--disable-gpu\"],\n record_video_dir=\"./recordings\",\n proxy={\n \"server\": \"http://proxy.example.com:8080\",\n \"username\": \"user\",\n \"password\": \"pass\",\n },\n)\n```\n\n## Supported LLM Providers\n\n| Provider | Class | Models |\n|----------|-------|--------|\n| **Google** | `ChatGoogle` | gemini-3-flash, gemini-3-pro |\n| **OpenAI** | `ChatOpenAI` | gpt-5.2, o4-mini, o3 |\n| **Anthropic** | `ChatAnthropic` | claude-sonnet-4-6, claude-opus-4-6 |\n| **Groq** | `ChatGroq` | llama-4-scout, qwen3-32b |\n| **AWS Bedrock** | `ChatAWSBedrock` | anthropic.claude-sonnet-4-6, amazon.nova-pro |\n| **AWS Bedrock (Anthropic)** | `ChatAnthropicBedrock` | Claude models via Anthropic Bedrock SDK |\n| **Azure OpenAI** | `ChatAzureOpenAI` | Any Azure-deployed model |\n| **OpenRouter** | `ChatOpenRouter` | Any model on openrouter.ai |\n| **DeepSeek** | `ChatDeepSeek` | deepseek-chat, deepseek-r1 |\n| **Cerebras** | `ChatCerebras` | llama-4-scout, qwen-3-235b |\n| **Ollama** | `ChatOllama` | llama-4-scout, deepseek-r1 (local) |\n| **OCI** | `ChatOCIRaw` | Oracle Cloud GenAI models |\n| **Browser-Use** | `ChatBrowserUse` | External LLM service |\n\n## Claude Code Plugin\n\nInstall OpenBrowser as a Claude Code plugin:\n\n```bash\n# Add the marketplace (one-time)\nclaude plugin marketplace add billy-enrizky/openbrowser-ai\n\n# Install the plugin\nclaude plugin install openbrowser@openbrowser-ai\n```\n\nThis installs the MCP server and 6 built-in skills:\n\n| Skill | Description |\n|-------|-------------|\n| `web-scraping` | Extract structured data, handle pagination |\n| `form-filling` | Fill forms, login flows, multi-step wizards |\n| `e2e-testing` | Test web apps by simulating user interactions |\n| `page-analysis` | Analyze page content, structure, metadata |\n| `accessibility-audit` | Audit pages for WCAG compliance |\n| `file-download` | Download files (PDFs, CSVs) using browser session |\n\nSee [plugin/README.md](plugin/README.md) for detailed tool parameter documentation.\n\n## Codex\n\nOpenBrowser works with OpenAI Codex via native skill discovery.\n\n### Quick Install\n\nTell Codex:\n\n```\nFetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.codex/INSTALL.md\n```\n\n### Manual Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.codex/openbrowser\n\n# Symlink skills for native discovery\nmkdir -p ~/.agents/skills\nln -s ~/.codex/openbrowser/plugin/skills ~/.agents/skills/openbrowser\n\n# Restart Codex\n```\n\nThen configure the MCP server in your project (see [MCP Server](#mcp-server) below).\n\nDetailed docs: [.codex/INSTALL.md](.codex/INSTALL.md)\n\n## OpenCode\n\nOpenBrowser works with [OpenCode.ai](https://opencode.ai) via plugin and skill symlinks.\n\n### Quick Install\n\nTell OpenCode:\n\n```\nFetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.opencode/INSTALL.md\n```\n\n### Manual Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.config/opencode/openbrowser\n\n# Create directories\nmkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills\n\n# Symlink plugin and skills\nln -s ~/.config/opencode/openbrowser/.opencode/plugins/openbrowser.js ~/.config/opencode/plugins/openbrowser.js\nln -s ~/.config/opencode/openbrowser/plugin/skills ~/.config/opencode/skills/openbrowser\n\n# Restart OpenCode\n```\n\nThen configure the MCP server in your project (see [MCP Server](#mcp-server) below).\n\nDetailed docs: [.opencode/INSTALL.md](.opencode/INSTALL.md)\n\n## OpenClaw\n\n[OpenClaw](https://openclaw.ai) supports OpenBrowser via the CLI daemon. Install OpenBrowser,\nthen use `openbrowser-ai -c` from the Bash tool:\n\n```bash\nopenbrowser-ai -c \"await navigate('https://example.com')\"\nopenbrowser-ai -c \"print(await evaluate('document.title'))\"\n```\n\nThe daemon starts automatically on first use and persists variables across calls.\n\nFor OpenClaw plugin documentation, see [docs.openclaw.ai/tools/plugin](https://docs.openclaw.ai/tools/plugin).\n\n## MCP Server\n\n[](https://registry.modelcontextprotocol.io/?q=openbrowser)\n\nOpenBrowser includes an MCP (Model Context Protocol) server that exposes browser automation as tools for AI assistants like Claude. Listed on the [MCP Registry](https://registry.modelcontextprotocol.io/?q=openbrowser) as `me.openbrowser/openbrowser-ai`. No external LLM API keys required -- the MCP client provides the intelligence.\n\nBy default, MCP sessions reuse `~/.config/openbrowser/profiles/default` and save cookies plus origin storage to `~/.config/openbrowser/profiles/default/storage_state.json`, so logins survive MCP restarts. OpenBrowser also auto-cleans disposable Chromium caches in managed profiles, which keeps disk usage down without deleting cookies or login state.\n\n### Quick Setup\n\n**Claude Code**: add to your project's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"openbrowser\": {\n \"command\": \"uvx\",\n \"args\": [\"openbrowser-ai\", \"--mcp\"]\n }\n }\n}\n```\n\n**Claude Desktop**: add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"openbrowser\": {\n \"command\": \"uvx\",\n \"args\": [\"openbrowser-ai\", \"--mcp\"],\n \"env\": {\n \"OPENBROWSER_HEADLESS\": \"true\"\n }\n }\n }\n}\n```\n\n**Run directly:**\n\n```bash\nuvx openbrowser-ai --mcp\n```\n\n### Tool\n\nThe MCP server exposes a single `execute_code` tool that runs Python code in a persistent namespace with browser automation functions. The LLM writes Python code to navigate, interact, and extract data, returning only what was explicitly requested.\n\n**Available functions** (all async, use `await`):\n\n| Category | Functions |\n|----------|-----------|\n| **Navigation** | `navigate(url, new_tab)`, `go_back()`, `wait(seconds)` |\n| **Interaction** | `click(index)`, `input_text(index, text, clear)`, `scroll(down, pages, index)`, `send_keys(keys)`, `upload_file(index, path)` |\n| **Dropdowns** | `select_dropdown(index, text)`, `dropdown_options(index)` |\n| **Tabs** | `switch(tab_id)`, `close(tab_id)` |\n| **JavaScript** | `evaluate(code)`: run JS in page context, returns Python objects |\n| **Downloads** | `download_file(url, filename)`: download a file using browser cookies, `list_downloads()`: list downloaded files |\n| **State** | `browser.get_browser_state_summary()`: get page metadata and interactive elements |\n| **CSS** | `get_selector_from_index(index)`: get CSS selector for an element |\n| **Completion** | `done(text, success)`: signal task completion |\n\n**Pre-imported libraries**: `json`, `csv`, `re`, `datetime`, `asyncio`, `Path`, `requests`, `numpy`, `pandas`, `matplotlib`, `BeautifulSoup`\n\n### Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `OPENBROWSER_HEADLESS` | Run browser without GUI | `true` |\n| `OPENBROWSER_ALLOWED_DOMAINS` | Comma-separated domain whitelist | (none) |\n| `OPENBROWSER_USER_DATA_DIR` | Chrome profile directory for persistent MCP sessions | `~/.config/openbrowser/profiles/default` |\n| `OPENBROWSER_STORAGE_STATE` | JSON file used to save and restore cookies plus localStorage | `~/.config/openbrowser/profiles/default/storage_state.json` |\n| `OPENBROWSER_COMPACT_DESCRIPTION` | Minimal tool description (~500 tokens) | `false` |\n| `OPENBROWSER_MAX_OUTPUT` | Max output characters per execution | `10000` |\n\n## Benchmark: Token Efficiency\n\n### CLI Benchmark: 4-Way Comparison (6 Tasks, N=3 runs)\n\nFour CLI tools compared with a single Bash tool each. Claude Sonnet 4.6 on Bedrock. Randomized order. All achieve 100% accuracy.\n\n\n ![\"CLI](\"benchmarks/cli_benchmark_scatter.png\")
\n
\n ![\"CLI](\"benchmarks/cli_benchmark_overview.png\")
\n
\n ![\"CLI](\"benchmarks/cli_benchmark_per_task.png\")
\n
\n ![\"E2E](\"benchmarks/benchmark_comparison.png\")
\n
\n \n
AI browser automation, powered by code.
\n\n---\n\n**Cloud dashboard for saved cookies and scheduled tasks is available in the hosted version. Join the waitlist for early access: https://openbrowser.me** :\n\nhttps://github.com/user-attachments/assets/b17f97f3-f9f8-4707-8e39-abbbbe1a693b\n\n**Automating Walmart Product Scraping:**\n\nhttps://github.com/user-attachments/assets/c517c739-9199-47b0-bac7-c2c642a21094\n\n**OpenBrowserAI Automatic Flight Booking:**\n\nhttps://github.com/user-attachments/assets/632128f6-3d09-497f-9e7d-e29b9cb65e0f\n\n**OpenBrowserAI Automatic Form Filling:**\n\nhttps://github.com/user-attachments/assets/16f7ef1a-beb1-45e2-a733-9592536e0ef7\n\n\n[](https://pypi.org/project/openbrowser-ai/)\n[](https://pepy.tech/projects/openbrowser-ai)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/billy-enrizky/openbrowser-ai/actions)\n[](https://codecov.io/gh/billy-enrizky/openbrowser-ai)\n\n\n\n**AI-powered browser automation using CodeAgent and CDP (Chrome DevTools Protocol)**\n\nOpenBrowser is a framework for intelligent browser automation. It combines direct CDP communication with a CodeAgent architecture, where the LLM writes Python code executed in a persistent namespace, to navigate, interact with, and extract information from web pages autonomously.\n\n## Table of Contents\n\n- [Documentation](#documentation)\n- [Key Features](#key-features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Supported LLM Providers](#supported-llm-providers)\n- [Claude Code Plugin](#claude-code-plugin)\n- [Codex](#codex)\n- [OpenCode](#opencode)\n- [OpenClaw](#openclaw)\n- [MCP Server](#mcp-server)\n- [Benchmark: Token Efficiency](#benchmark-token-efficiency)\n- [CLI Usage](#cli-usage)\n- [Project Structure](#project-structure)\n- [Backend and Frontend Deployment](#backend-and-frontend-deployment)\n- [Testing](#testing)\n- [Research: Reinforcement Fine-Tuning for Browser Agents](#research-reinforcement-fine-tuning-for-browser-agents)\n- [Contributing](#contributing)\n- [License](#license)\n- [Contact](#contact)\n\n## Documentation\n\n**Full documentation**: [https://docs.openbrowser.me](https://docs.openbrowser.me)\n\n## Key Features\n\n- **CodeAgent Architecture** - LLM writes Python code in a persistent Jupyter-like namespace for browser automation\n- **Raw CDP Communication** - Direct Chrome DevTools Protocol for maximum control and speed\n- **Vision Support** - Screenshot analysis for visual understanding of pages\n- **15 LLM Providers** - OpenAI, Anthropic, Google, Groq, AWS Bedrock, Azure, Ollama, DeepSeek, Cerebras, OpenRouter, OCI, and more\n- **MCP Server** - Model Context Protocol for Claude Desktop, Claude Code, Codex, OpenCode, and other AI assistants, with reusable saved login sessions\n- **CLI Daemon** - Persistent browser daemon with `-c` flag for direct code execution from Bash, saved login state, and 10-minute auto-shutdown\n- **Workflow Recording** - Record, replay, and export browser sessions to Jupyter notebooks or API crawler code\n- **Video Recording** - Record browser sessions as video files with ffmpeg\n- **Cloud Platform** - Full-stack web UI with real-time VNC streaming, saved logins (KMS-encrypted), scheduled workflows (EventBridge + SQS), and email notifications (SES)\n- **Plugin System** - Claude Code plugin with 6 guided skills (web scraping, form filling, e2e testing, page analysis, accessibility audit, file download)\n\n## Installation\n\n### Quick install (macOS / Linux)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh\n```\n\n### Quick install (Windows PowerShell)\n\n```powershell\nirm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex\n```\n\nDetects `uv`, `pipx`, or `pip` and installs OpenBrowser automatically.\n\nInstall to `~/.local/bin` without sudo:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh -s -- --local\n```\n\n### Homebrew (macOS / Linux)\n\n```bash\nbrew tap billy-enrizky/openbrowser\nbrew install openbrowser-ai\n```\n\n### pip\n\n```bash\npip install openbrowser-ai\n```\n\n### uv (recommended)\n\n```bash\nuv pip install openbrowser-ai\n```\n\n### uvx (zero install)\n\nRun directly without installing -- `uvx` downloads and caches the package automatically:\n\n```bash\n# MCP server mode\nuvx openbrowser-ai --mcp\n\n# CLI daemon mode\nuvx openbrowser-ai -c \"await navigate('https://example.com')\"\n```\n\n### pipx\n\n```bash\npipx install openbrowser-ai\n```\n\n### From source\n\n```bash\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git\ncd openbrowser-ai\nuv pip install -e \".[agent]\"\n```\n\n### Optional Dependencies\n\n```bash\npip install openbrowser-ai[agent] # LLM agent support (langgraph, langchain, litellm)\npip install openbrowser-ai[all] # All LLM providers\npip install openbrowser-ai[anthropic] # Anthropic Claude\npip install openbrowser-ai[groq] # Groq\npip install openbrowser-ai[ollama] # Ollama (local models)\npip install openbrowser-ai[aws] # AWS Bedrock\npip install openbrowser-ai[azure] # Azure OpenAI\npip install openbrowser-ai[video] # Video recording support\n```\n\n> **No separate browser install needed.** OpenBrowser auto-detects any installed Chromium-based browser (Chrome, Edge, Brave, Chromium) and uses it directly. If none is found and `uvx` is available, Chromium is installed automatically on first run. To pre-install manually (requires `uvx`): `openbrowser-ai install`\n\n## Quick Start\n\n### Basic Usage\n\n```python\nimport asyncio\nfrom openbrowser import CodeAgent, ChatGoogle\n\nasync def main():\n agent = CodeAgent(\n task=\"Go to google.com and search for 'Python tutorials'\",\n llm=ChatGoogle(model=\"gemini-3-flash\"),\n )\n\n result = await agent.run()\n print(f\"Result: {result}\")\n\nasyncio.run(main())\n```\n\n### With Different LLM Providers\n\n```python\nfrom openbrowser import CodeAgent, ChatOpenAI, ChatAnthropic, ChatGoogle\n\n# OpenAI\nagent = CodeAgent(task=\"...\", llm=ChatOpenAI(model=\"gpt-5.2\"))\n\n# Anthropic\nagent = CodeAgent(task=\"...\", llm=ChatAnthropic(model=\"claude-sonnet-4-6\"))\n\n# Google Gemini\nagent = CodeAgent(task=\"...\", llm=ChatGoogle(model=\"gemini-3-flash\"))\n```\n\n### Using Browser Session Directly\n\n```python\nimport asyncio\nfrom openbrowser import BrowserSession, BrowserProfile\n\nasync def main():\n profile = BrowserProfile(\n headless=True,\n viewport_width=1920,\n viewport_height=1080,\n )\n \n session = BrowserSession(browser_profile=profile)\n await session.start()\n \n await session.navigate_to(\"https://example.com\")\n screenshot = await session.screenshot()\n \n await session.stop()\n\nasyncio.run(main())\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Google (recommended)\nexport GOOGLE_API_KEY=\"...\"\n\n# OpenAI\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Anthropic\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# Groq\nexport GROQ_API_KEY=\"gsk_...\"\n\n# AWS Bedrock\nexport AWS_ACCESS_KEY_ID=\"...\"\nexport AWS_SECRET_ACCESS_KEY=\"...\"\nexport AWS_DEFAULT_REGION=\"us-west-2\"\n\n# Azure OpenAI\nexport AZURE_OPENAI_API_KEY=\"...\"\nexport AZURE_OPENAI_ENDPOINT=\"https://your-resource.openai.azure.com/\"\n```\n\n### BrowserProfile Options\n\n```python\nfrom openbrowser import BrowserProfile\n\nprofile = BrowserProfile(\n headless=True,\n viewport_width=1280,\n viewport_height=720,\n disable_security=False,\n extra_chromium_args=[\"--disable-gpu\"],\n record_video_dir=\"./recordings\",\n proxy={\n \"server\": \"http://proxy.example.com:8080\",\n \"username\": \"user\",\n \"password\": \"pass\",\n },\n)\n```\n\n## Supported LLM Providers\n\n| Provider | Class | Models |\n|----------|-------|--------|\n| **Google** | `ChatGoogle` | gemini-3-flash, gemini-3-pro |\n| **OpenAI** | `ChatOpenAI` | gpt-5.2, o4-mini, o3 |\n| **Anthropic** | `ChatAnthropic` | claude-sonnet-4-6, claude-opus-4-6 |\n| **Groq** | `ChatGroq` | llama-4-scout, qwen3-32b |\n| **AWS Bedrock** | `ChatAWSBedrock` | anthropic.claude-sonnet-4-6, amazon.nova-pro |\n| **AWS Bedrock (Anthropic)** | `ChatAnthropicBedrock` | Claude models via Anthropic Bedrock SDK |\n| **Azure OpenAI** | `ChatAzureOpenAI` | Any Azure-deployed model |\n| **OpenRouter** | `ChatOpenRouter` | Any model on openrouter.ai |\n| **DeepSeek** | `ChatDeepSeek` | deepseek-chat, deepseek-r1 |\n| **Cerebras** | `ChatCerebras` | llama-4-scout, qwen-3-235b |\n| **Ollama** | `ChatOllama` | llama-4-scout, deepseek-r1 (local) |\n| **OCI** | `ChatOCIRaw` | Oracle Cloud GenAI models |\n| **Browser-Use** | `ChatBrowserUse` | External LLM service |\n\n## Claude Code Plugin\n\nInstall OpenBrowser as a Claude Code plugin:\n\n```bash\n# Add the marketplace (one-time)\nclaude plugin marketplace add billy-enrizky/openbrowser-ai\n\n# Install the plugin\nclaude plugin install openbrowser@openbrowser-ai\n```\n\nThis installs the MCP server and 6 built-in skills:\n\n| Skill | Description |\n|-------|-------------|\n| `web-scraping` | Extract structured data, handle pagination |\n| `form-filling` | Fill forms, login flows, multi-step wizards |\n| `e2e-testing` | Test web apps by simulating user interactions |\n| `page-analysis` | Analyze page content, structure, metadata |\n| `accessibility-audit` | Audit pages for WCAG compliance |\n| `file-download` | Download files (PDFs, CSVs) using browser session |\n\nSee [plugin/README.md](plugin/README.md) for detailed tool parameter documentation.\n\n## Codex\n\nOpenBrowser works with OpenAI Codex via native skill discovery.\n\n### Quick Install\n\nTell Codex:\n\n```\nFetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.codex/INSTALL.md\n```\n\n### Manual Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.codex/openbrowser\n\n# Symlink skills for native discovery\nmkdir -p ~/.agents/skills\nln -s ~/.codex/openbrowser/plugin/skills ~/.agents/skills/openbrowser\n\n# Restart Codex\n```\n\nThen configure the MCP server in your project (see [MCP Server](#mcp-server) below).\n\nDetailed docs: [.codex/INSTALL.md](.codex/INSTALL.md)\n\n## OpenCode\n\nOpenBrowser works with [OpenCode.ai](https://opencode.ai) via plugin and skill symlinks.\n\n### Quick Install\n\nTell OpenCode:\n\n```\nFetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.opencode/INSTALL.md\n```\n\n### Manual Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.config/opencode/openbrowser\n\n# Create directories\nmkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills\n\n# Symlink plugin and skills\nln -s ~/.config/opencode/openbrowser/.opencode/plugins/openbrowser.js ~/.config/opencode/plugins/openbrowser.js\nln -s ~/.config/opencode/openbrowser/plugin/skills ~/.config/opencode/skills/openbrowser\n\n# Restart OpenCode\n```\n\nThen configure the MCP server in your project (see [MCP Server](#mcp-server) below).\n\nDetailed docs: [.opencode/INSTALL.md](.opencode/INSTALL.md)\n\n## OpenClaw\n\n[OpenClaw](https://openclaw.ai) supports OpenBrowser via the CLI daemon. Install OpenBrowser,\nthen use `openbrowser-ai -c` from the Bash tool:\n\n```bash\nopenbrowser-ai -c \"await navigate('https://example.com')\"\nopenbrowser-ai -c \"print(await evaluate('document.title'))\"\n```\n\nThe daemon starts automatically on first use and persists variables across calls.\n\nFor OpenClaw plugin documentation, see [docs.openclaw.ai/tools/plugin](https://docs.openclaw.ai/tools/plugin).\n\n## MCP Server\n\n[](https://registry.modelcontextprotocol.io/?q=openbrowser)\n\nOpenBrowser includes an MCP (Model Context Protocol) server that exposes browser automation as tools for AI assistants like Claude. Listed on the [MCP Registry](https://registry.modelcontextprotocol.io/?q=openbrowser) as `me.openbrowser/openbrowser-ai`. No external LLM API keys required -- the MCP client provides the intelligence.\n\nBy default, MCP sessions reuse `~/.config/openbrowser/profiles/default` and save cookies plus origin storage to `~/.config/openbrowser/profiles/default/storage_state.json`, so logins survive MCP restarts. OpenBrowser also auto-cleans disposable Chromium caches in managed profiles, which keeps disk usage down without deleting cookies or login state.\n\n### Quick Setup\n\n**Claude Code**: add to your project's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"openbrowser\": {\n \"command\": \"uvx\",\n \"args\": [\"openbrowser-ai\", \"--mcp\"]\n }\n }\n}\n```\n\n**Claude Desktop**: add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"openbrowser\": {\n \"command\": \"uvx\",\n \"args\": [\"openbrowser-ai\", \"--mcp\"],\n \"env\": {\n \"OPENBROWSER_HEADLESS\": \"true\"\n }\n }\n }\n}\n```\n\n**Run directly:**\n\n```bash\nuvx openbrowser-ai --mcp\n```\n\n### Tool\n\nThe MCP server exposes a single `execute_code` tool that runs Python code in a persistent namespace with browser automation functions. The LLM writes Python code to navigate, interact, and extract data, returning only what was explicitly requested.\n\n**Available functions** (all async, use `await`):\n\n| Category | Functions |\n|----------|-----------|\n| **Navigation** | `navigate(url, new_tab)`, `go_back()`, `wait(seconds)` |\n| **Interaction** | `click(index)`, `input_text(index, text, clear)`, `scroll(down, pages, index)`, `send_keys(keys)`, `upload_file(index, path)` |\n| **Dropdowns** | `select_dropdown(index, text)`, `dropdown_options(index)` |\n| **Tabs** | `switch(tab_id)`, `close(tab_id)` |\n| **JavaScript** | `evaluate(code)`: run JS in page context, returns Python objects |\n| **Downloads** | `download_file(url, filename)`: download a file using browser cookies, `list_downloads()`: list downloaded files |\n| **State** | `browser.get_browser_state_summary()`: get page metadata and interactive elements |\n| **CSS** | `get_selector_from_index(index)`: get CSS selector for an element |\n| **Completion** | `done(text, success)`: signal task completion |\n\n**Pre-imported libraries**: `json`, `csv`, `re`, `datetime`, `asyncio`, `Path`, `requests`, `numpy`, `pandas`, `matplotlib`, `BeautifulSoup`\n\n### Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `OPENBROWSER_HEADLESS` | Run browser without GUI | `true` |\n| `OPENBROWSER_ALLOWED_DOMAINS` | Comma-separated domain whitelist | (none) |\n| `OPENBROWSER_USER_DATA_DIR` | Chrome profile directory for persistent MCP sessions | `~/.config/openbrowser/profiles/default` |\n| `OPENBROWSER_STORAGE_STATE` | JSON file used to save and restore cookies plus localStorage | `~/.config/openbrowser/profiles/default/storage_state.json` |\n| `OPENBROWSER_COMPACT_DESCRIPTION` | Minimal tool description (~500 tokens) | `false` |\n| `OPENBROWSER_MAX_OUTPUT` | Max output characters per execution | `10000` |\n\n## Benchmark: Token Efficiency\n\n### CLI Benchmark: 4-Way Comparison (6 Tasks, N=3 runs)\n\nFour CLI tools compared with a single Bash tool each. Claude Sonnet 4.6 on Bedrock. Randomized order. All achieve 100% accuracy.\n\n\n \n
\n \n
\n \n
\n \n
\n \n
AI browser automation, powered by code.
\n\n---\n\n**Saved Cookies and Scheduled Tasks is available in the cloud-hosted version. Join the waitlist for early access: https://openbrowser.me** :\n\nhttps://github.com/user-attachments/assets/b17f97f3-f9f8-4707-8e39-abbbbe1a693b\n\n**Automating Walmart Product Scraping:**\n\nhttps://github.com/user-attachments/assets/c517c739-9199-47b0-bac7-c2c642a21094\n\n**OpenBrowserAI Automatic Flight Booking:**\n\nhttps://github.com/user-attachments/assets/632128f6-3d09-497f-9e7d-e29b9cb65e0f\n\n**OpenBrowserAI Automatic Form Filling:**\n\nhttps://github.com/user-attachments/assets/16f7ef1a-beb1-45e2-a733-9592536e0ef7\n\n\n[](https://pypi.org/project/openbrowser-ai/)\n[](https://pepy.tech/projects/openbrowser-ai)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/billy-enrizky/openbrowser-ai/actions)\n[](https://codecov.io/gh/billy-enrizky/openbrowser-ai)\n\n\n\n**AI-powered browser automation using CodeAgent and CDP (Chrome DevTools Protocol)**\n\nOpenBrowser is a framework for intelligent browser automation. It combines direct CDP communication with a CodeAgent architecture, where the LLM writes Python code executed in a persistent namespace, to navigate, interact with, and extract information from web pages autonomously.\n\n## Table of Contents\n\n- [Documentation](#documentation)\n- [Key Features](#key-features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Supported LLM Providers](#supported-llm-providers)\n- [Claude Code Plugin](#claude-code-plugin)\n- [Codex](#codex)\n- [OpenCode](#opencode)\n- [OpenClaw](#openclaw)\n- [MCP Server](#mcp-server)\n- [Benchmark: Token Efficiency](#benchmark-token-efficiency)\n- [CLI Usage](#cli-usage)\n- [Project Structure](#project-structure)\n- [Backend and Frontend Deployment](#backend-and-frontend-deployment)\n- [Testing](#testing)\n- [Research: Reinforcement Fine-Tuning for Browser Agents](#research-reinforcement-fine-tuning-for-browser-agents)\n- [Contributing](#contributing)\n- [License](#license)\n- [Contact](#contact)\n\n## Documentation\n\n**Full documentation**: [https://docs.openbrowser.me](https://docs.openbrowser.me)\n\n## Key Features\n\n- **CodeAgent Architecture** - LLM writes Python code in a persistent Jupyter-like namespace for browser automation\n- **Raw CDP Communication** - Direct Chrome DevTools Protocol for maximum control and speed\n- **Vision Support** - Screenshot analysis for visual understanding of pages\n- **12+ LLM Providers** - OpenAI, Anthropic, Google, Groq, AWS Bedrock, Azure OpenAI, Ollama, and more\n- **MCP Server** - Model Context Protocol support for Claude Desktop integration\n- **CLI Daemon** - Persistent browser daemon with `-c` flag for direct code execution from Bash\n- **Video Recording** - Record browser sessions as video files\n\n## Installation\n\n### Quick install (macOS / Linux)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh\n```\n\n### Quick install (Windows PowerShell)\n\n```powershell\nirm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex\n```\n\nDetects `uv`, `pipx`, or `pip` and installs OpenBrowser automatically.\n\nInstall to `~/.local/bin` without sudo:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh -s -- --local\n```\n\n### Homebrew (macOS / Linux)\n\n```bash\nbrew tap billy-enrizky/openbrowser\nbrew install openbrowser-ai\n```\n\n### pip\n\n```bash\npip install openbrowser-ai\n```\n\n### uv (recommended)\n\n```bash\nuv pip install openbrowser-ai\n```\n\n### uvx (zero install)\n\nRun directly without installing -- `uvx` downloads and caches the package automatically:\n\n```bash\n# MCP server mode\nuvx openbrowser-ai --mcp\n\n# CLI daemon mode\nuvx openbrowser-ai -c \"await navigate('https://example.com')\"\n```\n\n### pipx\n\n```bash\npipx install openbrowser-ai\n```\n\n### From source\n\n```bash\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git\ncd openbrowser-ai\nuv pip install -e \".[agent]\"\n```\n\n### Optional Dependencies\n\n```bash\npip install openbrowser-ai[agent] # LLM agent support (langgraph, langchain, litellm)\npip install openbrowser-ai[all] # All LLM providers\npip install openbrowser-ai[anthropic] # Anthropic Claude\npip install openbrowser-ai[groq] # Groq\npip install openbrowser-ai[ollama] # Ollama (local models)\npip install openbrowser-ai[aws] # AWS Bedrock\npip install openbrowser-ai[azure] # Azure OpenAI\npip install openbrowser-ai[video] # Video recording support\n```\n\n> **No separate browser install needed.** OpenBrowser auto-detects any installed Chromium-based browser (Chrome, Edge, Brave, Chromium) and uses it directly. If none is found and `uvx` is available, Chromium is installed automatically on first run. To pre-install manually (requires `uvx`): `openbrowser-ai install`\n\n## Quick Start\n\n### Basic Usage\n\n```python\nimport asyncio\nfrom openbrowser import CodeAgent, ChatGoogle\n\nasync def main():\n agent = CodeAgent(\n task=\"Go to google.com and search for 'Python tutorials'\",\n llm=ChatGoogle(model=\"gemini-3-flash\"),\n )\n\n result = await agent.run()\n print(f\"Result: {result}\")\n\nasyncio.run(main())\n```\n\n### With Different LLM Providers\n\n```python\nfrom openbrowser import CodeAgent, ChatOpenAI, ChatAnthropic, ChatGoogle\n\n# OpenAI\nagent = CodeAgent(task=\"...\", llm=ChatOpenAI(model=\"gpt-5.2\"))\n\n# Anthropic\nagent = CodeAgent(task=\"...\", llm=ChatAnthropic(model=\"claude-sonnet-4-6\"))\n\n# Google Gemini\nagent = CodeAgent(task=\"...\", llm=ChatGoogle(model=\"gemini-3-flash\"))\n```\n\n### Using Browser Session Directly\n\n```python\nimport asyncio\nfrom openbrowser import BrowserSession, BrowserProfile\n\nasync def main():\n profile = BrowserProfile(\n headless=True,\n viewport_width=1920,\n viewport_height=1080,\n )\n \n session = BrowserSession(browser_profile=profile)\n await session.start()\n \n await session.navigate_to(\"https://example.com\")\n screenshot = await session.screenshot()\n \n await session.stop()\n\nasyncio.run(main())\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Google (recommended)\nexport GOOGLE_API_KEY=\"...\"\n\n# OpenAI\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Anthropic\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# Groq\nexport GROQ_API_KEY=\"gsk_...\"\n\n# AWS Bedrock\nexport AWS_ACCESS_KEY_ID=\"...\"\nexport AWS_SECRET_ACCESS_KEY=\"...\"\nexport AWS_DEFAULT_REGION=\"us-west-2\"\n\n# Azure OpenAI\nexport AZURE_OPENAI_API_KEY=\"...\"\nexport AZURE_OPENAI_ENDPOINT=\"https://your-resource.openai.azure.com/\"\n```\n\n### BrowserProfile Options\n\n```python\nfrom openbrowser import BrowserProfile\n\nprofile = BrowserProfile(\n headless=True,\n viewport_width=1280,\n viewport_height=720,\n disable_security=False,\n extra_chromium_args=[\"--disable-gpu\"],\n record_video_dir=\"./recordings\",\n proxy={\n \"server\": \"http://proxy.example.com:8080\",\n \"username\": \"user\",\n \"password\": \"pass\",\n },\n)\n```\n\n## Supported LLM Providers\n\n| Provider | Class | Models |\n|----------|-------|--------|\n| **Google** | `ChatGoogle` | gemini-3-flash, gemini-3-pro |\n| **OpenAI** | `ChatOpenAI` | gpt-5.2, o4-mini, o3 |\n| **Anthropic** | `ChatAnthropic` | claude-sonnet-4-6, claude-opus-4-6 |\n| **Groq** | `ChatGroq` | llama-4-scout, qwen3-32b |\n| **AWS Bedrock** | `ChatAWSBedrock` | anthropic.claude-sonnet-4-6, amazon.nova-pro |\n| **AWS Bedrock (Anthropic)** | `ChatAnthropicBedrock` | Claude models via Anthropic Bedrock SDK |\n| **Azure OpenAI** | `ChatAzureOpenAI` | Any Azure-deployed model |\n| **OpenRouter** | `ChatOpenRouter` | Any model on openrouter.ai |\n| **DeepSeek** | `ChatDeepSeek` | deepseek-chat, deepseek-r1 |\n| **Cerebras** | `ChatCerebras` | llama-4-scout, qwen-3-235b |\n| **Ollama** | `ChatOllama` | llama-4-scout, deepseek-r1 (local) |\n| **OCI** | `ChatOCIRaw` | Oracle Cloud GenAI models |\n| **Browser-Use** | `ChatBrowserUse` | External LLM service |\n\n## Claude Code Plugin\n\nInstall OpenBrowser as a Claude Code plugin:\n\n```bash\n# Add the marketplace (one-time)\nclaude plugin marketplace add billy-enrizky/openbrowser-ai\n\n# Install the plugin\nclaude plugin install openbrowser@openbrowser-ai\n```\n\nThis installs the MCP server and 6 built-in skills:\n\n| Skill | Description |\n|-------|-------------|\n| `web-scraping` | Extract structured data, handle pagination |\n| `form-filling` | Fill forms, login flows, multi-step wizards |\n| `e2e-testing` | Test web apps by simulating user interactions |\n| `page-analysis` | Analyze page content, structure, metadata |\n| `accessibility-audit` | Audit pages for WCAG compliance |\n| `file-download` | Download files (PDFs, CSVs) using browser session |\n\nSee [plugin/README.md](plugin/README.md) for detailed tool parameter documentation.\n\n## Codex\n\nOpenBrowser works with OpenAI Codex via native skill discovery.\n\n### Quick Install\n\nTell Codex:\n\n```\nFetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.codex/INSTALL.md\n```\n\n### Manual Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.codex/openbrowser\n\n# Symlink skills for native discovery\nmkdir -p ~/.agents/skills\nln -s ~/.codex/openbrowser/plugin/skills ~/.agents/skills/openbrowser\n\n# Restart Codex\n```\n\nThen configure the MCP server in your project (see [MCP Server](#mcp-server) below).\n\nDetailed docs: [.codex/INSTALL.md](.codex/INSTALL.md)\n\n## OpenCode\n\nOpenBrowser works with [OpenCode.ai](https://opencode.ai) via plugin and skill symlinks.\n\n### Quick Install\n\nTell OpenCode:\n\n```\nFetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.opencode/INSTALL.md\n```\n\n### Manual Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.config/opencode/openbrowser\n\n# Create directories\nmkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills\n\n# Symlink plugin and skills\nln -s ~/.config/opencode/openbrowser/.opencode/plugins/openbrowser.js ~/.config/opencode/plugins/openbrowser.js\nln -s ~/.config/opencode/openbrowser/plugin/skills ~/.config/opencode/skills/openbrowser\n\n# Restart OpenCode\n```\n\nThen configure the MCP server in your project (see [MCP Server](#mcp-server) below).\n\nDetailed docs: [.opencode/INSTALL.md](.opencode/INSTALL.md)\n\n## OpenClaw\n\n[OpenClaw](https://openclaw.ai) supports OpenBrowser via the CLI daemon. Install OpenBrowser,\nthen use `openbrowser-ai -c` from the Bash tool:\n\n```bash\nopenbrowser-ai -c \"await navigate('https://example.com')\"\nopenbrowser-ai -c \"print(await evaluate('document.title'))\"\n```\n\nThe daemon starts automatically on first use and persists variables across calls.\n\nFor OpenClaw plugin documentation, see [docs.openclaw.ai/tools/plugin](https://docs.openclaw.ai/tools/plugin).\n\n## MCP Server\n\n[](https://registry.modelcontextprotocol.io/?q=openbrowser)\n\nOpenBrowser includes an MCP (Model Context Protocol) server that exposes browser automation as tools for AI assistants like Claude. Listed on the [MCP Registry](https://registry.modelcontextprotocol.io/?q=openbrowser) as `me.openbrowser/openbrowser-ai`. No external LLM API keys required -- the MCP client provides the intelligence.\n\n### Quick Setup\n\n**Claude Code**: add to your project's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"openbrowser\": {\n \"command\": \"uvx\",\n \"args\": [\"openbrowser-ai\", \"--mcp\"]\n }\n }\n}\n```\n\n**Claude Desktop**: add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"openbrowser\": {\n \"command\": \"uvx\",\n \"args\": [\"openbrowser-ai\", \"--mcp\"],\n \"env\": {\n \"OPENBROWSER_HEADLESS\": \"true\"\n }\n }\n }\n}\n```\n\n**Run directly:**\n\n```bash\nuvx openbrowser-ai --mcp\n```\n\n### Tool\n\nThe MCP server exposes a single `execute_code` tool that runs Python code in a persistent namespace with browser automation functions. The LLM writes Python code to navigate, interact, and extract data, returning only what was explicitly requested.\n\n**Available functions** (all async, use `await`):\n\n| Category | Functions |\n|----------|-----------|\n| **Navigation** | `navigate(url, new_tab)`, `go_back()`, `wait(seconds)` |\n| **Interaction** | `click(index)`, `input_text(index, text, clear)`, `scroll(down, pages, index)`, `send_keys(keys)`, `upload_file(index, path)` |\n| **Dropdowns** | `select_dropdown(index, text)`, `dropdown_options(index)` |\n| **Tabs** | `switch(tab_id)`, `close(tab_id)` |\n| **JavaScript** | `evaluate(code)`: run JS in page context, returns Python objects |\n| **Downloads** | `download_file(url, filename)`: download a file using browser cookies, `list_downloads()`: list downloaded files |\n| **State** | `browser.get_browser_state_summary()`: get page metadata and interactive elements |\n| **CSS** | `get_selector_from_index(index)`: get CSS selector for an element |\n| **Completion** | `done(text, success)`: signal task completion |\n\n**Pre-imported libraries**: `json`, `csv`, `re`, `datetime`, `asyncio`, `Path`, `requests`, `numpy`, `pandas`, `matplotlib`, `BeautifulSoup`\n\n### Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `OPENBROWSER_HEADLESS` | Run browser without GUI | `false` |\n| `OPENBROWSER_ALLOWED_DOMAINS` | Comma-separated domain whitelist | (none) |\n| `OPENBROWSER_COMPACT_DESCRIPTION` | Minimal tool description (~500 tokens) | `false` |\n| `OPENBROWSER_MAX_OUTPUT` | Max output characters per execution | `10000` |\n\n## Benchmark: Token Efficiency\n\n### CLI Benchmark: 4-Way Comparison (6 Tasks, N=3 runs)\n\nFour CLI tools compared with a single Bash tool each. Claude Sonnet 4.6 on Bedrock. Randomized order. All achieve 100% accuracy.\n\n\n \n
\n \n
\n \n
\n \n
\n \n
AI browser automation, powered by code.
\n\n**Saved Cookies and Scheduled Tasks is available in the cloud-hosted version. Join the waitlist for early access: https://openbrowser.me** :\n\nhttps://github.com/user-attachments/assets/b17f97f3-f9f8-4707-8e39-abbbbe1a693b\n\n**Automating Walmart Product Scraping:**\n\nhttps://github.com/user-attachments/assets/c517c739-9199-47b0-bac7-c2c642a21094\n\n**OpenBrowserAI Automatic Flight Booking:**\n\nhttps://github.com/user-attachments/assets/632128f6-3d09-497f-9e7d-e29b9cb65e0f\n\n**OpenBrowserAI Automatic Form Filling:**\n\nhttps://github.com/user-attachments/assets/16f7ef1a-beb1-45e2-a733-9592536e0ef7\n\n\n[](https://pypi.org/project/openbrowser-ai/)\n[](https://pepy.tech/projects/openbrowser-ai)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/billy-enrizky/openbrowser-ai/actions)\n[](https://codecov.io/gh/billy-enrizky/openbrowser-ai)\n\n\n\n**AI-powered browser automation using CodeAgent and CDP (Chrome DevTools Protocol)**\n\nOpenBrowser is a framework for intelligent browser automation. It combines direct CDP communication with a CodeAgent architecture, where the LLM writes Python code executed in a persistent namespace, to navigate, interact with, and extract information from web pages autonomously.\n\n## Table of Contents\n\n- [Documentation](#documentation)\n- [Key Features](#key-features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Supported LLM Providers](#supported-llm-providers)\n- [Claude Code Plugin](#claude-code-plugin)\n- [Codex](#codex)\n- [OpenCode](#opencode)\n- [OpenClaw](#openclaw)\n- [MCP Server](#mcp-server)\n- [Benchmark: Token Efficiency](#benchmark-token-efficiency)\n- [CLI Usage](#cli-usage)\n- [Project Structure](#project-structure)\n- [Backend and Frontend Deployment](#backend-and-frontend-deployment)\n- [Testing](#testing)\n- [Research: Reinforcement Fine-Tuning for Browser Agents](#research-reinforcement-fine-tuning-for-browser-agents)\n- [Contributing](#contributing)\n- [License](#license)\n- [Contact](#contact)\n\n## Documentation\n\n**Full documentation**: [https://docs.openbrowser.me](https://docs.openbrowser.me)\n\n## Key Features\n\n- **CodeAgent Architecture** - LLM writes Python code in a persistent Jupyter-like namespace for browser automation\n- **Raw CDP Communication** - Direct Chrome DevTools Protocol for maximum control and speed\n- **Vision Support** - Screenshot analysis for visual understanding of pages\n- **12+ LLM Providers** - OpenAI, Anthropic, Google, Groq, AWS Bedrock, Azure OpenAI, Ollama, and more\n- **MCP Server** - Model Context Protocol support for Claude Desktop integration\n- **CLI Daemon** - Persistent browser daemon with `-c` flag for direct code execution from Bash\n- **Video Recording** - Record browser sessions as video files\n\n## Installation\n\n### Quick install (macOS / Linux)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh\n```\n\n### Quick install (Windows PowerShell)\n\n```powershell\nirm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex\n```\n\nDetects `uv`, `pipx`, or `pip` and installs OpenBrowser automatically.\n\nInstall to `~/.local/bin` without sudo:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh -s -- --local\n```\n\n### Homebrew (macOS / Linux)\n\n```bash\nbrew tap billy-enrizky/openbrowser\nbrew install openbrowser-ai\n```\n\n### pip\n\n```bash\npip install openbrowser-ai\n```\n\n### uv (recommended)\n\n```bash\nuv pip install openbrowser-ai\n```\n\n### uvx (zero install)\n\nRun directly without installing -- `uvx` downloads and caches the package automatically:\n\n```bash\n# MCP server mode\nuvx openbrowser-ai --mcp\n\n# CLI daemon mode\nuvx openbrowser-ai -c \"await navigate('https://example.com')\"\n```\n\n### pipx\n\n```bash\npipx install openbrowser-ai\n```\n\n### From source\n\n```bash\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git\ncd openbrowser-ai\nuv pip install -e \".[agent]\"\n```\n\n### Optional Dependencies\n\n```bash\npip install openbrowser-ai[agent] # LLM agent support (langgraph, langchain, litellm)\npip install openbrowser-ai[all] # All LLM providers\npip install openbrowser-ai[anthropic] # Anthropic Claude\npip install openbrowser-ai[groq] # Groq\npip install openbrowser-ai[ollama] # Ollama (local models)\npip install openbrowser-ai[aws] # AWS Bedrock\npip install openbrowser-ai[azure] # Azure OpenAI\npip install openbrowser-ai[video] # Video recording support\n```\n\n> **No separate browser install needed.** OpenBrowser auto-detects any installed Chromium-based browser (Chrome, Edge, Brave, Chromium) and uses it directly. If none is found and `uvx` is available, Chromium is installed automatically on first run. To pre-install manually (requires `uvx`): `openbrowser-ai install`\n\n## Quick Start\n\n### Basic Usage\n\n```python\nimport asyncio\nfrom openbrowser import CodeAgent, ChatGoogle\n\nasync def main():\n agent = CodeAgent(\n task=\"Go to google.com and search for 'Python tutorials'\",\n llm=ChatGoogle(model=\"gemini-3-flash\"),\n )\n\n result = await agent.run()\n print(f\"Result: {result}\")\n\nasyncio.run(main())\n```\n\n### With Different LLM Providers\n\n```python\nfrom openbrowser import CodeAgent, ChatOpenAI, ChatAnthropic, ChatGoogle\n\n# OpenAI\nagent = CodeAgent(task=\"...\", llm=ChatOpenAI(model=\"gpt-5.2\"))\n\n# Anthropic\nagent = CodeAgent(task=\"...\", llm=ChatAnthropic(model=\"claude-sonnet-4-6\"))\n\n# Google Gemini\nagent = CodeAgent(task=\"...\", llm=ChatGoogle(model=\"gemini-3-flash\"))\n```\n\n### Using Browser Session Directly\n\n```python\nimport asyncio\nfrom openbrowser import BrowserSession, BrowserProfile\n\nasync def main():\n profile = BrowserProfile(\n headless=True,\n viewport_width=1920,\n viewport_height=1080,\n )\n \n session = BrowserSession(browser_profile=profile)\n await session.start()\n \n await session.navigate_to(\"https://example.com\")\n screenshot = await session.screenshot()\n \n await session.stop()\n\nasyncio.run(main())\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Google (recommended)\nexport GOOGLE_API_KEY=\"...\"\n\n# OpenAI\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Anthropic\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# Groq\nexport GROQ_API_KEY=\"gsk_...\"\n\n# AWS Bedrock\nexport AWS_ACCESS_KEY_ID=\"...\"\nexport AWS_SECRET_ACCESS_KEY=\"...\"\nexport AWS_DEFAULT_REGION=\"us-west-2\"\n\n# Azure OpenAI\nexport AZURE_OPENAI_API_KEY=\"...\"\nexport AZURE_OPENAI_ENDPOINT=\"https://your-resource.openai.azure.com/\"\n```\n\n### BrowserProfile Options\n\n```python\nfrom openbrowser import BrowserProfile\n\nprofile = BrowserProfile(\n headless=True,\n viewport_width=1280,\n viewport_height=720,\n disable_security=False,\n extra_chromium_args=[\"--disable-gpu\"],\n record_video_dir=\"./recordings\",\n proxy={\n \"server\": \"http://proxy.example.com:8080\",\n \"username\": \"user\",\n \"password\": \"pass\",\n },\n)\n```\n\n## Supported LLM Providers\n\n| Provider | Class | Models |\n|----------|-------|--------|\n| **Google** | `ChatGoogle` | gemini-3-flash, gemini-3-pro |\n| **OpenAI** | `ChatOpenAI` | gpt-5.2, o4-mini, o3 |\n| **Anthropic** | `ChatAnthropic` | claude-sonnet-4-6, claude-opus-4-6 |\n| **Groq** | `ChatGroq` | llama-4-scout, qwen3-32b |\n| **AWS Bedrock** | `ChatAWSBedrock` | anthropic.claude-sonnet-4-6, amazon.nova-pro |\n| **AWS Bedrock (Anthropic)** | `ChatAnthropicBedrock` | Claude models via Anthropic Bedrock SDK |\n| **Azure OpenAI** | `ChatAzureOpenAI` | Any Azure-deployed model |\n| **OpenRouter** | `ChatOpenRouter` | Any model on openrouter.ai |\n| **DeepSeek** | `ChatDeepSeek` | deepseek-chat, deepseek-r1 |\n| **Cerebras** | `ChatCerebras` | llama-4-scout, qwen-3-235b |\n| **Ollama** | `ChatOllama` | llama-4-scout, deepseek-r1 (local) |\n| **OCI** | `ChatOCIRaw` | Oracle Cloud GenAI models |\n| **Browser-Use** | `ChatBrowserUse` | External LLM service |\n\n## Claude Code Plugin\n\nInstall OpenBrowser as a Claude Code plugin:\n\n```bash\n# Add the marketplace (one-time)\nclaude plugin marketplace add billy-enrizky/openbrowser-ai\n\n# Install the plugin\nclaude plugin install openbrowser@openbrowser-ai\n```\n\nThis installs the MCP server and 6 built-in skills:\n\n| Skill | Description |\n|-------|-------------|\n| `web-scraping` | Extract structured data, handle pagination |\n| `form-filling` | Fill forms, login flows, multi-step wizards |\n| `e2e-testing` | Test web apps by simulating user interactions |\n| `page-analysis` | Analyze page content, structure, metadata |\n| `accessibility-audit` | Audit pages for WCAG compliance |\n| `file-download` | Download files (PDFs, CSVs) using browser session |\n\nSee [plugin/README.md](plugin/README.md) for detailed tool parameter documentation.\n\n## Codex\n\nOpenBrowser works with OpenAI Codex via native skill discovery.\n\n### Quick Install\n\nTell Codex:\n\n```\nFetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.codex/INSTALL.md\n```\n\n### Manual Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.codex/openbrowser\n\n# Symlink skills for native discovery\nmkdir -p ~/.agents/skills\nln -s ~/.codex/openbrowser/plugin/skills ~/.agents/skills/openbrowser\n\n# Restart Codex\n```\n\nThen configure the MCP server in your project (see [MCP Server](#mcp-server) below).\n\nDetailed docs: [.codex/INSTALL.md](.codex/INSTALL.md)\n\n## OpenCode\n\nOpenBrowser works with [OpenCode.ai](https://opencode.ai) via plugin and skill symlinks.\n\n### Quick Install\n\nTell OpenCode:\n\n```\nFetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.opencode/INSTALL.md\n```\n\n### Manual Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.config/opencode/openbrowser\n\n# Create directories\nmkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills\n\n# Symlink plugin and skills\nln -s ~/.config/opencode/openbrowser/.opencode/plugins/openbrowser.js ~/.config/opencode/plugins/openbrowser.js\nln -s ~/.config/opencode/openbrowser/plugin/skills ~/.config/opencode/skills/openbrowser\n\n# Restart OpenCode\n```\n\nThen configure the MCP server in your project (see [MCP Server](#mcp-server) below).\n\nDetailed docs: [.opencode/INSTALL.md](.opencode/INSTALL.md)\n\n## OpenClaw\n\n[OpenClaw](https://openclaw.ai) supports OpenBrowser via the CLI daemon. Install OpenBrowser,\nthen use `openbrowser-ai -c` from the Bash tool:\n\n```bash\nopenbrowser-ai -c \"await navigate('https://example.com')\"\nopenbrowser-ai -c \"print(await evaluate('document.title'))\"\n```\n\nThe daemon starts automatically on first use and persists variables across calls.\n\nFor OpenClaw plugin documentation, see [docs.openclaw.ai/tools/plugin](https://docs.openclaw.ai/tools/plugin).\n\n## MCP Server\n\n[](https://registry.modelcontextprotocol.io/?q=openbrowser)\n\nOpenBrowser includes an MCP (Model Context Protocol) server that exposes browser automation as tools for AI assistants like Claude. Listed on the [MCP Registry](https://registry.modelcontextprotocol.io/?q=openbrowser) as `me.openbrowser/openbrowser-ai`. No external LLM API keys required -- the MCP client provides the intelligence.\n\n### Quick Setup\n\n**Claude Code**: add to your project's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"openbrowser\": {\n \"command\": \"uvx\",\n \"args\": [\"openbrowser-ai\", \"--mcp\"]\n }\n }\n}\n```\n\n**Claude Desktop**: add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"openbrowser\": {\n \"command\": \"uvx\",\n \"args\": [\"openbrowser-ai\", \"--mcp\"],\n \"env\": {\n \"OPENBROWSER_HEADLESS\": \"true\"\n }\n }\n }\n}\n```\n\n**Run directly:**\n\n```bash\nuvx openbrowser-ai --mcp\n```\n\n### Tool\n\nThe MCP server exposes a single `execute_code` tool that runs Python code in a persistent namespace with browser automation functions. The LLM writes Python code to navigate, interact, and extract data, returning only what was explicitly requested.\n\n**Available functions** (all async, use `await`):\n\n| Category | Functions |\n|----------|-----------|\n| **Navigation** | `navigate(url, new_tab)`, `go_back()`, `wait(seconds)` |\n| **Interaction** | `click(index)`, `input_text(index, text, clear)`, `scroll(down, pages, index)`, `send_keys(keys)`, `upload_file(index, path)` |\n| **Dropdowns** | `select_dropdown(index, text)`, `dropdown_options(index)` |\n| **Tabs** | `switch(tab_id)`, `close(tab_id)` |\n| **JavaScript** | `evaluate(code)`: run JS in page context, returns Python objects |\n| **Downloads** | `download_file(url, filename)`: download a file using browser cookies, `list_downloads()`: list downloaded files |\n| **State** | `browser.get_browser_state_summary()`: get page metadata and interactive elements |\n| **CSS** | `get_selector_from_index(index)`: get CSS selector for an element |\n| **Completion** | `done(text, success)`: signal task completion |\n\n**Pre-imported libraries**: `json`, `csv`, `re`, `datetime`, `asyncio`, `Path`, `requests`, `numpy`, `pandas`, `matplotlib`, `BeautifulSoup`\n\n### Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `OPENBROWSER_HEADLESS` | Run browser without GUI | `false` |\n| `OPENBROWSER_ALLOWED_DOMAINS` | Comma-separated domain whitelist | (none) |\n| `OPENBROWSER_COMPACT_DESCRIPTION` | Minimal tool description (~500 tokens) | `false` |\n| `OPENBROWSER_MAX_OUTPUT` | Max output characters per execution | `10000` |\n\n## Benchmark: Token Efficiency\n\n### CLI Benchmark: 4-Way Comparison (6 Tasks, N=3 runs)\n\nFour CLI tools compared with a single Bash tool each. Claude Sonnet 4.6 on Bedrock. Randomized order. All achieve 100% accuracy.\n\n\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n
\n \n