diff --git a/README.md b/README.md index b661b3141..7a1396713 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ [![Slack](https://img.shields.io/badge/Slack-Join%20us-4A154B?logo=slack&logoColor=white)](https://dub.sh/browserOS-slack) [![Twitter](https://img.shields.io/twitter/follow/browserOS_ai?style=social)](https://twitter.com/browseros_ai) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE) +[![Docs](https://img.shields.io/badge/Docs-docs.browseros.com-blue)](https://docs.browseros.com)

Download for macOS (beta) @@ -22,38 +23,72 @@
-## -🌐 BrowserOS is an open-source Chromium fork that runs AI agents natively. **The privacy-first alternative to ChatGPT Atlas, Perplexity Comet, and Dia.** +BrowserOS is an open-source Chromium fork that runs AI agents natively. **The privacy-first alternative to ChatGPT Atlas, Perplexity Comet, and Dia.** -πŸ”’ Use your own API keys or run local models with Ollama. Your data never leaves your machine. +Use your own API keys or run local models with Ollama. Your data never leaves your machine. -πŸ’‘ Join our [Discord](https://discord.gg/YKwjt5vuKr) or [Slack](https://dub.sh/browserOS-slack) and help us build! Have feature requests? [Suggest here](https://github.com/browseros-ai/BrowserOS/issues/99). +> **[Documentation](https://docs.browseros.com)** Β· **[Discord](https://discord.gg/YKwjt5vuKr)** Β· **[Slack](https://dub.sh/browserOS-slack)** Β· **[Twitter](https://x.com/browserOS_ai)** Β· **[Feature Requests](https://github.com/browseros-ai/BrowserOS/issues/99)** -## Quick start +## Quick Start -1. Download and install BrowserOS: - - [macOS](https://files.browseros.com/download/BrowserOS.dmg) - - [Windows](https://files.browseros.com/download/BrowserOS_installer.exe) - - [Linux (AppImage)](https://files.browseros.com/download/BrowserOS.AppImage) - - [Linux (Debian)](https://cdn.browseros.com/download/BrowserOS.deb) +1. **Download and install** BrowserOS β€” [macOS](https://files.browseros.com/download/BrowserOS.dmg) Β· [Windows](https://files.browseros.com/download/BrowserOS_installer.exe) Β· [Linux (AppImage)](https://files.browseros.com/download/BrowserOS.AppImage) Β· [Linux (Debian)](https://cdn.browseros.com/download/BrowserOS.deb) +2. **Import your Chrome data** (optional) β€” bookmarks, passwords, extensions all carry over +3. **Connect your AI provider** β€” Claude, OpenAI, Gemini, ChatGPT Pro via OAuth, or local models via Ollama/LM Studio -2. Import your Chrome data (optional) +## Features -3. Connect your AI provider β€” use Claude, OpenAI, Gemini, or local models via Ollama and LMStudio. +| Feature | Description | Docs | +|---------|-------------|------| +| **AI Agent** | 53+ browser automation tools β€” navigate, click, type, extract data, all with natural language | [Guide](https://docs.browseros.com/getting-started) | +| **MCP Server** | Control the browser from Claude Code, Gemini CLI, or any MCP client | [Setup](https://docs.browseros.com/features/use-with-claude-code) | +| **Workflows** | Build repeatable browser automations with a visual graph builder | [Docs](https://docs.browseros.com/features/workflows) | +| **Cowork** | Combine browser automation with local file operations β€” research the web, save reports to your folder | [Docs](https://docs.browseros.com/features/cowork) | +| **Scheduled Tasks** | Run agents on autopilot β€” daily, hourly, or every few minutes | [Docs](https://docs.browseros.com/features/scheduled-tasks) | +| **Memory** | Persistent memory across conversations β€” your assistant remembers context over time | [Docs](https://docs.browseros.com/features/memory) | +| **SOUL.md** | Define your AI's personality and instructions in a single markdown file | [Docs](https://docs.browseros.com/features/soul-md) | +| **LLM Hub** | Compare Claude, ChatGPT, and Gemini responses side-by-side on any page | [Docs](https://docs.browseros.com/features/llm-chat-hub) | +| **40+ App Integrations** | Gmail, Slack, GitHub, Linear, Notion, Figma, Salesforce, and more via MCP | [Docs](https://docs.browseros.com/features/connect-apps) | +| **Vertical Tabs** | Side-panel tab management β€” stay organized even with 100+ tabs open | [Docs](https://docs.browseros.com/features/vertical-tabs) | +| **Ad Blocking** | uBlock Origin + Manifest V2 support β€” [10x more protection](https://docs.browseros.com/features/ad-blocking) than Chrome | [Docs](https://docs.browseros.com/features/ad-blocking) | +| **Cloud Sync** | Sync browser config and agent history across devices | [Docs](https://docs.browseros.com/features/sync) | +| **Skills** | Custom instruction sets that shape how your AI assistant behaves | [Docs](https://docs.browseros.com/features/skills) | +| **Smart Nudges** | Contextual suggestions to connect apps and use features at the right moment | [Docs](https://docs.browseros.com/features/smart-nudges) | -4. Start automating! +## Demos + +### BrowserOS agent in action +[![BrowserOS agent in action](docs/videos/browserOS-agent-in-action.gif)](https://www.youtube.com/watch?v=SoSFev5R5dI) +

+ +### Install [BrowserOS as MCP](https://docs.browseros.com/features/use-with-claude-code) and control it from `claude-code` + +https://github.com/user-attachments/assets/c725d6df-1a0d-40eb-a125-ea009bf664dc + +

+ +### Use BrowserOS to chat + +https://github.com/user-attachments/assets/726803c5-8e36-420e-8694-c63a2607beca + +

+ +### Use BrowserOS to scrape data + +https://github.com/user-attachments/assets/9f038216-bc24-4555-abf1-af2adcb7ebc0 + +

## Install `browseros-cli` Use `browseros-cli` to launch and control BrowserOS from the terminal or from AI coding agents like Claude Code. -### macOS / Linux +**macOS / Linux:** ```bash curl -fsSL https://cdn.browseros.com/cli/install.sh | bash ``` -### Windows +**Windows:** ```powershell irm https://cdn.browseros.com/cli/install.ps1 | iex @@ -61,125 +96,110 @@ irm https://cdn.browseros.com/cli/install.ps1 | iex After install, run `browseros-cli init` to connect the CLI to your running BrowserOS instance. -## What makes BrowserOS special -- 🏠 Feels like home β€” same Chrome interface, all your extensions just work -- πŸ€– AI agents that run on YOUR browser, not in the cloud -- πŸ”’ Privacy first β€” bring your own keys or run local models with Ollama. Your browsing history stays on your machine -- 🀝 [BrowserOS as MCP server](https://docs.browseros.com/features/use-with-claude-code) β€” control the browser from `claude-code`, `gemini-cli`, or any MCP client (31 tools) -- πŸ”„ [Workflows](https://docs.browseros.com/features/workflows) β€” build repeatable browser automations with a visual graph builder -- πŸ“‚ [Cowork](https://docs.browseros.com/features/cowork) β€” combine browser automation with local file operations. Research the web, save reports to your folder -- ⏰ [Scheduled Tasks](https://docs.browseros.com/features/scheduled-tasks) β€” run the agent on autopilot, daily or every few minutes -- πŸ’¬ [LLM Hub](https://docs.browseros.com/features/llm-chat-hub) β€” compare Claude, ChatGPT, and Gemini side-by-side on any page -- πŸ“Œ [Vertical Tabs](https://docs.browseros.com/features/vertical-tabs) β€” move tabs to a side panel for a cleaner layout, even with 100+ tabs open -- πŸ›‘οΈ Built-in ad blocker β€” [10x more protection than Chrome](https://docs.browseros.com/features/ad-blocking) with uBlock Origin + Manifest V2 support -- πŸš€ 100% open source under AGPL-3.0 +## LLM Providers -## Demos +BrowserOS works with any LLM. Bring your own keys, use OAuth, or run models locally. -### πŸ€– BrowserOS agent in action -[![BrowserOS agent in action](docs/videos/browserOS-agent-in-action.gif)](https://www.youtube.com/watch?v=SoSFev5R5dI) -

+| Provider | Type | Auth | +|----------|------|------| +| Kimi K2.5 | Cloud (default) | Built-in | +| ChatGPT Pro/Plus | Cloud | [OAuth](https://docs.browseros.com/features/chatgpt) | +| GitHub Copilot | Cloud | [OAuth](https://docs.browseros.com/features/github-copilot) | +| Qwen Code | Cloud | [OAuth](https://docs.browseros.com/features/qwen-code) | +| Claude (Anthropic) | Cloud | API key | +| GPT-4o / o3 (OpenAI) | Cloud | API key | +| Gemini (Google) | Cloud | API key | +| Azure OpenAI | Cloud | API key | +| AWS Bedrock | Cloud | IAM credentials | +| OpenRouter | Cloud | API key | +| Ollama | Local | [Setup](https://docs.browseros.com/features/ollama) | +| LM Studio | Local | [Setup](https://docs.browseros.com/features/lm-studio) | -### πŸŽ‡ Install [BrowserOS as MCP](https://docs.browseros.com/features/use-with-claude-code) and control it from `claude-code` +## How We Compare -https://github.com/user-attachments/assets/c725d6df-1a0d-40eb-a125-ea009bf664dc +| | BrowserOS | Chrome | Brave | Dia | Comet | Atlas | +|---|:---:|:---:|:---:|:---:|:---:|:---:| +| Open Source | βœ… | ❌ | βœ… | ❌ | ❌ | ❌ | +| AI Agent | βœ… | ❌ | ❌ | ❌ | βœ… | βœ… | +| MCP Server | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ | +| Visual Workflows | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ | +| Cowork (files + browser) | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ | +| Scheduled Tasks | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ | +| Bring Your Own Keys | βœ… | ❌ | βœ… | ❌ | ❌ | ❌ | +| Local Models (Ollama) | βœ… | ❌ | βœ… | ❌ | ❌ | ❌ | +| Local-first Privacy | βœ… | ❌ | βœ… | ❌ | ❌ | ❌ | +| Ad Blocking (MV2) | βœ… | ❌ | βœ… | ❌ | βœ… | ❌ | -

+**Detailed comparisons:** +- [BrowserOS vs Chrome DevTools MCP](https://docs.browseros.com/comparisons/chrome-devtools-mcp) β€” developer-focused comparison for browser automation +- [BrowserOS vs Claude Cowork](https://docs.browseros.com/comparisons/claude-cowork) β€” getting real work done with AI +- [BrowserOS vs OpenClaw](https://docs.browseros.com/comparisons/openclaw) β€” everyday AI assistance -### πŸ’¬ Use BrowserOS to chat +## Architecture -https://github.com/user-attachments/assets/726803c5-8e36-420e-8694-c63a2607beca +BrowserOS is a monorepo with two main subsystems: the **browser** (Chromium fork) and the **agent platform** (TypeScript/Go). -

+``` +BrowserOS/ +β”œβ”€β”€ packages/browseros/ # Chromium fork + build system (Python) +β”‚ β”œβ”€β”€ chromium_patches/ # Patches applied to Chromium source +β”‚ β”œβ”€β”€ build/ # Build CLI and modules +β”‚ └── resources/ # Icons, entitlements, signing +β”‚ +β”œβ”€β”€ packages/browseros-agent/ # Agent platform (TypeScript/Go) +β”‚ β”œβ”€β”€ apps/ +β”‚ β”‚ β”œβ”€β”€ server/ # MCP server + AI agent loop (Bun) +β”‚ β”‚ β”œβ”€β”€ agent/ # Browser extension UI (WXT + React) +β”‚ β”‚ β”œβ”€β”€ cli/ # CLI tool (Go) +β”‚ β”‚ β”œβ”€β”€ eval/ # Benchmark framework +β”‚ β”‚ └── controller-ext/ # Chrome API bridge extension +β”‚ β”‚ +β”‚ └── packages/ +β”‚ β”œβ”€β”€ agent-sdk/ # Node.js SDK (npm: @browseros-ai/agent-sdk) +β”‚ β”œβ”€β”€ cdp-protocol/ # CDP type bindings +β”‚ └── shared/ # Shared constants +``` -### ⚑ Use BrowserOS to scrape data - -https://github.com/user-attachments/assets/9f038216-bc24-4555-abf1-af2adcb7ebc0 - -

- -## Why We're Building BrowserOS - -For the first time since Netscape pioneered the web in 1994, AI gives us the chance to completely reimagine the browser. We've seen tools like Cursor deliver 10x productivity gains for developersβ€”yet everyday browsing remains frustratingly archaic. - -You're likely juggling 70+ tabs, battling your browser instead of having it assist you. Routine tasks, like ordering something from amazon or filling a form should be handled seamlessly by AI agents. - -At BrowserOS, we're convinced that AI should empower you by automating tasks locally and securelyβ€”keeping your data private. We are building the best browser for this future! - -## How we compare - -
-vs Chrome -
-While we're grateful for Google open-sourcing Chromium, but Chrome hasn't evolved much in 10 years. No AI features, no automation, no MCP support. -
- -
-vs Brave -
-We love what Brave started, but they've spread themselves too thin with crypto, search, VPNs. We're laser-focused on AI-powered browsing. -
- -
-vs Arc/Dia -
-Many loved Arc, but it was closed source. When they abandoned users, there was no recourse. We're 100% open source - fork it anytime! -
- -
-vs Perplexity Comet -
-They're a search/ad company. Your browser history becomes their product. We keep everything local. -
- -
-vs ChatGPT Atlas -
-Your browsing data could be used for ads or to train their models. We keep your history and agent interactions strictly local. -
+| Package | What it does | +|---------|-------------| +| [`packages/browseros`](packages/browseros/) | Chromium fork β€” patches, build system, signing | +| [`apps/server`](packages/browseros-agent/apps/server/) | Bun server exposing 53+ MCP tools and running the AI agent loop | +| [`apps/agent`](packages/browseros-agent/apps/agent/) | Browser extension β€” new tab, side panel chat, onboarding, settings | +| [`apps/cli`](packages/browseros-agent/apps/cli/) | Go CLI β€” control BrowserOS from the terminal or AI coding agents | +| [`apps/eval`](packages/browseros-agent/apps/eval/) | Benchmark framework β€” WebVoyager, Mind2Web evaluation | +| [`agent-sdk`](packages/browseros-agent/packages/agent-sdk/) | Node.js SDK for browser automation with natural language | +| [`cdp-protocol`](packages/browseros-agent/packages/cdp-protocol/) | Type-safe Chrome DevTools Protocol bindings | ## Contributing -We'd love your help making BrowserOS better! +We'd love your help making BrowserOS better! See our [Contributing Guide](CONTRIBUTING.md) for details. -- πŸ› [Report bugs](https://github.com/browseros-ai/BrowserOS/issues) -- πŸ’‘ [Suggest features](https://github.com/browseros-ai/BrowserOS/issues/99) -- πŸ’¬ [Join Discord](https://discord.gg/YKwjt5vuKr) -- 🐦 [Follow on Twitter](https://x.com/browserOS_ai) +- [Report bugs](https://github.com/browseros-ai/BrowserOS/issues) +- [Suggest features](https://github.com/browseros-ai/BrowserOS/issues/99) +- [Join Discord](https://discord.gg/YKwjt5vuKr) Β· [Join Slack](https://dub.sh/browserOS-slack) +- [Follow on Twitter](https://x.com/browserOS_ai) + +**Agent development** (TypeScript/Go) β€” see the [agent monorepo README](packages/browseros-agent/README.md) for setup instructions. + +**Browser development** (C++/Python) β€” requires ~100GB disk space. See [`packages/browseros`](packages/browseros/) for build instructions. + +## Credits + +- [ungoogled-chromium](https://github.com/ungoogled-software/ungoogled-chromium) β€” BrowserOS uses some patches for enhanced privacy. Thanks to everyone behind this project! +- [The Chromium Project](https://www.chromium.org/) β€” at the core of BrowserOS, making it possible to exist in the first place. ## License BrowserOS is open source under the [AGPL-3.0 license](LICENSE). -## Credits - -- [ungoogled-chromium](https://github.com/ungoogled-software/ungoogled-chromium) - BrowserOS uses some patches for enhanced privacy. Thanks to everyone behind this project! -- [The Chromium Project](https://www.chromium.org/) - At the core of BrowserOS, making it possible to exist in the first place. - -## Citation - -If you use BrowserOS in your research or project, please cite: - -```bibtex -@software{browseros2025, - author = {Sonti, Nithin and Sonti, Nikhil and {BrowserOS-team}}, - title = {BrowserOS: The open-source Agentic browser}, - url = {https://github.com/browseros-ai/BrowserOS}, - year = {2025}, - publisher = {GitHub}, - license = {AGPL-3.0}, -} -``` - Copyright © 2025 Felafax, Inc. ## Stargazers + Thank you to all our supporters! [![Star History Chart](https://api.star-history.com/svg?repos=browseros-ai/BrowserOS&type=Date)](https://www.star-history.com/#browseros-ai/BrowserOS&Date) -##

Built with ❀️ from San Francisco

- diff --git a/packages/browseros-agent/README.md b/packages/browseros-agent/README.md index a8255535b..6bae0716e 100644 --- a/packages/browseros-agent/README.md +++ b/packages/browseros-agent/README.md @@ -1,8 +1,6 @@ # BrowserOS Agent -Monorepo for the BrowserOS-agent -- contains 3 packages: agent-UI, server (which contains the agent loop) and controller-extension (which is used by the tools within the agent loop). - -> **⚠️ NOTE:** This is only a submodule, the main project is at -- https://github.com/browseros-ai/BrowserOS +The agent platform powering [BrowserOS](https://github.com/browseros-ai/BrowserOS) β€” contains the MCP server, agent UI, CLI, evaluation framework, and SDK. ## Monorepo Structure @@ -10,17 +8,25 @@ Monorepo for the BrowserOS-agent -- contains 3 packages: agent-UI, server (which apps/ server/ # Bun server - MCP endpoints + agent loop agent/ # Agent UI (Chrome extension) + cli/ # Go CLI for controlling BrowserOS from the terminal + eval/ # Evaluation framework for benchmarking agents controller-ext/ # BrowserOS Controller (Chrome extension for chrome.* APIs) packages/ + agent-sdk/ # Node.js SDK (@browseros-ai/agent-sdk) + cdp-protocol/ # Type-safe Chrome DevTools Protocol bindings shared/ # Shared constants (ports, timeouts, limits) ``` | Package | Description | |---------|-------------| | `apps/server` | Bun server exposing MCP tools and running the agent loop | -| `apps/agent` | Agent UI - Chrome extension for the chat interface | -| `apps/controller-ext` | BrowserOS Controller - Chrome extension that bridges `chrome.*` APIs (tabs, bookmarks, history) to the server via WebSocket | +| `apps/agent` | Agent UI β€” Chrome extension for the chat interface | +| `apps/cli` | Go CLI β€” control BrowserOS from the terminal or AI coding agents | +| `apps/eval` | Benchmark framework β€” WebVoyager, Mind2Web evaluation | +| `apps/controller-ext` | BrowserOS Controller β€” bridges `chrome.*` APIs to the server via WebSocket | +| `packages/agent-sdk` | Node.js SDK for browser automation with natural language | +| `packages/cdp-protocol` | Auto-generated CDP type bindings used by the server | | `packages/shared` | Shared constants used across packages | ## Architecture diff --git a/packages/browseros-agent/apps/agent/README.md b/packages/browseros-agent/apps/agent/README.md index c74d5e511..21a8a6b23 100644 --- a/packages/browseros-agent/apps/agent/README.md +++ b/packages/browseros-agent/apps/agent/README.md @@ -1,16 +1,24 @@ -# BrowserOS Agent Chrome Extension +# BrowserOS Agent Extension -The official Chrome extension for BrowserOS Agent, providing the UI layer for interacting with BrowserOS Core and Controllers. This extension enables intelligent browser automation, AI-powered search, and seamless integration with multiple LLM providers. +[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](../../../../LICENSE) + +The built-in browser extension that powers BrowserOS's AI interface β€” new tab with unified search, side panel chat, onboarding, and settings. Built with [WXT](https://wxt.dev) and React. + +> For user-facing feature documentation, see [docs.browseros.com](https://docs.browseros.com). ## Features - **AI-Powered New Tab**: Custom new tab page with unified search across Google and AI assistants -- **Side Panel Chat**: Full-featured chat interface for interacting with BrowserOS Core +- **Side Panel Chat**: Full-featured chat interface for interacting with BrowserOS - **Multi-Provider Support**: Connect to various LLM providers (OpenAI, Anthropic, Azure, Bedrock, and more) - **MCP Integration**: Model Context Protocol support for extending AI capabilities - **Visual Feedback**: Animated glow effect on tabs during AI agent operations - **Privacy-First**: Local data handling with configurable provider settings +## How It Connects + +The extension communicates with the [BrowserOS Server](../../apps/server/) running locally. The server handles the AI agent loop, MCP tools, and CDP connections β€” the extension provides the UI layer. + ## Project Structure ``` @@ -80,47 +88,20 @@ Settings dashboard with multiple sections: Content script that creates a visual indicator (pulsing orange glow) around the browser viewport when an AI agent is actively working on a tab. -## How Tools Are Used - -### Bun - -Bun is the exclusive runtime and package manager: -- All scripts use `bun run