mini-browser

mini-browser (mb) — Browser CLI for Agents

mb is a browser CLI where each command is a small Unix tool. It talks to Chrome over CDP (port 9222) via puppeteer-core.

Setup (only if not already available)

Setup is only needed when mb is not installed or Chrome is not reachable. Run these checks first — if both pass, skip straight to the Command Reference.

Check if ready

# 1. Is mb installed?
which mb && echo "mb: ok" || echo "mb: MISSING"

# 2. Is Chrome listening on CDP?
curl -sf http://127.0.0.1:9222/json/version > /dev/null && echo "chrome: ok" || echo "chrome: NOT RUNNING"

If both print "ok", everything is ready — go use mb commands directly.

Install (only if mb is missing)

npm install -g @runablehq/mini-browser

Start Chrome (only if not running)

mb-start-chrome

This launches Chrome with --remote-debugging-port=9222, a fresh profile, and a 1024×768 window. It no-ops if Chrome is already running.

To kill and relaunch:

mb-restart-chrome

Verify

mb go "https://example.com" && mb text

Environment Variables

Command Reference

Navigation

Observation

Interaction

Recording

Tabs

Other

Flags

Usage Patterns

Observe → Act loop

The standard agent loop: snapshot the page, pick an element, act on it.

mb snap                          # list interactive elements with (x, y)
mb click 512 380                 # click the button at those coordinates
mb wait networkidle              # wait for the page to settle
mb snap                          # observe again

Fill and submit a form

mb go "https://example.com/login"
mb fill "Email=user@example.com" "Password=hunter2"
mb key Enter
mb wait url:/dashboard

Take a screenshot

mb shot page.png
mb shot page.png --width 1440 --height 900

Extract text

mb text "main"                   # text from <main>
mb text "#content"               # text from #content
mb text                          # full body text

Run JavaScript

mb js 'document.title'
echo 'document.querySelectorAll("a").length' | mb js -

Record a screencast

mb record start demo.mp4 --fps 30 --scale 1
# ... interact with the page ...
mb record stop

Design audit

mb audit                         # human-readable report
mb audit --json                  # structured JSON output

Dismiss overlays

Cookie banners and modals block clicks. Remove them with JS:

mb js 'document.querySelector("[class*=cookie]")?.remove()'

Wait strategies

mb wait 2000                     # sleep 2 seconds
mb wait ".modal"                 # wait for selector to appear
mb wait networkidle              # wait for no network activity
mb wait url:/dashboard           # wait for URL to contain string

Important Notes

• Viewport is 1024×768. snap only returns elements in the current viewport — scroll and snap again to find more.
• text uses querySelector — returns first match only. Use text "main" over text "p" for better results.
• go waits for networkidle. For heavy SPAs, follow up with wait ".selector".
• type with coordinates triple-clicks first to select existing text, then types the replacement.
• fill field matching order: aria-label → placeholder → name attr → id → label text → CSS selector (use #/./[ prefix).
• --json output: snap → [{role, name, x, y, state}], tab list → [{index, url, title}], logs → JSON lines, audit → full audit object.
• Recording state is stored in ~/.mb-recorder.json. Only one recording at a time.
• tab close cannot close the last remaining tab.

Troubleshooting