dom0 — Extension Setup

Guide for installing and configuring the dom0 Chrome extension.

Prerequisites

• Chrome browser (version 116+)
• Node.js 20+
• pnpm 9+

Building the Extension

1. Build All Packages

From the monorepo root:

# Build dom0 core, CLI, and extension
pnpm dom0:build

This builds:

• packages/dom0/dist/ — Core types
• packages/dom0-cli/dist/ — CLI
• packages/dom0-extension/dist/ — Extension bundle

2. Verify Build Output

ls packages/dom0-extension/dist/
# Should contain:
# manifest.json
# background.js
# icons/

Installing the Extension

1. Open Chrome Extensions

Navigate to:

chrome://extensions

Or: Menu → Extensions → Manage Extensions

2. Enable Developer Mode

Toggle "Developer mode" in the top-right corner.

3. Load Unpacked Extension

1. Click "Load unpacked"
2. Select: packages/dom0-extension/dist
3. Click "Select Folder"

4. Verify Installation

You should see:

• dom0 in your extensions list
• Extension icon in the Chrome toolbar

Verifying Connection

1. Test with CLI

# Start daemon and test connection
dom0 ping

Expected output:

Pong! (42ms)

2. Check Status

dom0 status

Expected output:

Daemon: Running (port 9222)
Extension: Connected (v0.1.0)
Active tab: New Tab (chrome://newtab)

3. Test a Snapshot

# Navigate somewhere first
dom0 navigate https://example.com
dom0 snapshot

Expected output:

URL: https://example.com
Title: Example Domain

@d1  link "More information..."

Troubleshooting

Extension Not Connecting

Symptoms:

Error: Extension not connected

Solutions:

1. Refresh the extension:

   • Go to chrome://extensions
   • Find dom0
   • Click the refresh icon (↻)

2. Check service worker:

   • Click "service worker" link under dom0
   • Look for errors in DevTools console
   • Common issue: WebSocket connection errors

3. Verify daemon is running:

   bash

   dom0 status

4. Restart daemon:

   bash

   dom0 stop
   dom0 ping  # This auto-starts daemon

Service Worker Errors

Check the console:

1. Go to chrome://extensions
2. Click "service worker" under dom0
3. View console for errors

Common errors:

WebSocket connection to 'ws://localhost:9222/' failed

→ Daemon not running. Run dom0 ping to start it.

Uncaught (in promise) Error: Could not establish connection

→ Rebuild extension: pnpm --filter @bot0/dom0-extension build

Port Already in Use

Error: Port 9222 already in use

Solutions:

1. Kill existing process:

   bash

   lsof -i :9222
   kill <PID>

2. Or use dom0 stop:

   bash

   dom0 stop
   dom0 ping

Chrome Debugger Permission

When using dom0, Chrome may show:

"dom0" started debugging this browser

This is expected. The extension needs debugger access to:

• Get the accessibility tree
• Dispatch input events
• Navigate pages

Click "Cancel" to deny (breaks dom0) or just ignore the banner.

Development Setup

Watch Mode

For development with auto-rebuild:

# Terminal 1: Watch all dom0 packages
pnpm dom0:dev

# Terminal 2: Test commands
dom0 snapshot

Rebuilding After Changes

# Rebuild extension
pnpm --filter @bot0/dom0-extension build

# Reload in Chrome
# Go to chrome://extensions → dom0 → refresh icon

Viewing Extension Logs

1. Go to chrome://extensions
2. Find dom0
3. Click "service worker" link
4. DevTools opens with console

Look for:

[dom0] Extension v0.1.0 initializing...
[dom0] Connected to CLI
[dom0] Extension registered (v0.1.0)

Extension Permissions

The manifest requests these permissions:

Why These Permissions?

debugger — Required for:

• Accessibility.getFullAXTree — Get page elements
• Input.dispatchMouseEvent — Click elements
• Input.dispatchKeyEvent — Type text
• Page.navigate — Go to URLs
• Page.captureScreenshot — Take screenshots

tabs — Required for:

• Getting current URL and title
• Listing open tabs
• Switching between tabs

activeTab — Required for:

• Accessing the currently active tab
• Attaching debugger to active tab

Uninstalling

Remove Extension

1. Go to chrome://extensions
2. Find dom0
3. Click "Remove"

Stop Daemon

dom0 stop

Clean Build Artifacts

pnpm --filter @bot0/dom0-extension clean
pnpm --filter @bot0/dom0-cli clean

Security Notes

Local Only

The daemon only accepts connections from localhost:

new WebSocketServer({
  host: 'localhost',  // Not exposed to network
  port: 9222
});

No Data Storage

dom0 does not:

• Store browsing history
• Save passwords or cookies
• Log page content
• Send data externally

Debugger Banner

Chrome shows a banner when debugging is active:

"dom0" started debugging this browser

This is a Chrome security feature and cannot be hidden.

Known Limitations

Service Worker Sleep

Chrome MV3 service workers can sleep after 30 seconds of inactivity. The extension handles this by:

1. Reconnecting WebSocket on wake
2. Re-registering with daemon
3. Restoring tab state

If you experience issues after idle time, refresh the extension.