browser

ブラウザー自動化

Claude で browse CLI を使用してブラウザー操作を自動化します。

セットアップの確認

ブラウザーコマンドを実行する前に、CLI が利用可能であることを確認してください。

which browse || npm install -g browse

環境の選択（ローカルとリモート）

CLI では、コマンドごとに環境フラグを明示的に指定できます。何も指定しない場合、BROWSERBASE_API_KEY が設定されていれば次のセッションは Browserbase がデフォルトになり、設定されていなければローカルがデフォルトになります。

ローカルモード

• browse open <url> --local は、分離されたクリーンなローカルブラウザーを起動します
• browse open <url> --auto-connect は、すでに実行中のデバッグ可能な Chrome に接続します。デバッグ可能な Chrome が利用できない場合は、--local を使用してください
• browse open <url> --cdp <port|url> は、特定の CDP ターゲットに接続します
• 最適な用途：開発、localhost、信頼できるサイト、再現性の高い実行

リモートモード（Browserbase）

• browse open <url> --remote は、Browserbase セッションを開始します
• ローカルフラグを指定しない場合、BROWSERBASE_API_KEY が設定されていれば Browserbase がデフォルトになります
• 提供機能：Browserbase Identity、Verified ブラウザー、自動 CAPTCHA 解決、住宅用プロキシ、セッションの永続化
• リモートモードを使用する場合： 対象サイトでボット検出、CAPTCHA、IP レート制限、Cloudflare による保護がある場合、または地域固有のアクセスが必要な場合
• 認証情報は https://browserbase.com/settings で取得してください

どちらを選ぶか

• 再現性の高いローカルテスト／クリーンな状態：browse open <url> --local
• ローカルのログイン情報／Cookie を再利用：browse open <url> --auto-connect
• シンプルなブラウジング（ドキュメント、Wiki、公開 API）：ローカルモードで問題ありません
• 保護されたサイト（ログイン壁、CAPTCHA、スクレイピング対策）：リモートモードを使用してください
• ローカルモードでボット検出やアクセス拒否が発生する場合：リモートモードに切り替えてください

コマンド

デーモンの起動後は、ほとんどのドライバーコマンドをローカル、リモート、CDP の各セッションで使用できます。

ナビゲーション

browse open <url>                        # Go to URL
browse open <url> --local                # Go to URL in a clean local browser
browse open <url> --remote               # Go to URL in a Browserbase session
browse reload                            # Reload current page
browse back                              # Go back in history
browse forward                           # Go forward in history

ページの状態（スクリーンショットよりスナップショットを優先）

browse snapshot                          # Get accessibility tree with element refs (fast, structured)
browse screenshot --path <path>          # Take visual screenshot (slow, uses vision tokens)
browse get url                           # Get current URL
browse get title                         # Get page title
browse get text <selector>               # Get text content (use "body" for all text)
browse get html <selector>               # Get HTML content of element
browse get markdown [selector]           # Get page content as markdown (defaults to body)
browse get value <selector>              # Get form field value

ページの状態を把握するには、デフォルトで browse snapshot を使用してください。操作に使える要素参照を含むアクセシビリティツリーが返されます。視覚的なコンテキスト（レイアウト、画像、デバッグ）が必要な場合にのみ、browse screenshot を使用してください。

操作

browse click <ref>                       # Click element by ref from snapshot (e.g., @0-5)
browse type <text>                       # Type text into focused element
browse fill <selector> <value>           # Fill input; add --press-enter if Enter is needed
browse select <selector> <values...>     # Select dropdown option(s)
browse upload <selector> <files...>      # Upload file(s) to <input type="file">
browse press <key>                       # Press key (Enter, Tab, Escape, Cmd+A, etc.)
browse mouse drag <fromX> <fromY> <toX> <toY>  # Drag from one point to another
browse mouse scroll <x> <y> <deltaX> <deltaY>  # Scroll at coordinates
browse highlight <selector>              # Highlight element on page
browse is visible <selector>             # Check if element is visible
browse is checked <selector>             # Check if element is checked
browse wait <type> [arg]                 # Wait for: load, selector, timeout

CDP イベントの追跡

browse cdp <url|port>                    # Stream CDP events as NDJSON from any target
browse cdp 9222                          # Attach to local Chrome on port 9222
browse cdp ws://localhost:9222/devtools/browser/...  # Full WebSocket URL
browse cdp <url> --domain Network        # Only Network events
browse cdp <url> --domain Network --domain Console  # Multiple domains
browse cdp <url> --pretty                # Human-readable output
browse cdp <url> > events.jsonl          # Pipe to file
browse cdp <url> | jq '.method'          # Filter with jq

