ego-browser
ego-browser
ego-browser exposes a real Chromium browser through a CLI-accessible Node.js runtime. Its preloaded page, page.locator(...), browser, and taskSpaces facades follow Playwright-style names and call shapes; taskSpaces, site, fetch, and cdp provide ego-browser-specific capabilities.
For setup, install, or connection problems, read references/install.md.
Run browser work with the Bash tool as ego-browser nodejs <<'EOF' ... EOF. Put the JavaScript directly in the heredoc; do not create a .js file, import Playwright, launch another browser, or invent helper names.
A heredoc is only the JavaScript container; the Bash invocation is the execution round. Default to one Bash invocation for the whole browser task. Each await is an internal operation, not a step boundary. Before launch, encode every predictable observation, action, wait, extraction, verification, and bounded alternative in the script. Use browser results immediately in JavaScript and keep adapting in-process until the task completes; do not exit merely to inspect intermediate output or plan the next action. Start another Bash command only for required user or external control, visual inspection that cannot happen in-process, or a process-level failure the script cannot recover from.
Choose the least-stateful reliable route before inspecting page controls. When the task specifies an outcome or constraints but not a required interaction, prefer an already-correct state or a known stable URL or site route that directly encodes them; verify the resulting goal state instead of replaying equivalent filters, sorting, or navigation through the UI. Use page controls when the user requested that interaction, the interaction itself is under test, or no reliable equivalent is known. Never invent a brittle route.
Treat an already-satisfied postcondition as completed work. Before manipulating a control whose required value may already be visible, perform only the smallest read needed to decide that state. If it matches, do not open its editor, replay the interaction, or read it again; continue directly to the remaining unsatisfied outcomes. Words such as “set”, “select”, or “ensure” describe the required final state unless the user explicitly requires the transition or the interaction itself is under test.
Separate browser work from terminal completion. useOrCreate begins or resumes one user goal; keep its returned task.id, and reuse the same id or exact same name until that goal is terminal. Keep every predictable observation, action, wait, extraction, and verification compact, but do not call taskSpaces.complete(...) in a Bash invocation that is still determining whether the goal is satisfied. First finish the browser work and print evidence that every requested outcome and any required scope or coverage boundary has been proven. Only after reviewing that prior output may a dedicated final Bash invocation complete the original task space; it performs no page or browser work. This single lifecycle commit is the exception to the one-invocation default, not a browser step or round. Nonempty or plausible partial results, a stalled page, exhausted retries, or a fallback attempt are not completion evidence. keep: true preserves a terminal result for the user; it does not keep an unfinished task alive.
Freeze the time window for current or relative-date work. Establish “today/current/latest” once from the user/task environment or explicitly verified current page state before collecting records. Treat content timestamps as data, not as the clock. Older records revealed by scrolling, virtualization, reload, cache, or a changed result batch must not replace that anchor. Continue evaluating records against the original window; do not silently rebase the task to the newest content date observed.