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

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

// 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, it exports operations like click, goto, listTabs, fill, press, and task space management. These abstract away CDP complexity into familiar browser-automation verbs.

// 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) 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) 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) 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) provides cdp() and js() helpers that evaluate JavaScript inside the page via CDP. This bridges the gap between helper abstractions and raw page access.

// 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 — Navigation actions (goto, back, forward, reload)
• pointer.ts — Mouse clicks, moves, hovering
• keyboard.ts — Typing, key presses, shortcuts
• files.ts — File upload handling
• element-ops.ts — Element attribute extraction, visibility checks
• waits.ts — Explicit and implicit wait utilities
• screencast.ts — Screenshot and screen recording capture
• downloads.ts — Download initiation and path management
• 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) 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.

// 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 — Resolves workspace directory and runtime configuration
• output-sink.ts & 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 bootstraps; helpers.ts exposes the public API
• Runtime stack: browser-runtime.ts manages CDP sessions; state.ts holds mutable context
• Resolution logic: 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. 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, 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.

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