cdp コマンドは Chrome DevTools Protocol の任意のターゲットに直接接続し、イベントをストリーミングします。デーモンは使用せず、単独で実行される長時間プロセスです。停止するには Ctrl+C を押してください。デフォルトのドメイン：Network、Console、Runtime、Log、Page。

セッション管理

browse stop                              # Stop the browser daemon
browse status                            # Check daemon status and resolved mode
browse tab list                          # List all open tabs
browse tab switch <index-or-target-id>   # Switch to tab by index or target ID
browse tab close [index-or-target-id]    # Close tab

一般的なワークフロー

環境が重要な場合は、最初のブラウザーコマンドに --local、--remote、--auto-connect、または --cdp <port|url> を指定してください。

1. browse open <url> --local または browse open <url> --remote — ページに移動します
2. browse snapshot — アクセシビリティツリーを読み、ページ構造を把握して要素参照を取得します
3. browse click <ref> / browse type <text> / browse fill <selector> <value> — スナップショットの要素参照を使用して操作します
4. browse snapshot — 操作が成功したことを確認します
5. 必要に応じて手順 3～4 を繰り返します
6. browse stop — 完了したらブラウザーを閉じます

クイック例

browse open https://example.com
browse snapshot                          # see page structure + element refs
browse click @0-5                        # click element with ref 0-5
browse get title
browse stop

モードの比較

機能	ローカル	Browserbase
速度	高速	やや低速
セットアップ	Chrome が必要	API キーが必要
既存のローカル Cookie の再利用	browse open <url> --auto-connect を使用	該当なし
Verified ブラウザー	いいえ	はい（Identity 経由の Browserbase Verified ブラウザー）
CAPTCHA の解決	いいえ	はい（reCAPTCHA/hCaptcha を自動解決）
住宅用プロキシ	いいえ	はい（201 か国、地域ターゲティング）
セッションの永続化	いいえ	はい（コンテキスト経由で Cookie／認証情報を保持）
最適な用途	開発／シンプルなページ	保護されたサイト、Browserbase Identity と Verified アクセス、本番環境でのスクレイピング

ベストプラクティス

1. ローカルでの方法は意図的に選択してください：クリーンな状態にするには browse open <url> --local、既存のローカル認証情報を使うには browse open <url> --auto-connect、保護されたサイトには browse open <url> --remote を使用します
2. 操作を始める前に、必ず browse open を実行してください
3. ページの状態を確認するには browse snapshot を使用してください。処理が速く、要素の参照も取得できます
4. 視覚的な情報が必要な場合にのみスクリーンショットを撮影してください（レイアウトの確認、画像、デバッグなど）
5. クリックや操作には snapshot の参照を使用してください（例：browse click @0-5）
6. 完了したら browse stop を実行し、ブラウザーセッションをクリーンアップして環境変数の上書きを解除してください

トラブルシューティング

• 「No active page」：browse stop を実行してから、browse status を確認してください。それでも実行中と表示される場合は、pkill -f "browse.*daemon" でゾンビデーモンを終了してから、browse open を再試行してください
• Chrome が見つからない：Chrome をインストールしてください。デバッグ可能な Chrome がすでに起動している場合は browse open <url> --auto-connect を使用するか、browse open <url> --remote に切り替えてください
• 操作に失敗する：browse snapshot を実行して、利用可能な要素とその参照を確認してください
• Browserbase が失敗する：API キーが設定されていることを確認してください

リモートモードへの切り替え

次の状況を検出した場合は、リモートに切り替えてください：CAPTCHA（reCAPTCHA、hCaptcha、Turnstile）、ボット検出ページ（「Checking your browser...」）、HTTP 403/429、本来コンテンツがあるはずのサイトでページが空、またはユーザーから切り替えを求められた場合。

シンプルなサイト（ドキュメント、ウィキ、公開 API、localhost）では切り替えないでください。

browse open <url> --local          # clean isolated local browser
browse open <url> --auto-connect   # attach to existing debuggable Chrome
browse open <url> --remote         # Browserbase session

モードフラグはセッションの開始時に適用されます。browse stop の後、次回の開始時には環境変数に基づく自動検出にフォールバックします。デーモンの実行中に browse status を使用すると、解決されたモードとターゲットを確認できます。

詳しい例については、EXAMPLES.md を参照してください。 API リファレンスについては、REFERENCE.md を参照してください。