mini-browser

mini-browser (mb) — エージェント向けブラウザー CLI

mb は、各コマンドが小さな Unix ツールとして動作するブラウザー CLI です。puppeteer-core を介して CDP（ポート 9222）経由で Chrome と通信します。

セットアップ（まだ利用できない場合のみ）

セットアップが必要なのは、mb がインストールされていない場合、または Chrome に接続できない場合のみです。 まず次のチェックを実行してください。両方に合格した場合は、コマンドリファレンスに進んでください。

準備状況を確認

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

両方が「ok」と出力されれば、準備完了です。mb コマンドを直接使用してください。

インストール（mb が見つからない場合のみ）

npm install -g @runablehq/mini-browser

Chrome を起動（実行中でない場合のみ）

mb-start-chrome

これにより、--remote-debugging-port=9222、新しいプロファイル、1024×768 のウィンドウを指定して Chrome を起動します。Chrome がすでに実行中の場合は何も行いません。

終了して再起動するには：

mb-restart-chrome

確認

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

環境変数

変数	デフォルト	説明
CHROME_PORT	9222	CDP ポート
CHROME_BIN	自動検出	Chrome/Chromium バイナリのパス
CHROME_PID_FILE	<scripts>/.chrome-pid	PID ファイルの場所
CHROME_USER_DATA_DIR	<scripts>/.chrome-profile	Chrome プロファイルディレクトリ

コマンドリファレンス

ナビゲーション

コマンド	説明
mb go <url>	URL に移動します（networkidle を待機）
mb url	現在の URL を出力します
mb back	前のページに戻ります
mb forward	次のページに進みます

ページの確認

コマンド	説明
mb text [selector]	表示されているテキスト内容（デフォルト：body）
mb shot [file]	PNG 形式でスクリーンショットを保存します（デフォルト：./shot.png）
mb snap	操作可能な要素を座標とともに一覧表示します

操作

コマンド	説明
mb click <x> <y>	指定した座標をクリックします
mb type [x y] <text>	テキストを入力します（座標を指定した場合：最初の要素を選択）
mb fill <k=v...>	ラベル、名前、プレースホルダーを使ってフォームフィールドに入力します
mb key <key...>	キーを押します（Enter、Tab、Meta+a）
mb move <x> <y>	指定した座標にカーソルを合わせます
mb drag <x1> <y1> <x2> <y2>	指定した2点間をドラッグします
mb scroll [dir] [px]	スクロールします（デフォルト：下方向に500）

録画

コマンド	説明
mb record start <file>	録画を開始します（.webm、.mp4、.gif）
mb record stop	録画を停止して保存します
mb record status	録画中かどうかを確認します

タブ

コマンド	説明
mb tab list	開いているタブを一覧表示します
mb tab new [url]	新しいタブを開き、インデックスを出力します
mb tab close [n]	タブを閉じます（デフォルト：最後のタブ）

その他

コマンド	説明
mb js <code>	ページのコンテキストで JavaScript を実行します
mb wait <target>	ミリ秒／セレクター／networkidle／url:pattern を待機します
mb audit	デザイン監査（配色、タイポグラフィ、コントラスト、アクセシビリティ、SEO）
mb logs	コンソールログをストリーミングします（停止するには Ctrl+C）

フラグ

フラグ	デフォルト	説明
--timeout <ms>	30000	コマンドのタイムアウト
--tab <n>	0	対象のタブインデックス
--json	false	構造化 JSON 出力
--right	false	右クリック
--double	false	ダブルクリック
--fps <n>	30	録画のフレームレート
--scale <n>	1	録画のスケール係数

使用パターン

確認 → 操作のループ

標準的なエージェントのループ：ページのスナップショットを取得し、要素を選んで操作します。

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

フォームに入力して送信

mb go "https://example.com/login"
mb fill "[email protected]" "Password=hunter2"
mb key Enter
mb wait url:/dashboard

スクリーンショットを撮影

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

テキストを抽出

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

JavaScript を実行

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

画面を録画

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

デザイン監査

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

オーバーレイを閉じる

Cookie バナーやモーダルはクリックを妨げます。JS を使って削除してください：

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

待機方法

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

重要な注意事項

• ビューポートは1024×768です。 snap は現在のビューポート内の要素のみを返します。スクロールしてから、もう一度スナップすると、さらに要素を確認できます。
• text は querySelector を使用します — 最初に一致した要素のみを返します。より適切な結果を得るには、text "p" より text "main" を使用してください。
• go は networkidle まで待機します。 重い SPA では、続けて wait ".selector" を実行してください。
• 座標を指定した type は、最初にトリプルクリックして既存のテキストを選択し、その後に置き換えテキストを入力します。
• fill のフィールド照合順序： aria-label → placeholder → name 属性 → id → label テキスト → CSS セレクター（#／.／[ のいずれかを先頭に付けて使用）。
• --json の出力： snap → [{role, name, x, y, state}]、tab list → [{index, url, title}]、logs → JSON 行、audit → 監査オブジェクト全体。
• 録画状態は ~/.mb-recorder.json に保存されます。一度に録画できるのは1つだけです。
• tab close では、最後に残ったタブを閉じることはできません。

トラブルシューティング

問題	解決方法
「Chrome not found」	CHROME_BIN=/path/to/chrome を設定します
接続が拒否される	先に mb-start-chrome を実行します
録画状態が古い	~/.mb-recorder.json を削除します
Chrome ウィンドウのサイズが正しくない	mb-restart-chrome を実行します（新しいプロファイルが作成されます）
snap の出力に要素がない	mb scroll down 500 を実行してから、もう一度 mb snap を実行します