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

> Automate browser tasks with ego-lite, a Node.js SDK. Learn how this lightweight harness simplifies Playwright-style automation and integrates seamlessly with your scripts.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-24

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/nav.ts))
- **Element location**: `locator`, `getByText` (backed by [`src/driver/locator.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/locator.ts))
- **Pointer actions**: `click`, `dblclick`, `drag` (backed by [`src/driver/pointer.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/pointer.ts))
- **Keyboard input**: `press`, `fill`, `typeText` (backed by [`src/driver/keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/keyboard.ts))
- **Observation**: `screenshot`, `snapshot` (backed by [`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts))

### Browser Facade: Tab Management

The `createBrowserFacade()` function ([`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) to load and execute specialized automation bundles.

## Practical Automation Examples

### Basic Navigation and Screenshots

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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:

```bash
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`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts)**: Entry point containing `installEgoSdk()` and console flush logic
- **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)**: Factory for façades (`createPageFacade`, `createBrowserFacade`, `createTaskSpacesFacade`, `createSiteFacade`)
- **[`src/driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/nav.ts)**: Navigation primitives and tab management
- **[`src/driver/pointer.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/pointer.ts)**: Mouse and pointer actions
- **[`src/driver/keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/keyboard.ts)**: Keyboard simulation methods
- **[`src/driver/locator.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/locator.ts)**: Element resolution and selector engines
- **[`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts)**: Screenshot, snapshot, and event draining
- **[`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts)**: Site-skill bundle loading and execution
- **[`src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/cdp-eval.ts)**: Low-level CDP evaluation for custom protocol commands

## Summary

- **ego-lite** installs automatically via `installEgoSdk()` in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.