How to Report a Bug in ego‑lite: A Complete Guide for Developers

Submit a bug report in ego‑lite by opening a GitHub issue using the Bug report template at .github/ISSUE_TEMPLATE/bug_report.yml, providing your version numbers, a minimal reproducible script, and sanitized logs.

The ego‑lite project is a two‑part browser automation system maintained by Citrolabs. The open‑source component—the ego‑browser skill package—contains the JavaScript helpers and runtime logic that agents invoke. When something breaks, maintainers need precise information to route, reproduce, and fix the issue. This guide shows you exactly how to report a bug in ego‑lite using the project's official workflow and source code structure.

Understanding the ego‑lite Architecture

ego‑lite splits responsibility between a closed‑source binary and an open‑source package:

Component	Responsibility	Key Files
ego‑lite browser app	Provides CDP transport (ego.sendCDPMessage), owns the UI, runs the ego‑browser runtime	(binary—not in this repo)
ego‑browser skill package	Supplies helper functions (click(), fill(), captureScreenshot()), manages task‑spaces, snapshots, element resolution, and error handling	src/helpers.ts, src/element-resolver.ts, src/state.ts

Most bugs you'll encounter involve the skill package, where all public helpers are exported from helperContext() in [src/helpers.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts). Understanding this boundary helps you write reports that reach the right maintainer.

Prerequisites Before Reporting

Check for Existing Issues

The bug report template's first checkbox requires you to confirm the issue hasn't already been filed. Search GitHub Issues for keywords from your error message, helper name, or stack trace.

Gather Version Information

Run the CLI to collect critical version data:

ego-browser --version

This flag is implemented in [src/run.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts) and outputs both the ego‑lite app version and the ego‑browser skill version (found in package.json). Include these exact strings in your report—CI pipelines use them to select the correct Docker image and binary for reproduction.

Step‑by‑Step Bug Reporting Workflow

1. Create a Minimal Reproducible Script

Write a short heredoc‑compatible script using only public helpers from src/helpers.ts. The script should isolate the bug without unnecessary steps.

Example: Navigation and click failure

await go('https://example.com');
await waitFor('a[href="/login"]');
await click('a[href="/login"]');
await pageInfo();

Example: Screenshot capture issue

await go('https://example.com');
await captureScreenshot('homepage.png');
cliLog('Screenshot saved');

The helpers go, waitFor, click, pageInfo, captureScreenshot, and cliLog are all defined in [src/helpers.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts). The cliLog function routes through [src/output-sink.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/output-sink.ts), which handles structured runtime logging.

2. Collect and Sanitize Logs

The runtime prints structured logs via the output sink. Copy the relevant portion from your terminal, then remove any secrets (API keys, session tokens, credentials). The bug report template includes a checkbox explicitly reminding you to sanitize sensitive data.

3. Open the GitHub Issue

Navigate to the repository and select New issue → Bug report. The template at [.github/ISSUE_TEMPLATE/bug_report.yml](https://github.com/citrolabs/ego-lite/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) enforces required fields:

• Component selector (component dropdown) — Routes your issue to the correct maintainer ("ego‑browser runtime or CLI" vs "ego lite browser app")
• Version fields — Paste output from ego-browser --version
• Reproduction steps — Paste your minimal script in a fenced js code block
• Expected vs actual behavior — Describe precisely what should happen versus what occurred
• Logs — Paste sanitized output from the runtime

4. Submit and Monitor

After submission, watch for maintainer questions. The CI‑run E2E suite in scripts/real-browser-e2e/ may be used to automatically reproduce your report if it follows the template structure.

Advanced Reproduction: Task‑Space APIs

For bugs involving isolated agent sessions, include task‑space usage in your reproduction:

const space = await newTaskSpace('bug-repro');
await useOrCreateTaskSpace(space);
await go('https://example.com');
await completeTaskSpace(space, { keep: true });

These APIs live in src/taskspace.ts (exported via helpers.ts) and manage isolated task spaces tracked in [src/state.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts). The singleton runtime state in state.ts holds sessions, task‑spaces, and snapshots—making it a common source of state‑related bugs.

Why the Template Structure Matters

The [.github/ISSUE_TEMPLATE/bug_report.yml](https://github.com/citrolabs/ego-lite/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) template isn't bureaucratic overhead—it's designed for the project's operational needs:

• Component routing ensures browser‑binary bugs don't sit in the skill package queue
• Version specificity allows maintainers to pull exact Docker images matching your environment
• Reproducible scripts enable automated E2E verification using the scripts/real-browser-e2e/ suite
• Log sanitization reminders protect users from accidental credential exposure

Reports that skip these fields often require multiple back‑and‑forth rounds before maintainers can act.

Common Bug Categories and Relevant Source Files

Bug Symptom	Investigate This File	Typical Cause
Element not found, locator fails	src/element-resolver.ts	Incorrect @N index, malformed loc=css: or xpath= selector
State inconsistencies between steps	src/state.ts	Task‑space isolation, session lifecycle bugs
Helper function throws or hangs	src/helpers.ts	async/await handling, timeout configuration
Screenshot or output missing	src/output-sink.ts	Log routing, file permission issues

The element resolver in [src/element-resolver.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/element-resolver.ts) implements locator resolution logic (@N for indexed elements, loc=css: for CSS selectors, xpath= for XPath)—a frequent source of user confusion worth detailing in your report if relevant.

Summary

• Search existing issues before filing to avoid duplicates
• Run ego-browser --version to capture exact version strings from src/run.ts
• Write minimal scripts using public helpers from src/helpers.ts
• Sanitize logs from src/output-sink.ts to remove secrets
• Use the Bug report template at .github/ISSUE_TEMPLATE/bug_report.yml for proper routing and faster resolution
• Include component, versions, reproduction steps, expected/actual behavior, and logs—every field serves a specific diagnostic purpose

Frequently Asked Questions

How do I know whether my bug is in the browser app or the skill package?

If your script uses helpers like click(), fill(), or captureScreenshot(), the bug likely belongs to the ego‑browser skill package (this repo). If the issue involves UI rendering, CDP connection failures, or binary crashes before any script runs, it belongs to the ego‑lite browser app (closed‑source). The component dropdown in the bug report template lets you specify this distinction.

What makes a good minimal reproduction script?

A good script is heredoc‑compatible (can be fed directly to ego-browser), under 10 lines, uses only documented helpers from src/helpers.ts, and fails deterministically on your environment. Avoid external dependencies, dynamic URLs, or steps requiring manual intervention. The simpler the script, the faster maintainers can verify the bug in their own environment.

Where does ego‑lite store runtime logs?

Structured logs are emitted through the output sink implemented in [src/output-sink.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/output-sink.ts). When running via CLI, these appear in your terminal. Always copy the complete error stack and surrounding context—logs are essential for diagnosing element resolution failures and task‑space state issues.

Can I report security vulnerabilities the same way?

No—public visibility for security issues is discouraged. The standard bug report template is for functional bugs only. Check the repository's security policy (typically SECURITY.md) for responsible disclosure procedures regarding vulnerabilities in src/helpers.ts, src/state.ts, or other sensitive components.

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