# How to Integrate ego-browser with External Agent CLIs Like Claude Code

> Integrate ego-browser with external agent CLIs like Claude Code. Easily inject Playwright-style browser helpers into your JavaScript global scope using installEgoSdk from @citrolabs/ego-browser.

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

---

**You can integrate ego-browser with external agent CLIs by importing the `installEgoSdk` function from the `@citrolabs/ego-browser` package and invoking it to inject Playwright-style browser helpers into the JavaScript global scope.**

The `ego-browser` package from the [citrolabs/ego-lite](https://github.com/citrolabs/ego-lite) repository provides a tiny SDK designed for seamless embedding into any Node.js process. Because the library operates as plain JavaScript without native bindings, external agent CLIs that execute JavaScript snippets—including Claude Code—can immediately drive browser automation after a single function call.

## Core Integration Mechanism

The heart of the integration is the **`installEgoSdk`** function defined in [[`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts#L44-L66). When invoked, this function performs four critical operations:

1. **Builds the helper context** by calling `helpers.helperContext()` (line 22 in [[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts#L22)), which constructs the Playwright-style façade containing `page`, `browser`, `taskSpaces`, `site`, and `fetch` objects.
2. **Exposes helpers globally** by attaching every helper method to the target object (defaulting to `globalThis`), making them available as top-level variables in the CLI's JavaScript runtime.
3. **Wraps async operations** so that all helper calls automatically wait for an optional "ready" signal, ensuring the underlying ego-lite runtime is initialized before execution proceeds.
4. **Re-routes console output** to the host’s output sink, ensuring that `console.log` calls from the agent appear in the CLI's console stream.

## Step-by-Step Integration Guide

Follow these steps to integrate ego-browser with external agent CLIs:

### 1. Install the Package

Add the SDK to your project or CLI environment:

```bash
npm install @citrolabs/ego-browser

```

### 2. Load the SDK in the CLI Runtime

Import and invoke `installEgoSdk` at the entry point of your CLI script:

```javascript
import { installEgoSdk } from "ego-browser";

installEgoSdk();  // Injects page, browser, taskSpaces, site, fetch into globalThis

```

### 3. Configure Custom Logging (Optional)

To redirect SDK output to a custom logger instead of the default console, pass a `cliLog` function in the options object (see lines 71-80 in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts)):

```javascript
installEgoSdk(globalThis, {
  cliLog: (...args) => myLogger.log(...args)
});

```

### 4. Execute Browser Automation

Use the injected helpers to perform actions. All methods are exported from [[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts#L4-L30) and grouped under the `page` façade:

```javascript
await page.goto("https://example.com");
await page.locator("button").click();
const title = await page.title();
console.log("Page title:", title);

```

### 5. Manage Task Spaces

For persistent execution contexts, use the task-space API:

```javascript
const ts = await taskSpaces.useOrCreate("my-run");
await ts.claim();

```

The `useOrCreateTaskSpace` and `claimTaskSpace` functions are implemented in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) and manage isolated browser sessions.

### 6. Execute Site-Specific Skills

Invoke learned automation routines for specific websites:

```javascript
const result = await site.runTool("github", "searchIssues", { query: "bug" });

```

The `siteSkills` and `runSiteTool` functions are also exported from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts).

## Complete Integration Example for Claude Code

When Claude Code executes a JavaScript snippet, you can embed the full integration workflow in a single file:

```javascript
// claude-ego-integration.js
import { installEgoSdk } from "ego-browser";

/* 1️⃣ Install the SDK – creates page, browser, etc. facades */
installEgoSdk();

/* 2️⃣ Navigate and interact */
await page.goto("https://news.ycombinator.com");
await page.locator("a[title='comments']").first().click();

/* 3️⃣ Retrieve information */
const title = await page.title();
console.log("HN title:", title);

/* 4️⃣ Use a task-space (optional) */
const ts = await taskSpaces.useOrCreate("claude-run");
await ts.waitForAgentControl();   // ensures the agent has control

/* 5️⃣ Run a learned site tool (if any) */
const issues = await site.runTool("github", "listIssues", {
  repo: "citrolabs/ego-lite"
});
console.log("Open issues:", issues);

```

## Why This Architecture Works

The SDK's design ensures reliable integration with external CLIs through several key mechanisms:

**Single Source of Truth** – The `helperContext()` function (line 22 in [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts)) builds a consolidated object containing all browser facades, ensuring consistency across the API surface.

**Lazy Injection** – `installEgoSdk` only adds helpers that do not already exist on the target object, preventing collisions with existing global variables or other injected libraries.

**Ready-Signal Handling** – The optional `options.ready` parameter accepts a Promise that resolves when the underlying ego-lite app is initialized, safely queueing all helper calls until the runtime is active.

**Transparent Output** – By default, the SDK buffers `console.log` output and flushes it when the process exits, matching the expectations of most CLI environments without requiring explicit stream management.

## Summary

- **`installEgoSdk`** in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) (lines 44-66) is the single entry point required to bootstrap the SDK.
- The SDK exposes **Playwright-style helpers** (`page`, `browser`, `taskSpaces`, `site`, `fetch`) from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) onto the global scope.
- **Task-space management** via `useOrCreate` and `claim` enables persistent, isolated browser sessions across CLI invocations.
- **Site-specific tools** allow CLIs to execute learned automation routines through `site.runTool`.
- The integration requires no native extensions, functioning entirely within standard Node.js JavaScript execution contexts.

## Frequently Asked Questions

### Can I integrate ego-browser with CLIs other than Claude Code?

Yes. Any CLI tool capable of executing Node.js JavaScript can integrate ego-browser. The SDK only requires a JavaScript runtime environment where `installEgoSdk` can be called and `globalThis` is accessible. Tools like GitHub Copilot CLI, custom Node.js scripts, or embedded JavaScript engines in Python applications can all utilize the same integration pattern.

### How does the SDK prevent conflicts with existing global variables?

The `installEgoSdk` function performs a check before injecting each helper. If a property already exists on the target object (defaulting to `globalThis`), the SDK skips that injection. This lazy injection pattern ensures that existing `page`, `console`, or `fetch` globals remain untouched unless explicitly requested otherwise.

### Where are the low-level browser controls implemented?

While the high-level façade lives in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), the underlying Chrome DevTools Protocol (CDP) wrappers for clicks, keyboard input, and navigation reside in the [`src/driver/`](https://github.com/citrolabs/ego-lite/tree/main/package/ego-browser/src/driver) directory. These drivers provide the low-level automation primitives that the `page` and `browser` facades orchestrate.

### Does the SDK support custom output sinks for structured logging?

Yes. The `installEgoSdk` function accepts a `cliLog` option (handled in lines 71-80 of [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts)) that overrides the default console output. This allows you to route all SDK-generated logs through a custom function, enabling structured JSON logging, file output, or integration with the CLI's native logging infrastructure.