agent-webbridge

Let an AI agent drive your real Chrome — with your real logins — across many profiles and many tabs at once. One local endpoint, no account, no telemetry, nothing leaves 127.0.0.1.

agent-webbridge is a tiny Node daemon (one runtime dependency: ws) plus a clean-room MV3 Chrome extension. An agent POSTs a command to a local router → the router fans it out to the right profile's daemon → the extension attaches the Chrome DevTools Protocol per tab.

Overview

• Drive your real browser — your actual Chrome, your actual login sessions. No headless re-login, no scraping around auth.
• Run tabs in parallel — the extension attaches chrome.debugger per tab, so N tabs in one profile run concurrently. 10 tabs finish as fast as 1 (~2 s, flat).
• Span multiple profiles — one daemon per profile. Total concurrency = profiles × tabs, all from one endpoint.
• Stay private — own daemon, own MV3 extension, no closed-source dependency, no account. Everything is local.

Install

npm i -g agent-webbridge        # 1. the daemon + the `awb` CLI
awb setup "Work"                # 2. opens the Chrome Web Store; click "Add to Chrome"

awb setup opens the Agent WebBridge listing in your chosen profile and polls while you click Add to Chrome. As soon as it detects the install, it wires the profile to its daemon and brings the fleet up.

Requirements: macOS · Google Chrome · Node.js ≥ 18.

Quickstart

awb up "Work" "Personal"        # bring profiles up (setup did this on first run)

# Drive any profile by name — same endpoint, one extra field
curl -s -X POST http://127.0.0.1:10086/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"navigate","args":{"url":"https://news.ycombinator.com"},"session":"scan","profile":"Work"}'

awb down                        # stop the fleet when done

Every call is a POST /command on 127.0.0.1:10086. "session" groups a task's tabs into one Chrome tab group; "profile" picks which Chrome profile to drive.

Tools

| Tool | Does | |---|---| | navigate | Open a URL in a new or existing tab | | find_tab | Locate a tab by URL / title | | evaluate | Run JavaScript in the page, return the result | | snapshot | Accessibility tree with stable @e element refs | | click | Click an element by @e ref | | fill | Set native inputs and contenteditable fields | | upload | Upload a file to a file input | | screenshot | Capture a page screenshot | | save_as_pdf | Save the page as a PDF | | network | Capture network requests | | list_tabs | List the session's tabs | | close_tab | Close a tab | | close_session | Close a session and its tab group |

How it works

  AI agent  ──HTTP POST /command──▶  router (127.0.0.1:10086)   routes by "profile"
                                          │
                       ┌──────────────────┼──────────────────┐
                       ▼                  ▼                  ▼
                  daemon "Work"      daemon "Personal"     daemon …      one per profile
                       │  WebSocket
                       ▼
                  MV3 extension      ──chrome.debugger (a Map: one attach PER TAB)──▶
                       │
                       ▼
                  Chrome DevTools Protocol      tab 1 ║ tab 2 ║ tab 3   (concurrent)

The router proxies each command to the per-profile daemon on its deterministic hashed port; the daemon relays over WebSocket to that profile's extension; the extension keeps a Map of chrome.debugger attachments — one per tab — and issues CDP calls. That per-tab map is the whole trick: bridges that funnel everything through a single "current tab" can only drive one tab per profile; this drives N.

CLI

| Command | Does | |---|---| | awb setup <profile…> | One-time install: walk through "Load unpacked", connect, bring the fleet up | | awb up <profile…> | Start the named profiles' daemons + router, open windows, connect | | awb down | Stop the router + fleet | | awb connect <profile…> | Point each profile's extension at its daemon | | awb check [profile…] [--json] | Read-only readiness probe (folder? dev-mode? loaded? connected?) — what an agent polls during install | | awb status | Per-profile daemon + extension-connection status | | awb doctor | Diagnose the environment (Chrome, profiles, daemon, extension) | | awb profiles | List Chrome profiles, their hashed ports, and extension presence |

<profile> is anything that resolves uniquely — the profile name ("Work"), an email, or the Chrome directory ("Profile 2").

Use it from an AI agent

Ship it as a Claude Code skill / plugin — the bundled agent-webbridge skill teaches an agent the full flow (install via awb check --json, then drive over POST /command). To hack on the extension itself, awb install-dev Load-unpacks the in-repo build (chrome://extensions → Developer mode → Load unpacked → agent-webbridge-extension/); it ships its own key, so the dev id is stable across reloads.

Platform

macOS-first — the profile launcher uses AppleScript, so macOS + Google Chrome is supported today. Linux / Windows are a documented follow-up.

License

MIT © jeet-dhandha