Ego Browser

Problem

Web automation for AI agents often splits across two mismatched layers: the agent side must run scripts, wait, log, and manage task state, while the browser side needs access to document, window, real viewport metrics, and page JavaScript. ego-browser gives AI agents a CLI-accessible Node.js runtime with built-in helpers such as snapshot, click, evaluate, and cdp, so an agent can observe pages, interact with UI elements, evaluate browser-side JavaScript, and drive a real browser within one scripted workflow.

How It Works

Run browser operations through the Bash tool using the ego-browser nodejs { ... })() form. The heredoc body is Node.js code: put navigation, waits, console.log(...), and task-space management there. Anything that needs the page context—document, window, CSS selectors, or browser JavaScript—belongs inside evaluate(...). A typical loop is: inspect the page with snapshot or pageInfo(), check whether coordinates are valid, perform click or evaluate, then call completeTaskSpace(name, { keep }) when the task is done. Use { keep: false } by default; use { keep: true } only for concrete live-page cases.

Notes

• If await pageInfo() reports w: 0 or h: 0, stop coordinate actions and screenshots until the viewport is fixed. Try switching to the real tab, reloading, or checking CDP viewport metrics, then verify with pageInfo() and screenshot().
• A trailing [ego-browser:notice] line is an update hint, not an error. Do not interrupt the current task; after the task stops or completeTaskSpace() completes, ask whether to upgrade and restart ego lite.
• Assume the runtime is ready unless the first run errors. If the first run reports command not found or a missing environment, follow the installation flow and then return to the original task.