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

> Discover the two main components of the ego-lite architecture: a custom Chromium browser and a Node.js CDP harness for AI agent browser interaction.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: architecture
- Published: 2026-08-22

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts)):

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.