# ego‑lite vs ego‑browser Explained: Architecture, Differences, and How They Work Together

> Understand ego-lite vs ego-browser. ego-lite is the Chromium browser binary, while ego-browser is the Node.js SDK for AI agent control via Chrome DevTools Protocol. Learn their architecture and how they work together.

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

---

**ego‑lite is the native Chromium browser binary that users install; ego‑browser is the Node.js SDK that provides AI agents with a programmable JavaScript interface to control that browser via the Chrome DevTools Protocol (CDP).**

Understanding the distinction between **ego‑lite** and **ego‑browser** is essential for developers building AI agents that need to automate web browsers in a human‑shared environment. While the names sound similar, they represent fundamentally different layers of the Citro ecosystem: one is the browser itself, the other is the automation bridge. This article breaks down their architectural separation, key responsibilities, and how they interoperate using the `citrolabs/ego-lite` source code.

## What Is ego‑lite?

**ego‑lite** is the actual **Chromium‑based browser** that end users download and run on their machines. It ships as a native binary (currently available as `.dmg` for macOS, with Windows and Linux builds planned) and provides the visual interface where humans browse the web.

### Core Responsibilities

- Renders web pages, manages tabs and windows, and handles user interactions
- Maintains **Task Spaces** — isolated browsing contexts that keep agent sessions separate from each other and from human browsing
- Preserves login state, cookies, and extensions per Task Space
- Exposes a **CDP (Chrome DevTools Protocol) endpoint** that external programs can connect to

The ego‑lite binary is **closed‑source** and not part of the public repository. The downloadable build includes the `ego-browser` command, but this refers only to the CDP‑enabled browser process — not the JavaScript runtime code.

## What Is ego‑browser?

**ego‑browser** is the **open‑source Node.js runtime and SDK** located in `package/ego-browser/` within the `citrolabs/ego-lite` repository. It acts as the programmable bridge between AI agents and the ego‑lite browser.

### Key Components

