Agent Browser Bridge

A secure, local-first bridge that connects AI Agents to your web browser.

The Agent Browser Bridge allows AI tools (like Claude Desktop, Cursor, or Hermes) to securely extract data from your current browser tabs without giving them unrestricted access to your entire web session. It acts as an intermediary, enforcing strict security policies, managing pairing tokens, and providing a human-in-the-loop approval UI before any artifacts are written to your local file system.

Features

• Local-First Infrastructure: Runs entirely on your machine. No cloud sync, no remote servers.
• Chrome Extension: A Manifest V3 extension that securely captures the current page, a specific text selection, or visible threaded conversations.
• Secure Bridge Server: A local loopback server (127.0.0.1) that manages pairing, parses incoming data, and handles approvals.
• Human-in-the-Loop Approvals: Agents can read data, but generating artifacts or taking actions requires explicit user approval via the extension UI.
• MCP Server: Implements the Model Context Protocol (MCP) to seamlessly expose capabilities to agent harnesses.
• Asynchronous Webhooks: Instantly wakes up and notifies your agent when a page is captured or a proposal is approved.
• Audit Logging: Every action, capture, and policy decision is cryptographically hashed and logged to a local SQLite database for maximum transparency.

Project Structure

This is a TypeScript monorepo managed with pnpm.

• apps/extension: The Chrome extension (Manifest V3, built with Vite).
• apps/bridge: The local server that manages SQLite, auth, and the policy engine.
• packages/mcp: The MCP server for AI agents to connect to.
• packages/common: Shared Zod schemas, types, and constants.

---

Quick Start Guide

Here is how to set up and test the Agent Browser Bridge:

1. Load the Chrome Extension

1. Ensure you have built the project (pnpm -w run build).
2. Open Chrome and go to chrome://extensions/.
3. Enable Developer mode (toggle in the top right).
4. Click Load unpacked and select the folder: /path/to/agent_browser_bridge_package/apps/extension/dist
5. Pin the extension to your toolbar for easy access.

2. Run the Bridge Server

The Bridge Server acts as the secure middleman between the extension and the AI agents.

1. Navigate to the bridge directory:

   cd apps/bridge

2. (Optional) Configure webhooks by creating a .env file in the apps/bridge directory:

   WEBHOOK_URL="http://127.0.0.1:8644/webhooks/agent-bridge"
   WEBHOOK_SECRET="your_secret_here"

3. Start the server (it will automatically run the SQLite migrations):

   pnpm start

3. Pair the Extension

1. Click on the Agent Bridge extension icon in your Chrome toolbar.
2. Click the 🔗 Pair with Bridge button.
3. Check your terminal where the bridge is running. You will see a PAIRING REQUEST with a 6-digit code.
4. Enter this code into the extension popup and click Confirm.
5. Your terminal will print your BRIDGE_TOKEN. Save this for your agent configuration.

4. Connect the MCP Server (for AI Agents)

The MCP server connects your AI agent tools to the bridge.

For Claude Desktop, add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "agent-bridge": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/packages/mcp/src/server.ts"],
      "env": {
        "BRIDGE_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

5. Using the CLI

You can interact with the bridge database and inbox via the command line:

cd apps/bridge
BRIDGE_TOKEN="your_token" npx tsx src/cli/index.ts inbox

---

License

Licensed under the Apache License, Version 2.0. See LICENSE for more information.