browser-repl

name

browser-repl

description

Drive a live browser from a ClojureScript REPL - nbb + Playwright behind an nREPL, evaluated through the nrepl MCP. The powerhouse for verifying/testing web products, scraping, auth automation, bulk downloads, and UI prototyping. Gives liveness (browser + atoms persist across evals), token economy (targeted extracts and scoped aria instead of multi-KB snapshots), live network/console capture for backend correlation, the full Playwright API, and fire-and-poll for long ops. Use when you need to interactively drive or inspect a real browser at low token cost, or correlate UI actions with backend signals. Use jxa-browser only for a quick peek at the user's already-open everyday browser.

Browser REPL (browser-repl)

A live nbb (ClojureScript on Node) + Playwright session behind an nREPL. You drive it with ordinary nrepl-eval calls, so state is live (the browser, context, page, and capture atoms persist across evals) and you query exactly what you need instead of dumping huge snapshots.

agent -> nrepl MCP (auto-awaits cljs) -> nbb nREPL (holds browser + atoms) -> Playwright -> chromium

Stdlib: /Users/ryl/GitHub/agzam/death-contraptions/tools/browser-repl/browser_repl.cljs Launcher: /Users/ryl/GitHub/agzam/death-contraptions/tools/browser-repl/launch.bb

When to use which browser tool

• jxa-browser - the user's REAL, already-open everyday browser via AppleScript. Zero setup, non-invasive. Use for a quick peek at what they're looking at. No protocol-level network/devtools, no cross-origin iframes.
• browser-repl (this) - the powerhouse. Iterative driving, targeted extraction, live network/console capture, full Playwright API, long-running flows. Default choice for verifying/testing/automation.

Prerequisites

• Deps installed once: (cd /Users/ryl/GitHub/agzam/death-contraptions/tools/browser-repl && npm install) (pins nbb + playwright; postinstall fetches chromium - reused from the shared ms-playwright cache).
• nrepl MCP enabled: :servers {:nrepl {:disabled? false}} in local-config.edn.gpg, then bb setup.bb, then reload the MCP. macOS/Linux.

1. Start a session

Run the launcher (a background job). It starts the nbb nREPL, requires the stdlib, applies the mode, launches the browser, writes .nrepl-port, and prints the port. Keep it running; killing it tears the whole tree down.

bb /Users/ryl/GitHub/agzam/death-contraptions/tools/browser-repl/launch.bb --mode fresh

Modes (--mode):

