How sawyerhood/dev-browser works
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: browsers.ts Browser manager · main.ts Daemon service · run.ts Script execution · extend.ts Puppeteer extensions
Components 26
Agent interfaces
- CLI commands
src/cli/main.ts - MCP server
src/mcp/server.ts - Daemon client
src/cli/client.ts
Daemon runtime
- Daemon service
src/daemon/main.ts - Script execution
src/daemon/run.ts - Per-run context
src/daemon/run-context.ts - Script transform
src/daemon/transform.ts
Browser lifecycle
- Browser manager
src/daemon/browsers.ts - Page registry
src/daemon/pages.ts - Launch source
src/daemon/sources/launch.ts - CDP attach
src/daemon/sources/cdp.ts - Socket attach
src/daemon/sources/socket.ts
Page automation
- Puppeteer extensions
src/page/extend.ts - Accessibility snapshots
src/page/snapshot/snapshot.ts - In-page snapshot engine
src/page/snapshot/inpage.ts - Snapshot refs
src/page/snapshot/ref-handler.ts - Form filling
src/page/fill.ts - Page screenshots
src/page/shot.ts - Load waiting
src/page/wait-for-load.ts
Shared services
- Configuration
src/shared/config.ts - Runtime paths
src/shared/paths.ts - Wire protocol
src/shared/protocol.ts - Chrome discovery
src/shared/chrome.ts - Daemon logging
src/shared/log.ts
Other components
- Coding agent
- Chrome / Chromium
Connections 30
- Coding agent → CLI commands: runs scripts
README.md - Coding agent → MCP server: invokes tools
README.md - CLI commands → Daemon client: sends requests
src/cli/main.ts - MCP server → Daemon client: sends requests
src/mcp/server.ts - Daemon client → Daemon service: connects to
src/cli/client.ts - Daemon service → Browser manager: dispatches to
src/daemon/main.ts - Daemon service → Script execution: dispatches runs
src/daemon/main.ts - Script execution → Browser manager: uses browsers
src/daemon/run.ts - Script execution → Script transform: transforms scripts
src/daemon/run.ts - Script execution → Per-run context: establishes context
src/daemon/run.ts - Script execution → Puppeteer extensions: extends pages
src/daemon/run.ts - Browser manager → Page registry: manages pages
src/daemon/browsers.ts - Browser manager → Launch source: launches via
src/daemon/browsers.ts - Browser manager → CDP attach: attaches via
src/daemon/browsers.ts - Browser manager → Socket attach: attaches via
src/daemon/browsers.ts - Launch source → Chrome discovery: finds executable
src/daemon/sources/launch.ts - Chrome discovery → Chrome / Chromium: locates
src/shared/chrome.ts - Puppeteer extensions → Accessibility snapshots: provides snapshot
src/page/extend.ts - Puppeteer extensions → Form filling: provides filling
src/page/extend.ts - Puppeteer extensions → Page screenshots: provides screenshots
src/page/extend.ts - Puppeteer extensions → Load waiting: provides waiting
src/page/extend.ts - Accessibility snapshots → In-page snapshot engine: evaluates in page
src/page/snapshot/snapshot.ts - Accessibility snapshots → Snapshot refs: resolves refs
src/page/snapshot/index.ts - Daemon service → Configuration: loads settings
src/daemon/main.ts - Daemon service → Daemon logging: logs events
src/daemon/main.ts - Daemon client → Wire protocol: encodes frames
src/cli/client.ts - Daemon service → Wire protocol: handles messages
src/daemon/main.ts - Configuration → Runtime paths: reads config path
src/shared/config.ts - Browser manager → Configuration: uses settings
src/daemon/browsers.ts - Browser manager → Runtime paths: uses runtime paths
src/daemon/browsers.ts