authenticated-browser-control-via-cdp
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.
Unique: Uses direct CDP connection to a managed Chrome profile (v0.11.x architecture) instead of headless/isolated browser instances, preserving real authentication state and cookies. Site Adapter System bridges websites into CLI tools by executing JavaScript within the authenticated browser context, eliminating the need for websites to provide machine-readable APIs.
vs alternatives: Preserves user authentication state across runs unlike Playwright/Selenium headless instances; enables interaction with authenticated web apps without credential management unlike traditional web scraping libraries
site-adapter-ecosystem-for-domain-specific-automation
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.
Unique: Two-tier adapter loading system (local ~/.bb-browser/sites/ + synced community ~/.bb-browser/bb-sites/) with domain-based discovery and metadata-driven argument validation. Adapters execute JavaScript within the authenticated browser context (Tier 3 injection), giving direct access to page internals, localStorage, and internal JS variables without external API calls.
vs alternatives: Converts websites into APIs without requiring site cooperation or reverse-engineering, unlike web scraping libraries; community-driven ecosystem enables rapid adapter creation vs maintaining separate integrations for each platform
domain-based-adapter-discovery-and-recommendation
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.
Unique: Domain-based discovery system that suggests relevant adapters when users navigate to a website. Integrates with adapter metadata to provide contextual recommendations without explicit search.
vs alternatives: Proactive discovery vs requiring users to manually search for adapters; domain-based matching enables quick lookup vs full-text search
local-and-community-adapter-registry-management
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.
Unique: Dual-tier adapter registry (local + community) with automatic GitHub syncing for community adapters. Local adapters take precedence, enabling private customization while benefiting from community contributions.
vs alternatives: Community-driven ecosystem enables rapid adapter creation vs maintaining separate integrations; local override enables customization vs read-only community registry
browser-event-monitoring-and-debugging-tools
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.
Unique: Integrates CDP event monitoring into the automation workflow, exposing console logs, network activity, and performance metrics for debugging. Enables real-time monitoring of automation execution.
vs alternatives: Direct CDP access provides detailed debugging info vs Playwright/Selenium which abstract away low-level events; real-time monitoring enables interactive debugging
mcp-protocol-translation-for-ai-agent-integration
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.
Unique: Implements MCP as a stdio protocol translation layer that bridges AI agents to the bb-browserd daemon, converting high-level tool invocations into low-level CDP commands. Enables AI agents to discover and invoke browser actions as native tools without subprocess overhead.
vs alternatives: Tighter integration with AI agents than CLI-based invocation; standardized MCP protocol enables compatibility with multiple AI platforms vs custom integrations for each tool
dom-element-interaction-with-selector-based-targeting
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.
Unique: Uses CDP protocol for direct DOM interaction with built-in element visibility waits and multi-element batch operations. Integrates with the authenticated browser context to interact with pages as the logged-in user.
vs alternatives: More reliable than Playwright/Selenium for authenticated pages because it uses the real browser session; built-in waits reduce flakiness vs raw CDP usage
structured-data-extraction-from-dom-and-javascript-context
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.
Unique: Dual extraction mechanism: CSS selector-based DOM queries for structured data + JavaScript eval for accessing internal page state and localStorage. Executes within authenticated browser context, enabling access to user-specific data without API credentials.
vs alternatives: Accesses internal page state and localStorage unlike traditional web scraping; no need for reverse-engineered API calls or credential management
+5 more capabilities