# How ego-browser Integrates With External Agent CLIs Like Claude Code

> Discover how ego-browser connects AI agent CLIs like Claude Code to ego-lite via a three-step pipeline. Integrate your favorite AI tools seamlessly.

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

---

**ego-browser serves as the connection layer that lets any AI agent CLI—such as Claude Code, Cursor, or Codex—drive the ego-lite browser through a simple three-step pipeline involving STDIN heredocs, an injected SDK, and CDP message bridging.**

The **ego-browser** package in the [citrolabs/ego-lite](https://github.com/citrolabs/ego-lite) repository enables seamless integration between external agent command-line interfaces and the lightweight **ego-lite** browser. This architecture allows AI coding agents to perform browser automation tasks without managing the complexity of Chrome DevTools Protocol (CDP) sessions or task-space lifecycles themselves.

## The Three-Step Integration Pipeline

The integration between an external agent CLI and ego-lite operates through a clean abstraction pipeline:

### 1. CLI to ego-browser Binary (STDIN Execution)

An external agent such as **Claude Code** invokes the `ego-browser` executable as a Node.js script. The agent passes a JavaScript snippet via a heredoc (`<<'EOF' … EOF`). In [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) (lines 56-66), the binary reads this snippet from **STDIN**, wraps it in an async function, and executes it:

```typescript
// From src/index.ts - the CLI entry point handles heredoc input
async function runMain() {
  const code = await readStdin();           // reads heredoc from agent
  const wrapped = `(async () => { ${code} })()`;
  return eval(wrapped);                      // executes in Node context
}

```

This design lets any shell-capable CLI feed dynamic automation scripts without file-based intermediate steps.

### 2. ego-browser to Runtime SDK (Global Injection)

On startup, `ego-browser` calls `installEgoSdk()` (or executes directly via `runMain`). This function injects a **JavaScript SDK** onto `globalThis` containing all browser helpers. The helpers are defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 5-30) and re-exported from [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts):

```typescript
// From src/helpers.ts - core automation primitives
export const helpers = {
  click: (selector: string) => /* CDP-based click */,
  goto: (url: string, opts?: { wait?: boolean }) => /* navigation */,
  snapshot: () => /* capture page state */,
  snapshotText: () => /* extract readable text */,
  openOrReuseTab: (url: string, opts?: { wait?: boolean }) => /* tab management */,
  useOrCreateTaskSpace: (name: string) => /* persistent session handling */,
  // ... additional helpers
};

```

The SDK installation ensures **the same helper set is available** whether the agent uses CLI invocation or direct Node.js module imports.

### 3. SDK to ego-lite Bridge (CDP Communication)

The injected helpers communicate with the native `ego-lite` process through `ego.sendCDPMessage`. Browser actions are serialized into CDP commands, executed by the underlying browser instance, and results marshalled back to the agent script. This encapsulates all transport complexity—WebSocket management, message framing, response correlation—behind simple async function calls.

The CLI also redirects `console.log` to a dedicated **output sink** ([`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts), lines 75-82), ensuring agents can capture final results via stdout:

```typescript
// Output capture for agent consumption
const originalLog = console.log;
console.log = (...args) => {
  outputSink.write(args.join(' ') + '\n');
  originalLog.apply(console, args);
};

```

## Practical Usage Examples

### Claude Code Shell Invocation

```bash

# Driving ego-lite from Claude Code via heredoc

claude code --run '
ego-browser nodejs <<'"'"'EOF'"'"'
  // Re-use task space across multiple heredoc rounds
  const ts = await useOrCreateTaskSpace("demo-task")
  cliLog(`task space id: ${ts.id}`)

  // Navigate and extract content
  await openOrReuseTab("https://example.com", { wait: true })
  await cliLog(await snapshotText())
EOF
'

```

The same pattern works with **Cursor**, **Codex**, or any CLI capable of executing shell commands.

### Direct Node.js Embedding

```javascript
// For agents preferring programmatic integration
import { installEgoSdk } from "ego-browser";

installEgoSdk();  // Attaches helpers to globalThis

await openOrReuseTab("https://example.com");
console.log(await snapshotText());

```

## Key Integration Files

| File | Purpose |
|------|---------|
| [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) | CLI entry point; orchestrates `runMain()` vs `installEgoSdk()` paths |
| [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) | Defines and exports all agent-facing automation primitives |
| [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md) | Human-readable reference for agent developers describing available helpers and calling conventions |
| [`README.md`](https://github.com/citrolabs/ego-lite/blob/main/README.md) | Documents ego-browser as **"the connection layer between any agent CLI (Claude Code, Codex, Cursor, or a custom one) and ego-lite"** |

## Why This Architecture Works for Agent CLIs

- **Zero configuration**: Agents need only invoke the binary and pass JavaScript
- **Stateful sessions**: `useOrCreateTaskSpace()` preserves browser state across separate CLI invocations
- **Familiar API**: Helpers like `click`, `goto`, and `snapshot` mirror conventional browser automation libraries
- **Output capture**: Structured stdout streaming enables programmatic result consumption

## Summary

- **ego-browser** acts as the thin connection layer between external agent CLIs and the ego-lite browser
- Integration requires only: (1) invoking the `ego-browser` binary, and (2) feeding a JavaScript heredoc using exported helpers
- The SDK injects onto `globalThis` via `installEgoSdk()`, making helpers available in both CLI and module contexts
- All CDP communication, session management, and task-space handling is encapsulated internally
- [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) handles STDIN reading, async wrapping, and output sink redirection; [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) defines the public automation API

## Frequently Asked Questions

### What agent CLIs are compatible with ego-browser?

Any CLI capable of executing shell commands and passing heredocs works with ego-browser. The repository explicitly names **Claude Code**, **Codex**, and **Cursor** as supported integrations, though custom agent implementations following the same pattern function identically.

### How does ego-browser preserve state across multiple commands?

The `useOrCreateTaskSpace(name)` helper in the SDK maintains persistent browser sessions. When an agent invokes ego-browser multiple times with the same task space name, the underlying `ego-lite` process reuses the existing context rather than spawning fresh browser instances.

### Can I use ego-browser without the CLI wrapper?

Yes. Import `installEgoSdk` directly from the `ego-browser` package and call it in your Node.js application. This attaches all helpers to `globalThis` for programmatic use, bypassing the STDIN-based CLI path entirely.

### Where is the CDP communication actually implemented?

The SDK helpers in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) delegate to `ego.sendCDPMessage`, which serializes calls into Chrome DevTools Protocol commands. The `ego-lite` native process handles the actual WebSocket transport and browser execution, keeping transport complexity hidden from agent authors.