How ego-lite Differs from Traditional Browser Automation Frameworks

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

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

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:

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:

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) allow multiple AI agents to share browser instances without state collisions, unlike single-driver models.
• The snapshot and ref system (src/ref-map.ts, 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) includes 2-second TTL caching and 10,000-event buffering for resilient automation.
• Verb-first helper injection (src/helpers.ts) creates an agent-friendly API surface without import requirements, documented in 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 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) 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) 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, ego-lite captures the DOM state and assigns numeric refs (e.g., @12) that remain valid across navigations. Stored in 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.

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