browser-harness

browser-harness - 自己修復型 LLM ブラウザー自動化

キーワード：browser-harness · self-healing browser · llm browser automation · cdp agent

Chrome DevTools Protocol を介して、LLM エージェントと Chrome を WebSocket で直接接続します。エージェントはページを調査し、ヘルパーコードを作成し、ドメインスキルを再利用して、追加のブラウザー抽象化レイヤーを使わずにタスクを検証できます。

Browser Harness は、このカタログで削除された agent-browser スキルの正式な後継です。クリーンなブラウザーでの検証、自律的なブラウザータスク、Claude Code、Codex、Antigravity、Gemini CLI、OpenCode 間で移植可能な CDP 制御に使用してください。

このスキルを使用する場面

• ログイン、ページ移動、フォーム入力、データ抽出、ダウンロード、検証など、複数ステップのブラウザーワークフローを LLM エージェントに実行させる必要がある場合。
• ユーザーがすでに開いているブラウザーの状態ではなく、クリーンなブラウザープロファイルや再現可能な CDP 検証が必要な場合。
• Codex CLI または Antigravity から実行しており、シェル／Python コマンドで操作できるローカルブラウザーハーネスが必要な場合。
• ブラウザーのスクリーンショットの保存、サイズ変更、再オープン時に、Claude で画像／スクリーンショット／ツールのエラーが発生する場合。
• 対象の DOM が変化し、エージェントが agent-workspace/agent_helpers.py のヘルパーを追加または修正する必要がある場合。
• agent-workspace/domain-skills/ のサイト固有のドメインスキルがタスクに役立つ場合。
• 許可された対象で、並行ブラウザー、プロキシ、または CAPTCHA 解決が必要な場合は、Browser Use Cloud が適しています。

このスキルを使用しない場面

• ブラウザーの状態や JavaScript とのインタラクションを伴わない単純な HTML 抽出の場合 → scrapling を使用します。
• 人間による正確な UI 注釈や、レンダリングされた問題箇所を指し示す作業の場合 → agentation を使用します。
• ユーザーがすでに開いている認証済み Chrome プロファイルを再利用する必要がある場合 → playwriter を使用します。
• React コンポーネントのソースを取得する場合 → react-grab を使用します。
• エージェントの自律性を必要としない、通常の Playwright／Puppeteer スクリプトの作成の場合 → そのスタックを直接使用します。

手順

ステップ 1：実行パケットを選択する

コマンドを記述する前に、主要なパケットを 1 つ選んでください。

• local-cdp：--remote-debugging-port=9222 を使用するローカルの Chrome／Chromium。
• codex-cdp：Codex CLI が同じローカルチェックアウトと CDP エンドポイントを制御します。
• antigravity-cdp：Antigravity（agy）が同じワークスペースと Chrome のデバッグエンドポイントを使用します。
• claude-vision-safe：スクリーンショットのキャプチャに、以下の安全な画像処理パイプラインを使用する必要がある場合。
• domain-skill：agent-workspace/domain-skills/ にサイト固有のヘルパーを追加または修正する場合。
• cloud-browser：Browser Use Cloud が必要で、使用が許可されている場合。

ステップ 2：browser-harness をインストールする

Browser Harness は、シェルコマンドを実行できる任意のプラットフォームから、エージェントを使ってセットアップできます。

git clone https://github.com/browser-use/browser-harness.git
cd browser-harness
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Claude Code では、プロジェクト標準のセットアッププロンプトも使用できます。

Set up https://github.com/browser-use/browser-harness for me

要件：

• Python 3.10 以降
• Chrome または Chromium
• エージェントの実行環境から http://localhost:9222/json にアクセスできること

ステップ 3：Chrome のリモートデバッグを有効にする

ハーネスがクリーンなセッションを安全に作成できるよう、別のプロファイルを使用してください。

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows PowerShell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-debug"

確認します。

curl -s http://localhost:9222/json

ステップ 4：プラットフォーム固有の注意事項

プラットフォーム	browser-harness を使用する場面	セットアップに関する注意
Claude Code	自律的なブラウザー操作や Claude で安全に使えるスクリーンショットが必要な場合	画像を多用する作業の前に、スクリーンショットのパッチを適用してください
Codex CLI	リポジトリのタスクからローカル CDP 自動化が必要な場合	.venv をチェックアウト内に置き、そのシェルからコマンドを実行してください
Antigravity（agy）	Antigravity のワークフローから同じブラウザーハーネスを使用する場合	agy からチェックアウトと localhost:9222 にアクセスできることを確認してください
Gemini CLI / OpenCode	プラットフォーム固有の MCP 接続設定なしで移植可能なブラウザー自動化が必要な場合	同じローカル CDP と Python ワークスペースを使用してください

Codex と Antigravity では、Claude Code のプラグインコマンドが使えるとは想定しないでください。明示的なローカルコマンドを優先してください。

cd ~/browser-harness
source .venv/bin/activate
python -c "import browser_harness; print('browser-harness OK')"
curl -s http://localhost:9222/json

ステップ 5：Claude 対応のスクリーンショットパッチを適用する

