browse

browse：AI エージェント向けブラウザー＆ネイティブアプリの自動化

ターゲットの判断 — まず必ずここを確認

browse コマンドを実行する前に、適切なターゲットを判断します。

ユーザーの要望	ターゲット	コマンドの形式
URL を開く、ウェブサイトをテストする、ウェブコンテンツをスクレイピングする	ブラウザー（デフォルト）	browse goto <url>
ローカルの開発サーバー（localhost）をテストする	ブラウザー	browse goto http://localhost:3000
ボットをブロックするサイト（Cloudflare、Turnstile）を閲覧する	Camoufox	browse --runtime camoufox --headed goto <url>
特定の Camoufox フィンガープリントプロファイルで閲覧する	Camoufox	browse --runtime camoufox --camoufox-profile <name> --headed goto <url>
Google、YouTube、Amazon などを検索する	ブラウザー	browse goto @google "query"
iOS アプリ（設定、Safari、カスタムアプリ）を操作する	iOS シミュレーター	browse --platform ios --app <bundleId> <cmd>
Android アプリ（設定、Chrome、カスタムアプリ）を操作する	Android エミュレーター	browse --platform android --app <package> <cmd>
macOS デスクトップアプリ（システム設定、TextEdit）を操作する	macOS アプリ	browse --app <name> <cmd>
iOS の .app または .ipa ファイルをインストールしてテストする	iOS シミュレーター	browse sim start --platform ios --app ./MyApp.app --visible
Android の .apk ファイルをインストールしてテストする	Android エミュレーター	browse sim start --platform android --app ./app.apk --visible

重要なルール：

• --platform または --app フラグがない場合 → ブラウザー（Chromium）がターゲットです。goto で移動します。
• --runtime camoufox --headed → 検出を回避する Firefox です。通常の閲覧をブロックするサイトで使用します。Turnstile/CAPTCHA の回避パターンについては、/browse-stealth スキルを参照してください。
• goto URL 内の @macro → 検索マクロを展開します。browse goto @google "query" は Google 検索 URL に展開されます。マクロは 14 個あります：@google、@youtube、@amazon、@reddit、@wikipedia、@twitter、@yelp、@spotify、@netflix、@linkedin、@instagram、@tiktok、@twitch、@reddit_subreddit。
• --platform を付けずに --app を指定 → macOS アプリの自動化です。アプリが起動している必要があります。
• --platform ios --app → iOS シミュレーターです。起動していない場合は、先に browse sim start を使用します。
• --platform android --app → Android エミュレーターです。起動していない場合は、先に browse sim start を使用します。
• ネイティブアプリのターゲットでは、次の機能はサポートされません：goto、js、eval、tabs、cookies、route、har。これらはブラウザー専用です。
• すべてのターゲットでサポートされます：snapshot、text、tap、fill、type、press、swipe、screenshot。
• サイトにブロックされた場合は、--runtime camoufox --headed に切り替えます。それでもブロックされる場合は、完全な Turnstile 回避パターンについて /browse-stealth を使用してください。
• 使用するターゲットが不明な場合は、ユーザーに確認してください。 推測しないでください。誤ったターゲットを選ぶと作業が無駄になります。

目標

永続的な browse CLI を使用して、次の操作を行います。

• 実際のページに移動する
• レンダリングされたコンテンツと状態を調べる
• UI 要素を操作する
• スクリーンショット、コンソールログ、ネットワークアクティビティを取得する
• アクセシビリティ API を介してネイティブアプリ（iOS、Android、macOS）を自動化する
• 手順ごとに再起動することなく、ブラウザーまたはアプリの動作をエンドツーエンドで検証する

ステップ 0：利用可能か確認し、閲覧モードを選択する

まず、次を確認します。

browse --version

browse がインストールされていない場合：

• 停止します
• browse が必要であることをユーザーに伝えます
• references/commands.md のインストール手順を案内します

次に、必要なセッションの種類を判断します。

• 通常の単一エージェント作業ではデフォルトセッション
• エージェントを並行して分離する場合は --session <id>
• ブラウザーの ID を保持する場合は --profile <name>

ネイティブアプリのターゲットでは、先にシミュレーター／エミュレーターを起動します。

browse sim start --platform ios --app com.apple.Preferences --visible
browse sim start --platform android --app com.android.settings --visible
browse enable android    # first-time only: auto-installs adb, JDK, SDK, emulator
browse enable ios        # first-time only: builds iOS runner (needs Xcode)
browse enable macos      # first-time only: builds browse-ax bridge

