agent-browser-commands について
agent-browser-commands は、agent-browser によるブラウザー自動化向けの内部コマンドリファレンスです。ナビゲーション、ページ操作、デバッグ、ネットワーク、セッション、デバイスエミュレーションを扱い、自動化の入口として agent-browser スキルを案内します。
主な機能
- 01ナビゲーションとタブ管理
- 02ページ要素の検出と操作
- 03スクリーンショット、PDF、差分比較
- 04ネットワークリクエストの確認とモック
- 05セッション、認証、バッチ実行
- 06デバイスとメディアのエミュレーション
活用シーン
- 01ブラウザー自動化コマンドの確認
- 02フォーム操作や複数段階のページ処理
- 03ネットワークやページのエラー調査
- 04ビジュアル回帰テストとデバイスエミュレーション
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/agent-browser-commandsを入力して読み込まれたか確認します。
詳細
Agent Browser — コマンドリファレンス
内部向けリファレンス。 ブラウザー自動化タスクでは、エントリーポイントとして
agent-browserスキルを使用してください。
ナビゲーション
| コマンド | 説明 | 適用シーン |
|---|---|---|
open <url> | URL に移動します（chrome:// と chrome-extension:// に対応） | すべてのタスクの開始点 |
back / forward | ブラウザーの履歴を移動します | 複数ページのフローをさかのぼる |
reload | ページを更新します | 状態を強制的に更新する |
close | ブラウザーを閉じます | タスク終了後のクリーンアップ |
検出
| コマンド | 説明 | 適用シーン |
|---|---|---|
snapshot | 参照情報付きのアクセシビリティツリー | 操作可能な要素の参照を取得する |
snapshot -i | インタラクティブ要素のみ | 操作可能な要素に絞り込む |
snapshot -c | コンパクト表示（ノイズを低減） | 大きなページで出力のノイズを減らす |
snapshot -d <n> | ツリーの深さを制限します | 最上位の構造のみを確認する |
snapshot -s <sel> | CSS セレクターで範囲を指定します | ダイアログ／部分領域に絞り込む |
操作
| コマンド | 説明 | 適用シーン |
|---|---|---|
click @e1 | 要素をクリックします | ボタン／リンクを操作する |
dblclick @e1 | 要素をダブルクリックします | 編集可能なセル／テキストの選択 |
fill @e1 "text" | 入力欄をクリアして入力します | フォーム入力（既存の値を置き換える） |
type @e1 "text" | クリアせずに入力します（追記） | 内容の追記／制御されたコンポーネント |
keyboard type "text" | フォーカス中の要素に入力します。文字ごとに keydown/keypress/input/keyup を発生させますが、document レベルの keydown リスナーは確実には起動しません。document スコープのイベントハンドラーには eval dispatchEvent(new KeyboardEvent(...)) を使用してください | 対象にフォーカスがある状態で入力する |
keyboard inserttext "text" | すべてのキーイベントを発生させずにテキストを挿入します（keydown/keypress/keyup は発生しません） | キーボードイベントのインターセプトを回避してテキストを直接挿入する |
press <key> | 名前付きキーを押します：Enter、Tab、Control+a、ArrowDown | フォームの送信／ショートカット／矢印キー |
focus @e1 | 要素にフォーカスします | フォーカス後に keyboard type を使用する |
check @e1 / uncheck @e1 | チェックボックス／ラジオボタンを操作します | チェックボックス／ラジオボタンの操作 |
select @e1 "option" | ドロップダウンから選択します | <select> ドロップダウンメニュー |
hover @e1 | マウスを要素に合わせます | ホバーメニュー／ツールチップを表示する |
drag @e1 @e2 | ソース要素をターゲットにドラッグします。Playwright のポインターベースのドラッグを使用します。マウスイベント方式のドラッグ可能なライブラリ（Sortable.js、jQueryUI）で動作します。HTML5 DragEvent（dragstart/dragover/drop）は発生しません。HTML5 Drag API には eval を使用して DragEvent を手動で発生させてください | カンバンの並べ替え／ポインタードラッグ |
upload @e1 <file> | ファイルをアップロードします | ファイルアップロードフォーム |
download @e1 <path> | 要素をクリックしてファイルをダウンロードします | エクスポートボタンからダウンロードを開始する |
scroll down | ページをスクロールします（上下左右） | 遅延読み込み／さらに読み込む操作を行う |
scroll down --selector ".modal" | 特定のコンテナー内をスクロールします | ダイアログ内のコンテンツをスクロールする |
scrollintoview @e1 | 要素が表示領域に入るまでスクロールします | 要素が表示領域外にある場合に、クリックする前に使用する |
ダイアログ
| コマンド | 説明 | 適用シーン |
|---|---|---|
dialog accept | アラート／確認ダイアログを承認します | 確認操作のダイアログ |
dialog accept "text" | 入力付きのプロンプトダイアログを承認します | プロンプトに入力してから確定する |
dialog dismiss | ダイアログを閉じる／キャンセルします | 操作のキャンセル／アラートを閉じる |
dialog status | ダイアログが現在開いているか確認します | ダイアログの表示有無を検証する |
マウス（細かな制御）
ピクセル座標でポインター／マウスイベントを発生させます。キャンバス、描画アプリ、CSS／ポインターイベント方式のドラッグ可能なコンポーネントで使用します。HTML5 Drag API イベント（dragstart/dragover/drop）は発生しません。これらには eval DragEvent が必要です。
| コマンド | 説明 | 適用シーン |
|---|---|---|
mouse move <x> <y> | マウスを指定座標に移動します | キャンバス／描画アプリ |
mouse down [btn] | マウスボタンを押します | ドラッグの開始点 |
mouse up [btn] | マウスボタンを離します | ドラッグの終了点 |
mouse wheel <dy> [dx] | ホイールをスクロールします | スクロール量を正確に制御する |
情報の取得
| コマンド | 説明 | 適用シーン |
|---|---|---|
get text @e1 | 要素のテキストを取得します | 表示内容を検証する |
get html @e1 | inner HTML を取得します | 複雑な構造を確認する |
get value @e1 | 入力値を取得します | フォームの現在の値を検証する |
get attr @e1 href | 属性を取得します | リンク／data 属性を確認する |
get title / get url | ページ情報を取得します | ナビゲーション後のルートを検証する |
get count "selector" | 一致する要素の数を取得します | リスト項目数を検証する |
get box @e1 | バウンディングボックスを取得します（x、y、width、height） | 座標の正確な指定／スクリーンショットの切り抜き |
get styles @e1 | 計算済みスタイルを取得します | CSS スタイルのデバッグ |
get cdp-url | アクティブページの CDP WebSocket URL | 高度な CDP デバッグ |
状態チェック
| コマンド | 説明 | 適用場面 |
|---|---|---|
is visible @e1 | 表示されているかを確認 | 要素の表示アサーション |
is enabled @e1 | 有効になっているかを確認 | ボタンが操作可能かのアサーション |
is checked @e1 | チェックされているかを確認 | チェックボックスの状態アサーション |
待機
| コマンド | 説明 | 適用場面 |
|---|---|---|
wait @e1 | 要素が表示されるまで待機 | 非同期コンテンツのレンダリング |
wait @e1 --state hidden | 要素が非表示になるまで待機 | ローディングスピナーの消失 |
wait @e1 --state detached | 要素が DOM から削除されるまで待機 | ダイアログが閉じた後に続行 |
wait 1000 | ミリ秒単位で待機 | CSS トランジションアニメーションの完了 |
wait --load networkidle | ネットワークがアイドル状態になるまで待機 | ページの読み込み／ナビゲーション後 |
wait --url "**/dashboard" | URL がパターンに一致するまで待機 | ログイン後のリダイレクトを検証 |
wait --fn "window.ready" | JavaScript 式が true と評価されるまで待機 | カスタムの読み込み完了シグナル |
wait --text "Welcome" | ページにテキストが表示されるまで待機 | 非同期テキストのレンダリング |
wait --download [path] | ダウンロードが完了するまで待機 | ダウンロード開始後の完了待ち |
キャプチャ
| コマンド | 説明 | 適用場面 |
|---|---|---|
screenshot [path] | スクリーンショットを撮影 | 現在のビューポートのスナップショット |
screenshot --full | ページ全体のスクリーンショットを撮影 | ページ全体の記録／証拠 |
screenshot --annotate | 番号付きラベルを付けたスクリーンショットを撮影 | バグ報告／ドキュメント用のスクリーンショット |
pdf <path> | PDF として保存 | 印刷可能なレポートの生成 |
スクリーンショットのオプション：--screenshot-dir <path>（デフォルトのディレクトリ）、--screenshot-quality <0-100>（JPEG）、--screenshot-format png|jpeg
差分とビジュアルリグレッション
diff snapshot
agent-browser diff snapshot # vs last snapshot in session
agent-browser diff snapshot --baseline before.txt # vs saved snapshot file
agent-browser diff snapshot -s ".sidebar" # scope to selector
agent-browser diff snapshot -c -d 3 # compact + depth limit
適用場面：DOM 構造の変更検出、変更前後の比較
diff screenshot
agent-browser diff screenshot --baseline before.png
agent-browser diff screenshot --baseline before.png --output diff.png --threshold 0.1
agent-browser diff screenshot --baseline before.png -s "#main-content" --full
適用場面：ビジュアルリグレッションテスト、--threshold 0~1（デフォルトは 0.1。値が小さいほど厳密）
diff url
agent-browser diff url https://staging.example.com https://prod.example.com
agent-browser diff url https://v1.example.com https://v2.example.com --screenshot --full
agent-browser diff url <u1> <u2> --wait-until networkidle
適用場面：環境／バージョン間の比較、--screenshot でスクリーンショットも同時に比較
デバッグ
| コマンド | 説明 | 適用場面 |
|---|---|---|
inspect | Chrome DevTools を開く（CLI は引き続き動作します） | 対話的なデバッグ |
console | コンソールログを表示 | JS 出力の確認 |
console --pattern "err" | コンソールログをフィルタリング | エラーログのすばやい特定 |
console --clear | コンソールログのバッファーをクリア | 監視ウィンドウをリセット |
errors | JavaScript エラーを表示 | 最初に確認。問題の 80% をカバー |
errors --clear | エラーバッファーをクリア | エラー数をリセット |
highlight <sel> | 要素を視覚的に強調表示 | 要素の特定を視覚的に確認 |
network requests | すべてのネットワークリクエストを表示 | API 呼び出しの全記録 |
network requests --filter "api" | URL パターンでフィルタリング | 特定のエンドポイントに絞り込み |
network requests --type xhr,fetch | リソースタイプでフィルタリング | XHR／Fetch のみを表示 |
network requests --method POST | HTTP メソッドでフィルタリング | 書き込み操作のみを表示 |
network requests --status 4xx | ステータスコードでフィルタリング | 失敗したリクエストをすばやく特定 |
network requests --clear | ネットワークログをクリア | 記録をリセット |
network request <requestId> | リクエストとレスポンスの本文全体を表示 | ペイロード全体を確認 |
network har start [path] | HAR 記録を開始 | ネットワーク追跡の開始 |
network har stop | HAR ファイルの記録を停止して保存 | DevTools で分析するためにエクスポート |
trace start [path] | Playwright トレースの記録を開始 | Playwright のデバッグトレース |
trace stop | トレースを停止 | Playwright Trace Viewer で開く |
profiler start [path] | Chrome DevTools プロファイラーを開始 | パフォーマンス分析 |
profiler stop | プロファイラーを停止 | パフォーマンスレポートをエクスポート |
record start <path> [url] | 動画の記録を開始（WebM） | デモの録画／バグの再現 |
record stop | 動画の記録を停止して保存 | 動画を保存 |
record restart <path> [url] | 現在の記録を停止し、新しい記録を開始 | 再録画（撮り直し） |
eval "JS code" | JavaScript を実行 | カスタムクエリ／状態の注入 |
clipboard read | クリップボードの内容を読み取る | コピー結果を検証 |
clipboard write "text" | クリップボードに書き込む | クリップボードデータを注入 |
clipboard copy <sel> | 要素のテキストをクリップボードにコピー | コンテンツの抽出 |
clipboard paste <sel> | クリップボードの内容を要素に貼り付け | 入力欄への貼り付け |
ネットワークモック
| コマンド | 説明 | 適用場面 |
|---|---|---|
network route "**/*.png" --abort | 一致するリクエストをブロック | 画像／広告をブロックして読み込みを高速化 |
network route "**/api/**" --body '{"ok":true}' | レスポンス本文をモック | 特定の API レスポンスをテスト |
network unroute [url] | ルートを削除（URL の指定がない場合はすべて削除） | 実際のネットワークに戻す |
ストレージ
| コマンド | 説明 | 適用シーン |
|---|---|---|
cookies | すべての Cookie を表示 | セッション状態の確認 |
cookies set <name> <val> --domain example.com --secure --httpOnly | Cookie を設定 | 認証トークンの注入 |
cookies clear | すべての Cookie をクリア | セッション状態のリセット |
storage local | localStorage を表示 | 永続化データの確認 |
storage local get <key> | localStorage のキーを取得 | 特定のキーの読み取り |
storage local set <key> <val> | localStorage のキーを設定 | トークン／設定の注入 |
storage local clear | localStorage をクリア | フロントエンド状態のリセット |
storage session get <key> | SessionStorage（同じ API） | セッション単位のデータ操作 |
タブ
| コマンド | 説明 | 適用シーン |
|---|---|---|
tab new | 新しいタブを開く | 複数タブのワークフロー |
tab list | 現在のブラウザーコンテキスト内のすべてのタブを一覧表示 | 認識済みのタブの確認 |
tab <n> | インデックス（0 始まり）でタブを切り替え | 対象のタブに切り替え |
tab close <n> | インデックスでタブを閉じる | 補助タブを閉じる |
target="_blank"の制限：target="_blank"のリンクをクリックすると、ブラウザーは新しい BrowserContext で開くことがあります。agent-browser のtab listが追跡するのは、現在のコンテキスト内のタブのみです。新しいタブがtab listに表示されない場合は、tab newとopen <url>を使って手動で管理してください。
セッション
| コマンド | 説明 | 適用シーン |
|---|---|---|
session | 現在のセッション名を表示 | 現在のセッションの確認 |
session list | アクティブなセッションを一覧表示 | 複数セッションの同時確認 |
認証情報ボルト
ログイン認証情報を保存して再利用し、E2E の実行ごとに手動でログインする手間を省きます。
# Save once
agent-browser auth save myapp --url http://localhost:5173/login --username admin --password secret
# Reuse in any test (auto-fills and submits login form)
agent-browser auth login myapp
# Manage
agent-browser auth list
agent-browser auth show myapp
agent-browser auth delete myapp
認証情報は AES-256-GCM（
AGENT_BROWSER_ENCRYPTION_KEY）で暗号化されます。シェルの履歴に露出しないよう、--passwordよりも--password-stdinを使用してください。
一括実行
標準入力から複数のコマンドを JSON 配列として実行できます。シェルから順番に呼び出すより効率的です。
echo '[["fill","@e1","[email protected]"],["fill","@e2","pass"],["click","@e3"]]' | agent-browser batch
agent-browser batch --bail # stop on first error (default: continue all)
確認
明示的な承認が必要なアクション（--confirm-actions が設定されている場合）：
| コマンド | 説明 | 適用シーン |
|---|---|---|
confirm <id> | 保留中のアクションを承認 | 書き込み操作の承認 |
deny <id> | 保留中のアクションを拒否 | 危険な操作の拒否 |
デバイス／エミュレーション
| コマンド | 説明 | 適用シーン |
|---|---|---|
set viewport <w> <h> | ビューポートのサイズを設定 | レスポンシブテスト |
set viewport <w> <h> <scale> | デバイスのピクセル比を指定してビューポートを設定 | Retina ディスプレイのテスト |
set device "iPhone 15 Pro" | デバイスのプリセットエミュレーション | モバイルの完全なシミュレーション |
set geo <lat> <lng> | 位置情報を設定 | 位置情報機能のテスト |
set offline [on|off] | オフラインモードを切り替え（必ず set offline off で元に戻してください） | PWA／オフラインモードのテスト |
set headers <json> | ページのオリジンに適用する HTTP ヘッダーを設定 | Authorization の注入 |
set credentials <user> <pass> | HTTP ベーシック認証 | ベーシック認証を使用するサイト |
set media dark | ダークモード | ダークテーマのテスト |
set media dark reduced-motion | ダークモード＋視差効果の低減 | アクセシビリティテスト |
iOS Simulator（Xcode と Appium が必要）：-p ios フラグを使用
agent-browser -p ios open http://localhost:3000
agent-browser -p ios --device "iPhone 15 Pro" snapshot
agent-browser -p ios device list
agent-browser -p ios swipe up
セットアップ
| コマンド | 説明 | 適用シーン |
|---|---|---|
install | Chromium をダウンロード（初回セットアップ） | 初回インストール |
install --with-deps | システム依存関係もインストール（Linux） | Linux CI 環境 |
upgrade | agent-browser を最新バージョンにアップグレード（npm のみ。Homebrew の場合：brew upgrade agent-browser） | バージョン更新 |
セマンティックロケーター（find）
CSS セレクターよりも推奨されます。UI のリファクタリング後も使えます。
agent-browser find role button click --name "Submit"
agent-browser find role link click --name "Learn More"
agent-browser find role button click --name "Submit" --exact # exact name match
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "[email protected]"
agent-browser find placeholder "Search..." type "query"
agent-browser find testid "submit-button" click
agent-browser find alt "Company logo" click
agent-browser find first "button.primary" click
agent-browser find last "a.link" click
agent-browser find nth 2 ".card" hover # 0-based index
有効な find サブコマンド：role、text、label、placeholder、alt、title、testid、first、last、nth
❌ find ref は存在しません。
スナップショットの Ref を使用する
snapshot は [ref=e3] のような Ref を返します。これらは find 経由ではなく、アクションコマンドで直接使用できます。
# ✅ Direct ref usage
agent-browser click @e3
agent-browser fill @e3 "hello"
agent-browser hover @e3
# ✅ Refs in assertions
agent-browser is visible @e3
agent-browser get text @e3
agent-browser get value @e3
# ❌ Wrong — ref is not a find subcommand
agent-browser find ref e3 fill "hello"
グローバルオプション
| オプション | 説明 |
|---|---|
--headed | ブラウザーウィンドウを表示します。AGENT_BROWSER_HEADED=1 でも指定できます |
--engine chrome|lightpanda | ブラウザーエンジンです。AGENT_BROWSER_ENGINE でも指定できます |
-p, --provider <name> | ブラウザープロバイダー：ios、browserbase、kernel、browseruse、browserless |
--cdp <port> | CDP 経由で Chrome に接続します |
--auto-connect | 実行中の Chrome を自動検出します |
--profile <path> | 永続的なブラウザープロファイル（認証情報を再利用） |
--session <name> | 分離されたセッション |
--session-name <name> | Cookie と localStorage を自動保存／復元します |
--state <path> | JSON からストレージ状態を読み込みます |
--download-path <path> | デフォルトのダウンロードディレクトリです。AGENT_BROWSER_DOWNLOAD_PATH でも指定できます |
--headers '{"Authorization":"Bearer token"}' | 認証ヘッダー |
--proxy "http://127.0.0.1:7890" | プロキシサーバー（フォールバックとして HTTP_PROXY／HTTPS_PROXY／ALL_PROXY 環境変数も読み込みます） |
--proxy-bypass "localhost,*.internal" | プロキシをバイパスします（NO_PROXY 環境変数も読み込みます） |
--color-scheme dark|light | カラースキームの設定 |
--ignore-https-errors | TLS 証明書エラーを無視します |
--allow-file-access | file:// URL へのアクセスを許可します |
--user-agent <ua> | カスタム User-Agent |
--allowed-domains <list> | 承認済みドメインに制限します（セキュリティ）。--domain-allowlist |
--action-policy <path> | 許可／ブロックするアクションカテゴリを定義する JSON ファイル |
--confirm-actions <list> | 確認が必要なアクションカテゴリ |
--confirm-interactive | TTY で対話型の確認プロンプトを表示します |
--content-boundaries | ページ出力を境界マーカーで囲みます（--max-output の解析に役立ちます） |
--max-output <chars> | ページ出力を N 文字に切り詰めます。AGENT_BROWSER_MAX_OUTPUT でも指定できます |
--json | JSON 出力 |
--full / -f | ページ全体（スクリーンショット） |
--annotate | 注釈付き出力 |
--debug | デバッグ出力 |
主な環境変数
| 変数 | 説明 |
|---|---|
AGENT_BROWSER_HEADED=1 | ブラウザーウィンドウを表示します |
AGENT_BROWSER_ENGINE=chrome|lightpanda | ブラウザーエンジン（デフォルトは chrome） |
AGENT_BROWSER_NATIVE=1 | ⚠️ レガシーエイリアス — 受け付けられますが、0.22 以降ではドキュメントに記載されていません。指定しないことを推奨します（デフォルトのブラウザーエンジンは chrome です） |
AGENT_BROWSER_DEFAULT_TIMEOUT | デフォルトのアクションタイムアウト（ミリ秒、デフォルト：25000） |
AGENT_BROWSER_MAX_OUTPUT | ページ出力の最大文字数 |
AGENT_BROWSER_STREAM_PORT | ポートで WebSocket ストリーミングを有効にします（例：9223） |
AGENT_BROWSER_IDLE_TIMEOUT_MS | N ミリ秒間操作がない場合にデーモンを自動終了します |
AGENT_BROWSER_ENCRYPTION_KEY | AES-256-GCM Auth Vault 暗号化用の 64 文字の 16 進数キー |
AGENT_BROWSER_SCREENSHOT_DIR | デフォルトのスクリーンショット出力ディレクトリ |
コメント
Markdown 対応