# siropkin/chrome-bridge architecture

> Architecture diagram of the GitHub repository siropkin/chrome-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siropkin/chrome-bridge
- Repository: https://github.com/siropkin/chrome-bridge

## Overview

chrome-bridge lets an AI agent operate the user’s existing, logged-in Chrome through a Node CLI, local bridge server, and Chrome extension. The main workflow is CLI command → server routing/profile selection → extension command execution against tabs → result returned to the CLI; snapshots, page actions, and screenshots are core outcomes. The README also documents setup/health management, browser diagnostics and network capture, human release controls, and optional in-page AI features. Extension internals are only partially excerpted, so edges to specific unsampled command subsystems are omitted where their dispatch is not evidenced.

Main entry points: [`extension/background.js`](https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js) (Command worker), [`server.mjs`](https://github.com/siropkin/chrome-bridge/blob/master/server.mjs) (HTTP and WS bridge), [`extension/popup.js`](https://github.com/siropkin/chrome-bridge/blob/master/extension/popup.js) (Popup controls), [`cli.mjs`](https://github.com/siropkin/chrome-bridge/blob/master/cli.mjs) (Command CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Agent interface"]
  node_cli["Command CLI<br/>[cli.mjs]"]
end

subgraph group_bridge["Local bridge"]
  node_server["HTTP and WS bridge<br/>[server.mjs]"]
  node_health["Health and profiles<br/>[server.mjs]"]
  node_activity["Activity feed<br/>[server.mjs]"]
end

subgraph group_extension["Chrome extension"]
  node_worker["Command worker<br/>[background.js]"]
  node_tabmark["Driven-tab narration<br/>[background.js]"]
  node_snapshot["Page snapshots<br/>[background.js]"]
  node_pageactions["Page interactions<br/>[background.js]"]
  node_capture["Screenshots and diffs<br/>[background.js]"]
  node_debugger["Debugger and emulation<br/>[background.js]"]
  node_popup["Popup controls<br/>[popup.js]"]
end

subgraph group_browser["Browser capabilities"]
  node_chrome["Chrome tabs"]
  node_web["Web pages"]
  node_nano["Chrome Nano model"]
end

node_agent(("AI agent"))

node_agent -->|"runs commands"| node_cli
node_cli -->|"posts commands"| node_server
node_server -->|"dispatches commands"| node_worker
node_worker -->|"returns replies"| node_server
node_worker -.->|"controls tabs"| node_chrome
node_worker -.->|"marks activity"| node_tabmark
node_worker -.->|"creates snapshots"| node_snapshot
node_worker -.->|"executes actions"| node_pageactions
node_worker -.->|"captures images"| node_capture
node_worker -->|"uses debugger"| node_debugger
node_pageactions -.->|"acts on pages"| node_web
node_capture -->|"captures viewport"| node_web
node_cli -->|"checks status"| node_health
node_server -->|"serves health"| node_health
node_server -->|"serves feed"| node_activity
node_popup -->|"fetches status"| node_health
node_popup -->|"requests release"| node_worker
node_popup -->|"queries active tab"| node_chrome
node_agent -.->|"asks page questions"| node_nano

click node_cli "https://github.com/siropkin/chrome-bridge/blob/master/cli.mjs"
click node_server "https://github.com/siropkin/chrome-bridge/blob/master/server.mjs"
click node_health "https://github.com/siropkin/chrome-bridge/blob/master/server.mjs"
click node_activity "https://github.com/siropkin/chrome-bridge/blob/master/server.mjs"
click node_worker "https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js"
click node_tabmark "https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js"
click node_snapshot "https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js"
click node_pageactions "https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js"
click node_capture "https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js"
click node_debugger "https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js"
click node_popup "https://github.com/siropkin/chrome-bridge/blob/master/extension/popup.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli toneBlue
class node_server,node_health,node_activity toneAmber
class node_worker,node_tabmark,node_snapshot,node_pageactions,node_capture,node_debugger,node_popup toneMint
class node_chrome,node_web,node_nano toneRose
class node_agent toneIndigo
```

## Components

### Agent interface

- [Command CLI](https://github.com/siropkin/chrome-bridge/blob/master/cli.mjs): `cli.mjs`

### Local bridge

- [HTTP and WS bridge](https://github.com/siropkin/chrome-bridge/blob/master/server.mjs): `server.mjs`
- [Health and profiles](https://github.com/siropkin/chrome-bridge/blob/master/server.mjs): `server.mjs`
- [Activity feed](https://github.com/siropkin/chrome-bridge/blob/master/server.mjs): `server.mjs`

### Chrome extension

- [Command worker](https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js): `extension/background.js`
- [Driven-tab narration](https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js): `extension/background.js`
- [Page snapshots](https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js): `extension/background.js`
- [Page interactions](https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js): `extension/background.js`
- [Screenshots and diffs](https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js): `extension/background.js`
- [Debugger and emulation](https://github.com/siropkin/chrome-bridge/blob/master/extension/background.js): `extension/background.js`
- [Popup controls](https://github.com/siropkin/chrome-bridge/blob/master/extension/popup.js): `extension/popup.js`

### Browser capabilities

- **Chrome tabs**
- **Web pages**
- **Chrome Nano model**

### Other components

- **AI agent**

## Connections

- AI agent → Command CLI: runs commands (evidence: `README.md`)
- Command CLI → HTTP and WS bridge: posts commands (evidence: `README.md`)
- HTTP and WS bridge → Command worker: dispatches commands (evidence: `server.mjs`)
- Command worker → HTTP and WS bridge: returns replies (evidence: `server.mjs`)
- Command worker → Chrome tabs: controls tabs
- Command worker → Driven-tab narration: marks activity (evidence: `extension/background.js`)
- Command worker → Page snapshots: creates snapshots (evidence: `extension/background.js`)
- Command worker → Page interactions: executes actions (evidence: `extension/background.js`)
- Command worker → Screenshots and diffs: captures images (evidence: `extension/background.js`)
- Command worker → Debugger and emulation: uses debugger (evidence: `extension/background.js`)
- Page interactions → Web pages: acts on pages
- Screenshots and diffs → Web pages: captures viewport (evidence: `extension/background.js`)
- Command CLI → Health and profiles: checks status (evidence: `cli.mjs`)
- HTTP and WS bridge → Health and profiles: serves health (evidence: `server.mjs`)
- HTTP and WS bridge → Activity feed: serves feed (evidence: `server.mjs`)
- Popup controls → Health and profiles: fetches status (evidence: `extension/popup.js`)
- Popup controls → Command worker: requests release (evidence: `extension/popup.js`)
- Popup controls → Chrome tabs: queries active tab (evidence: `extension/popup.js`)
- AI agent → Chrome Nano model: asks page questions