# ashish797/gbrow architecture

> Architecture diagram of the GitHub repository ashish797/gbrow, 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/ashish797/gbrow
- Repository: https://github.com/ashish797/gbrow

## Overview

Gbrow is a persistent, HTTP-controlled headless browser workstation for AI agents. The principal workflow is an agent sending an authenticated command to the server, which dispatches browser navigation or interaction, reads page content (especially as an accessibility snapshot with reusable refs), and returns structured results. Additional capabilities include tab and session management, screenshots/PDFs, CSS inspection and editing, and importing cookies from installed browsers. Edges are limited to relationships shown in README or sampled source/index; the sidebar agent is included, but its wiring was not verified.

Main entry points: [`src/server.ts`](https://github.com/ashish797/gbrow/blob/main/src/server.ts) (HTTP server), [`src/browser-manager.ts`](https://github.com/ashish797/gbrow/blob/main/src/browser-manager.ts) (Browser manager), [`src/write-commands.ts`](https://github.com/ashish797/gbrow/blob/main/src/write-commands.ts) (Navigation and interaction), [`src/read-commands.ts`](https://github.com/ashish797/gbrow/blob/main/src/read-commands.ts) (Page reading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Server and session"]
  node_http["HTTP server<br/>[server.ts]"]
  node_sidebar["Sidebar agent<br/>[sidebar-agent.ts]"]
end

subgraph group_browser["Browser operations"]
  node_browser_manager["Browser manager<br/>[browser-manager.ts]"]
  node_write["Navigation and interaction<br/>[write-commands.ts]"]
  node_meta["Tabs and session tools<br/>[meta-commands.ts]"]
end

subgraph group_inspection["Reading and inspection"]
  node_read["Page reading<br/>[read-commands.ts]"]
  node_snapshot["Accessibility snapshots<br/>[snapshot.ts]"]
  node_inspector["CDP inspector<br/>[cdp-inspector.ts]"]
end

subgraph group_integration["Cookie integration"]
  node_cookie_routes["Cookie picker routes"]
  node_cookie_import["Browser cookie import"]
  node_cookie_ui["Cookie picker UI"]
end

subgraph group_support["Shared runtime"]
  node_activity["Activity tracking<br/>[activity.ts]"]
  node_buffers["Event buffers<br/>[buffers.ts]"]
  node_config["Runtime configuration<br/>[config.ts]"]
  node_url_validation["Navigation URL checks<br/>[url-validation.ts]"]
  node_platform["Platform utilities<br/>[platform.ts]"]
end

node_agent(("AI agent"))
node_chromium["Chromium browser"]

node_agent -->|"sends HTTP commands"| node_http
node_http -->|"dispatches browser work"| node_browser_manager
node_http -->|"dispatches reads"| node_read
node_http -->|"dispatches interactions"| node_write
node_http -->|"dispatches meta commands"| node_meta
node_http -->|"requests watch snapshots"| node_snapshot
node_http -->|"routes cookie requests"| node_cookie_routes
node_http -->|"runs inspection"| node_inspector
node_http -->|"loads configuration"| node_config
node_browser_manager -->|"validates navigation"| node_url_validation
node_browser_manager -.->|"controls browser"| node_chromium
node_write -->|"uses browser session"| node_browser_manager
node_write -->|"validates destinations"| node_url_validation
node_write -->|"imports cookies"| node_cookie_import
node_write -->|"undoes style edits"| node_inspector
node_read -->|"reads browser session"| node_browser_manager
node_read -->|"inspects elements"| node_inspector
node_meta -->|"manages tabs and state"| node_browser_manager
node_meta -->|"requests snapshots"| node_snapshot
node_meta -->|"gets page text"| node_read
node_snapshot -->|"stores element refs"| node_browser_manager
node_cookie_routes -->|"lists and imports cookies"| node_cookie_import
node_cookie_routes -->|"serves picker UI"| node_cookie_ui
node_activity -->|"uses shared buffers"| node_buffers
node_read -->|"checks safe paths"| node_platform
node_snapshot -->|"checks safe paths"| node_platform
node_write -->|"checks safe paths"| node_platform
node_sidebar -.->|"may integrate"| node_http

click node_http "https://github.com/ashish797/gbrow/blob/main/src/server.ts"
click node_browser_manager "https://github.com/ashish797/gbrow/blob/main/src/browser-manager.ts"
click node_write "https://github.com/ashish797/gbrow/blob/main/src/write-commands.ts"
click node_read "https://github.com/ashish797/gbrow/blob/main/src/read-commands.ts"
click node_snapshot "https://github.com/ashish797/gbrow/blob/main/src/snapshot.ts"
click node_meta "https://github.com/ashish797/gbrow/blob/main/src/meta-commands.ts"
click node_inspector "https://github.com/ashish797/gbrow/blob/main/src/cdp-inspector.ts"
click node_cookie_routes "https://github.com/ashish797/gbrow/blob/main/src/cookie-picker-routes.ts"
click node_cookie_import "https://github.com/ashish797/gbrow/blob/main/src/cookie-import-browser.ts"
click node_cookie_ui "https://github.com/ashish797/gbrow/blob/main/src/cookie-picker-ui.ts"
click node_sidebar "https://github.com/ashish797/gbrow/blob/main/src/sidebar-agent.ts"
click node_activity "https://github.com/ashish797/gbrow/blob/main/src/activity.ts"
click node_buffers "https://github.com/ashish797/gbrow/blob/main/src/buffers.ts"
click node_config "https://github.com/ashish797/gbrow/blob/main/src/config.ts"
click node_url_validation "https://github.com/ashish797/gbrow/blob/main/src/url-validation.ts"
click node_platform "https://github.com/ashish797/gbrow/blob/main/src/platform.ts"

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_http,node_sidebar,node_chromium toneBlue
class node_browser_manager,node_write,node_meta toneAmber
class node_read,node_snapshot,node_inspector toneMint
class node_cookie_routes,node_cookie_import,node_cookie_ui toneRose
class node_activity,node_buffers,node_config,node_url_validation,node_platform,node_agent toneIndigo
```

## Components

### Server and session

- [HTTP server](https://github.com/ashish797/gbrow/blob/main/src/server.ts): `src/server.ts`
- [Sidebar agent](https://github.com/ashish797/gbrow/blob/main/src/sidebar-agent.ts): `src/sidebar-agent.ts`

### Browser operations

- [Browser manager](https://github.com/ashish797/gbrow/blob/main/src/browser-manager.ts): `src/browser-manager.ts`
- [Navigation and interaction](https://github.com/ashish797/gbrow/blob/main/src/write-commands.ts): `src/write-commands.ts`
- [Tabs and session tools](https://github.com/ashish797/gbrow/blob/main/src/meta-commands.ts): `src/meta-commands.ts`

### Reading and inspection

- [Page reading](https://github.com/ashish797/gbrow/blob/main/src/read-commands.ts): `src/read-commands.ts`
- [Accessibility snapshots](https://github.com/ashish797/gbrow/blob/main/src/snapshot.ts): `src/snapshot.ts`
- [CDP inspector](https://github.com/ashish797/gbrow/blob/main/src/cdp-inspector.ts): `src/cdp-inspector.ts`

### Cookie integration

- [Cookie picker routes](https://github.com/ashish797/gbrow/blob/main/src/cookie-picker-routes.ts): `src/cookie-picker-routes.ts`
- [Browser cookie import](https://github.com/ashish797/gbrow/blob/main/src/cookie-import-browser.ts): `src/cookie-import-browser.ts`
- [Cookie picker UI](https://github.com/ashish797/gbrow/blob/main/src/cookie-picker-ui.ts): `src/cookie-picker-ui.ts`

### Shared runtime

- [Activity tracking](https://github.com/ashish797/gbrow/blob/main/src/activity.ts): `src/activity.ts`
- [Event buffers](https://github.com/ashish797/gbrow/blob/main/src/buffers.ts): `src/buffers.ts`
- [Runtime configuration](https://github.com/ashish797/gbrow/blob/main/src/config.ts): `src/config.ts`
- [Navigation URL checks](https://github.com/ashish797/gbrow/blob/main/src/url-validation.ts): `src/url-validation.ts`
- [Platform utilities](https://github.com/ashish797/gbrow/blob/main/src/platform.ts): `src/platform.ts`

### Other components

- **AI agent**
- **Chromium browser**

## Connections

- AI agent → HTTP server: sends HTTP commands (evidence: `README.md`)
- HTTP server → Browser manager: dispatches browser work (evidence: `src/server.ts`)
- HTTP server → Page reading: dispatches reads (evidence: `src/server.ts`)
- HTTP server → Navigation and interaction: dispatches interactions (evidence: `src/server.ts`)
- HTTP server → Tabs and session tools: dispatches meta commands (evidence: `src/server.ts`)
- HTTP server → Accessibility snapshots: requests watch snapshots (evidence: `src/server.ts`)
- HTTP server → Cookie picker routes: routes cookie requests (evidence: `src/server.ts`)
- HTTP server → CDP inspector: runs inspection (evidence: `src/server.ts`)
- HTTP server → Runtime configuration: loads configuration (evidence: `src/server.ts`)
- Browser manager → Navigation URL checks: validates navigation (evidence: `src/browser-manager.ts`)
- Browser manager → Chromium browser: controls browser (evidence: `README.md`)
- Navigation and interaction → Browser manager: uses browser session (evidence: `src/write-commands.ts`)
- Navigation and interaction → Navigation URL checks: validates destinations (evidence: `src/write-commands.ts`)
- Navigation and interaction → Browser cookie import: imports cookies (evidence: `src/write-commands.ts`)
- Navigation and interaction → CDP inspector: undoes style edits (evidence: `src/write-commands.ts`)
- Page reading → Browser manager: reads browser session (evidence: `src/read-commands.ts`)
- Page reading → CDP inspector: inspects elements (evidence: `src/read-commands.ts`)
- Tabs and session tools → Browser manager: manages tabs and state (evidence: `src/meta-commands.ts`)
- Tabs and session tools → Accessibility snapshots: requests snapshots (evidence: `src/meta-commands.ts`)
- Tabs and session tools → Page reading: gets page text (evidence: `src/meta-commands.ts`)
- Accessibility snapshots → Browser manager: stores element refs (evidence: `src/snapshot.ts`)
- Cookie picker routes → Browser cookie import: lists and imports cookies (evidence: `src/cookie-picker-routes.ts`)
- Cookie picker routes → Cookie picker UI: serves picker UI (evidence: `src/cookie-picker-routes.ts`)
- Activity tracking → Event buffers: uses shared buffers (evidence: `src/activity.ts`)
- Page reading → Platform utilities: checks safe paths (evidence: `src/read-commands.ts`)
- Accessibility snapshots → Platform utilities: checks safe paths (evidence: `src/snapshot.ts`)
- Navigation and interaction → Platform utilities: checks safe paths (evidence: `src/write-commands.ts`)
- Sidebar agent → HTTP server: may integrate