• fresh (default) - ephemeral context, wipes cookies. Best for most testing.
• persistent - reuses a login profile (--user-data-dir); log in once, reuse.
• attach - connects to an existing browser over CDP (--cdp-endpoint http://127.0.0.1:9222); real session + network depth, fills jxa's protocol gap.

Other flags: --port <n> (else a free ephemeral port), --headless, --port-file-dir <dir> (where .nrepl-port is written; default CWD).

Note the printed port - you will pass it to nrepl-eval explicitly.

2. Drive it via nrepl-eval

Pass :port <the launcher's port> and :await true. Both are now usually auto-handled - the launcher advertises its port to the registry dir (~/.cache/nrepl-ports/, override $NREPL_MCP_PORT_DIR) so the MCP can auto-discover a session even in a sibling repo, and the MCP classifies nbb correctly so it auto-awaits cljs ports. But explicit :port + :await true stays the reliable default (and is the only thing that works until the MCP has reloaded those fixes). :await true is what makes promises resolve - nbb returns the promise object otherwise (see gotchas).

The stdlib is loaded as the browser-repl namespace. Call it qualified (browser-repl/goto) or alias it once per session: (require '[browser-repl :as b]).

(browser-repl/goto "https://example.com")     ; -> "https://example.com/"
(browser-repl/status)                          ; compact session state

Navigation/interaction (each auto-starts the browser if needed):

• (goto url) (current-url) (wait-url glob-or-regex) (wait-for target)
• (wait-load "load|domcontentloaded|networkidle") (wait-networkidle) - PAGE lifecycle, e.g. after a click that fires background XHRs. wait-for is for a target's state only; for page settle use these (passing wait-for a {:state "load"} map errors with "Could not find instance method: first").
• (click target) (fill target s) (type-text target s) (press target key)

target is a spec resolved at action time (no "built before start" trap):

• "css selector" | a Playwright Locator
• [:role "button" {:name "Save"}] | [:text s] | [:label s] | [:placeholder s] | [:testid s]

3. Eyes and extraction (token economy)

Prefer targeted reads over snapshots:

• (aria) / (aria target) - scoped ARIA snapshot, the compact "eyes" (default body).
• (texts target) - vector of trimmed text contents. (text target) - first one.
• (count-of target) (attrs target "href") (visible? target)
• (eval-js "document.title") - escape hatch.

4. Network and console capture (correlation)

Opt-in; attach BEFORE the action so nothing is missed.

(browser-repl/capture-net! {:url-filter "/api/v1"})  ; record matching requests/responses
(browser-repl/goto "...")
(browser-repl/net-summary)                            ; {:requests N :responses M :by-status {200 ..}}
(browser-repl/net-where "/api/v1/datasets")           ; compact matching entries + correlation headers

Each net entry is {:phase :req|:resp :method :url :status :headers :ts}; net-where projects :phase :method :status :url :headers. :headers on a :req holds the request-side correlation keys (x-request-id, traceparent, ...) - the join key for a backend watcher (see the monitor skill) - but it is often {}: many backends (Qlik included) inject trace ids server-side at the gateway, so the browser never sends them. When :headers is empty, correlate on tenant + endpoint + time instead. (capture-console!) + (console-tail n) for console output.

5. Long ops: fire-and-poll

For slow flows, do not block a tool call. Kick the work off and poll between turns:

(browser-repl/run-job! :crawl (fn [] (p/let [...] result)))  ; returns :crawl immediately
(browser-repl/job :crawl)                                     ; {:status :running|:done|:error ...}

6. Iterating on the stdlib (live REPL development)

Editing browser_repl.cljs? Reload it in place - defonce keeps the live browser and capture atoms:

(require '[browser-repl] :reload)   ; nbb has NO load-file; use :reload
(browser-repl/status)               ; still :started? true after reload

Errors and gotchas

• With :await true, a failed call is a GENUINE error: isError, the real message (e.g. the full Playwright timeout + call log), and *e bound to it - inspect with (ex-message *e). A success sets *1 for chaining. (*2/*3 are not reliable: nbb's history vars are global and the await poll shifts them.)
• "nth not supported on this type function(a,b,c,d){this.cc=a;...}" is nbb's spurious print of a promise-bearing eval. The await path now tolerates it (eval-code-await polls the sentinels instead of bailing). If you STILL see it on a :await true call, either you omitted :await true, or the MCP is serving stale code - call nrepl-server-info; stale? true means a source file is newer than the running process, so reload the MCP.
• eval-js takes a JS EXPRESSION string. A bare "() => document.title" returns the function (serializes to nil). Use "document.title" or an IIFE.
• nbb has no load-file; load/reload the stdlib with (require '[browser-repl] :reload).
• Combining async reads in one eval: use p/let, not let. Every browser-repl fn returns a promise, so (let [u (current-url) t (eval-js "document.title")] {:u u :t t}) yields a map of unresolved #<Promise>s; (p/let [u (current-url) t (eval-js "document.title")] {:u u :t t}) resolves them. (Driving over the proto bencode client --await, the kickoff already wraps your form in p/let, so the form itself can be a plain p/let.)
• A browser that closes underneath the session (crash, window closed) no longer wedges it silently: started? reflects real liveness (checks .isClosed) and the next (goto ...)/action drops the dead handles and relaunches. Caveat: a :persistent session whose chromium lingers holding the profile lock surfaces Opening in existing browser session ... profile is already in use - that is the actionable error (not the old cryptic "Target page... closed"). Recover by killing the launcher bg job (its shutdown hook tree-kills the zombie + frees the lock), then relaunch.

Safety

• Local-only: the nREPL evaluates ARBITRARY code (RCE-equivalent). The launcher binds 127.0.0.1 only - never expose the port or bind a public interface.
• Fresh-profile default: fresh mode persists no cookies/credentials. Use persistent/attach only for deliberate tenant/session testing.
• Mutation gating: on a real or shared tenant, confirm before any create/run/ delete UI action. Prefix any created artifacts and clean them up.
• Never echo credentials: for logins, fill from values pulled out of the encrypted config; never print passwords, tokens, or cookies into the chat, and do not dump full network payloads that may contain secrets.

Teardown

Kill the launcher background job (eca__bg_job action=kill) - its shutdown hook SIGTERMs then SIGKILLs the whole tree (nbb + chromium) and removes the .nrepl-port it wrote. fresh leaves nothing behind; persistent keeps its profile so the next run skips re-auth.

API reference (browser-repl ns)

configure! start! stop! page started? status api
goto current-url wait-url wait-for wait-load wait-networkidle
click fill type-text press        ; target := "css" | [:role r {opts}] | [:text/:label/:placeholder/:testid s] | Locator
loc css by-role by-text by-label by-placeholder by-testid
texts text count-of attrs visible? aria eval-js
capture-net! net-summary net-where net-clear!   capture-console! console-tail console-clear!
download! assert! assert-visible   run-job! job
atoms: net console jobs state ; config keys: :mode :headless? :user-data-dir :cdp-endpoint :viewport