Where to Find Documentation for the ego-browser Runtime Harness

All documentation for the ego-browser runtime harness is located in the SKILL.md file within the skill package and the TypeScript source files in package/ego-browser/src/, particularly 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. 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. 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 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 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. 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 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 builds a dynamic help system by parsing JSDoc comments from 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. 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:

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:

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:

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. 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, with installation instructions in skills/ego-browser/references/install.md.
• Implementation details are found in 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, which injects helpers into the heredoc context.
• Dynamic help is generated at runtime from src/help-runtime.ts by parsing JSDoc comments in the source files.
• State persistence is handled in 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 within the citrolabs/ego-lite repository. For implementation specifics, inspect 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. 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 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 and 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 as the entry point. This module invokes helperContext() from 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.

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