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

> Learn to install and use ego-browser as a Node.js module. Inject automation helpers like openOrReuseTab and snapshotText onto the global object with easy steps.

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

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/references/install.md), macOS users can execute the automated script at [`skills/ego-browser/scripts/install.sh`](https://github.com/citrolabs/ego-lite/blob/main/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:

```bash
npm install ego-browser-v2

```

The package entry point at [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/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:

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

installEgoSdk();  // Injects helpers onto globalThis

```

As implemented in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/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:

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

```

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

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

```

The browser runtime in [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts):

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) detects CLI usage via `isDirectCli()` (around line 75) and invokes `runMain()`. The [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/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:

```bash
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:

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

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/scripts/install.sh) or manual installation before using the npm package
- **Import and initialize** by calling `installEgoSdk()` from [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts).