ego-browser-o

ego-browser gives AI agents a CLI-accessible Node.js runtime, with built-in helpers — snapshotText, click, js, cdp, and more — that agents call directly inside JS scripts to observe pages, interact with UI, evaluate browser-side JavaScript, and drive a real browser for any web automation task.

Use the Bash tool to run all browser operations via ego-browser nodejs <<'EOF' ... EOF heredoc. Do not write code to a .js file first.

Quick start

ego-browser nodejs <<'EOF'
// Required bootstrap: select a browsing context before any browser op. Use the same name every round.
const task = await useOrCreateTaskSpace('inspect-example')

await openOrReuseTab('https://example.com', { wait: true, timeout: 20 })

cliLog(await snapshotText())
EOF

The heredoc body runs as a Node.js script that controls the selected ego-browser browsing context. All ego-browser helpers are preloaded into that script.

useOrCreateTaskSpace(nameOrId) is a required bootstrap, not optional. Without it, every browser op — even read-only ones like listTabs / snapshotText — fails with Task space not selected. The selection does not survive across heredocs (each Node process exits and forgets it), so every working heredoc must start with useOrCreateTaskSpace(nameOrId) using the same name to re-select the same context with its tabs.

nameOrId can be a name, numeric id, or digit-only id string. String values match name/taskId first, then digit-only strings fall back to numeric id. Number values match existing numeric ids only. Use a short name describing the task and keep using that same name across rounds so all rounds share one context and its tabs.

Common helpers

• Bootstrap: useOrCreateTaskSpace
• Navigation / state: listTabs, openOrReuseTab, closeTab, gotoAndWait, currentTab, switchTab, gotoUrl, pageInfo, ensureRealTab
• Observation: snapshotText, captureScreenshot, drainEvents
• Scroll / mouse: scrollBy, scrollToBottomUntil, scroll, click, doubleClick, hover, dragMouse
• Keyboard & input: typeText, fillInput, pressKey, dispatchKey
• File: uploadFile
• Wait: wait, waitForLoad, waitForElement, waitForNetworkIdle
• Fetch: serverFetch, browserFetch
• CDP / evaluate: js, cdp
• Output: cliLog, help

Notes:

• cliLog(value) — prints to the terminal; it is the only output mechanism inside a heredoc, and all final results must go through it.
• await pageInfo() — normally resolves to { url, title, w, h, sx, sy, pw, ph }; if a native browser dialog is open, resolves to { dialog: ... } instead because page JavaScript is blocked.
• If await pageInfo() resolves to { dialog: ... }, handle the dialog with await cdp('Page.handleJavaScriptDialog', { accept: true }) or accept: false before running page JavaScript.
• await ensureRealTab() — switches to an existing non-internal page tab if needed and resolves to it; resolves to null when none exists. It does not create a tab — use await openOrReuseTab(...) for that.
• await closeTab(target?) — closes the given target id / tab object, or the current tab when omitted.
• await drainEvents() — consumes and returns the async event queue produced by the page (navigation events, network events, etc.).
• await serverFetch(url, options) — issues a request from Node and returns the response body.
• await browserFetch(url, options) — issues a request from the current browser page context and returns the response body.
• help(name) — prints usage for a given helper, e.g. cliLog(help('click')).

Scroll / mouse

// DOM scroll
await scrollBy(900)
await scrollToBottomUntil(
  async () => await js(String.raw`document.querySelectorAll('article').length`) >= 20,
  { step: 900, wait: 1, maxSteps: 20 }
)

// Real wheel event
await scroll({ dy: 900 })

Element-target helpers such as click, doubleClick, hover, dragMouse, fillInput, uploadFile, and waitForElement accept the same selector/ref surface: raw CSS, xpath=..., @N / ref=N, and loc=... values from snapshotText() (loc=css:..., loc=role:..., loc=href:...). @N refs are for ego-browser helpers only; they are not valid selectors inside document.querySelector(...).

click, doubleClick, hover, and dragMouse share these target formats. Coordinates are in CSS pixels:

• string — CSS selector, xpath=..., @N / ref=N, or loc=...; clicks the element's center.
• [x, y] or {x, y} — viewport coordinates.
• {selector} — CSS selector, xpath=..., @N / ref=N, or loc=...; clicks the element's center.
• {selector, x, y} — offset from the element's top-left corner by x/y.
• options.label (optional) — a 3-6 word action description; triggers a visual highlight animation.

await click('@21', { label: 'check login status' })
await click('button.primary', { label: 'click submit button' })
await click([420, 260])
await click({ x: 420, y: 260 })
await click({ selector: 'canvas#stage', x: 12, y: 8 })
await hover('@5', { label: 'hover to reveal menu' })
await dragMouse([from, to], { label: 'drag card' })

uploadFile

await uploadFile('input[type="file"]', "/absolute/path/to/file.pdf")

js

js() is essentially Runtime.evaluate and takes a string. You can pass a function, but doing so triggers a one-time warning and wraps it via .toString() — closures are not captured and there is no argument channel. Do not use js() the way you would Puppeteer / Playwright's page.evaluate(fn, ...args).

