browser-use

browser-use によるブラウザー自動化

すべてのコマンドで、自己完結型のラッパー bu.sh を使用します。このラッパーは次の処理を行います。

• 初回実行時にローカルの .venv を自動でセットアップします（uv 経由で依存関係をダウンロードします。一度だけ約60秒かかります）
• PYTHONUTF8=1 を自動で設定します（Windows で絵文字や Unicode を扱えます）
• ブラウザーデーモンを維持し、呼び出しごとの遅延を約50ミリ秒に抑えます

省略表記 — 以下のすべての例で、bu は次を意味します。

bash ~/.claude/skills/browser-use/bu.sh

前提条件

• uv がインストールされている必要があります（uv --version）
• 初回実行時に、GitHub から ~/.claude/skills/browser-use/.venv へ browser-use がインストールされます

基本的なワークフロー

1. 移動：bu open <url> — 必要に応じてブラウザーとデーモンを起動します
2. 確認：bu state — クリック可能な要素とインデックスを返します
3. 操作：state のインデックスを使用します（bu click 5、bu input 3 "text"）
4. 検証：bu state または bu screenshot で確認します
5. 繰り返し：コマンド間でブラウザーは開いたままです
6. クリーンアップ：完了したら bu close を実行します

ブラウザーモード

bu open <url>                         # Default: headless Chromium
bu --headed open <url>                # Visible window
bu --profile "Default" open <url>     # Real Chrome with Default profile (existing logins/cookies)
bu --profile "Profile 1" open <url>   # Real Chrome with named profile
bu --connect open <url>               # Auto-discover running Chrome via CDP
bu --cdp-url ws://localhost:9222/... open <url>  # Connect via specific CDP URL

--connect、--cdp-url、--profile は相互に排他的です。

コマンド

# Navigation
bu open <url>                    # Navigate to URL
bu back                          # Go back in history
bu scroll down                   # Scroll down (--amount N for pixels)
bu scroll up                     # Scroll up
bu switch <tab>                  # Switch to tab by index
bu close-tab [tab]               # Close tab (current if no index)

# Page State — always run state first to get element indices
bu state                         # URL, title, clickable elements with indices
bu screenshot [path.png]         # Screenshot (base64 if no path, --full for full page)

# Interactions — use indices from state
bu click <index>                 # Click element by index
bu click <x> <y>                 # Click at pixel coordinates
bu type "text"                   # Type into focused element
bu input <index> "text"          # Click element, then type
bu keys "Enter"                  # Send keyboard keys (also "Control+a", etc.)
bu select <index> "option"       # Select dropdown option
bu upload <index> <path>         # Upload file to file input
bu hover <index>                 # Hover over element
bu dblclick <index>              # Double-click element
bu rightclick <index>            # Right-click element

# Data Extraction
bu eval "js code"                # Execute JavaScript, return result
bu get title                     # Page title
bu get html [--selector "h1"]    # Page HTML (or scoped to selector)
bu get text <index>              # Element text content
bu get value <index>             # Input/textarea value
bu get attributes <index>        # Element attributes
bu get bbox <index>              # Bounding box (x, y, width, height)

# Wait
bu wait selector "css"           # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
bu wait text "text"              # Wait for text to appear

# Cookies
bu cookies get [--url <url>]     # Get cookies (optionally filtered)
bu cookies set <name> <value>    # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
bu cookies clear [--url <url>]   # Clear cookies
bu cookies export <file>         # Export to JSON
bu cookies import <file>         # Import from JSON

# Python — persistent session with browser access
bu python "code"                 # Execute Python (variables persist across calls)
bu python --file script.py       # Run file
bu python --vars                 # Show defined variables
bu python --reset                # Clear namespace

# Session
bu close                         # Close browser and stop daemon
bu sessions                      # List active sessions
bu close --all                   # Close all sessions

# Recipes — store and replay DOM access patterns (no screenshot on repeat runs)
bu recipe list                   # Show all installed recipes + run history
bu recipe run <name>             # Execute a recipe directly against the DOM
bu recipe run <name> --connect   # Override auth: use CDP connect mode
bu recipe run <name> --headed    # Override: show browser window (debug)
bu recipe show <name>            # Print recipe JSON
bu recipe save <name> --file <path>  # Install a recipe JSON file
bu recipe delete <name>          # Remove a recipe

Python の browser オブジェクトでは、次の操作ができます。browser.url、browser.title、browser.html、browser.goto(url)、browser.back()、browser.click(index)、browser.type(text)、browser.input(index, text)、browser.keys(keys)、browser.upload(index, path)、browser.screenshot(path)、browser.scroll(direction, amount)、browser.wait(seconds)。

クラウド API

bu cloud connect                 # Provision cloud browser and connect
bu cloud connect --timeout 120 --proxy-country US  # With options
bu cloud login <api-key>         # Save API key (or set BROWSER_USE_API_KEY)
bu cloud logout                  # Remove API key
bu cloud v2 GET /browsers        # REST passthrough (v2 or v3)
bu cloud v2 POST /tasks '{"task":"...","url":"..."}'
bu cloud v2 poll <task-id>       # Poll task until done

