browserforce

BrowserForce — あなたの実際の Chrome ブラウザー

BrowserForce を使うと、ユーザーが実際に使っている Chrome ブラウザーを利用できます。ログイン状態、Cookie、拡張機能はすべて有効なままです。ヘッドレスブラウザーや新しいプロファイルは使いません。

前提条件

ユーザーは次の条件を満たしている必要があります。

1. BrowserForce Chrome 拡張機能がインストールされ、接続済みである（アイコンが緑色）
2. リレーは最初のコマンドで自動的に起動するため、手動での操作は不要です

次のコマンドで確認します：browserforce status

まずコマンドを使う

セッションコマンドは、CLI の呼び出し間で、アクティブなタブやスナップショット参照を含む永続的なブラウザーセッションを共有します。同じコマンド言語が MCP の browserforce ツールでも使われます。

browserforce tabs                # List tabs: stable t<N> handles + names
browserforce use t2              # Switch the active tab
browserforce open <url> --as docs  # Open a new tab, optionally named
browserforce snapshot            # Accessibility tree + @eN refs
browserforce click @e2           # Act on a ref from the last snapshot
browserforce screenshot [n]      # Screenshot tab n (PNG to stdout)
browserforce -e "<code>"         # Raw Playwright JavaScript (one-shot escape hatch)

コマンド層でタスクを表現できない場合に限り、-e を使います。

カーソルに自分の名前を表示する

ユーザーがゴーストカーソルを有効にしている場合、どのエージェントが操作しているかカーソルに表示されます。ただし、自分が誰なのかを指定した場合に限ります。コマンドを実行する前に、次の環境変数を設定してください。

export BROWSERFORCE_AGENT_NAME="Claude"

最大 24 文字で、使用できる文字は A-Z a-z 0-9 space . _ - です。それ以外の文字は拒否されずに削除され、連続する空白は 1 つにまとめられ、長い名前は切り詰められます。サニタイズ後に空になる名前は、ラベルがまったく表示されません。変更されない名前を選んでください。

ほかのエージェントとマシンを共有していますか？ その場合は、BF_SESSIOND_LOCK_PATH=/tmp/bf-<your-name>.json も個別に設定してください。1 つのセッションデーモンが単一の接続を介してすべての CLI 呼び出しに対応し、起動時の環境から名前を取得します。そのため、自分専用のデーモンがなければ、クリック操作は最初のエージェントの名前に紐づけられます。

基本のワークフロー：観察 → 操作 → 観察

browserforce open https://example.com/login
browserforce snapshot                      # find the email/password/submit refs
browserforce fill @e3 "[email protected]"
browserforce fill @e4 "hunter2"
browserforce click @e5
browserforce wait url "**/dashboard"
browserforce snapshot                      # verify the result

ページが変わると参照はすぐに古くなるため、次の参照操作の前に必ずスナップショットを取り直してください。

複数タブでの作業

browserforce open https://docs.example.com --as docs
browserforce open https://app.example.com --as app
browserforce snapshot --tab app            # read app without switching tabs
browserforce click @e2 --tab app
browserforce use docs                      # or switch the active tab

タブは安定したハンドル（t2）または名前で指定してください。リスト上の位置では指定しないでください。タブ名は一意です。名前を別のタブに意図的に移す場合に限り、--replace を渡してください。

安定したハンドルと名前はセッション中ずっと維持されます。browserforce tabs で確認できます。ハンドルはアイドル状態からの再接続後も維持され、reset を実行した場合にのみ無効になります。

ブラウザー作業をサブエージェントに引き継ぐ

サブエージェントはブラウザーセッションを自動的に共有します。マシンごとにデーモンは 1 つなので、設定なしでタブ、ログイン状態、スナップショット参照を確認できます。次のいずれかをサブエージェントのプロンプトに貼り付けてください。

順次実行するサブエージェント。 アクティブなタブを共有します。

ブラウザー：browserforce CLI を使ってください。ユーザーが実際に使っている Chrome にすでに接続されており、このセッションのタブを共有しています。browserforce tabs でタブを確認し、browserforce use <handle> でタブを選んでから、snapshot / click @eN / fill @eN <text> を実行してください。

並列実行するサブエージェント。 それぞれに個別の ID を割り当てると、アクティブなタブもそれぞれ専用になります。

ブラウザー：BROWSERFORCE_CLIENT_ID=<your-name> を設定して、browserforce CLI を使ってください。他のエージェントとセッションのタブやログイン状態を共有しますが、アクティブなタブは自分専用です。use や open を実行しても、他のエージェントのタブは移動しません。

