# How ego-lite Differs from Traditional Browser Automation Frameworks

> Discover how ego-lite revolutionizes browser automation with its CDP-first, snapshot-aware architecture, empowering AI agents to collaborate with users unlike traditional frameworks.

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

---

**ego-lite fundamentally replaces the WebDriver-oriented control model with a CDP-first, snapshot-aware architecture built explicitly for AI agents to collaborate with human users through isolated task spaces.**

The open-source harness that powers the `ego-browser` binary, maintained at citrolabs/ego-lite, diverges from classic automation stacks like Selenium, Playwright, and Puppeteer by reimagining browser control for multi-agent workflows rather than single-script execution.

## Control Model: Task Spaces vs. Single Driver Sessions

Traditional frameworks operate on a single-driver model where one automation process owns the entire browser session via WebDriver or CDP protocols. In contrast, **ego-lite implements isolated task spaces** that allow multiple AI agents to run concurrently within the same browser instance.

According to the source code in [`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts), each agent receives its own sandboxed view of the page while retaining access to shared user login states. This prevents agents from interfering with each other during parallel execution, a capability absent from conventional WebDriver architectures.

## Session Management and Runtime Resilience

Where traditional tools require external reconnection logic when browser sessions drop, **ego-lite's browser runtime** ([`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts)) handles session persistence automatically. The runtime maintains a 2-second TTL session cache and buffers up to 10,000 events to ensure continuity across network interruptions or page navigations.

This CDP-native approach eliminates the fragile session management typically found in WebDriver-based frameworks, allowing agents to resume operations without manual state reconstruction. Unlike distributed Node packages, the actual Chromium binary is bundled with the ego-lite runtime, keeping the agent-centric execution lightweight.

## The Snapshot and Ref System

Unlike traditional frameworks that require scripts to re-query the DOM after every navigation, **ego-lite snapshots the DOM** and builds a persistent ref-map ([`src/ref-map.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ref-map.ts)). Short-lived numeric references (e.g., `@21`) allow scripts to refer to stable elements across navigation or DOM changes.

When a script invokes `snap()` from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), the system captures the current page state and assigns numeric refs. These references survive navigation events, automatically triggering fresh snapshots only when necessary, as implemented in the snapshot workflow within [`src/ref-state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ref-state.ts).

## Element Resolution and Locator Strategy

Traditional automation relies primarily on CSS or XPath selectors with implicit waits. **ego-lite's element resolver** ([`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts)) supports a unified locator syntax including `@N` snapshot references, `loc=css:`, `loc=role:`, and `loc=href:` prefixes.

The resolver classifies failures as either transient or permanent, driving reliable retry loops without manual timeout configuration. This approach reduces brittle selector patterns common in conventional frameworks.

## API Surface: Injected Helpers vs. Import Libraries

Rather than distributing as a Node package requiring imports, **ego-lite injects a compact helper surface** directly into the script's execution scope. The `helperContext()` function in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) generates verb-first helpers like `click()`, `fill()`, and `snap()` at runtime.

These helpers are generated from JSDoc annotations, enabling the `help()` function to introspect available methods dynamically. This design eliminates import boilerplate and creates an AI-readable API surface documented in the repository's [`SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/SKILL.md) file.

## Agent-First Design and Site Skills

While traditional frameworks target human-written test scripts, **ego-lite is deliberately agent-friendly**. The helper functions expose simple, stateless operations that LLMs can invoke without maintaining complex state across calls.

Furthermore, the **learning subsystem** (`src/learning/`) enables per-site "skill packs"—JSON manifests with validated tools that extend ego-lite for specific domains. This allows reusable, verifiable automations without custom library development, contrasting sharply with the extension models of Selenium or Playwright.

## Practical Usage Examples

The following patterns demonstrate ego-lite's CLI-first execution model and helper API.

### Running Scripts via CLI

The `ego-browser` binary reads JavaScript from stdin, executing within the helper context without requiring module imports:

```bash
ego-browser nodejs <<'EOF'
await nav("https://example.com")
await click("text=Login")
await fill("input[name=username]", "bob")
await snap()
await click("@12")
await screenshot({ path: "login.png" })
EOF

```

### Using Snapshot References Across Navigation

Refs captured via `snap()` persist across page changes, enabling stable element references:

```javascript
await nav('https://example.com/products');
await click('@34');
await nav('https://example.com/cart');
await click('@34');  // References the same product after navigation

```

### Agent-Generated Script Patterns

Scripts execute with automatic helper injection, eliminating import statements:

```javascript
await nav('https://github.com/citrolabs/ego-lite');
await waitFor('text=README.md');
const readmeRef = await snap();
await click('a[href="README.md"]');
await screenshot({ path: 'readme.png' });

```

## Summary

- **ego-lite** diverges from traditional frameworks by using **CDP-first architecture** rather than WebDriver protocols, enabling tighter browser integration.
- **Isolated task spaces** ([`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts)) allow multiple AI agents to share browser instances without state collisions, unlike single-driver models.
- The **snapshot and ref system** ([`src/ref-map.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ref-map.ts), [`src/ref-state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ref-state.ts)) provides stable `@N` references that survive navigation, eliminating the need for constant DOM re-querying.
- **Automatic session management** ([`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts)) includes 2-second TTL caching and 10,000-event buffering for resilient automation.
- **Verb-first helper injection** ([`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)) creates an agent-friendly API surface without import requirements, documented in [`SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/SKILL.md).
- The **learning subsystem** (`src/learning/`) supports site-specific skill packs for reusable domain automations.

## Frequently Asked Questions

### How does ego-lite handle element locators differently than Selenium or Playwright?

Unlike CSS or XPath-only approaches, ego-lite's [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts) implements a unified resolver supporting `@N` snapshot refs, `loc=css:`, `loc=role:`, and `loc=href:` prefixes. The system classifies resolution failures as transient or permanent to drive intelligent retry loops, eliminating the brittle wait patterns common in traditional frameworks.

### Can multiple automation scripts run simultaneously in the same browser instance?

Yes. ego-lite's task space architecture ([`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts)) creates isolated sandboxed views for each AI agent while preserving shared session state like user logins. This allows concurrent agent execution impossible under traditional single-driver WebDriver models.

### What happens when the browser connection drops during automation?

The browser runtime ([`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts)) automatically re-attaches to lost sessions using a 2-second TTL cache and buffers up to 10,000 events during disconnection. This built-in resilience contrasts with traditional frameworks that require manual session reconstruction and external reconnection logic.

### How does the snapshot reference system improve automation stability?

When scripts call `snap()` from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), ego-lite captures the DOM state and assigns numeric refs (e.g., `@12`) that remain valid across navigations. Stored in [`src/ref-map.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ref-map.ts), these references prevent stale element exceptions and eliminate the need to re-query selectors after page changes, a common source of flakiness in conventional tools.