How to Use the API Provided by ego-lite: Complete SDK Reference

Initialize the ego-browser SDK by importing installEgoSdk from src/index.ts and invoking it to inject navigation, element control, and task-management helpers into the global scope.

The citrolabs/ego-lite repository ships a lightweight JavaScript SDK that bridges your automation scripts to the ego lite browser runtime. Located in package/ego-browser/, this SDK exposes a comprehensive API for browser automation without requiring additional binaries. Learning how to use the API provided by ego-lite lets you navigate pages, resolve DOM elements, manage isolated task spaces, and execute site-specific skills through the Chrome DevTools Protocol (CDP) bridge.

Installing and Initializing the SDK

Every script starts with the installEgoSdk function exported from src/index.ts. This function bootstraps the SDK by injecting all public helpers into your chosen target object (defaults to globalThis).

Under the hood, installEgoSdk calls helperContext() to instantiate the helper functions and wraps asynchronous calls so they block until an optional ready signal resolves (see implementation lines 57–66 in src/index.ts). Once initialized, your script can access the full ego-lite API surface without additional imports.

import { installEgoSdk } from "./package/ego-browser/src/index.js";

// Inject all helpers into globalThis
installEgoSdk();

// SDK is now ready for use
await goto("https://example.com");

Core API Categories

The ego-browser SDK organizes functionality into logical groups defined in src/helpers.ts. Each category routes commands through the CDP runtime (src/browser-runtime.ts) and CDP evaluator (src/cdp-eval.ts).

Navigation and Tab Control

These functions manage browser navigation and tab lifecycle:

• goto(url) – Navigates the current tab to the specified URL using the nav driver in src/driver/nav.ts, which dispatches ego.sendCDPMessage.
• openOrReuseTab(url, opts) – Opens a new tab or reuses an existing one matching the criteria.
• switchTab(target) and listTabs() – Switch context between tabs or enumerate open tabs.

Element Interaction

Element helpers perform actions after resolving locators through src/element-resolver.ts, which translates selectors like loc=css:button or @23 into CDP node IDs:

• click(locator), dblclick(locator), hover(locator) – Pointer interactions.
• press(key), fill(locator, value) – Keyboard input and form population.
• evaluateLocator(locator, expression) – Execute JavaScript in the context of a resolved element.

Waiting and Synchronization

Control script execution flow until DOM or network conditions are met:

• waitForSelector(locator, opts) – Pause until an element appears.
• waitForLoadState(state) – Wait for network idle or document load.
• waitForTimeout(ms) – Explicit delay.

Screenshots and Snapshots

Capture visual state and event logs:

• screenshot(opts) – Save a PNG of the current viewport.
• snapshot() – Retrieve a serialized DOM representation.
• drainEvents() – Flush buffered CDP events for inspection.

Task-Space Management

Isolate browser state into named containers to prevent cross-contamination between workflows:

• newTaskSpace(name) – Create a fresh isolation context.
• useOrCreateTaskSpace(name) – Switch to an existing space or create one.
• switchTaskSpace(name) and handOffTaskSpace(name) – Transfer control between spaces.
• completeTaskSpace(name, opts) – Clean up and optionally persist the space.

Network Requests

Perform HTTP operations without leaving the script context:

• browserFetch(url, opts) – Fetch via the browser's network stack.
• serverFetch(url, opts) – Fetch via the ego lite backend.

Site-Specific Skills

Execute learned behaviors bundled for specific domains:

• siteSkillsForUrl(url) – List available skills for a domain.
• runSiteTool(domain, toolName, params) – Invoke a learned tool implemented in src/learning/index.ts.
• learnContext(opts) – Trigger the learning pipeline for the current page.

How the SDK Works Internally

When you call a helper like goto, the SDK routes the request through several layers. The public API in src/helpers.ts delegates to the CDP runtime (src/browser-runtime.ts), which manages the transport session and event buffering. Navigation specifically uses the driver architecture in src/driver/nav.ts, while element resolution happens in src/element-resolver.ts, converting locators into CDP node IDs before sending commands via ego.sendCDPMessage.

Site-specific skills are loaded and executed by the learning module at src/learning/index.ts, which dynamically bundles domain-specific logic.

Complete Usage Examples

Basic Navigation and Screenshot

This script demonstrates navigation, element waiting, interaction, and image capture:

import { installEgoSdk } from "./package/ego-browser/src/index.js";

installEgoSdk();

await goto("https://example.com");
await waitForSelector("text=More information");
await click("text=More information");
const snap = await screenshot();
console.log("Screenshot saved:", snap.path);

Isolating Work with Task Spaces

Use task spaces to isolate cookies, storage, and execution context between runs:

import { installEgoSdk } from "./package/ego-browser/src/index.js";

installEgoSdk();

const space = await newTaskSpace("scrape-run");
await useOrCreateTaskSpace(space.name);
await goto("https://news.ycombinator.com");
await waitForSelector("a.storylink");
const titles = await evaluateAll(`
  Array.from(document.querySelectorAll('a.storylink')).map(el => el.textContent)
`);
console.log(titles);
await completeTaskSpace(space.name, { keep: false });

Running Site-Specific Tools

Invoke domain-specific automation bundles without writing custom selectors:

import { installEgoSdk } from "./package/ego-browser/src/index.js";

installEgoSdk();

const result = await runSiteTool("github.com", "searchRepos", {
  query: "ego-lite",
});
console.log(result);

Summary

• Initialize first: Call installEgoSdk() from src/index.ts to expose the API on globalThis.
• Navigation and elements: Use goto, click, and waitForSelector for core browser automation, backed by src/driver/nav.ts and src/element-resolver.ts.
• Isolation: Leverage newTaskSpace and useOrCreateTaskSpace to compartmentalize workflows.
• Extensibility: Execute learned behaviors with runSiteTool from the src/learning/index.ts module.
• Architecture: All commands route through the CDP bridge managed in src/browser-runtime.ts and src/cdp-eval.ts.

Frequently Asked Questions

What is the entry point for the ego-lite API?

The primary entry point is installEgoSdk exported from package/ego-browser/src/index.ts. Importing and invoking this function injects all helper methods—navigation, element control, task spaces, and network utilities—into the global scope (or a specified target), making them available for the duration of your script.

How does ego-lite resolve element locators?

ego-lite uses the element resolver in src/element-resolver.ts to translate locators (such as css:button, text=Submit, or numeric refs like @23) into CDP node IDs. Once resolved, element action helpers like click or fill send CDP commands through the browser runtime to interact with the specific DOM node.

What is a task space and when should I use it?

A task space is an isolated browser context that segregates cookies, localStorage, and execution environment. Create one with newTaskSpace() and switch to it via useOrCreateTaskSpace() when you need to run parallel or sequential workflows without cross-contamination, such as scraping multiple accounts on the same domain.

Does ego-lite require separate browser binaries?

No. The ego-browser SDK is pure JavaScript and communicates with the ego lite runtime through the global ego bridge object. You only need the citrolabs/ego-lite repository (or its NPM package) and a running ego lite environment that exposes this bridge; no additional driver binaries like Selenium or Playwright are required.

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