When you need to run multi-step logic inside the browser, wrap it in a single self-invoking closure and return once — don't split it across multiple await js() calls:

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),
  }))
})()`)

Recommended workflow

Every heredoc — for all three workflows below — must start with const task = await useOrCreateTaskSpace(nameOrId) before any browser op. Skipping it fails with Task space not selected, even for read-only observation.

ego-browser has three main workflows. Pick the workflow that fits the page and task before acting.

Use the semantic workflow first for ordinary websites with real DOM controls. For canvas-like productivity apps and rich editors — including Google Docs, Google Sheets, Lark/Feishu Docs, Notion, Figma, whiteboards, maps, and other virtualized editors — use the visual workflow first for the main editing surface. These apps often expose toolbars, title inputs, hidden textareas, offscreen iframes, or canvas layers in the DOM that do not represent the actual user-editable document or grid. Do not rely on await fillInput(...), DOM selectors, or snapshotText() refs for the main editing surface unless a small write probe proves the text lands in the intended place.

Before writing substantial content into a rich editor, perform a tiny write probe, then verify it with await captureScreenshot(), an export/readback path, or another reliable visual/state check. If the probe appears in the title bar, toolbar search, hidden input, or any wrong field, stop using DOM/input helpers for that surface and switch to screenshot-guided mouse actions plus real keyboard operations.

1. Semantic workflow: snapshotText() + refs / locators — default for most pages with normal text, links, buttons, forms, tables, and lists.

   • Bootstrap the context: const task = await useOrCreateTaskSpace(name).
   • Open or switch pages with await openOrReuseTab(url, { wait: true }); use await gotoAndWait(url, { timeout, settle }) only when navigating inside the current tab.
   • Observe with await snapshotText() to get a full-page semantic tree annotated with [ref=N, loc=..., url=...].
   • Act with await click('@N'), await fillInput('@N', ...), or stable loc=... values. Use direct DOM logic only when it is simpler than helper calls.
   • After meaningful clicks, input, or navigation, observe again with await snapshotText(), await pageInfo(), or await captureScreenshot() before assuming success.

2. Visual workflow: await captureScreenshot() + coordinate/keyboard actions — use when the page is primarily visual, canvas-like, heavily virtualized, or when accessibility / semantic structure is incomplete.

   • Inspect the screenshot, act with viewport coordinates such as await click([x, y]), await doubleClick([x, y]), await pressKey(...), and await typeText(...), then verify with another screenshot or a reliable export/readback path.
   • Prefer this path for rich editors, spreadsheets, visual menus, map/canvas UIs, drag interactions, and targets that are obvious visually but poor in the DOM/AX tree.

3. Direct DOM / CDP workflow: await js(...) / await cdp(...) — use when you need browser state, compact data extraction, custom DOM traversal, or raw browser capabilities.

   • Keep browser-side logic in one explicit IIFE and return once.
   • Use await cdp(...) for browser protocol operations that helpers do not cover.

These workflows can be combined. A task may take multiple heredoc rounds when the next step depends on fresh page state. Each round must re-bootstrap with useOrCreateTaskSpace(name) before any browser op. In each round, write a coherent script that advances the task: observe, act or extract, verify, and report with cliLog(...). Avoid tiny probe scripts, but don't force the whole task into one oversized script.

Caveats

• wait(...) and timeout values are in seconds; only parameters whose names end in Ms are milliseconds.
• snapshotText() defaults to scope: 'full_page', covering the whole page. Use the default in almost every case; only pass scope: 'only_within_viewport' when the task needs only visible content.
• @N refs are only valid for the most recent snapshotText call — every call rebuilds the refMap. Ref numbers come from the CDP backendNodeId, so the same element keeps the same number across calls; but to use @N, N must appear in the latest snapshotText output. An element scrolled out of the viewport, a DOM re-render, or a previous call with scope:'only_within_viewport' that didn't cover the element will all cause Unknown ref. For elements you need to reference long-term, use the loc=... value from snapshotText output as a stable selector, or write a CSS selector directly.
• js() returns the evaluated result, not a JSON string — don't wrap it with JSON.parse(...).
• Inside a js(...) template string, regex backslashes must be doubled (e.g. \\d, \\s), or use String.raw.
• If the source passed to js() contains a top-level return, it will be auto-wrapped in an IIFE; return inside nested callbacks can also trigger this accidentally. For complex expressions, prefer the explicit (() => { ... })() form.
• If await pageInfo() reports w: 0 or h: 0, do not continue coordinate actions or screenshots until the viewport is fixed. Try switching to the real tab, reloading, or using CDP viewport metrics, then verify with await pageInfo() and await captureScreenshot().
• Code in the heredoc body runs in Node.js; code inside js(...) runs in the browser page. Navigation, waits, and cliLog(...) belong in the heredoc body; document, window, and page selectors belong inside js(...).
• When the user explicitly asks to use ego-browser, assume both ego-browser and the repo runtime are ready. Do not pre-check which ego-browser, node -v, package metadata, or help output. Only investigate environment issues if the first run produces an error.
• If the first run reports command not found / a missing environment (most likely ego lite isn't installed yet), stop and tell the user ego lite needs to be installed rather than guessing at a fix — do not give up silently, and do not keep retrying the same heredoc.