How to Run the Examples in ego-lite: A Complete Step-by-Step Guide

To run the examples in ego-lite, install the skill with npx skills add, build the Node-based helper runtime, and pipe JavaScript snippets into the bundled CLI via STDIN.

The ego-lite repository from Citrolabs provides a lightweight browser automation framework that connects to a closed-source browser binary through the Chrome DevTools Protocol (CDP). The examples demonstrate core automation patterns—navigation, screenshots, and element interaction—using a helper runtime that exposes convenient async functions.

Install the ego-lite Skill and Dependencies

Before running any examples, you need the skill registered in your shell and the Node dependencies installed.

Register the Skill

The skill installer adds helper commands and configures the environment:

npx skills add citrolabs/ego-lite

Install Package Dependencies

Navigate to the browser package and install dependencies:

cd package/ego-browser
npm ci

This installs the runtime requirements defined in package/ego-browser/package.json.

Build the Helper Runtime

The examples rely on a bundled CLI that communicates with the ego-lite browser. Build it with:

npm test

This command:

1. Compiles the TypeScript source
2. Outputs the bundled CLI to dist/out/index.js
3. Runs unit tests that include embedded example snippets

The build process is defined in the package scripts and produces the executable entry point for all example workflows.

Run Examples via STDIN (Heredoc Method)

The primary way to execute examples is piping JavaScript directly into the built CLI. The runtime exposes helper functions from src/helpers.ts—including openOrReuseTab, screenshot, click, and getPageInfo—that abstract CDP operations.

Basic Example: Open a Page and Extract Title

node dist/out/index.js <<'JS'
await openOrReuseTab('https://example.com', { wait: true })
const info = await getPageInfo()
console.log('Page title:', info.title)
JS

Screenshot Example

node dist/out/index.js <<'JS'
await openOrReuseTab('https://example.com', { wait: true })
await screenshot({ fullPage: true, path: 'full.png' })
JS

Interaction Example

node dist/out/index.js <<'EOF'
await openOrReuseTab('https://example.com', { wait: true })
await click('text=More info')
await screenshot({ path: 'info.png' })
EOF

The openOrReuseTab function optionally accepts a wait: true parameter to block until the page load event fires. Screenshots support both viewport-only and fullPage captures.

Run the Full End-to-End Example Suite

For comprehensive verification against a real Chromium instance, execute the e2e runner:

npm run e2e

This script—located at scripts/real-browser-e2e/—performs the following:

• Launches the bundled ego-lite binary
• Creates a temporary task workspace
• Executes example flows covering navigation, evaluation, interaction, and observation

The individual test cases reside in scripts/real-browser-e2e/cases/*.mjs and serve as reference implementations for common automation patterns.

Key Source Files for Understanding Examples

File Path	Purpose
package/ego-browser/src/helpers.ts	Defines the helper context (openOrReuseTab, screenshot, click, etc.) available to example scripts
package/ego-browser/src/browser-runtime.ts	Core CDP transport and session management
package/ego-browser/README.md	Quick-start documentation and CLI usage
skills/ego-browser/SKILL.md	Skill definition and public API reference
scripts/real-browser-e2e/cases/*.mjs	Standalone example test cases

Troubleshooting Common Issues

• CLI not found: Ensure npm test completed successfully and check that dist/out/index.js exists
• Connection failures: Verify the ego-lite browser binary is accessible in your PATH
• Helper functions undefined: Confirm you're piping JavaScript into the built CLI, not running raw Node

Summary

• Install: npx skills add citrolabs/ego-lite registers the skill; npm ci installs dependencies
• Build: npm test produces dist/out/index.js and validates examples
• Execute: Pipe JS snippets via heredoc to the CLI; helper functions from src/helpers.ts handle CDP communication
• Verify: npm run e2e runs the full example suite against a real browser instance

Frequently Asked Questions

What helper functions are available in ego-lite examples?

The runtime exposes async helpers defined in package/ego-browser/src/helpers.ts: openOrReuseTab, screenshot, click, getPageInfo, evaluate, fill, press, and others. These abstract CDP commands into concise, awaitable operations.

Can I run examples without building first?

No. The CLI at dist/out/index.js must exist before executing examples. The build step bundles the TypeScript source and helper context. Run npm test once to generate it.

Where are the example scripts stored?

Unit test examples embed in the test suite. Full workflow examples live in package/ego-browser/scripts/real-browser-e2e/cases/*.mjs—individual modules demonstrating navigation, page evaluation, element interaction, and visual observation.

How does the runtime communicate with the browser?

src/browser-runtime.ts establishes a CDP WebSocket connection to the ego-lite browser binary, exposing a session-based transport layer that the helper functions use to send commands and receive events.

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