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

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

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:

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):

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/package/ego-browser/src/helpers.ts#L4-L30) and grouped under the page façade:

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:

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

The useOrCreateTaskSpace and claimTaskSpace functions are implemented in src/helpers.ts and manage isolated browser sessions.

6. Execute Site-Specific Skills

Invoke learned automation routines for specific websites:

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

The siteSkills and runSiteTool functions are also exported from 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:

// 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) 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 (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 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, the underlying Chrome DevTools Protocol (CDP) wrappers for clicks, keyboard input, and navigation reside in the 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) 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.

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