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

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	Installs the SDK onto globalThis, exposes the runMain entry point
Script runner	src/run.ts	Reads JavaScript heredocs from STDIN, wraps them in async IIFE, injects helpers
Helper surface	src/helpers.ts	High‑level API: click(), goto(), snapshot(), fill(), screenshot(), Task Space management
CDP runtime	src/browser-runtime.ts	Manages CDP WebSocket transport, session caches, and event buffering
Element resolver	src/element-resolver.ts	Translates locator strings (@N, CSS selectors, XPath, ARIA) into CDP node IDs
Low‑level CDP	src/cdp-eval.ts	Direct cdp() calls and js() evaluation primitives
Site learning	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:

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 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.

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, src/run.ts, src/helpers.ts, src/browser-runtime.ts

Practical Code Examples

Basic Navigation and Form Interaction

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: useOrCreateTaskSpace() isolates the agent's work, while goto(), fill(), click(), and waitForLoadState() abstract CDP commands into token‑efficient JavaScript calls.

Site‑Specific Skill Execution

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) 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, 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 module provides the primary agent interface: navigation, element interaction, screenshots, and Task Space management
• src/browser-runtime.ts manages the underlying CDP transport and session state
• Agents execute JavaScript via STDIN heredocs processed by src/run.ts, with per‑site skills loaded from 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, 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 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.

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