# Main Modules of ego-lite: A Deep Dive into the Browser Automation SDK

> Explore the main modules of ego-lite, a browser automation SDK. Understand CDP session management, element resolution, and site-specific learning within the ego-lite codebase.

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

---

**ego-lite organizes its codebase into discrete TypeScript modules under `package/ego-browser/src/`, each handling specific responsibilities from CDP session management to element resolution and site-specific learning.**

The **ego-lite** repository provides a compact browser-automation harness that exposes a high-level API to agents through global `ego` bindings. Rather than monolithic architecture, the project splits functionality into focused, single-responsibility modules. This guide walks through each module's purpose, key source files, and how they interact to enable agent-driven browser automation.

## SDK Entry Point: Installing the Global API

The **SDK entry point** ([`index.ts`](https://github.com/citrolabs/ego-lite/blob/main/index.ts)) bootstraps the entire system. It exposes internal helpers, installs the SDK on `globalThis`, and wires console output for short-lived heredoc processes. When the bundle executes, calling `installEgoSdk()` makes all browser controls available globally.

```javascript
// SDK installation happens automatically on bundle load
installEgoSdk();   // from package/ego-browser/src/index.ts

// After installation, helpers are available globally
await goto('https://example.com');
await click('text=Login');

```

## Helper Context: The Agent-Facing API

The **helper context** module defines all public functions agents invoke. Located in [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts), it exports operations like `click`, `goto`, `listTabs`, `fill`, `press`, and task space management. These abstract away CDP complexity into familiar browser-automation verbs.

```javascript
// Navigation and interaction helpers
await goto('https://example.com');
await click('text=Login');
await fill('input[name="email"]', 'user@example.com');
await press('Enter');

// Task space management
const ts = await useOrCreateTaskSpace('my-space');
await switchTaskSpace(ts.id);
await newTaskSpace();
await completeTaskSpace(ts.id, {keep: true});

```

## Browser Runtime: CDP Session Orchestration

The **browser runtime** ([`browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts)) manages Chrome DevTools Protocol (CDP) sessions, maintains preferred targets, and handles session invalidation. This module sits between the high-level helpers and the actual browser instance, ensuring connections stay healthy and targets remain addressable.

## State Management: Centralized Mutable State

The **state management** module ([`state.ts`](https://github.com/citrolabs/ego-lite/blob/main/state.ts)) holds runtime state as a singleton: current page reference, active task spaces, and other mutable context that persists across async operations. Keeping state centralized prevents drift and simplifies debugging of agent sessions.

## Element Resolution: Selector Logic and Error Classification

The **element resolution** module ([`element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/element-resolver.ts)) implements selector parsing for multiple locator strategies:
- **CSS selectors** (`div.content`)
- **Text selectors** (`text=Submit`)
- **XPath expressions**
- **Role-based locators**
- **Reference syntax** (`@N` for nth element)

It also classifies resolution failures as **transient** (retryable) or **permanent** (definitive missing element), guiding agent retry policies.

## CDP Evaluation: In-Page JavaScript Execution

The **CDP evaluation** module ([`cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/cdp-eval.ts)) provides `cdp()` and `js()` helpers that evaluate JavaScript inside the page via CDP. This bridges the gap between helper abstractions and raw page access.

```javascript
// Execute arbitrary JavaScript in page context
const title = await js('document.title');
console.log('Page title →', title);

```

## Driver Layer: Low-Level CDP Actions

The **driver layer** splits low-level CDP interactions across focused files under `package/ego-browser/src/driver/`:

- **[`nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/nav.ts)** — Navigation actions (`goto`, `back`, `forward`, `reload`)
- **[`pointer.ts`](https://github.com/citrolabs/ego-lite/blob/main/pointer.ts)** — Mouse clicks, moves, hovering
- **[`keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/keyboard.ts)** — Typing, key presses, shortcuts
- **[`files.ts`](https://github.com/citrolabs/ego-lite/blob/main/files.ts)** — File upload handling
- **[`element-ops.ts`](https://github.com/citrolabs/ego-lite/blob/main/element-ops.ts)** — Element attribute extraction, visibility checks
- **[`waits.ts`](https://github.com/citrolabs/ego-lite/blob/main/waits.ts)** — Explicit and implicit wait utilities
- **[`screencast.ts`](https://github.com/citrolabs/ego-lite/blob/main/screencast.ts)** — Screenshot and screen recording capture
- **[`downloads.ts`](https://github.com/citrolabs/ego-lite/blob/main/downloads.ts)** — Download initiation and path management
- **[`locator.ts`](https://github.com/citrolabs/ego-lite/blob/main/locator.ts)** — Internal locator construction utilities

Each driver file talks directly to CDP, translating high-level intent into protocol commands.

## Learning Subsystem: Site-Specific Skills

The **learning subsystem** ([`learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/learning/index.ts)) loads site-specific "learnings" — manifest files, tools, and validation rules that adapt automation behavior to particular domains. This allows agents to run optimized workflows for known sites without hardcoding logic.

```javascript
// Execute a site-specific tool from loaded learnings
await runSiteTool('github', {repo: 'octocat/Hello-World'});

```

## Environment and Output Utilities

Two modules handle operational concerns:

- **[`env.ts`](https://github.com/citrolabs/ego-lite/blob/main/env.ts)** — Resolves workspace directory and runtime configuration
- **[`output-sink.ts`](https://github.com/citrolabs/ego-lite/blob/main/output-sink.ts) & [`update-notice.ts`](https://github.com/citrolabs/ego-lite/blob/main/update-notice.ts)** — Buffer console output for heredoc processes and print version-update trailers

The output sink is critical for ego-lite's short-lived execution model, capturing all logs before the process exits.

## Summary

- **Module organization**: ego-lite splits functionality across 10+ focused modules under `package/ego-browser/src/`
- **Entry architecture**: [`index.ts`](https://github.com/citrolabs/ego-lite/blob/main/index.ts) bootstraps; [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts) exposes the public API
- **Runtime stack**: [`browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts) manages CDP sessions; [`state.ts`](https://github.com/citrolabs/ego-lite/blob/main/state.ts) holds mutable context
- **Resolution logic**: [`element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/element-resolver.ts) handles multiple selector types with error classification
- **Driver granularity**: Low-level CDP actions live in `driver/` submodules (nav, pointer, keyboard, etc.)
- **Extensibility**: `learning/` enables site-specific automation workflows

## Frequently Asked Questions

### What is the main entry point for the ego-lite SDK?

The main entry point is [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts). It exports `installEgoSdk()`, which attaches all browser automation helpers to `globalThis` and configures console output handling.

### How does ego-lite handle element selection?

Selection logic lives in [`element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/element-resolver.ts), which parses CSS, XPath, text, role-based, and reference (`@N`) selectors. It returns resolved element handles and categorizes failures as transient or permanent to inform retry behavior.

### What is the purpose of the driver/ subdirectory?

The `driver/` directory contains granular CDP implementations for specific action categories: navigation, pointer, keyboard, files, element operations, waits, screencast, downloads, and locator utilities. This separation keeps each file focused and testable.

### How does ego-lite support site-specific automation?

The `learning/` module loads manifest files and tools for known sites. Agents call `runSiteTool(siteName, params)` to execute prevalidated workflows tailored to specific domains rather than writing generic selectors.