# Where to Find Documentation for the ego-browser Runtime Harness

> Find ego-browser runtime harness documentation in SKILL.md and TypeScript source files at citrolabs/ego-lite. Learn how to interact with the ego-browser runtime harness effectively.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: api-reference
- Published: 2026-08-26

---

**All documentation for the ego-browser runtime harness is located in the [`SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/SKILL.md) file within the skill package and the TypeScript source files in `package/ego-browser/src/`, particularly [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) which defines every interaction helper available to agents.**

The **ego-browser** is the core Node.js runtime that powers the **ego-lite** browser automation suite from the `citrolabs/ego-lite` repository. When agents execute heredoc scripts via the `ego-browser nodejs` command, the runtime harness automatically injects a comprehensive set of helpers—such as `click()`, `snapshotText()`, and `js()`—into the script's execution context. Understanding where to find the authoritative reference material ensures you can leverage the full capabilities of the browser automation API.

## Primary Documentation Locations

The project splits documentation between user-facing guides and implementation source code. Both are essential for mastering the runtime harness.

### Agent-Facing Skill Guide (SKILL.md)

The primary reference manual for agents is **[`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md)**. This file provides a complete description of all public helpers, usage patterns, and workflow recommendations. It serves as the definitive guide for writing automation scripts that interact with web pages through the ego-browser runtime.

### Installation and Setup (install.md)

For environment configuration, refer to **[`skills/ego-browser/references/install.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/references/install.md)**. This document explains how to obtain the ego-lite binary and make the `ego-browser` command available in your system path, which is a prerequisite for executing any scripts against the runtime harness.

## Core Source Files

While [`SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/SKILL.md) offers high-level guidance, the source code in `package/ego-browser/src/` provides the ground truth for API behavior and implementation details.

### Helper Implementations (src/helpers.ts)

The file **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)** contains the definitions for every interaction helper available in the runtime. Functions like `click()`, `snapshotText()`, `js()`, `cdp()`, and task-space utilities (`useOrCreateTaskSpace`, `completeTaskSpace`) are implemented here. When the runtime executes a heredoc script, it calls `helperContext()` from this file to inject these functions into the script's global scope.

### Script Entry Point (src/run.ts)

The entry point for all heredoc execution is **[`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts)**. This module orchestrates the runtime environment by creating the helper context and binding it to the executing script. It ensures that all helpers from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) are available without requiring explicit imports in your automation code.

### Runtime Help System (src/help-runtime.ts)

For inline documentation during development, **[`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts)** builds a dynamic help system by parsing JSDoc comments from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts). You can call `help(name)` within any running script to print usage instructions, parameters, and examples for any specific helper function.

### State Management (src/state.ts)

The shared mutable runtime state—including the current task-space, active tab, and element reference map—is managed in **[`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts)**. Understanding this file helps clarify how the runtime maintains context between helper calls during complex automation workflows.

## Using the Runtime Harness

In practice, agents interact with the ego-browser runtime harness by chaining task-space management with observation and action helpers. The runtime automatically injects these functions, so you can write imperative automation scripts without import statements.

### Basic Workflow Example

This example demonstrates opening a page, capturing semantic text snapshots, and interacting with elements:

```javascript
await useOrCreateTaskSpace('example workflow')
await openOrReuseTab('https://example.com', { wait: true })
cliLog('Opened page – snapshot:')
cliLog(await snapshotText())          // semantic snapshot with @N refs
await click('button.primary')         // click by CSS selector
await waitForLoad()                   // wait for navigation or network idle
cliLog('Resulting text:')
cliLog(await snapshotText())

```

### Custom JavaScript Evaluation

To execute arbitrary code within the browser context and return structured data:

```javascript
const data = await js(String.raw`(() => {
  const items = [...document.querySelectorAll('article')]
  return items.map(el => ({
    text: el.innerText,
    links: [...el.querySelectorAll('a')].map(a => a.href)
  }))
})()`)
cliLog(JSON.stringify(data, null, 2))

```

### Hand-Off Workflows

The runtime supports interactive hand-off patterns where control returns to a human user before the script resumes:

```javascript
await handOffTaskSpace()
/* …user interacts with the browser… */
await takeOverTaskSpace()
await click('@23')
await completeTaskSpace('example workflow', { keep: false })

```

## Accessing Dynamic Help

During script execution, you can query the runtime's own documentation system. Calling `help('click')` or `help('snapshotText')` prints the JSDoc-derived signature and description for any helper defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts). This feature is particularly useful when working offline or when you need to verify parameter types without leaving the execution environment.

## Summary

- **Primary documentation** for the ego-browser runtime harness lives in [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md), with installation instructions in [`skills/ego-browser/references/install.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/references/install.md).
- **Implementation details** are found in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts), which defines all public API methods including `click`, `js`, and task-space utilities.
- **Script execution** begins at [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts), which injects helpers into the heredoc context.
- **Dynamic help** is generated at runtime from [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) by parsing JSDoc comments in the source files.
- **State persistence** is handled in [`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts), maintaining the task-space and tab context across helper invocations.

## Frequently Asked Questions

### Where is the complete API reference for ego-browser helpers?

The complete API reference is documented in [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md) within the citrolabs/ego-lite repository. For implementation specifics, inspect [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) in the `package/ego-browser` directory, which contains the actual TypeScript definitions for every method available in the runtime harness.

### How do I install the ego-browser runtime harness?

Installation instructions are located in [`skills/ego-browser/references/install.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/references/install.md). This guide covers downloading the ego-lite binary, configuring system paths, and verifying that the `ego-browser` command is accessible from your terminal before running heredoc scripts.

### What is the difference between SKILL.md and the source code?

[`SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/SKILL.md) provides a user-facing, narrative description of workflows and helper usage patterns intended for agents writing automation scripts. The source files—particularly [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) and [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts)—contain the actual implementation, type signatures, and runtime injection logic that power the harness.

### How does the runtime inject helpers into heredoc scripts?

When executing a script via `ego-browser nodejs`, the runtime uses [`src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/run.ts) as the entry point. This module invokes `helperContext()` from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) to create a context object containing all helper functions, which is then bound to the global scope of the executing heredoc script, making methods like `click()` and `snapshotText()` available without requiring import statements.