How to Install and Use ego-browser as a Node.js Module

To use ego-browser as a Node.js module, first install the ego-lite binary, then import ego-browser-v2 and call installEgoSdk() to inject automation helpers like openOrReuseTab and snapshotText onto the global object.

The ego-browser package is the official Node.js interface for the ego-lite browser automation harness developed by Citro Labs. Available as the ego-browser-v2 npm package within the citrolabs/ego-lite repository, it exposes a lightweight SDK for programmatically controlling browser sessions. This guide covers installing the binary prerequisite, initializing the module, and driving browser automation using the actual source implementation.

Prerequisites – Installing the ego-lite Binary

Before importing the module, you must install the ego-lite application binary that provides the ego-browser command. According to skills/ego-browser/references/install.md, macOS users can execute the automated script at skills/ego-browser/scripts/install.sh, which downloads the DMG, installs the app, strips quarantine attributes, and launches the service.

After installation, verify the binary is available in your PATH (typically ~/.local/bin). If the command is not found, prepend that directory to your $PATH and retry.

Installing the NPM Package

Once the binary is available, add the package to your project:

npm install ego-browser-v2

The package entry point at package/ego-browser/src/index.ts exports the SDK installer and all helpers, making them available for both programmatic use and CLI execution.

Using ego-browser as a Node.js Module

Initializing the SDK with installEgoSdk

To use the module in your own scripts, import the installer and initialize it:

import { installEgoSdk } from 'ego-browser-v2';

installEgoSdk();  // Injects helpers onto globalThis

As implemented in src/index.ts (lines 80-86), installEgoSdk iterates over the helper map, wraps each helper to respect the ready signal, and attaches them to the target object (defaulting to globalThis). After initialization, you can call helpers like openOrReuseTab and snapshotText directly without importing them individually.

Working with Task Spaces

Task spaces isolate browsing contexts between different automation sessions. Create or claim a space using:

const task = await useOrCreateTaskSpace('my-automation');

To resume work in an existing space across separate script executions, use claimTaskSpace with the space ID:

await claimTaskSpace(12345);  // Replace with actual task.id from previous session

The browser runtime in src/browser-runtime.ts manages these task-space lifecycles and session caching.

Core Automation Helpers

With the SDK installed, drive browser interactions using the helper surface defined in src/helpers.ts:

await openOrReuseTab('https://github.com/citrolabs/ego-lite', { wait: true });
await click('a[href*="README.md"]');
const text = await snapshotText();
cliLog(text);

Helpers operate on the most recent snapshot. Note that element references (@N) are only valid for the latest snapshotText call, as documented in skills/ego-browser/SKILL.md.

Running Scripts via CLI

When executing ego-browser directly from the command line, the entry point at src/index.ts detects CLI usage via isDirectCli() (around line 75) and invokes runMain(). The src/run.ts file wraps your heredoc script body in an async function and automatically injects all helpers, so you only write the task logic:

ego-browser nodejs <<'EOF'
const task = await useOrCreateTaskSpace('demo');
await openOrReuseTab('https://example.com');
cliLog(await snapshotText());
EOF

Advanced Techniques

Executing JavaScript in the Browser Context

Use the js helper to run code inside the page and return structured data:

const data = await js(String.raw`(() => {
  const els = [...document.querySelectorAll('article')];
  return els.map(e => ({ title: e.querySelector('h1')?.innerText }));
})()`);
cliLog(JSON.stringify(data, null, 2));

Raw Chrome DevTools Protocol (CDP) Commands

When a high-level helper does not exist, fall back to raw CDP:

await cdp('Network.enable');
await cdp('Network.setUserAgentOverride', { userAgent: 'my-bot/1.0' });

Summary

• Install the binary first using the official macOS script at skills/ego-browser/scripts/install.sh or manual installation before using the npm package
• Import and initialize by calling installEgoSdk() from src/index.ts to inject helpers onto globalThis
• Manage state with useOrCreateTaskSpace() and claimTaskSpace() to persist browsing contexts across script executions
• Drive automation using helpers like openOrReuseTab, click, and snapshotText after SDK initialization
• Run ad-hoc scripts via CLI heredocs, which src/run.ts automatically wraps in an async context

Frequently Asked Questions

What is the difference between ego-browser and ego-browser-v2?

The npm package ego-browser-v2 is the current version of the Node.js module that interfaces with the ego-lite binary. It provides the installEgoSdk function and all browser automation helpers exported from src/helpers.ts.

Why do I need to install a binary before using the npm package?

The ego-browser command requires the ego-lite application binary to manage the Chromium-based browser runtime and CDP transport layer implemented in src/browser-runtime.ts. The npm package alone cannot launch browser instances without this binary being present on the system PATH.

Can I use ego-browser without polluting the global scope?

Yes. While installEgoSdk() defaults to injecting helpers onto globalThis, you can import helpers directly from the package without calling the installer. The module exports all helpers directly via export * from "./helpers.js" in src/index.ts, allowing you to use destructured imports in your own scope if you prefer not to modify the global object.

How do I preserve browser state between script runs?

Use useOrCreateTaskSpace() to create a named task space and note the returned task.id. In subsequent script executions, call claimTaskSpace(id) to reconnect to that browsing context, as the runtime maintains session caching and task-space lifecycles in the background according to src/browser-runtime.ts.

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