How to Use ego-lite to Automate Browser Tasks: A Complete Node.js SDK Guide

ego-lite is a lightweight Node.js harness that exposes Playwright-style façade objects—page, browser, taskSpaces, and site—automatically installing them into the global scope when you run scripts via the ego-browser binary.

The citrolabs/ego-lite repository provides a streamlined browser automation framework that eliminates Chrome DevTools Protocol (CDP) boilerplate by providing high-level SDK helpers. When you execute JavaScript through the ego-browser CLI or import the module, the installEgoSdk() function immediately exposes navigation, interaction, and task-management primitives. This guide demonstrates how to use ego-lite to automate browser tasks using the façade implementations and driver architecture found in the source code.

SDK Initialization and Global Scope

The ego-lite SDK initializes automatically upon module load. In src/index.ts (lines 64–66), the installEgoSdk() function is invoked at the end of the file, attaching helper objects to the global ego object (or any custom target you provide).

The core factory function helperContext() in src/helpers.ts constructs four distinct façade objects that mimic the Playwright API. When your script completes, buffered console output flushes automatically (handled in src/index.ts lines 80–87), ensuring logs appear in the correct order for agent monitoring.

The Four Core Facade Objects

Page Facade: Navigation and Interaction

The createPageFacade() function (defined in src/helpers.ts lines 84–108) provides the primary interface for page automation. It aggregates functionality from several driver modules:

• Navigation: goto, pageInfo (backed by src/driver/nav.ts)
• Element location: locator, getByText (backed by src/driver/locator.ts)
• Pointer actions: click, dblclick, drag (backed by src/driver/pointer.ts)
• Keyboard input: press, fill, typeText (backed by src/driver/keyboard.ts)
• Observation: screenshot, snapshot (backed by src/driver/observe.ts)

Browser Facade: Tab Management

The createBrowserFacade() function (src/helpers.ts lines 73–83) exposes tab-level controls for multi-page workflows:

• listTabs: Enumerate open tabs
• currentTab: Access the active tab identifier
• switchTab: Change active context
• openOrReuseTab: Create or claim an existing tab
• closeTab: Terminate specific tabs

Task-Space Facade: Isolated Contexts

The createTaskSpacesFacade() function (src/helpers.ts lines 85–97) encapsulates isolated browsing contexts that prevent state pollution between automation runs:

• useOrCreate(name): Claim or initialize a named task space
• complete(options): Finalize the task, with keep: true leaving the tab open for manual inspection

Site-Skill Facade: Per-Site Automation

The createSiteFacade() function (src/helpers.ts lines 99–107) loads per-site learning bundles and executes domain-specific tools:

• skillsForUrl(url): Retrieve available tools for a given domain
• runTool(siteName, toolName, params): Execute a learned automation routine
• runBrowserTool: Execute browser-specific variants

This façade interfaces with src/learning/index.ts to load and execute specialized automation bundles.

Practical Automation Examples

Basic Navigation and Screenshots

// Navigate, wait for network idle, and capture state
await page.goto('https://example.com');
await page.waitForLoadState('networkidle');
const title = await page.title();
console.log('Page title:', title);
await page.screenshot({ path: 'example.png' });

Form Filling and Submission

// Locate a form, fill credentials, and submit
const login = page.locator('#login-form');
await login.fill({ username: 'alice', password: 'secret' });
await login.locator('button[type="submit"]').click();
await page.waitForURL('**/dashboard');

Creating Isolated Task Spaces

// Isolate work in a dedicated context
const ts = await taskSpaces.useOrCreate('my-automation-run');
await page.goto('https://news.ycombinator.com');
await page.locator('a.storylink').first().click();
await ts.complete({ keep: true }); // Preserve tab for manual review

Running Site-Specific Tools

// Execute learned skills for GitHub automation
const skills = await site.skillsForUrl('https://github.com');
console.log('Available tools:', skills);
const repoInfo = await site.runTool('github', 'repoInfo', { 
  owner: 'octocat', 
  repo: 'Hello-World' 
});
console.log('Repo description:', repoInfo.description);

Executing Scripts with the CLI

Run any of the above snippets using the ego-browser binary with a heredoc:

ego-browser node <<'JS'
await page.goto('https://example.com');
console.log(await page.title());
JS

Key Source Files in the Architecture

Understanding the driver layout helps when extending the SDK or debugging:

• src/index.ts: Entry point containing installEgoSdk() and console flush logic
• src/helpers.ts: Factory for façades (createPageFacade, createBrowserFacade, createTaskSpacesFacade, createSiteFacade)
• src/driver/nav.ts: Navigation primitives and tab management
• src/driver/pointer.ts: Mouse and pointer actions
• src/driver/keyboard.ts: Keyboard simulation methods
• src/driver/locator.ts: Element resolution and selector engines
• src/driver/observe.ts: Screenshot, snapshot, and event draining
• src/learning/index.ts: Site-skill bundle loading and execution
• src/cdp-eval.ts: Low-level CDP evaluation for custom protocol commands

Summary

• ego-lite installs automatically via installEgoSdk() in src/index.ts, exposing page, browser, taskSpaces, and site globals.
• The Page façade provides high-level navigation and interaction methods backed by specialized drivers in src/driver/.
• Task spaces isolate automation contexts, while the Site façade enables domain-specific learned behaviors.
• Execute scripts through the ego-browser CLI to leverage automatic console flushing and CDP connection management.

Frequently Asked Questions

How do I install ego-lite and run my first script?

Install the ego-browser binary from the citrolabs/ego-lite repository, then execute JavaScript directly via ego-browser node <<'JS' … JS. The SDK installs automatically when the module loads, exposing page and other helpers globally without additional configuration.

What is the difference between task spaces and browser tabs?

Browser tabs (browser.openOrReuseTab) are standard browser contexts, while task spaces (taskSpaces.useOrCreate) are logical isolation units that may encompass tabs, storage partitioning, and session state. Task spaces provide higher-level lifecycle management with complete() methods for cleanup or handoff.

How do I execute low-level Chrome DevTools Protocol commands?

Use the utilities in src/cdp-eval.ts which expose cdp and evaluate functions for raw protocol access. These low-level primitives underpin the high-level façade methods but remain available for custom automation logic requiring direct CDP transport control.

Can I migrate existing Playwright code to ego-lite?

Yes. The Page façade (createPageFacade in src/helpers.ts) mirrors Playwright’s API with methods like goto, locator, fill, and click. While method signatures aim for compatibility, verify specific behaviors in src/driver/ implementations, as ego-lite utilizes CDP transport rather than Playwright’s WebSocket protocol.

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