agent-browser

name	agent-browser
description	agent-browser CLIを使ってローカルのWebアプリをブラウザで動作確認し、スクリーンショットをユーザーに見せる。 「動作確認して」「ブラウザで確認して」「スクリーンショット撮って」「実際に動かして確認して」と言われたとき、 またはコードを変更した後に実際の見た目を確認したいときに使う。 chrome-devtools MCPより軽量で、Bashコマンドだけで完結する。

agent-browser を使った動作確認

基本ワークフロー

1. ページを開いてスクリーンショットを撮る

agent-browser open <url> && agent-browser wait 2000 && agent-browser screenshot /tmp/result.png

撮ったら必ず Read ツールで画像を読んでユーザーに見せる。

2. ログインが必要な場合

フォームから直接ログインするのが一番シンプル。

# ページを開く
agent-browser open <url>

# ログインフォームを入力
agent-browser find label メールアドレス fill "[e-mail]"
agent-browser find label パスワード fill "password"
agent-browser find role button click --name "ログイン"
agent-browser wait 2000

認証状態を保存して次回省略する:

# 初回：session-name つきで起動してログインする
agent-browser --session-name myapp open <url>
# ... ログイン操作 ...

# 2回目以降：同じ session-name を使うと自動的にログイン済み状態が復元される
agent-browser --session-name myapp open <url>

3. ページ全体を確認したい場合

# ビューポートを広げてスクロールしながら確認
agent-browser set viewport 1280 1024
agent-browser scroll down 300
agent-browser screenshot /tmp/result.png

よく使うコマンド

やること	コマンド
ページを開く	agent-browser open <url>
スクリーンショット	agent-browser screenshot /tmp/result.png
待機	agent-browser wait 2000
テキスト入力	agent-browser find label <ラベル名> fill "<値>"
ボタンクリック	agent-browser find role button click --name "<ボタン名>"
スクロール	agent-browser scroll down 300
ビューポート変更	agent-browser set viewport 1280 1024
セッションを閉じる	agent-browser close --all
プロファイル指定	agent-browser close --all && agent-browser --profile Default open <url>

トラブルシューティング

「--profile ignored: daemon already running」と出る: agent-browser close --all でデーモンを落としてから再実行する。

ページがロード中のままスクリーンショットされる: agent-browser wait 2000 を挟む。重いページは 3000 に増やす。

スクリーンショットが途中で切れる: agent-browser set viewport 1280 1024 でビューポートを広げるか、scroll で見たい箇所まで移動する。

find text "<テキスト>" click でクリックイベントが届かない: テキストが正確に一致していてもクリックが無視されることがある。確実にクリックしたいときは、まず snapshot でアクセシビリティツリーの ref を確認し、click @ref で直接クリックする。

# snapshot で ref を確認
agent-browser --session-name myapp snapshot | grep "ボタン名"
# → button "下書き保存" [ref=e3]

# ref でクリック
agent-browser --session-name myapp click @e3

ボタンを押す操作全般で、find text より @ref の方が確実。特にクリック後にAPIリクエストが期待通り発火しない場合はこの方法を試す。

スクリーンショットの撮り方

ファイル名の規則

操作ごとに連番＋説明のファイル名で保存する。上書きしないことで、あとからステップを遡れる。

agent-browser screenshot /tmp/ab_01_top.png
agent-browser screenshot /tmp/ab_02_partners.png
agent-browser screenshot /tmp/ab_03_edit_dialog.png

• プレフィックスは ab_（agent-browser の略）
• 連番は2桁ゼロ埋め
• 説明はスネークケースで画面・操作を表す単語

会話への表示

操作ごとに撮るが、Read で表示するのは以下の2タイミングのみ。

ユーザーに判断を求めるとき — 選択肢を提示したり「このまま進めてよいか」と確認するとき。

agent-browser screenshot /tmp/ab_NN_before_decision.png
# → Read で表示 → AskUserQuestion またはテキストで選択肢を提示

作業が完了したとき — 動作確認の結果を報告するとき。

agent-browser screenshot /tmp/ab_NN_done.png
# → Read で表示 → 完了報告のテキストを出す

途中経過（操作ステップの合間・エラー調査中など）は撮るが表示しない。ユーザーから「ステップNを見せて」と言われたら、該当ファイルを Read で表示する。