成功基準：browse が利用可能で、ターゲット（ブラウザーまたはネイティブアプリ）が決定され、セッション／プロファイルの選択がタスクに適していること。

ステップ 1：安全に移動し、ページを安定させる

browse goto <url> を使用して移動します。

移動後は、読み取りや操作を行う前に必ずページを安定させます。

• 一般的なページや SPA では browse wait --network-idle
• ページに既知のシグナルがある場合は、より具体的な条件を指定して browse wait

重要なルール：

• browse は PATH 上の単独のコマンドとして呼び出します
• browse コマンドのプレフィックスにシェル変数を使用しないでください
• #id CSS セレクターは避け、[id=foo] を優先してください
• ページが信頼できない場合は、--content-boundaries と --allowed-domains の使用を検討してください

成功基準：コンテンツと操作可能な状態を確実に確認できる程度に、ページが読み込まれていること。

ステップ 2：最も効率的な確認方法を選ぶ

質問に答えられる中で、最も軽量なコマンドを使用します。

• 整形済みのページコンテンツには text
• ナビゲーション構造には links
• 正確な対象の抽出には js
• 実行時のデバッグには console、errors、network
• 操作可能な要素と安定した参照には snapshot -i

操作が多いタスクでは、セレクターを推測する前に snapshot -i を優先してください。

読み込むファイル：

• 正確なコマンド構文については references/commands.md
• コマンドの選び方と速度に関するルールについては references/guides.md

成功基準：不要なトークン消費や不安定なセレクターの使用を避け、必要な情報を得ていること。

ステップ 3：まず refs で操作し、次にセレクターを使う

クリック、入力、チェック、選択などの操作では：

1. browse snapshot -i を優先します
2. @eN refs を使って操作します
3. refs が使えない、または実用的でない場合に限り、CSS セレクターを使用します

移動後や DOM の更新後は：

• refs が無効になっている可能性があるものとして扱います
• 続行する前に新しいスナップショットを取得します

ルール：

• .browse/sessions/<id>/ 以下に、内容がわかる名前でスクリーンショットを保存します
• 分離する意図がない限り、状態を伴うフローは同じセッション内で続けます
• iframe のコンテンツを操作する前に frame を使用します

成功基準：操作が安定しており、現在描画されているページの状態に基づいていること。

ステップ 4：ブロッカーと特殊なケースをデバッグする

問題が発生した場合：

• ページや実行時の問題には console と errors を使用します
• リクエストの確認には network を使用します
• モックや障害モードのテストが必要な場合に限り、route または offline を使用します
• headed モードやブラウザーの引き継ぎを使うのは、CAPTCHA、MFA、OAuth の壁など、実際にブロックされた場合に限ります

数回試してもブロッカーを解消できない場合：

• references/guides.md を読み込みます
• 引き継ぎプロトコルに正確に従います
• 人間への引き継ぎフローを開始する前に AskUserQuestion を使用します

成功基準：正しい引き継ぎプロトコルに従って、ブロッカーを解決するか、適切にエスカレーションしていること。

ステップ 5：証拠を記録し、明確に報告する

タスクに検証が含まれる場合は、必要最小限の証拠を記録します。

• 関連するページテキストまたは構造化データの抽出結果
• 表示内容が重要な場合はスクリーンショットのパス
• デバッグ時はコンソールやネットワークの調査結果
• 問題を報告する際は、失敗した正確な手順またはセレクター／ref

以下を報告します。

• どこに移動したか
• 実行した操作
• ページで実際に起きたこと
• スクリーンショット、HAR、動画など、作成した成果物

成功基準：別のエンジニアが、フロー全体をやみくもに再実行せずに、確認されたブラウザーの動作を理解できること。

重要なルール

• コマンド間でブラウザーの状態は保持されます。Cookie、タブ、セッションの状態は引き継がれます。
• goto の後は、コンテンツを読み取ったり操作したりする前に待機します。
• snapshot -i を標準の操作インターフェースとして使用します。
• スクリーンショットは .browse/sessions/<session-id>/ または .browse/sessions/default/ 以下に保存します。
• 書き込みコマンドの後、refs を含む ARIA 差分には --context delta を、refs を含む完全なスナップショットには --context full を使用します。
• 自動で何かをインストールしないでください。
• Claude の設定を自動で変更しないでください。ユーザーが事前に許可された browse 権限を求める場合は、references/permissions.md を案内してください。

