What Are the Two Main Components of the ego-lite Architecture?

The ego-lite architecture consists of two tightly-coupled parts: a native macOS browser embedding a custom Chromium build, and a Node.js CDP harness called the ego-browser Skill that serves as a programmable bridge between AI agents and the browser runtime.

The citrolabs/ego-lite repository enables AI agents to perform browser automation while users retain full control of their personal tabs. The ego-lite architecture achieves this through a clear separation between the execution environment (the native browser) and the control interface (the JavaScript skill package), communicating exclusively via the Chrome DevTools Protocol (CDP).

Component 1: The ego-lite Browser (Native Runtime)

The first pillar of the ego-lite architecture is the native macOS browser application. This component embeds a custom Chromium build and stores all browser state—including user logins, cookies, extensions, and bookmarks—within its own isolated storage context.

CDP Transport and Execution

According to the source code in package/ego-browser/src/browser-runtime.ts, the native browser exposes a CDP transport via the ego.sendCDPMessage interface. This protocol endpoint allows external processes to dispatch debugging commands directly to the Chromium engine. The browser handles page rendering, JavaScript execution, and network management while maintaining strict boundaries between different automation contexts.

Task Space Isolation

The native runtime implements Task Spaces as isolation mechanisms. Each task space represents a dedicated browsing environment with separate session storage, cookies, and local state. When agents create a new task space using nav.newTaskSpace(), the native browser instantiates a fresh context that remains invisible to the user's personal tabs and other concurrent agent operations.

Component 2: The ego-browser Skill (Programmatic Bridge)

Located in package/ego-browser/, the second component is an open-source JavaScript package that implements the ego-browser skill. This Node.js harness converts high-level agent instructions into low-level CDP messages dispatched to the native browser.

CDP Client Implementation

The file package/ego-browser/src/browser-runtime.ts implements the lightweight CDP client that manages session attachment, event buffering, and dialog tracking. It wraps the raw ego.sendCDPMessage transport exposed by the native application, handling connection lifecycle and message serialization.

Helper API Architecture

The package/ego-browser/src/helpers.ts file defines the agent-facing API, exporting functions such as nav(), click(), fill(), and snapshot(). These abstractions hide CDP complexity from AI agents. Task space management logic resides in package/ego-browser/src/taskspace.ts, which handles creation, claiming, switching, and cleanup of isolated environments through the completeTaskSpace() function.

How the Components Interact

The two components communicate exclusively via CDP, ensuring agent code remains sandboxed from user browsing data. Below is a representative workflow executed within the skill's runtime (CLI entry point src/run.ts):

// Helpers are automatically injected when the skill runs
const { nav, click, fill, snapshot, completeTaskSpace } = egoBrowserHelpers;

// Create an isolated task space in the native browser
const space = await nav.newTaskSpace('lead-generation');

// Navigate within the isolated context
await nav.goto('https://example.com/contact', { taskSpace: space.id });

// Perform automated interactions
await fill('input[name="email"]', 'lead@mycompany.com', { taskSpace: space.id });
await click('button[type="submit"]', { taskSpace: space.id });

// Capture compressed DOM/CSS snapshot for LLM processing
const pageSnapshot = await snapshot({ taskSpace: space.id });

// Terminate the isolated environment
await completeTaskSpace(space.id, { keep: false });

Key implementation details include:

• All helper functions require an explicit { taskSpace } option to enforce isolation boundaries
• snapshot returns a compressed representation of DOM structure, CSS, and layout data
• package/ego-browser/src/index.ts wires the public helpers into the injected globalThis.ego runtime object

Summary

• The ego-lite architecture comprises a native macOS browser runtime and a Node.js skill package that together enable secure AI browser automation.
• The native browser component handles rendering, state persistence, and CDP command execution via the ego.sendCDPMessage interface.
• The ego-browser skill provides the nav(), click(), fill(), and snapshot() helpers that translate agent intentions into CDP messages.
• Task Spaces provide process-level isolation, ensuring agent sessions cannot access user data or interfere with other automation contexts.
• Communication occurs exclusively through the Chrome DevTools Protocol, eliminating the need for external browser drivers like Selenium or Playwright.

Frequently Asked Questions

What is CDP and why does ego-lite use it?

CDP (Chrome DevTools Protocol) is a remote debugging interface native to Chromium browsers. The ego-lite architecture leverages CDP because it provides granular, low-level control over page navigation, DOM manipulation, and network interception without the overhead of additional browser drivers. The native browser exposes CDP through ego.sendCDPMessage, while the skill implements the client transport in package/ego-browser/src/browser-runtime.ts.

How does task space isolation work?

Task spaces are isolated browsing environments created via nav.newTaskSpace() and managed in package/ego-browser/src/taskspace.ts. Each space maintains separate cookies, localStorage, and session state within the native browser. The architecture requires every helper function call to specify a taskSpace parameter, ensuring CDP commands execute within the correct isolation boundary and preventing data leakage between agent sessions or user tabs.

Is the native browser component available for platforms other than macOS?

Currently, the native browser is macOS-only as implemented in the citrolabs/ego-lite source. The architecture relies on macOS-specific mechanisms for embedding the custom Chromium build and managing the CDP transport layer. While the Node.js skill package could execute on other platforms, it requires connection to the native macOS browser to perform any browser automation.

How do AI agents communicate with the browser runtime?

Agents communicate through the helper functions defined in package/ego-browser/src/helpers.ts. When an agent invokes click() or fill(), the skill serializes these commands into CDP protocol messages via the transport layer in browser-runtime.ts. These messages traverse the globalThis.ego runtime bridge to reach the native browser's ego.sendCDPMessage endpoint, which executes the actions within the designated task space.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}