ego-lite Project Structure: A Complete Guide to the CDP Browser Automation Runtime

ego-lite is organized as a single-purpose Node.js package with three logical layers: the TypeScript runtime core in package/ego-browser/, agent-facing skill assets in skills/ego-browser/, and project boilerplate at the repository root.

The ego-lite repository by citrolabs ships a streamlined browser automation system built on the Chrome DevTools Protocol (CDP). Unlike monolithic browser frameworks, ego-lite separates the runtime engine from the skill packaging system that AI agents consume. This architecture enables lightweight distribution while maintaining full CDP capabilities for programmatic web interaction.

Runtime Core: The Browser Automation Engine

The heart of ego-lite lives in package/ego-browser/src/, where TypeScript modules implement the CDP-driven browser harness.

Entry Point and SDK Installation

package/ego-browser/src/index.ts serves dual purposes: it acts as the CLI entry point when invoked directly, and exports installEgoSdk for embedding into agent environments.

// When called as CLI: executes JS from stdin
// When imported: installs SDK helpers onto globalThis
const { installEgoSdk } = require('ego-browser');
installEgoSdk(globalThis);

The isDirectCli check determines execution mode. Direct invocation triggers runMain() to evaluate JavaScript piped via stdin; module import triggers SDK installation.

Helper Surface API

package/ego-browser/src/helpers.ts defines the public API that agents call. Every helper is wrapped with a "ready" promise that resolves once the underlying browser session initializes.

Helper	Purpose
goto(url)	Navigate to URL with wait conditions
click(locator)	Click element via CSS, XPath, text, or ref
snapshot()	Capture high-quality page state for LLM consumption
evaluate(script)	Execute JavaScript in page context
newTaskSpace(name)	Create isolated browsing context

Browser Runtime and Session Management

package/ego-browser/src/browser-runtime.ts manages the CDP transport layer. It wraps ego.sendCDPMessage, caches sessions, and implements Task Spaces — isolated browsing contexts that prevent agent actions from interfering with each other.

// Create and manage isolated workspace
const space = await newTaskSpace('research-task');
await switchTaskSpace(space.id);
// ... perform actions ...
await completeTaskSpace(space.id, { keep: false });

Element Resolution Pipeline

package/ego-browser/src/element-resolver.ts translates human-readable locators into CDP node IDs. It supports multiple locator strategies and classifies failures as transient (retryable, e.g., element not yet ready) or permanent (e.g., selector not found).

Skill Assets: Agent-Facing Distribution Layer

The skills/ego-browser/ directory contains static files bundled with the skill and installed via npx skills add citrolabs/ego-lite.

Skill Documentation

skills/ego-browser/SKILL.md provides the canonical usage guide that AI agents reference when learning to use ego-lite.

Site-Specific Learning Packs

The learnings/ subdirectory contains per-site optimization packs:

skills/ego-browser/learnings/
├── x-com/
│   ├── manifest.json      # Tool definitions for X/Twitter

│   └── notes/...
└── google/
    └── manifest.json      # Tool definitions for Google services

Agents invoke these via runSiteTool(site, tool, params):

// Use pre-bundled extraction logic for X.com
await runSiteTool('x-com', 'extract-post', { 
  url: 'https://x.com/example/status/123' 
});

Agent Configuration

skills/ego-browser/agents/openai.yaml contains agent-specific configuration parameters for OpenAI-compatible systems.

Project Boilerplate

Repository-root files handle distribution, licensing, and contributor guidelines:

• README.md — High-level overview and quick-start instructions
• AGENTS.md — Internal guidelines for contributors and agent developers
• install.md — macOS binary installation steps
• package/ego-browser/package.json — NPM metadata, test scripts, dependencies

Complete Directory Layout

ego-lite/
├─ .github/                    # CI workflows

├─ assets/                     # Logo, banner images

├─ docs/                       # Public documentation assets

├─ install.md                  # macOS binary install guide

