How to Debug Clicks with the `--debug-clicks` Flag for Visual Highlighting in ego-lite

Passing --debug-clicks to the ego-browser CLI sets EGO_BROWSER_DEBUG_CLICKS=1, which overlays a transient visual highlight on every automated click so you can instantly verify target coordinates.

The ego-browser package in the citrolabs/ego-lite repository provides a built-in mechanism to debug click actions. You can enable visual highlighting directly from the command line without altering your automation scripts, making it a fast way to troubleshoot selectors and timing issues.

How --debug-clicks Enables Visual Highlighting

The CLI entrypoint in package/ego-browser/src/run.ts processes the flag before any user script runs. At line 85, the harness checks the first argument:

if (argv[0] === "--debug-clicks") {

When this condition matches, the code sets the environment variable EGO_BROWSER_DEBUG_CLICKS to 1. Downstream pointer logic detects this variable and renders a lightweight overlay—a semi-transparent circle or rectangle—at the exact coordinates of each dispatched click. The indicator fades shortly after appearing, giving you precise visual confirmation of the click target.

Running ego-browser with the --debug-clicks Flag

Supply the flag when invoking the CLI to activate visual debugging for the entire session.

ego-browser --debug-clicks <<'JS'
  await nav('https://example.com')
  await click('button.login')
JS

While the script runs, every click call produces a brief colored highlight on the rendered page. This lets you confirm that the automation interacted with the intended element rather than an empty coordinate or a hidden overlay.

Alternative: Debug with the Environment Variable

You can also enable the same behavior by setting the environment variable manually. This approach is useful when running scripts through node or in containers where you prefer not to pass CLI flags.

EGO_BROWSER_DEBUG_CLICKS=1 node my-ego-script.js

Because run.ts evaluates the flag early in the lifecycle, exporting the variable before process start ensures the debug overlay remains active from the first navigation onward.

Example: Visual Highlighting for Locator Verification

Consider a script that navigates Hacker News and clicks a navigation link:

await nav('https://news.ycombinator.com')
await click('a[href="newest"]')
await waitFor('a.storylink')

When you execute this block with --debug-clicks, a transient highlight appears on the "newest" anchor. If the highlight surfaces in the wrong location, you immediately know the locator needs refinement before the script proceeds to an unexpected page.

Key Source Files

Understanding where the logic is implemented helps when reading the source or contributing patches.

• package/ego-browser/src/run.ts – Contains the argument check at line 85 that triggers the debug mode. See the implementation here.

• package/ego-browser/README.md – Lists the --debug-clicks flag among the available CLI options. Review the documentation here.

• CONTRIBUTING.md – Explains the relationship between the flag and its equivalent environment variable for developers. Read the details here.

Summary

The --debug-clicks flag offers a zero-code method to debug with visual highlighting in ego-browser.

• package/ego-browser/src/run.ts parses --debug-clicks and sets EGO_BROWSER_DEBUG_CLICKS=1.
• Downstream pointer code draws a fading overlay at each click coordinate.
• You can replace the flag with the environment variable in manual or CI workflows.
• Visual feedback accelerates debugging of selectors, coordinate mismatches, and timing errors.

Frequently Asked Questions

Can I use --debug-clicks with any ego-browser script?

Yes. Because run.ts processes the flag before evaluating user code, the visual overlay is active for the entire automation session regardless of which pages or elements the script touches.

How do I enable click debugging without passing CLI flags?

Export EGO_BROWSER_DEBUG_CLICKS=1 in your environment before starting the process. The downstream pointer code reads this variable and produces the same visual highlights as the --debug-clicks flag.

What type of visual indicator does the flag produce?

When enabled, the pointer logic injects a transient, semi-transparent circle or rectangle directly at the click coordinates. The overlay fades automatically after a short interval, leaving the page state unchanged.

Where is the --debug-clicks argument handled in the source?

The argument is parsed in [package/ego-browser/src/run.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts#L85). When argv[0] equals "--debug-clicks", the harness sets the corresponding environment variable and continues with script execution.

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