よくあるワークフロー

認証済みブラウジング（既存の Chrome セッション）

bu --connect open https://gmail.com   # Reuse logged-in Chrome via CDP
bu --connect state
bu --connect eval "document.title"

Chrome を --remote-debugging-port=9222 を付けて起動する必要があります。

認証済みブラウジング（Chrome プロファイル）

bu profile list                                # Check available profiles
bu --profile "Default" open https://github.com # Already logged in

JavaScript によるデータ抽出

bu --connect open https://x.com/notifications
bu --connect eval "Array.from(document.querySelectorAll('[data-testid=\"notification\"]')).slice(0,10).map(n => n.innerText).join('\n---\n')"

ローカルの開発サーバーを公開する

bu tunnel 3000                             # → https://abc.trycloudflare.com
bu open https://abc.trycloudflare.com

コマンドの連結

bu open https://example.com && bu state
bu input 5 "[email protected]" && bu input 6 "password" && bu click 7

途中の出力が不要な場合はコマンドを連結します。インデックスを特定するために state を解析する必要がある場合は、コマンドを個別に実行します。

グローバルオプション

オプション	説明
--headed	ブラウザーウィンドウを表示します
--profile [NAME]	実際の Chrome を使用します（引数なしの --profile では「Default」を使用します）
--connect	CDP 経由で実行中の Chrome を自動検出します
--cdp-url <url>	CDP URL（http:// または ws://）経由で接続します
--session NAME	名前付きセッションを指定します（デフォルト：「default」）
--json	JSON 形式で出力します
--mcp	標準入力／標準出力経由で MCP サーバーとして実行します

ヒント

1. 最初に必ず state を実行して、利用可能な要素とそのインデックスを確認します
2. デバッグには --headed を使用して、ブラウザーの動作を確認します
3. セッションは維持されます — コマンド間でブラウザーは開いたままです
4. 複雑なページからの抽出には、JS を使った eval が最も強力な方法です

トラブルシューティング

• 初回実行が遅いですか？ 正常です。約200MBの依存関係を .venv にダウンロードしています。2回目以降の実行は即座に完了します。
• ブラウザーが起動しませんか？ bu close の後、bu --headed open <url> を実行します
• 要素が見つかりませんか？ bu scroll down の後、bu state を実行します
• Unicode エラーが発生しますか？ 対応済みです。bu.sh が PYTHONUTF8=1 を自動で設定します

クリーンアップ

bu close           # Close browser session
bu tunnel stop --all  # Stop tunnels (if any)

レシピシステム

レシピには DOM アクセスのパターンが保存されるため、同じタスクを繰り返す際に視覚的な確認を省略できます。

初回実行：セレクターを手動で特定し、レシピ JSON を作成します 2回目以降の実行：bu recipe run <name> で JS を直接実行します — スクリーンショットや要素のスキャンは不要です

レシピ JSON の形式

{
  "name": "my_recipe",
  "version": 1,
  "description": "What this recipe does",
  "url": "https://example.com/page",

  "auth": {
    "mode": "connect",      // "connect" | "profile" | "headless"
    "profile": null,        // Chrome profile name (mode=profile only)
    "headed": false,
    "session": "default"
  },

  "steps": [
    {
      "id": "nav",
      "type": "navigate",
      "url": "https://example.com/page",
      "wait_for": ".main-content",
      "wait_timeout_ms": 10000
    },
    {
      "id": "extract",
      "type": "eval",
      "js": "document.querySelector('.result')?.innerText",
      "output_var": "result",
      "fallback_selectors": [".alt-result", "[data-result]"]
    }
  ],

  "output": { "format": "text", "var": "result" },
  "metadata": { "created": "2026-01-01", "last_run": null, "run_count": 0, "broken_step": null }
}

ステップの種類

種類	必須フィールド	動作
navigate	url	URL を開きます。CSS セレクターを指定すると、そのセレクターが表示されるまで待機します
eval	js	JavaScript を実行し、結果を output_var に保存します
click	index	bu state のインデックスで要素をクリックします
input	index、text	要素をクリックしてからテキストを入力します
wait	selector または text	要素またはテキストが表示されるまで待機します
scroll	direction	up または down へスクロールします

自己修復フォールバック

eval ステップが失敗した場合：

1. 各 fallback_selectors エントリを document.querySelector('SEL')?.innerText として試します
2. 最初に一致した結果を標準エラー出力に記録し、レシピを続行します
3. すべてのフォールバックが失敗した場合：スクリーンショットを recipes/.broken_<name>_<step>.png に保存し、メタデータの broken_step を設定して、終了コード 1 で終了します

レシピの例

CDP 接続を使用して X.com の通知を取得する recipes/x_notifications.json をご覧ください。

プラットフォームのサポート

Linux、macOS、Windows（Windows では Git Bash または WSL が必要）で動作します。 bash が PATH で利用可能である必要があります。標準的な構成ではすべて利用できます。