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

Variable	Default	Description
CHROME_PORT	9222	CDP port
CHROME_BIN	auto-detected	Path to Chrome/Chromium binary
CHROME_PID_FILE	<scripts>/.chrome-pid	PID file location
CHROME_USER_DATA_DIR	<scripts>/.chrome-profile	Chrome profile directory

Command Reference

Navigation

Command	Description
mb go <url>	Navigate to URL (waits for networkidle)
mb url	Print current URL
mb back	Go back
mb forward	Go forward

Observation

Command	Description
mb text [selector]	Visible text content (default: body)
mb shot [file]	Screenshot to PNG (default: ./shot.png)
mb snap	List interactive elements with coordinates

Interaction

Command	Description
mb click <x> <y>	Click at coordinates
mb type [x y] <text>	Type text (with coords: selects first)
mb fill <k=v...>	Fill form fields by label/name/placeholder
mb key <key...>	Press keys (Enter, Tab, Meta+a)
mb move <x> <y>	Hover at coordinates
mb drag <x1> <y1> <x2> <y2>	Drag between points
mb scroll [dir] [px]	Scroll (default: down 500)

Recording

Command	Description
mb record start <file>	Start recording (.webm, .mp4, .gif)
mb record stop	Stop recording and save
mb record status	Check if recording is active

Tabs

Command	Description
mb tab list	List open tabs
mb tab new [url]	Open new tab, print index
mb tab close [n]	Close tab (default: last)

Other

Command	Description
mb js <code>	Run JavaScript in page context
mb wait <target>	Wait for ms / selector / networkidle / url:pattern
mb audit	Design audit (palette, typography, contrast, a11y, SEO)
mb logs	Stream console logs (Ctrl+C to stop)

Flags

Flag	Default	Description
--timeout <ms>	30000	Command timeout
--tab <n>	0	Target tab index
--json	false	Structured JSON output
--right	false	Right-click
--double	false	Double-click
--fps <n>	30	Recording frame rate
--scale <n>	1	Recording scale factor

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

Problem	Fix
"Chrome not found"	Set CHROME_BIN=/path/to/chrome
Connection refused	Run mb-start-chrome first
Stale recording state	Delete ~/.mb-recorder.json
Chrome window wrong size	mb-restart-chrome (creates fresh profile)
Element not in snap output	mb scroll down 500 then mb snap again