ego-lite-bridge

Windows-compatible replacement for the ego lite browser runtime.

The ego lite browser by CitroLabs lets AI agents (Claude Code, Codex, Cursor) work alongside you in isolated browser Spaces. It's currently macOS-only.

ego-lite-bridge bridges the open-source ego-browser CLI to standard Chrome on Windows via CDP (Chrome DevTools Protocol), so you can use ego-browser on Windows today.

How it works

AI Agent (Claude Code / Codex)
    ↓ Bash: ego-browser nodejs <<'EOF' ... EOF
ego-browser npm package (upstream, MIT)
    ↓ expects globalThis.ego.sendCDPMessage()
ego-lite-bridge (this package)
    ↓ CDP WebSocket
Chrome / Chromium (Windows)

The bridge implements globalThis.ego — the API that the ego-browser package expects — using Puppeteer to control a standard Chrome instance.

Status

This is an early-stage project. Core functionality works:

• ✅ Chrome launch & CDP transport
• ✅ Tab management (list, open, close, switch)
• ✅ Task Space system (isolated BrowserContexts, ownership model)
• ✅ Semantic page snapshots (CDP Accessibility tree)
• ✅ Screenshots
• ✅ Event buffer
• ✅ Click highlight animation
• 🔄 WIP: full ego-browser integration testing
• 🔄 WIP: site learnings integration

Prerequisites

• Windows 10/11 (also works on macOS/Linux for testing)
• Node.js >= 22
• Google Chrome (any recent version)

Quick Start

1. Install

cd ego-lite-bridge
powershell -ExecutionPolicy Bypass -File install.ps1 -RegisterPath

Or manually:

cd ego-lite-bridge
npm install --ignore-scripts
npm run build

2. Verify

node dist/index.js --doctor

3. Set up login state (one-time)

On modern Chrome (127+ App-Bound Encryption / 136+ debug-port restriction), the bridge cannot inherit your real Chrome's logged-in sessions. Instead, log into sites once in the bridge's dedicated automation profile:

node dist/index.js --setup-login

A visible Chrome window opens. Log in to the sites your agent needs (GitHub, Google, etc.), then press Ctrl+C (or close the window). Your login state is saved and reused by every future agent run — with zero credentials handed to the model.

4. Start the bridge daemon

node dist/daemon.js

Keep this terminal running. The daemon keeps Chrome warm and recovers from crashes. Health check: curl http://127.0.0.1:9230/.

5. Use with ego-browser

In another terminal, with the daemon running:

ego-browser nodejs <<'EOF'
const task = await useOrCreateTaskSpace('test')
await openOrReuseTab('https://github.com', { wait: true })
console.log(await snapshot())
EOF

Architecture

ego-lite-bridge/
├── src/
│   ├── index.ts              # Entry point — globalThis.ego implementation
│   └── ego-runtime/
│       ├── cdp-transport.ts   # CDP message passing (ego.sendCDPMessage)
│       ├── tab-manager.ts     # Tab CRUD via puppeteer
│       ├── task-space.ts      # Isolated BrowserContext management
│       ├── snapshot.ts        # Semantic page snapshots via CDP AXTree
│       ├── event-buffer.ts    # Buffered CDP event queue
│       ├── launcher.ts        # Chrome detection and launch
│       └── extension-relay.ts # WebSocket relay for the Chrome Extension
├── extension/                 # MV3 Chrome Extension (chrome.debugger bridge)
│   ├── manifest.json
│   └── background.js
├── dist/                      # Build output
├── install.ps1                # Windows installer
├── package.json
└── tsconfig.json

CLI Options

ego-lite-bridge [options]

Options:
  --port PORT          Chrome DevTools debugging port (default: 9222)
  --headless           Run Chrome in headless mode
  --user-data-dir DIR  Chrome profile directory (default: dedicated automation profile)
  --chrome-path PATH   Custom path to Chrome executable
  --use-running-chrome Attach to running Chrome (live login sync; limited on Chrome 136+)
  --seed-from-chrome   Best-effort copy of user Chrome profile on first launch
  --setup-login        Open Chrome to log into sites once; state persists for agents
  --args LIST          Comma-separated extra Chrome CLI args
  --doctor             Check that Chrome is available
  -h, --help           Show this help

Login state: the honest picture

ego lite (macOS) inherits your real browser's logins because it controls its own Chromium kernel. This bridge relies on standard Chrome, where Google has deliberately closed that door:

• Chrome 127+ App-Bound Encryption (v20) — session cookies are encrypted against the Chrome install + profile path. Copying them to a new profile makes them undecryptable; Chrome silently drops them on launch.
• Chrome 136+ — --remote-debugging-port/--remote-debugging-pipe are ignored against the default user-data-dir (DevTools remote debugging requires a non-default data directory).

There are two ways to get login state, depending on what you need:

Option A — reuse your real login (Chrome Extension)

This is the closest to ego lite's macOS behavior: drive your already-logged-in tabs directly, with zero credentials handed to the model.

1. Load the extension: chrome://extensions → enable "Developer mode" → "Load unpacked" → select the extension/ directory.

2. In the browser, open the site you're logged into (e.g. GitHub).

3. Run with --extension:

   ego-browser nodejs --extension <<'EOF'
   const info = await pageInfo()
   console.log(info.url)             // your logged-in URL, not /login
   await goto('https://github.com/notifications', { waitUntil: 'load' })
   console.log(await snapshot())
   EOF

Notes:

• Chrome shows a "… is debugging this browser" banner while attached — expected.
• All tabs share your profile, so Task Spaces collapse to a single space.
• Only Chrome/Edge are supported (they expose chrome.debugger).

Option B — dedicated profile (one-time login)

The default, most stable path. Log in once in a dedicated automation profile, then reuse it forever:

node dist/index.js --setup-login

For background on why these two paths exist, see VALIDATION-REPORT.md.

Limitations

Compared to the native ego lite macOS browser:

1. Snapshot quality: Uses standard CDP Accessibility.getFullAXTree instead of kernel-level DOM customization. Snapshot output is functional but may use more tokens.
2. Logon state inheritance: Not possible by profile copy on modern Chrome. Use --setup-login (dedicated profile) or --extension (reuse your real tabs) instead.
3. No kernel-level customization: The ego lite browser's "strongest snapshot" feature cannot be replicated without modifying Chromium itself.
4. Integration with ego-browser: The bridge runs as a separate long-lived process that ego-browser CLI connects to. This differs from the native macOS setup where the app bundles everything.

License

MIT — see LICENSE in parent repo.

Related

• ego-lite — upstream repo (MIT-licensed skill + npm package)
• ego lite website — official site and docs