スクリーンショットに関して Claude で画像認識、画像アップロード、PNG 読み込み、またはツールのエラーが発生する場合は、src/browser_harness/helpers.py にパッチを適用し、スクリーンショットをメモリ上でデコードしてリサイズするとともに、オーバーレイを保存する前に PIL のファイルハンドルを閉じます。

必要な変更：

diff --git a/src/browser_harness/helpers.py b/src/browser_harness/helpers.py
--- a/src/browser_harness/helpers.py
+++ b/src/browser_harness/helpers.py
@@
-import base64, importlib.util, json, math, os, sys, time, urllib.request
+import base64, importlib.util, io, json, math, os, sys, time, urllib.request
@@
-            img = Image.open(path)
+            with Image.open(path) as src:
+                img = src.copy()
@@
-    open(path, "wb").write(base64.b64decode(r["data"]))
+    data = base64.b64decode(r["data"])
     if max_dim:
         from PIL import Image
-        img = Image.open(path)
+        img = Image.open(io.BytesIO(data))
         if max(img.size) > max_dim:
             img.thumbnail((max_dim, max_dim))
-            img.save(path)
+            buf = io.BytesIO()
+            img.save(buf, format="PNG")
+            data = buf.getvalue()
+    with open(path, "wb") as f:
+        f.write(data)

重要な理由：

• Image.open(path) は、コピーまたはクローズしない限り、遅延ファイルハンドルを保持します。
• PNG を開いて書き換えた直後にエージェントが再度開くと、Claude の画像／ツールの処理パイプラインでエラーが発生しやすくなります。
• io.BytesIO を使ってメモリ上でリサイズすると、書き込み・読み込み・書き込みのサイクルを避けられます。
• with open(path, "wb") を使って一度だけ書き込むと、Claude のビジョンアップロードに適した安定したファイルが生成されます。

Claude 向けの推奨スクリーンショット呼び出し：

path = capture_screenshot(max_dim=1800)

高 DPI ディスプレイでは max_dim=1800 を使用し、一般的な画像の片側 2000px の制限を超えないようにします。

ステップ 6：ブラウザータスクを実行する

エージェントに自然言語でタスクを指示します：

Open the local app, complete the signup form, and verify that the dashboard appears.
Navigate to GitHub, open the first open issue, and summarize the acceptance criteria.
Fill in the contact form at example.com and confirm the success message.

エージェントは次の処理を行います。

1. CDP 経由で Chrome に接続します。
2. タブとページの状態を確認します。
3. agent-workspace/agent_helpers.py にある既存のヘルパーを再利用します。
4. 不足しているヘルパーを agent-workspace/agent_helpers.py または agent-workspace/domain-skills/ に追加します。
5. テキスト、URL、DOM の状態、スクリーンショット、またはダウンロードした成果物の証拠を使って、完了を確認します。

ステップ 7：ドメインスキルで拡張する

ドメインスキルは、特定のサイト向けのプレイブックです。小さく、再利用しやすいものにします：

agent-workspace/domain-skills/
├── github.py
├── linkedin.py
└── your-site.py

例：

def login(page, username: str, password: str):
    """Log into mysite.com."""
    page.goto("https://mysite.com/login")
    page.fill("#username", username)
    page.fill("#password", password)
    page.click("button[type=submit]")
    page.wait_for_url("**/dashboard")

ステップ 8：Browser Use Cloud へのエスカレーション

ローカルの Chrome では不十分で、対象が自動化を許可している場合に限り、Browser Use Cloud を使用します：

from browser_harness import BrowserUseCloud

client = BrowserUseCloud(api_key="YOUR_API_KEY")
result = client.run("Extract the dashboard data and return a CSV summary")
print(result)

ベストプラクティス

1. まず local-cdp を使い、ローカルの CDP エンドポイントでタスクを実行できない場合にのみエスカレーションします。
2. コアパッケージの編集は最小限にします。通常のワークフローロジックは agent_helpers.py またはドメインスキルに配置します。
3. 画像を多用する Claude Code の実行前に、Claude 対応のスクリーンショットパッチを適用します。
4. Codex と Antigravity では、Claude 専用のプラグイン手順より、明示的なシェル／Python コマンドを優先します。
5. エージェントが最終的な証拠を記録するまで、ブラウザータスクは未完了として扱います。
6. ステートレスなスクレイピングには scrapling を使い、すでに開いている認証済みブラウザーの再利用には playwriter を使います。
7. サイトの利用規約、robots の設定、レート制限、または認可の境界を回避しないでください。

簡単な検証

cd ~/browser-harness
source .venv/bin/activate
python -c "import browser_harness; print('browser-harness OK')"
curl -s http://localhost:9222/json

参考資料

• browser-use/browser-harness GitHub
• scrapling — エージェントが所有するブラウザー状態を使わない、ステートレスな HTML／JS スクレイピング
• playwriter — 既存のログイン／セッション状態が重要な場合に、実行中のブラウザーを再利用
• agentation — レンダリング済み UI へのフィードバックと、人による注釈パケット