参照を読み込むタイミング

• references/commands.md 正確なコマンド構文、フラグ、詳しい使用例を確認する場合に使用します。

• references/guides.md 速度に関するルール、コマンド選択のガイダンス、アーキテクチャに関する注意事項、必須の CAPTCHA/MFA 引き継ぎプロトコルを確認する場合に使用します。

• references/permissions.md ユーザーが Claude の設定で browse コマンドを事前に許可したい場合に使用します。

ガードレール

• 汎用的なブラウザー検証スキルであるため、disable-model-invocation を追加しないでください。
• ブラウザーの結果は通常、現在のフローで必要になるため、context: fork を追加しないでください。
• 汎用的なワークフロースキルであるため、paths: を追加しないでください。
• SKILL.md に CLI マニュアル全文を記載しないでください。
• ユーザーから明示的な確認を得ずに browse handoff を実行しないでください。
• browse セッションのディレクトリ外にスクリーンショットを保存しないでください。

ランタイムの選択

デフォルトでは、browse は Playwright 経由で Chromium を使用します。代替ランタイムは次のとおりです。

ランタイム	エンジン	用途	インストール
playwright (default)	Chromium	一般的なブラウジング、テスト	同梱
camoufox	Firefox (検出回避)	ボット検出のあるサイト	npm install camoufox-js && npx camoufox-js fetch
rebrowser	Chromium (ステルス)	代替のステルス方式	npm install rebrowser-playwright
lightpanda	Lightpanda	高速なヘッドレスレンダリング	lightpanda.io を参照
chrome	システムの Chrome	拡張機能を含めて実際の Chrome を使用	Chrome のインストールが必要

browse --runtime camoufox --headed goto https://protected-site.com
BROWSE_RUNTIME=camoufox browse goto https://example.com

新機能

検索マクロ

browse goto @google "best coffee beans"    # Google search
browse goto @youtube "tutorial"            # YouTube search
browse goto @amazon "laptop"               # Amazon search
browse goto @reddit "programming"          # Reddit search

すべてのマクロ：@google、@youtube、@amazon、@reddit、@reddit_subreddit、@wikipedia、@twitter、@yelp、@spotify、@netflix、@linkedin、@instagram、@tiktok、@twitch

安全フラグ（オプトイン機能）

フラグ	デフォルト	動作
BROWSE_CONSENT_DISMISS=1	OFF	ナビゲーション後に Cookie バナーを自動で閉じます
BROWSE_CLICK_FORCE=1 または --force	OFF	オーバーレイによる操作の妨げを無視して強制クリックします
BROWSE_READINESS=1 または --ready	OFF	goto の後、ハイドレーションが完了するまで待機します
BROWSE_SERP_FASTPATH=1 または --serp	OFF	Google SERP の DOM を抽出します（高速、参照なし）
BROWSE_COMMAND_LOCK=0	ON	セッションごとのコマンド直列化を無効にします
BROWSE_CAMOUFOX_PROFILE=<name>	OFF	名前付きの camoufox プロファイル（.browse/camoufox-profiles/<name>.json）を使用します

新しいコマンド

コマンド	説明
images [sel] [--limit N] [--inline]	ページ内の画像を src／alt／寸法とともに一覧表示します
youtube-transcript <url> [--lang en]	yt-dlp またはブラウザー経由で YouTube の字幕を抽出します
schema	JSON-LD、Microdata、RDFa の構造化データを抽出します（解析済み JSON）
meta	ページのメタタグを抽出します（title、description、canonical、OG、Twitter、hreflang、robots、viewport）
headings	H1〜H6 の見出し階層を、件数とインデント付きツリーで抽出します
profiles	.browse/camoufox-profiles/ 内の利用可能な camoufox プロファイルを一覧表示します

スナップショットのウィンドウ化

大きなスナップショット（80K 文字超）は自動的にページ分割されます：

browse snapshot -i                     # first page
browse snapshot -i --offset 500        # next page (line offset from previous output)

出力要件

次の内容を報告してください。

1. テストしたページまたはフロー
2. 該当する場合は、使用したセッション／プロファイルのモード
3. 実行した主なコマンドまたは操作
4. 観測した結果
5. スクリーンショット、コンソールエラー、ネットワーク障害、引き継ぎ状態などの成果物や阻害要因