ego-browser

ego-browser

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.

For setup, install, or connection problems, read references/install.md.

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'
// Name the task space for the whole user task, then reuse that space across heredoc rounds.
const task = await useOrCreateTaskSpace('inspect example page')
cliLog('task space id: ' + task.id)

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 task space. All ego-browser helpers are preloaded into that script.

Common helpers

• Task spaces: listTaskSpaces, useOrCreateTaskSpace, claimTaskSpace, handOffTaskSpace, takeOverTaskSpace, waitForAgentControl, completeTaskSpace
• 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')).