├─ LICENSE                     # MIT license

├─ README.md                   # Project overview

├─ AGENTS.md                   # Contributor guidelines

├─ package/
│   └─ ego-browser/
│       ├─ src/
│       │   ├─ index.ts               # CLI & SDK installer

│       │   ├─ helpers.ts             # Public API surface

│       │   ├─ browser-runtime.ts    # CDP transport & Task Spaces

│       │   ├─ element-resolver.ts   # Locator → node ID translation

│       │   ├─ ref-map.ts             # Ref ↔ backendNodeId mapping

│       │   ├─ ref-state.ts           # Ref lifecycle management

│       │   ├─ cdp-eval.ts            # Low-level CDP/JS evaluation

│       │   ├─ output-sink.ts         # Buffered agent output logging

│       │   └─ update-notice.ts       # Version update notifications

│       ├─ tsconfig.json
│       ├─ package.json
│       └─ README.md
├─ skills/
│   └─ ego-browser/
│       ├─ SKILL.md                 # Agent usage guide

│       ├─ references/              # Detailed install docs, videos

│       │   ├─ install.md
│       │   └─ video.md
│       ├─ agents/
│       │   └─ openai.yaml          # Agent configuration

│       ├─ learnings/               # Site-specific skill packs

│       │   ├─ x-com/manifest.json
│       │   └─ google/manifest.json
│       └─ assets/                  # Skill icons

└─ scripts/                         # Build and validation utilities

How Components Interact

1. Installation: npx skills add citrolabs/ego-lite copies skill assets and installs the npm package
2. SDK Bootstrap: Agent imports runtime; installEgoSdk(globalThis) attaches helpers
3. Session Creation: First helper call triggers browser-runtime.ts to establish CDP connection
4. Task Execution: Agents use Task Spaces for isolation; element resolution handles locator diversity
5. Site Tools: Optional learning packs provide pre-built extraction logic for common sites

Summary

• Runtime core (package/ego-browser/src/) implements CDP browser automation in TypeScript
• Skill assets (skills/ego-browser/) package documentation, config, and site-specific tools for agent consumption
• Entry point (src/index.ts) duals as CLI executor and SDK installer via installEgoSdk
• Helper surface (src/helpers.ts) exposes goto, click, snapshot, and Task Space methods to agents
• Element resolution (src/element-resolver.ts) bridges human locators to CDP node IDs with retry logic
• Learning packs (skills/ego-browser/learnings/*/manifest.json) enable runSiteTool() for optimized site interaction

Frequently Asked Questions

What is the CDP in ego-lite?

CDP stands for Chrome DevTools Protocol. In ego-lite, browser-runtime.ts uses CDP via ego.sendCDPMessage to control the browser: create browsing contexts, evaluate JavaScript, capture screenshots, and extract DOM information. This provides lower-level access than Puppeteer or Playwright with less overhead.

How do Task Spaces isolate agent sessions?

Task Spaces, implemented in browser-runtime.ts, create separate browser contexts (equivalent to incognito windows) that don't share cookies, localStorage, or session state. Agents call newTaskSpace(), switchTaskSpace(), and completeTaskSpace() to manage these isolation boundaries. This prevents one agent's actions from affecting another's environment.

What locator syntax does ego-lite support?

src/element-resolver.ts parses multiple locator prefixes: css: for CSS selectors, xpath: for XPath expressions, text= for text content matching, @N for numeric ref IDs, and role: for ARIA role attributes. The resolver classifies resolution failures as transient (retryable) or permanent to guide agent retry logic.

How are site-specific learning packs used?

Learning packs under skills/ego-browser/learnings/ contain manifest.json files defining tools like extract-post for X.com. Agents invoke these via runSiteTool(site, tool, params), which loads the manifest and executes pre-defined JavaScript optimized for that site's DOM structure. Packs are optional; the runtime functions without them using generic helpers.

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