surf-cli Codebase
Architecture
cli.cjs --socket:/tmp/surf.sock--> host.cjs --native-msg--> service-worker/index.ts --CDP/chrome-APIs--> browser
Add CLI Command
- Add to
TOOLS in native/cli.cjs:158 (args, opts, examples)
- Add handler in src/service-worker/index.ts:50
handleMessage() switch
- CDP op? → add method src/cdp/controller.ts:60
- DOM interaction? → add handler src/content/accessibility-tree.ts:99
Add CDP Operation
- Add method to
CDPController class src/cdp/controller.ts:60
- Use
this.send(tabId, "Domain.method", params)
- Handle events in
handleCDPEvent() if needed
Core Files
src/service-worker/index.ts (~2500L) - Central msg router, CDP ops, screenshot cache, tab registry
- Msg types: EXECUTE_CLICK, EXECUTE_TYPE, READ_PAGE, EXECUTE_SCREENSHOT
- Screenshot cache: generateScreenshotId(), cacheScreenshot(), getScreenshot()
- Tab names: tabNameRegistry Map<name,tabId>
src/cdp/controller.ts (~1000L) - CDP wrapper, CDPController class
- Mouse: click(), rightClick(), doubleClick(), hover(), drag()
- Keyboard: type(), pressKey(), pressKeyChord()
- Screenshots: captureScreenshot(), captureRegion()
- Network/Console: enableNetworkTracking(), getNetworkRequests(), getResponseBody(), subscribeToNetwork(), enableConsoleTracking(), getConsoleMessages()
- Emulation: emulateNetwork(), emulateCPU(), emulateGeolocation()
src/content/accessibility-tree.ts (~1900L) - Content script, generates a11y tree YAML, element interactions
- Handlers: GENERATE_ACCESSIBILITY_TREE, CLICK_ELEMENT, FORM_INPUT, GET_ELEMENT_COORDINATES, WAIT_FOR_ELEMENT, WAIT_FOR_URL
- Element refs: e1, e2... in window.__piRefs for stable references
native/cli.cjs (~2100L) - CLI parser, socket client
- TOOLS: command defs with args/opts
- ALIASES: shortcut→command map
- AUTO_SCREENSHOT_TOOLS: commands that auto-capture
- parseArgs(), sendRequest()
native/host.cjs (~2100L) - Socket server, AI integration
- handleToolRequest(): main dispatcher
- mapToolToMessage(): tool→extension msg converter
- queueAiRequest(): AI request serialization
- AI clients: chatgptClient, geminiClient, perplexityClient
src/native/port-manager.ts - Extension↔native messaging, auto-reconnect, request/response tracking
Message Flow
- CLI:
surf click e5
- cli.cjs parses → socket → host.cjs
- host.cjs routes to EXECUTE_CLICK msg
- Native msg → service-worker/index.ts
- Service worker: CDP (cdp/controller.ts) or content script (chrome.tabs.sendMessage)
- Response flows back to CLI
Debug
- Extension logs: chrome://extensions → Service Worker → Console
- Host logs: /tmp/surf-host.log
- CLI raw output:
--json flag
Test
npm run build # Build ext
npm test # Run tests
npm run test:coverage # Coverage
Element Refs
A11y tree assigns e1, e2... during READ_PAGE. Stored window.__piRefs. Reset each read command.
Network Capture
- CDP captures via Network.* events cdp/controller.ts:73
- Storage: /tmp/surf/requests.jsonl
- Formatters: native/formatters/network.cjs:259
Build/Install
npm run dev # Watch mode
npm run build # Prod → dist/
# Load dist/ as unpacked ext
surf install <ext-id> # Register native host
Gotchas
- CDP attach: 100-500ms first time/tab
- chrome:// pages restricted
- Content script needs page refresh on existing tabs
- Screenshots auto-resize 1200px unless --full
1---2name: surf-codebase3description: Navigate and modify surf-cli codebase - Chrome extension + native host for AI browser automation. Use for surf-cli code work, architecture questions, implementing browser control/CDP/accessibility/network features.4metadata:5 source: https://skillmd.com/skills/nicobailon/surf-codebase6---78# surf-cli Codebase910## Architecture11```12cli.cjs --socket:/tmp/surf.sock--> host.cjs --native-msg--> service-worker/index.ts --CDP/chrome-APIs--> browser13```1415## Add CLI Command16171. Add to `TOOLS` in native/cli.cjs:158 (args, opts, examples)182. Add handler in src/service-worker/index.ts:50 `handleMessage()` switch193. CDP op? → add method src/cdp/controller.ts:60204. DOM interaction? → add handler src/content/accessibility-tree.ts:992122## Add CDP Operation23241. Add method to `CDPController` class src/cdp/controller.ts:60252. Use `this.send(tabId, "Domain.method", params)`263. Handle events in `handleCDPEvent()` if needed2728## Core Files2930**src/service-worker/index.ts** (~2500L) - Central msg router, CDP ops, screenshot cache, tab registry31- Msg types: EXECUTE_CLICK, EXECUTE_TYPE, READ_PAGE, EXECUTE_SCREENSHOT32- Screenshot cache: generateScreenshotId(), cacheScreenshot(), getScreenshot()33- Tab names: tabNameRegistry Map<name,tabId>3435**src/cdp/controller.ts** (~1000L) - CDP wrapper, CDPController class36- Mouse: click(), rightClick(), doubleClick(), hover(), drag()37- Keyboard: type(), pressKey(), pressKeyChord()38- Screenshots: captureScreenshot(), captureRegion()39- Network/Console: enableNetworkTracking(), getNetworkRequests(), getResponseBody(), subscribeToNetwork(), enableConsoleTracking(), getConsoleMessages()40- Emulation: emulateNetwork(), emulateCPU(), emulateGeolocation()4142**src/content/accessibility-tree.ts** (~1900L) - Content script, generates a11y tree YAML, element interactions43- Handlers: GENERATE_ACCESSIBILITY_TREE, CLICK_ELEMENT, FORM_INPUT, GET_ELEMENT_COORDINATES, WAIT_FOR_ELEMENT, WAIT_FOR_URL44- Element refs: e1, e2... in window.__piRefs for stable references4546**native/cli.cjs** (~2100L) - CLI parser, socket client47- TOOLS: command defs with args/opts48- ALIASES: shortcut→command map49- AUTO_SCREENSHOT_TOOLS: commands that auto-capture50- parseArgs(), sendRequest()5152**native/host.cjs** (~2100L) - Socket server, AI integration53- handleToolRequest(): main dispatcher54- mapToolToMessage(): tool→extension msg converter55- queueAiRequest(): AI request serialization56- AI clients: chatgptClient, geminiClient, perplexityClient5758**src/native/port-manager.ts** - Extension↔native messaging, auto-reconnect, request/response tracking5960## Message Flow61621. CLI: `surf click e5`632. cli.cjs parses → socket → host.cjs643. host.cjs routes to EXECUTE_CLICK msg654. Native msg → service-worker/index.ts665. Service worker: CDP (cdp/controller.ts) or content script (chrome.tabs.sendMessage)676. Response flows back to CLI6869## Debug7071- Extension logs: chrome://extensions → Service Worker → Console72- Host logs: /tmp/surf-host.log73- CLI raw output: `--json` flag7475## Test7677```bash78npm run build # Build ext79npm test # Run tests80npm run test:coverage # Coverage81```8283## Element Refs8485A11y tree assigns e1, e2... during READ_PAGE. Stored window.__piRefs. Reset each `read` command.8687## Network Capture8889- CDP captures via Network.* events cdp/controller.ts:7390- Storage: /tmp/surf/requests.jsonl91- Formatters: native/formatters/network.cjs:2599293## Build/Install9495```bash96npm run dev # Watch mode97npm run build # Prod → dist/98# Load dist/ as unpacked ext99surf install <ext-id> # Register native host100```101102## Gotchas103104- CDP attach: 100-500ms first time/tab105- chrome:// pages restricted106- Content script needs page refresh on existing tabs107- Screenshots auto-resize 1200px unless --full