ID を設定できないクライアントでは、代わりにすべての実行でタブを固定してください。snapshot、click、fill、type、press、hover、wait、get、eval に --tab <handle> を渡し、use や open は実行しないでください。tabs には --tab は不要で、指定もできません。

独自のセッションを維持するサブエージェント。 専用のデーモンを割り当ててください。

ブラウザー：BF_SESSIOND_LOCK_PATH=/tmp/bf-<name>.json と BROWSERFORCE_CDP_CLIENT_LABEL=<name> を設定して、browserforce CLI を使ってください。独自のセッション状態と、自分が作成したタブ用の独自の Chrome ウィンドウが使えます。

この方法ではセッション状態と新しいタブを開く場所が分離されます。ただし、サンドボックスではありません。すべての BrowserForce クライアントから、ブラウザー内のすべてのタブを確認し、操作できます。触れてはいけないタブがある場合、そのタブに関わる作業を委任しないでください。

ハンドル（t<N>）はセッション中ずっと維持されるため、サブエージェントに渡したハンドルは、実行時も同じタブを指します。

コマンドリファレンス

browserforce snapshot [--tab docs] [--selector "#main"] [--search "login"] [--interactive]
browserforce hover @e3                         # Hover a ref
browserforce type @e2 "more text"              # Type without clearing
browserforce press Enter                        # Send a key
browserforce wait text "Saved"                  # Wait for text
browserforce wait url "**/dashboard"            # Wait for a URL glob
browserforce wait load domcontentloaded          # Wait for a load state
browserforce wait fn "window.ready === true"    # Wait for a JavaScript predicate
browserforce get url|title                      # Read the current page
browserforce get text|html @e5                  # Read a referenced element
browserforce eval --stdin                       # Run piped JS in the persistent session
browserforce rename docs api-docs                # Rename a tab
browserforce forget api-docs                     # Remove a tab name
browserforce run "click @e2 --tab docs"         # Run a command string

参照には @e1、e1、または ref=e1 を使用できます。参照／読み取りコマンドでは、アクティブなタブを切り替えずに --tab <handle|name|text> を指定できます。eval は MCP の exec と同じガード付き境界を使用します。page、context、state、および snapshot() にアクセスでき、state はセッション内のコマンド間で保持されます。コマンド結果を機械可読形式にするには、--json を追加します。

データを抽出する

browserforce get url                       # current URL
browserforce get text @e5                  # text content of a ref
browserforce get html @e5                  # innerHTML of a ref
echo "return await page.title();" | browserforce eval --stdin

ワンショットの -e（回避手段）

各 browserforce -e 呼び出しは独立しています（-e 呼び出し間で状態は保持されません）。すべてを1つのスニペット内で実行してください。

browserforce -e "
  state.page = await context.newPage();
  await state.page.goto('https://example.com');
  await waitForPageLoad();
  return await snapshot();
"

ルール

1. スクリーンショットよりスナップショットを優先する — スナップショットはテキストを返し、高速かつ低コストです。視覚的なレイアウト確認に限り、スクリーンショットを使用してください。
2. ページが変わるたびにスナップショットを取り直す — 参照はすぐに古くなります。
3. 既存のタブに移動しない — browserforce open で自分用のタブを開いてください。
4. -e よりコマンドを優先する — コマンド層でタスクを表現できない場合に限り、生の Playwright を使用してください。
5. コマンドエラーから次の手順がわかる — 参照が古い場合はスナップショットを取り直し、タブが不明な場合は browserforce tabs を実行してください。修正して再試行します。
6. バックエンドのフォールバックは明示される — auto は拡張機能が接続されていれば実際の Chrome を使用し、管理対象の Chrome にフォールバックすると警告します。フォールバックせずに失敗させるには --real を使用してください。

ページが表示されているだけでは証明にならない

読み取っているタブは、変更する前から開かれており、ログイン済みだった可能性があります。そのため、変更とは無関係な理由でページが正しく表示されることがあります。ブラウザー上の結果を検証済みと判断する前に、新たにページを開く、サーバーログを確認する、テストを実行するといった独立した証拠と照合してください。

トラブルシューティング

エラーからの復旧

• 「Unknown ref」：ページが変わっています — browserforce snapshot を実行し、新しい参照を使用してください
• 「No tab named …」：browserforce tabs を実行し、一覧にあるハンドルまたは名前を指定してください
• 接続が切れた場合：ユーザーは browserforce status を確認してください
• タブがない場合：browserforce open https://example.com
• 要素が見つからない場合：browserforce snapshot --search "button"

重要

これはユーザーの実際のブラウザーです。敬意を持って使用してください。

• 自分が開いていないタブを閉じないでください
• 自分が作成していないタブに移動しないでください
• ブラウザーの設定や保存済みデータを変更しないでください