Skip to content
Back to search

mini-browser

An agent first browser cli

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/runablehq-mini-browser/badge.svg)](/listings/runablehq-mini-browser)

HTML

<a href="/listings/runablehq-mini-browser"><img src="/api/listings/runablehq-mini-browser/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

As an agent skill (recommended)

npx skills add runablehq/mini-browser --all --global

This installs the `mini-browser` skill for all your agents via [skills.sh](https://skills.sh/runablehq/mini-browser/mini-browser). Your agent will automatically know how to use `mb` commands.

As a global CLI

npm install -g @runablehq/mini-browser

Then start Chrome

mb-start-chrome            # starts Chrome with --remote-debugging-port=9222
mb go "https://example.com"

> **Try it online** at [runable.com](https://runable.com/npm/@runablehq/mini-browser) — no install needed.

Also ships `mb-restart-chrome` to kill and relaunch the debug Chrome instance.

For local development: `bun install && bun run build`, then use `node dist/mb.js`.

Chrome scripts

| Script | What it does | |---|---| | `mb-start-chrome` | Launches Chrome with `--remote-debugging-port=9222`. No-ops if already running. Creates a fresh profile each time so `--window-size=1024,768` is always respected. | | `mb-restart-chrome` | Kills the running instance (via PID file) then calls `mb-start-chrome`. |

Both scripts honour these environment variables:

| Variable | Default | |---|---| | `CHROME_PORT` | `9222` | | `CHROME_BIN` | auto-detected (`google-chrome-stable`, `chromium`, …) | | `CHROME_PID_FILE` | `<scripts>/.chrome-pid` | | `CHROME_USER_DATA_DIR` | `<scripts>/.chrome-profile` |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 220 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mb · mini-browser for agents
  2. Browser CLI for agents. Each command is a small Unix tool — reads args, writes stdout, composes with pipes and `&&`.
  3. <p align="center">
  4. <img src="assets/demo.gif" alt="mb demo — install, browse, snap, screenshot" width="860" />
  5. </p>
  6. <p align="center">
  7. <a href="https://www.npmjs.com/package/@runablehq/mini-browser"><img alt="npm" src="https://img.shields.io/npm/v/@runablehq/mini-browser"></a>
  8. <a href="https://runable.com/npm/@runablehq/mini-browser"><img alt="runable" src="https://img.shields.io/badge/runable.com-try%20it-blue"></a>
  9. <a href="https://skills.sh/runablehq/mini-browser/mini-browser"><img alt="skills.sh" src="https://img.shields.io/badge/skills.sh-install-green"></a>
  10. </p>
  11. ## Setup
  12. ### As an agent skill (recommended)
  13. ```bash
  14. npx skills add runablehq/mini-browser --all --global
  15. ```
  16. This installs the `mini-browser` skill for all your agents via [skills.sh](https://skills.sh/runablehq/mini-browser/mini-browser). Your agent will automatically know how to use `mb` commands.
  17. ### As a global CLI
  18. ```bash
  19. npm install -g @runablehq/mini-browser
  20. ```
  21. ### Then start Chrome
  22. ```bash
  23. mb-start-chrome # starts Chrome with --remote-debugging-port=9222
  24. mb go "https://example.com"
  25. ```
  26. > **Try it online** at [runable.com](https://runable.com/npm/@runablehq/mini-browser) — no install needed.
  27. Also ships `mb-restart-chrome` to kill and relaunch the debug Chrome instance.
  28. For local development: `bun install && bun run build`, then use `node dist/mb.js`.
  29. ### Chrome scripts
  30. | Script | What it does |
  31. |---|---|
  32. | `mb-start-chrome` | Launches Chrome with `--remote-debugging-port=9222`. No-ops if already running. Creates a fresh profile each time so `--window-size=1024,768` is always respected. |
  33. | `mb-restart-chrome` | Kills the running instance (via PID file) then calls `mb-start-chrome`. |
  34. Both scripts honour these environment variables:
  35. | Variable | Default |
  36. |---|---|
  37. | `CHROME_PORT` | `9222` |
  38. | `CHROME_BIN` | auto-detected (`google-chrome-stable`, `chromium`, …) |
  39. | `CHROME_PID_FILE` | `<scripts>/.chrome-pid` |
  40. | `CHROME_USER_DATA_DIR` | `<scripts>/.chrome-profile` |
  41. ## Commands
  42. ```
  43. Navigation:
  44. go <url> Navigate (waits for networkidle)
  45. url Print current URL
  46. back / forward History navigation
  47. Observe:
  48. text [selector] Visible text (selector uses querySelector, default: body)
  49. shot [file] Screenshot (default: ./shot.png)
  50. --width/--height temporarily resize viewport for the shot
  51. snap Interactive elements via Accessibility Tree
  52. Interact:
  53. click <x> <y> Click at coordinates
  54. type [x y] <text> Type text (with coords: triple-clicks to select first)
  55. fill <k=v...> Fill form fields by label/name/placeholder/selector
  56. key <key...> Press keys — supports combos: Meta+a, Ctrl+Shift+T
  57. move <x> <y> Hover
  58. drag <x1> <y1> <x2> <y2> Drag between points
  59. scroll [dir] [px] Scroll (default: down 500)
  60. Recording:
  61. record start <file> Start recording (.webm, .mp4, .gif)
  62. record stop Stop recording and save
  63. record status Check recording status
  64. Tabs:
  65. tab list / new [url] / close [id]
  66. Other:
  67. js <code> Eval JS in page — strings print raw, objects print JSON
  68. wait <ms|selector|networkidle|url:pattern>
  69. audit Design audit (colors, fonts, contrast, SEO, a11y)
  70. logs Stream console logs (Ctrl+C to stop)
  71. Flags:
  72. --timeout <ms> (default: 30000)
  73. --tab <id> target tab by stable Chrome id (default: first page)
  74. --json structured output (snap, tab list, logs, audit)
  75. --right right-click
  76. --double double-click
  77. --width <px> screenshot viewport width
  78. --height <px> screenshot viewport height
  79. --fps <n> recording frame rate (default: 30)
  80. --scale <n> recording scale factor (default: 1)
  81. ```
  82. ## Notes
  83. All output goes to stdout. Pipe to grep, jq, wc, or redirect to files as usual.
  84. ### Navigation
  85. `go` waits for `networkidle0` before returning, so SPAs render before the next
  86. command runs. For heavy SPAs that fetch data after mount, follow up with
  87. `wait ".selector"` for a content element.
  88. ### Observation
  89. `shot --width <px> --height <px>` temporarily resizes the viewport to the
  90. given dimensions for the screenshot, then restores the original viewport.
  91. `text` calls `querySelector` — returns first match only. `text "p"` may return
  92. empty if the first `<p>` on the page is empty. Use a scoped selector like
  93. `text "main"` or `text "#content"` for better results on noisy pages.
  94. `snap` output format:
  95. ```
  96. [0] button "Submit" (512, 380)
  97. [1] textbox "Email" (512, 245) [disabled=true]
  98. ```
  99. It returns role, accessible name, center (x,y) coords, and state flags (checked,
  100. expanded, disabled, selected, pressed, haspopup). Only elements in the current
  101. viewport are returned — scroll down and snap again to find more.
  102. ### Interaction
  103. `click` supports `--right` for right-click and `--double` for double-click.
  104. `type` without coordinates types at current focus. With coordinates it
  105. triple-clicks the field first (selects all existing text) then types the
  106. replacement.
  107. `fill` matches fields by accessible name, `aria-label`, placeholder, `name`
  108. attribute, id, then label text in that order. Use `fill "#my-input=value"` to
  109. target by CSS selector when labels are missing.
  110. `scroll` defaults to `scroll down 500` if called with no args.
  111. ### JavaScript
  112. `js` reads from stdin with `-`:
  113. ```bash
  114. echo 'document.title' | mb js -
  115. cat scrape.js | mb js -
  116. ```
  117. ### Recording
  118. `record start <file>` spawns a background daemon that captures the active tab
  119. via Chrome's screencast API. Supported formats: `.webm`, `.mp4`, `.gif`.
  120. Use `--fps` and `--scale` to control frame rate and resolution.
  121. `record stop` sends SIGTERM to the daemon and waits up to 60 s for encoding to
  122. finish.
  123. `record status` prints whether a recording is in progress and how long it has
  124. been running.
  125. State is stored in `~/.mb-recorder.json`.
  126. ### Wait
  127. `wait` picks its strategy from the argument format:
  128. ```
  129. wait 2000 sleep (ms)
  130. wait ".modal" wait for selector
  131. wait networkidle wait for no network activity
  132. wait url:/dashboard wait for URL to contain string
  133. ```
  134. ### Audit
  135. `audit` collects palette, typography, spacing, contrast (via CDP), accessibility
  136. checks, and basic SEO metadata in a single pass. Pass `--json` for structured
  137. output.
  138. ### Tabs
  139. Every tab has a stable id (Chrome's CDP `targetId`) that survives other tabs
  140. opening or closing. Use `--tab <id>` to target a specific tab from any
  141. command. Without `--tab`, commands operate on the first open page.
  142. `tab list` prints id, URL, and title for each open tab.
  143. `tab new [url]` opens a new tab (optionally navigating) and prints its id.
  144. `tab close [id]` closes a tab by id (default: last opened). Cannot close the
  145. last remaining tab.
  146. ```bash
  147. ID=$(mb tab new https://example.com)
  148. mb --tab "$ID" shot example.png
  149. mb tab close "$ID"
  150. ```
  151. ### JSON output
  152. `--json` on `snap` returns `[{role, name, x, y, state}]`.
  153. `--json` on `tab list` returns `[{id, url, title}]`.
  154. `--json` on `logs` emits JSON lines `{tab, type, time, message}`.
  155. `--json` on `audit` returns the full audit data as a JSON object.
  156. ### Overlays
  157. Overlays (cookie banners, modals) block clicks on elements underneath. Dismiss
  158. them first, or remove via JS:
  159. ```bash
  160. mb js 'document.querySelector("[class*=cookie]")?.remove()'
  161. mb js 'document.body.style.overflow="auto"'
  162. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.