bb-browser

Direct Chrome DevTools Protocol (CDP) connection to a managed Chrome profile that preserves user authentication state (cookies, localStorage, sessionStorage, tokens). Unlike headless automation tools, bb-browser operates on a real browser instance with the user's actual login credentials, enabling interaction with authenticated web applications without credential re-entry or session simulation. The daemon layer (bb-browserd) maintains persistent CDP connections and translates CLI/MCP commands into low-level CDP protocol messages.

A plugin architecture where JavaScript adapters (loaded from ~/.bb-browser/sites/ for local/private adapters and ~/.bb-browser/bb-sites/ for community adapters) define domain-specific commands that run within the browser's authenticated context. Each adapter includes @meta JSON metadata declaring the target domain, available commands, and argument schemas. The system uses domain-based discovery to suggest relevant adapters when users navigate to specific websites, and executes adapter code via eval() within the page context to access internal APIs, DOM, or localStorage without external API calls.

Analyzes the current page's domain and suggests relevant site adapters using the getSiteHintForDomain function. When a user navigates to a website, bb-browser can recommend available adapters for that domain, helping users discover automation capabilities without manual search. The system maintains a mapping of domains to available adapters, enabling quick lookup and suggestion.

Manages two adapter directories: local (~/.bb-browser/sites/ for private/custom adapters) and community (~/.bb-browser/bb-sites/ synced from public GitHub repository). The system loads adapters from both locations, with local adapters taking precedence. Community adapters are automatically synced from a GitHub repository, enabling users to benefit from community-maintained adapters without manual installation. Adapter discovery and execution use this unified registry.

Provides monitoring and debugging commands (monitor, logs, debug) that expose browser events, console logs, network activity, and performance metrics via CDP protocol. These tools help developers understand what's happening in the browser during automation, diagnose failures, and optimize performance. Monitoring can be streamed in real-time or retrieved after execution.

Wraps bb-browser's CLI capabilities in a Model Context Protocol (MCP) stdio server, translating MCP tool invocations into daemon commands. The MCP layer (packages/mcp/src/index.ts) acts as a protocol adapter that converts AI agent tool calls into bb-browser CLI commands, executes them against the bb-browserd daemon, and returns structured results back to the agent. This enables AI coding assistants (Claude Code, Cursor) to control the browser as a native tool without CLI invocation overhead.

Provides CLI commands (click, type, hover, focus, scroll) that target DOM elements using CSS selectors or XPath expressions. Commands are translated to CDP protocol messages that interact with the page's DOM in real-time. The system supports multi-element operations (e.g., clicking all elements matching a selector) and includes built-in waits for element visibility/stability before interaction, reducing flakiness in dynamic web applications.

Provides data extraction capabilities via two mechanisms: (1) DOM-based extraction using CSS selectors to query elements and return text/attributes/HTML, and (2) JavaScript eval-based extraction that executes arbitrary code within the page context to access internal state, localStorage, sessionStorage, or page-specific APIs. Results are returned as structured JSON, enabling AI agents and scripts to parse and process extracted data programmatically.

Manages multiple browser tabs and frames through CDP protocol, enabling navigation to different URLs, switching between tabs, and executing commands within specific frame contexts. The system tracks tab state and provides commands to create new tabs, close tabs, and target commands to specific tabs or frames. This enables complex workflows that require interaction across multiple pages or frames within a single browser session.

Captures full-page or viewport screenshots via CDP protocol and returns them as PNG data (base64-encoded or file-based). Supports capturing specific regions or elements and includes options for viewport sizing and device emulation. Screenshots are useful for visual verification, debugging automation failures, and providing visual context to AI agents for understanding page state.

The bb-browserd daemon (Daemon Layer Architecture) manages the Chrome browser lifecycle, maintaining persistent CDP connections and translating CLI/MCP commands into protocol messages. The daemon handles browser startup, profile management, connection pooling, and graceful shutdown. This architecture decouples the CLI/MCP interface from the browser control logic, enabling multiple clients (CLI, MCP, custom tools) to share a single browser instance and session state.

Tier 1 and Tier 2 adapter execution modes that extract authentication credentials (cookies, Bearer tokens from localStorage/sessionStorage) from the authenticated browser context and use them to make direct HTTP requests to internal APIs. This enables adapters to call backend APIs without navigating the UI, using the user's existing authentication state. Requests are made with the extracted credentials, bypassing the need for credential re-entry or API key management.

Provides a comprehensive CLI (packages/cli/src/index.ts) with subcommands for browser control (navigate, click, type, extract, screenshot), site adapter management (list, search, info, recommend), and debugging (monitor, logs). Arguments are parsed and validated against adapter metadata schemas, providing help text and error messages. The CLI layer translates user commands into daemon requests, enabling both interactive and scripted automation workflows.