| Component | Source File | Purpose |
|-----------|-------------|---------|
| **CLI bootstrap** | [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) | Installs the SDK onto `globalThis`, exposes the `runMain` entry point |
| **Script runner** | [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts) | Reads JavaScript heredocs from STDIN, wraps them in async IIFE, injects helpers |
| **Helper surface** | [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) | High‑level API: `click()`, `goto()`, `snapshot()`, `fill()`, `screenshot()`, Task Space management |
| **CDP runtime** | [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts) | Manages CDP WebSocket transport, session caches, and event buffering |
| **Element resolver** | [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts) | Translates locator strings (`@N`, CSS selectors, XPath, ARIA) into CDP node IDs |
| **Low‑level CDP** | [`src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/cdp-eval.ts) | Direct `cdp()` calls and `js()` evaluation primitives |
| **Site learning** | [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) | Loads per‑site "skill packs" from `skills/ego-browser/learnings/` |

### How Agents Use ego‑browser

Agents invoke ego‑browser through a CLI pattern that pipes JavaScript directly into the runtime:

```bash
ego-browser nodejs <<'EOF'
await useOrCreateTaskSpace("demo");
await goto("https://example.com");
await screenshot({ path: "page.png" });
await completeTaskSpace("demo", { keep: false });
EOF

```

The [`run.ts`](https://github.com/citrolabs/ego-lite/blob/main/run.ts) module captures this heredoc, wraps it in an async function, and executes it with full access to the helper methods exported from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts).

## ego‑lite vs ego‑browser: Side‑by‑Side Comparison

| Aspect | ego‑lite | ego‑browser |
|--------|----------|-------------|
| **Type** | Native Chromium binary (closed‑source) | Node.js NPM package (`package/ego-browser`) |
| **Location** | User's machine, downloaded installer | `citrolabs/ego-lite` repository |
| **Primary role** | Browser UI, rendering, human interaction | Agent automation, CDP command dispatch |
| **Runtime** | Desktop application process | Short‑lived Node.js process per heredoc |
| **State ownership** | Tabs, cookies, logins, Task Spaces | Session handles, CDP connection caches |
| **Installation method** | Download `.dmg` / future installers | `npx skills add citrolabs/ego-lite` |
| **JavaScript execution** | None (no JS runtime included) | Full Node.js environment with injected helpers |
| **Key source files** | Not in repo | [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts), [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts), [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts) |

## Practical Code Examples

### Basic Navigation and Form Interaction

```javascript
await useOrCreateTaskSpace("login-flow");
await goto("https://example.com/signin");
await fill("input[name=email]", "agent@example.com");
await fill("input[type=password]", "secure-password-123");
await click("button[type=submit]");
await waitForLoadState("networkidle");
const confirmation = await snapshot();
await completeTaskSpace("login-flow", { keep: true });

```

This snippet demonstrates the **helper surface** from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts): `useOrCreateTaskSpace()` isolates the agent's work, while `goto()`, `fill()`, `click()`, and `waitForLoadState()` abstract CDP commands into token‑efficient JavaScript calls.

### Site‑Specific Skill Execution

```javascript
await useOrCreateTaskSpace("github-work");
await runSiteTool("github", "createIssue", {
  owner: "citrolabs",
  repo: "ego-lite",
  title: "Feature request: batch screenshot API",
  body: "Generated by automated agent analysis."
});
await completeTaskSpace("github-work", { keep: false });

```

The `runSiteTool()` helper (implemented via the learning system in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts)) loads domain‑specific automation rules from `skills/ego-browser/learnings/github/`, allowing agents to perform complex multi‑step workflows without brittle DOM selectors.

## How the Architecture Enables Human‑Agent Collaboration

The separation of **ego‑lite** (browser) and **ego‑browser** (SDK) is deliberate. It allows:

1. **Shared browser state** — Humans and agents coexist in the same browser process without session collision, thanks to Task Space isolation
2. **Token efficiency** — Agents write concise JavaScript using high‑level helpers rather than raw CDP JSON
3. **Parallel execution** — Multiple agents can connect to the same ego‑lite instance via separate CDP sessions, each in its own Task Space
4. **Site resilience** — The learning system in `src/learning/` provides abstraction layers that adapt when websites change their DOM structure

The CDP connection is maintained by [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts), which handles WebSocket transport, reconnections, and event buffering so that agents can issue commands without managing protocol state manually.

## Summary

- **ego‑lite** is the installable Chromium browser that humans use; it exposes CDP for external control but contains no JavaScript runtime
- **ego‑browser** is the Node.js SDK in `package/ego-browser/` that agents use to automate the browser through high‑level helpers
- The [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) module provides the primary agent interface: navigation, element interaction, screenshots, and Task Space management
- [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts) manages the underlying CDP transport and session state
- Agents execute JavaScript via STDIN heredocs processed by [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts), with per‑site skills loaded from [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts)
- Together they enable secure, isolated, programmable browser automation that shares the same environment as human users

## Frequently Asked Questions

### Can I use ego‑browser without installing ego‑lite?

No. ego‑browser requires a running ego‑lite browser process to connect to via CDP. The `ego-browser` CLI command included with ego‑lite is just a launcher that finds the local browser instance; the actual automation logic comes from the NPM package installed through the skills system.

### Where is the ego‑lite browser source code?

The ego‑lite browser binary is **closed‑source** and distributed as a native installer. Only the **ego‑browser** SDK (`package/ego-browser/`) and skill definitions (`skills/ego-browser/`) are open‑source in the `citrolabs/ego-lite` repository.

### How do Task Spaces prevent conflicts between agents and humans?

Task Spaces are isolated browsing contexts maintained by ego‑lite at the browser level. When an agent calls `useOrCreateTaskSpace("name")` from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), the browser creates a separate cookie jar, localStorage, and session state. Agents can `completeTaskSpace()` to tear down these contexts, optionally preserving them for later reuse.

### What is the performance overhead of ego‑browser's Node.js runtime?

Each heredoc execution spawns a **short‑lived Node.js process** that connects to the long‑running browser via WebSocket. The [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts) module maintains connection pooling and session caching to minimize per‑command latency. For typical agent workflows, the overhead is negligible compared to network and rendering time.