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

> Explore the ego-lite project structure for the CDP browser automation runtime. Understand its three core layers: TypeScript runtime, agent skills, and project boilerplate.

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

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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.

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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)`:

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/README.md)** — High-level overview and quick-start instructions
- **[`AGENTS.md`](https://github.com/citrolabs/ego-lite/blob/main/AGENTS.md)** — Internal guidelines for contributors and agent developers
- **[`install.md`](https://github.com/citrolabs/ego-lite/blob/main/install.md)** — macOS binary installation steps
- **[`package/ego-browser/package.json`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts)) duals as CLI executor and SDK installer via `installEgoSdk`
- **Helper surface** ([`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)) exposes `goto`, `click`, `snapshot`, and Task Space methods to agents
- **Element resolution** ([`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.