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

> Debug ego-lite clicks visually with the --debug-clicks flag. Highlight automated clicks instantly to verify target coordinates and improve your testing.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-07-28

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts) processes the flag before any user script runs. At line 85, the harness checks the first argument:

```typescript
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.

```bash
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.

```bash
EGO_BROWSER_DEBUG_CLICKS=1 node my-ego-script.js

```

Because [`run.ts`](https://github.com/citrolabs/ego-lite/blob/main/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:

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts)** – Contains the argument check at line 85 that triggers the debug mode. See the implementation [here](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts#L85).

- **[`package/ego-browser/README.md`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/README.md)** – Lists the `--debug-clicks` flag among the available CLI options. Review the documentation [here](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/README.md#L35).

- **[`CONTRIBUTING.md`](https://github.com/citrolabs/ego-lite/blob/main/CONTRIBUTING.md)** – Explains the relationship between the flag and its equivalent environment variable for developers. Read the details [here](https://github.com/citrolabs/ego-lite/blob/main/CONTRIBUTING.md#L129).

## Summary

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

- [`package/ego-browser/src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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)](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.