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
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 |
