mini-browser

$27

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