# sawyerhood/dev-browser architecture

> Architecture diagram of the GitHub repository sawyerhood/dev-browser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sawyerhood/dev-browser
- Repository: https://github.com/sawyerhood/dev-browser

## Overview

dev-browser lets coding agents run JavaScript against persistent Chrome pages through a CLI or MCP server. The main workflow sends a script request to a warm daemon, which manages a launched or attached browser, extends Puppeteer pages with agent-oriented helpers, and streams results back. README documents page snapshots, actions, screenshots, load waiting, persistent named tabs, and launch-or-attach modes. Edges reflect the supplied excerpts, source-index references, or README; unsampled subsystems are included where documented, without asserting unshown internal calls.

Main entry points: [`src/daemon/browsers.ts`](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/browsers.ts) (Browser manager), [`src/daemon/main.ts`](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/main.ts) (Daemon service), [`src/daemon/run.ts`](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/run.ts) (Script execution), [`src/page/extend.ts`](https://github.com/sawyerhood/dev-browser/blob/main/src/page/extend.ts) (Puppeteer extensions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Agent interfaces"]
  node_cli["CLI commands<br/>[main.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_client["Daemon client<br/>[client.ts]"]
end

subgraph group_daemon["Daemon runtime"]
  node_daemon_main["Daemon service<br/>[main.ts]"]
  node_run["Script execution<br/>[run.ts]"]
  node_run_context["Per-run context<br/>[run-context.ts]"]
  node_transform["Script transform<br/>[transform.ts]"]
end

subgraph group_browser["Browser lifecycle"]
  node_browser_manager["Browser manager<br/>[browsers.ts]"]
  node_page_registry["Page registry<br/>[pages.ts]"]
  node_launch["Launch source<br/>[launch.ts]"]
  node_cdp["CDP attach<br/>[cdp.ts]"]
  node_socket_source["Socket attach<br/>[socket.ts]"]
end

subgraph group_page["Page automation"]
  node_page_extend["Puppeteer extensions<br/>[extend.ts]"]
  node_snapshot["Accessibility snapshots<br/>[snapshot.ts]"]
  node_snapshot_inpage["In-page snapshot engine<br/>[inpage.ts]"]
  node_snapshot_refs["Snapshot refs<br/>[ref-handler.ts]"]
  node_fill["Form filling<br/>[fill.ts]"]
  node_shot["Page screenshots<br/>[shot.ts]"]
  node_load_wait["Load waiting<br/>[wait-for-load.ts]"]
end

subgraph group_shared["Shared services"]
  node_config["Configuration<br/>[config.ts]"]
  node_paths["Runtime paths<br/>[paths.ts]"]
  node_protocol["Wire protocol<br/>[protocol.ts]"]
  node_chrome_discovery["Chrome discovery<br/>[chrome.ts]"]
  node_logger["Daemon logging<br/>[log.ts]"]
end

node_agent(("Coding agent"))
node_chrome(("Chrome / Chromium"))

node_agent -->|"runs scripts"| node_cli
node_agent -->|"invokes tools"| node_mcp
node_cli -->|"sends requests"| node_client
node_mcp -->|"sends requests"| node_client
node_client -->|"connects to"| node_daemon_main
node_daemon_main -->|"dispatches to"| node_browser_manager
node_daemon_main -->|"dispatches runs"| node_run
node_run -->|"uses browsers"| node_browser_manager
node_run -->|"transforms scripts"| node_transform
node_run -->|"establishes context"| node_run_context
node_run -->|"extends pages"| node_page_extend
node_browser_manager -->|"manages pages"| node_page_registry
node_browser_manager -->|"launches via"| node_launch
node_browser_manager -->|"attaches via"| node_cdp
node_browser_manager -->|"attaches via"| node_socket_source
node_launch -->|"finds executable"| node_chrome_discovery
node_chrome_discovery -->|"locates"| node_chrome
node_page_extend -->|"provides snapshot"| node_snapshot
node_page_extend -->|"provides filling"| node_fill
node_page_extend -->|"provides screenshots"| node_shot
node_page_extend -->|"provides waiting"| node_load_wait
node_snapshot -->|"evaluates in page"| node_snapshot_inpage
node_snapshot -->|"resolves refs"| node_snapshot_refs
node_daemon_main -->|"loads settings"| node_config
node_daemon_main -->|"logs events"| node_logger
node_client -->|"encodes frames"| node_protocol
node_daemon_main -->|"handles messages"| node_protocol
node_config -->|"reads config path"| node_paths
node_browser_manager -->|"uses settings"| node_config
node_browser_manager -->|"uses runtime paths"| node_paths

click node_cli "https://github.com/sawyerhood/dev-browser/blob/main/src/cli/main.ts"
click node_mcp "https://github.com/sawyerhood/dev-browser/blob/main/src/mcp/server.ts"
click node_client "https://github.com/sawyerhood/dev-browser/blob/main/src/cli/client.ts"
click node_daemon_main "https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/main.ts"
click node_run "https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/run.ts"
click node_run_context "https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/run-context.ts"
click node_transform "https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/transform.ts"
click node_browser_manager "https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/browsers.ts"
click node_page_registry "https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/pages.ts"
click node_launch "https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/sources/launch.ts"
click node_cdp "https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/sources/cdp.ts"
click node_socket_source "https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/sources/socket.ts"
click node_page_extend "https://github.com/sawyerhood/dev-browser/blob/main/src/page/extend.ts"
click node_snapshot "https://github.com/sawyerhood/dev-browser/blob/main/src/page/snapshot/snapshot.ts"
click node_snapshot_inpage "https://github.com/sawyerhood/dev-browser/blob/main/src/page/snapshot/inpage.ts"
click node_snapshot_refs "https://github.com/sawyerhood/dev-browser/blob/main/src/page/snapshot/ref-handler.ts"
click node_fill "https://github.com/sawyerhood/dev-browser/blob/main/src/page/fill.ts"
click node_shot "https://github.com/sawyerhood/dev-browser/blob/main/src/page/shot.ts"
click node_load_wait "https://github.com/sawyerhood/dev-browser/blob/main/src/page/wait-for-load.ts"
click node_config "https://github.com/sawyerhood/dev-browser/blob/main/src/shared/config.ts"
click node_paths "https://github.com/sawyerhood/dev-browser/blob/main/src/shared/paths.ts"
click node_protocol "https://github.com/sawyerhood/dev-browser/blob/main/src/shared/protocol.ts"
click node_chrome_discovery "https://github.com/sawyerhood/dev-browser/blob/main/src/shared/chrome.ts"
click node_logger "https://github.com/sawyerhood/dev-browser/blob/main/src/shared/log.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_cli,node_mcp,node_client toneBlue
class node_daemon_main,node_run,node_run_context,node_transform toneAmber
class node_browser_manager,node_page_registry,node_launch,node_cdp,node_socket_source toneMint
class node_page_extend,node_snapshot,node_snapshot_inpage,node_snapshot_refs,node_fill,node_shot,node_load_wait toneRose
class node_config,node_paths,node_protocol,node_chrome_discovery,node_logger,node_agent,node_chrome toneIndigo
```

## Components

### Agent interfaces

- [CLI commands](https://github.com/sawyerhood/dev-browser/blob/main/src/cli/main.ts): `src/cli/main.ts`
- [MCP server](https://github.com/sawyerhood/dev-browser/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [Daemon client](https://github.com/sawyerhood/dev-browser/blob/main/src/cli/client.ts): `src/cli/client.ts`

### Daemon runtime

- [Daemon service](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/main.ts): `src/daemon/main.ts`
- [Script execution](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/run.ts): `src/daemon/run.ts`
- [Per-run context](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/run-context.ts): `src/daemon/run-context.ts`
- [Script transform](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/transform.ts): `src/daemon/transform.ts`

### Browser lifecycle

- [Browser manager](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/browsers.ts): `src/daemon/browsers.ts`
- [Page registry](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/pages.ts): `src/daemon/pages.ts`
- [Launch source](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/sources/launch.ts): `src/daemon/sources/launch.ts`
- [CDP attach](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/sources/cdp.ts): `src/daemon/sources/cdp.ts`
- [Socket attach](https://github.com/sawyerhood/dev-browser/blob/main/src/daemon/sources/socket.ts): `src/daemon/sources/socket.ts`

### Page automation

- [Puppeteer extensions](https://github.com/sawyerhood/dev-browser/blob/main/src/page/extend.ts): `src/page/extend.ts`
- [Accessibility snapshots](https://github.com/sawyerhood/dev-browser/blob/main/src/page/snapshot/snapshot.ts): `src/page/snapshot/snapshot.ts`
- [In-page snapshot engine](https://github.com/sawyerhood/dev-browser/blob/main/src/page/snapshot/inpage.ts): `src/page/snapshot/inpage.ts`
- [Snapshot refs](https://github.com/sawyerhood/dev-browser/blob/main/src/page/snapshot/ref-handler.ts): `src/page/snapshot/ref-handler.ts`
- [Form filling](https://github.com/sawyerhood/dev-browser/blob/main/src/page/fill.ts): `src/page/fill.ts`
- [Page screenshots](https://github.com/sawyerhood/dev-browser/blob/main/src/page/shot.ts): `src/page/shot.ts`
- [Load waiting](https://github.com/sawyerhood/dev-browser/blob/main/src/page/wait-for-load.ts): `src/page/wait-for-load.ts`

### Shared services

- [Configuration](https://github.com/sawyerhood/dev-browser/blob/main/src/shared/config.ts): `src/shared/config.ts`
- [Runtime paths](https://github.com/sawyerhood/dev-browser/blob/main/src/shared/paths.ts): `src/shared/paths.ts`
- [Wire protocol](https://github.com/sawyerhood/dev-browser/blob/main/src/shared/protocol.ts): `src/shared/protocol.ts`
- [Chrome discovery](https://github.com/sawyerhood/dev-browser/blob/main/src/shared/chrome.ts): `src/shared/chrome.ts`
- [Daemon logging](https://github.com/sawyerhood/dev-browser/blob/main/src/shared/log.ts): `src/shared/log.ts`

### Other components

- **Coding agent**
- **Chrome / Chromium**

## Connections

- Coding agent → CLI commands: runs scripts (evidence: `README.md`)
- Coding agent → MCP server: invokes tools (evidence: `README.md`)
- CLI commands → Daemon client: sends requests (evidence: `src/cli/main.ts`)
- MCP server → Daemon client: sends requests (evidence: `src/mcp/server.ts`)
- Daemon client → Daemon service: connects to (evidence: `src/cli/client.ts`)
- Daemon service → Browser manager: dispatches to (evidence: `src/daemon/main.ts`)
- Daemon service → Script execution: dispatches runs (evidence: `src/daemon/main.ts`)
- Script execution → Browser manager: uses browsers (evidence: `src/daemon/run.ts`)
- Script execution → Script transform: transforms scripts (evidence: `src/daemon/run.ts`)
- Script execution → Per-run context: establishes context (evidence: `src/daemon/run.ts`)
- Script execution → Puppeteer extensions: extends pages (evidence: `src/daemon/run.ts`)
- Browser manager → Page registry: manages pages (evidence: `src/daemon/browsers.ts`)
- Browser manager → Launch source: launches via (evidence: `src/daemon/browsers.ts`)
- Browser manager → CDP attach: attaches via (evidence: `src/daemon/browsers.ts`)
- Browser manager → Socket attach: attaches via (evidence: `src/daemon/browsers.ts`)
- Launch source → Chrome discovery: finds executable (evidence: `src/daemon/sources/launch.ts`)
- Chrome discovery → Chrome / Chromium: locates (evidence: `src/shared/chrome.ts`)
- Puppeteer extensions → Accessibility snapshots: provides snapshot (evidence: `src/page/extend.ts`)
- Puppeteer extensions → Form filling: provides filling (evidence: `src/page/extend.ts`)
- Puppeteer extensions → Page screenshots: provides screenshots (evidence: `src/page/extend.ts`)
- Puppeteer extensions → Load waiting: provides waiting (evidence: `src/page/extend.ts`)
- Accessibility snapshots → In-page snapshot engine: evaluates in page (evidence: `src/page/snapshot/snapshot.ts`)
- Accessibility snapshots → Snapshot refs: resolves refs (evidence: `src/page/snapshot/index.ts`)
- Daemon service → Configuration: loads settings (evidence: `src/daemon/main.ts`)
- Daemon service → Daemon logging: logs events (evidence: `src/daemon/main.ts`)
- Daemon client → Wire protocol: encodes frames (evidence: `src/cli/client.ts`)
- Daemon service → Wire protocol: handles messages (evidence: `src/daemon/main.ts`)
- Configuration → Runtime paths: reads config path (evidence: `src/shared/config.ts`)
- Browser manager → Configuration: uses settings (evidence: `src/daemon/browsers.ts`)
- Browser manager → Runtime paths: uses runtime paths (evidence: `src/daemon/browsers.ts`)
