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

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 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 (lines 56-66), the binary reads this snippet from STDIN, wraps it in an async function, and executes it:

// 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 (lines 5-30) and re-exported from src/index.ts:

// 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, lines 75-82), ensuring agents can capture final results via stdout:

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

# 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

// 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	CLI entry point; orchestrates runMain() vs installEgoSdk() paths
package/ego-browser/src/helpers.ts	Defines and exports all agent-facing automation primitives
skills/ego-browser/SKILL.md	Human-readable reference for agent developers describing available helpers and calling conventions
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 handles STDIN reading, async wrapping, and output sink redirection; 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 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.

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