Chrome Bridge

Connect AI agents directly to your real, logged-in Google Chrome browser.

Unlike Puppeteer or Playwright which launch isolated, empty browser instances, Chrome Bridge connects to your existing browser session:

• Live User Session: Retains all cookies, logins, credentials, and active tab states (Gmail, GitHub, internal dashboards).
• Native Messaging IPC: Communicates directly with Chrome via standard Chrome Native Messaging and fast local IPC.
• 99% Token Reduction: Translates full DOM trees into compact text outlines with numbered interactive reference IDs ([#1], [#2]).
• Stateful Python REPL: Agents write procedural Python in a persistent runtime where state, variables, and tab bindings persist across turns.

Architecture & Request Flow

sequenceDiagram
    autonumber
    actor Agent as AI Agent (Claude Code / Cursor / Claude Desktop / Antigravity)
    participant REPL as Python Runtime (chrome_sdk)
    participant Host as Native Host (stdio IPC)
    participant Ext as Chrome MV3 Extension
    participant Tab as Live Chrome Tab (DOM & Shadow DOM)

    Agent->>REPL: execute_python("chrome.click(14)")
    Note over REPL: Resolves active tab & serializes JSON packet
    REPL->>Host: JSON message via length-prefixed stdio
    Host->>Ext: Chrome Native Messaging port
    Ext->>Tab: Dispatches trusted event / queries Shadow DOM
    Tab-->>Ext: Element updated / DOM mutated
    Ext-->>Host: Action ack & distilled Ref-ID delta
    Host-->>REPL: stdio response stream
    REPL-->>Agent: Action return value / refreshed snapshot outline

flowchart LR
    subgraph ClientLayer ["AI & Client Runtime"]
        A["AI Agent<br/>(Claude Code / Cursor / Claude Desktop / Antigravity)"]
        B["Python REPL Runtime<br/>(chrome_sdk)"]
        A -->|"execute_python(code)"| B
    end

    subgraph NativeBridge ["OS Native Bridge"]
        C["Native Messaging Host<br/>(native_host.py / stdio)"]
        B -->|"Length-prefixed stdio"| C
    end

    subgraph BrowserEngine ["Chrome Browser (Live Session)"]
        D["MV3 Extension Service Worker"]
        E["Active Tab & Content Scripts<br/>(DOM, Shadow DOM, Ref-IDs)"]
        C -->|"Native Messaging Port"| D
        D -->|"chrome.tabs / scripting"| E
    end

Installation (2 Steps)

Step 1: Run the Automated Setup

uvx --refresh antigravity-chrome-bridge setup

This single command automatically:

• Provisions the isolated Python runtime (~/.chrome-bridge).
• Registers the Native Messaging Host for Chrome, Brave, and Edge across Linux, macOS, and Windows.
• Automatically configures MCP servers for Claude Code, Claude Desktop, Cursor, and Antigravity CLI.

# macOS & Linux
git clone https://github.com/sh7vansh/chrome-bridge.git && cd chrome-bridge && ./setup.sh

# Windows (PowerShell)
git clone https://github.com/sh7vansh/chrome-bridge.git; cd chrome-bridge; .\setup.ps1

Step 2: Load the Extension in Chrome

1. Open Google Chrome and navigate to chrome://extensions.
2. Enable Developer mode using the toggle in the top-right corner.
3. Click Load unpacked (top-left) and select ~/.chrome-bridge/extension (or chrome-bridge/extension if installed from source).
4. You're done! The Chrome Bridge icon in your toolbar will show connected status.

{
  "mcpServers": {
    "chrome-bridge": {
      "command": "uvx",
      "args": ["--refresh", "antigravity-chrome-bridge", "mcp"]
    }
  }
}

Python SDK Quick Reference

The synchronous chrome client is ready to use directly in Python scripts and agent REPL sessions:

from chrome_sdk import chrome

# Inspect current page structure with numbered Ref-IDs
print(chrome.snapshot())

# Click button or link by element ID
chrome.click(12)

# Type into input field and submit
chrome.type(3, "Search query", press_enter=True)

# Select dropdown option
chrome.select(5, "option_value")

# Multimedia fast-path (Shadow-DOM & audio/video)
chrome.media.play_pause()
chrome.media.seek(30)

# Tab management
tab = chrome.new_tab("https://github.com")
print(chrome.tabs)

Core API Methods

Testing

Run the test suite to verify the native host and SDK bindings:

./test.sh
# or
pytest tests/

Security & Architecture Principles

• Local-Only Communication: All data transfer occurs over local standard I/O pipes. No data leaves your machine.
• No Cloud Proxies: All browsing sessions execute against your local Chrome application directly.
• Bot-Detection Immunity: Operates within your actual user profile and existing session cookies without triggering automation or CAPTCHA defenses.

License

MIT License. See LICENSE for details.