mcpField
C
cmux-browser

cmux-browser

github.com/manaflow-aiエージェントワークフロー39756 回インストール9 週間前に更新
リポジトリ

cmux-browser について

cmux-browser は cmux の WebView サーフェス向けブラウザー自動化スキルです。ワークスペース内のページ操作や検査が必要なエージェントを対象とし、呼び出し元のワークスペースに操作範囲を限定します。

主な機能

  1. 01指定したワークスペースでブラウザーサーフェスを開く
  2. 02ページの移動、待機、状態確認
  3. 03DOM 要素やフォームの操作
  4. 04コンソール、エラー、ネットワークの検査
  5. 05ブラウザーセッションの保存と復元

活用シーン

  1. 01cmux WebView でローカルサイトを検証
  2. 02フォーム入力と送信結果の確認
  3. 03スクリーンショット、診断情報、セッション状態の保存

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/manaflow-ai/cmux-skills --skill cmux-browser

インストール後、Claude Code で/cmux-browserを入力して読み込まれたか確認します。

同梱ファイルagents/openai.yamlreferences/commands.md

詳細

cmux ブラウザー

cmux の WebView サーフェス内でブラウザーを自動操作する場合は、このスキルを使用します。スタンドアロンのブラウザー自動操作ツールとは異なり、すべてのブラウザーサーフェスは cmux のワークスペース、ペイン、サーフェストポロジー内にあります。

デフォルトルール

ユーザーが別のワークスペースまたはウィンドウを明示的に指定しない限り、現在の呼び出し元ワークスペースでブラウザーサーフェスを開いて操作します。

ブラウザーの状態を変更する前に、呼び出し元を特定します。

printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" \
  "${CMUX_SURFACE_ID:-}" \
  "${CMUX_SOCKET_PATH:-}"
cmux identify --json

新しいブラウザー分割には CMUX_WORKSPACE_ID を使用し、自動操作を呼び出したターミナルを確認するには CMUX_SURFACE_ID を使用します。呼び出し元のワークスペースと異なる場合は、画面上でフォーカスされているワークスペースにブラウザーを開かないでください。

基本的なワークフロー

# Open in the caller workspace and capture the returned surface ref.
cmux --json browser open https://example.com --workspace "${CMUX_WORKSPACE_ID:-}"

# Use the returned surface, for example surface:7.
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive --compact
cmux browser surface:7 click e2 --snapshot-after
cmux browser surface:7 snapshot --interactive --compact

ナビゲート、URL の確認、待機、スナップショットの取得、操作、再スナップショットの順に繰り返します。スナップショットの参照は一時的なものです。ナビゲーション、モーダルの変更、タブの変更、DOM の更新後は、スナップショットを再取得してください。

ターゲット指定

ほとんどのサブコマンドではブラウザーサーフェスの指定が必要です。

cmux browser identify
cmux browser identify --surface surface:2
cmux browser surface:2 get url
cmux browser --surface surface:2 get title

open コマンドでは、ブラウザー分割を新規作成するか、既存のものを再利用できます。

cmux browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux browser open-split https://example.com --workspace workspace:2 --json
cmux browser new https://example.com --window window:1 --json

ユーザーが複数のタブやページを求めていない限り、タスクごとにブラウザーサーフェスは1つにしてください。

コマンドグループ

コマンドの全一覧は references/commands.md を参照してください。主なグループは次のとおりです。

  • ナビゲーションとターゲット指定：identify、open、open-split、new、navigate、goto、back、forward、reload、url、focus-webview、is-webview-focused。
  • 待機：wait --selector、--text、--url-contains、--load-state、--function。
  • DOM 操作：click、dblclick、hover、focus、check、uncheck、scroll-into-view、type、fill、press、keydown、keyup、select、scroll。
  • 確認：snapshot、screenshot、get、is、find、highlight。
  • JavaScript とインジェクション：eval、addinitscript、addscript、addstyle。
  • フレーム、ダイアログ、ダウンロード：frame、dialog、download。
  • 状態とセッション：cookies、storage、state。
  • タブと診断：tab、console、errors。
  • 環境と低レベル API：viewport、geolocation、offline、trace、network、screencast、input。

よくあるパターン

永続的なキャプチャ

ブラウザーのスクリーンショット、トレース、ダウンロードした診断データ、再利用可能なセッション状態は、ユーザーに報告する前に /tmp ではなく /cmux-assets/<branch>/browser/... に保存してください。

BRANCH="$(git branch --show-current 2>/dev/null || true)"
BRANCH="${BRANCH:-$(basename "$PWD")}"
BRANCH="$(printf '%s' "$BRANCH" | tr -cs 'A-Za-z0-9._-' '-' | sed 's/^-//;s/-$//')"
ASSET_BASE="/cmux-assets"
if ! mkdir -p "$ASSET_BASE/$BRANCH" 2>/dev/null; then
  ASSET_BASE="$(pwd)/cmux-assets"
  mkdir -p "$ASSET_BASE/$BRANCH"
fi
BROWSER_ASSET_ROOT="$ASSET_BASE/$BRANCH/browser/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BROWSER_ASSET_ROOT"

ルートボリュームが読み取り専用で /cmux-assets を利用できない場合は、代替パスを使用し、そのパスを明記してください。最終的なスクリーンショットやセッションファイルを /tmp のみに残さないでください。

ナビゲート、待機、確認
cmux --json browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}"
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive --compact
cmux browser surface:7 get title
フォーム入力
cmux browser surface:7 fill "#email" --text "[email protected]"
cmux browser surface:7 fill "#password" --text "$PASSWORD"
cmux browser surface:7 click "button[type='submit']" --snapshot-after
cmux browser surface:7 wait --text "Welcome" --timeout-ms 15000
cmux browser surface:7 is visible "#dashboard"
デバッグ用キャプチャ
cmux browser surface:7 console list
cmux browser surface:7 errors list
cmux browser surface:7 screenshot --out "$BROWSER_ASSET_ROOT/cmux-failure.png"
cmux browser surface:7 snapshot --interactive --compact
セッションの保存と復元
cmux browser surface:7 state save "$BROWSER_ASSET_ROOT/cmux-browser-session.json"
cmux browser surface:7 state load "$BROWSER_ASSET_ROOT/cmux-browser-session.json"
cmux browser surface:7 reload --snapshot-after

リモートワークスペース

リモート SSH ワークスペースでは、ブラウザーペインの HTTP および WebSocket トラフィックはリモートマシン経由でルーティングされます。localhost:3000 はリモートホストの localhost を指し、ブラウザーのストレージはリモートワークスペースのコンテキストごとに分離されています。

再ビルドと再読み込み

ブラウザーの自動操作で cmux アプリ／ランタイムの変更を検証する場合は、まずアクティブなワークツリーからタグ付きアプリをビルドします。

./scripts/reload.sh --tag <short-tag>
CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}"

テストやドッグフードビルドでは、タグなしのデバッグソケットに対して自動操作を行わないでください。

ルール

  • 特に指定がない限り、ブラウザーの起動と操作は現在の呼び出し元ワークスペースに限定します。
  • cmux のターミナルからブラウザーサーフェスを作成する場合は、--workspace "${CMUX_WORKSPACE_ID:-}" を渡します。
  • 返された surface:N 参照を使用し、状態を変更する操作の後はスナップショットを再取得します。
  • ページの状態を待機または診断する前に、get url で URL を確認します。
  • 変更を加える操作の直後に確認が必要な場合は、--snapshot-after を使用します。
  • スクリプトでは get、is、find を優先します。人による確認にはスクリーンショットとスナップショットを使用します。
  • ユーザーが対象を指定していない限り、呼び出し元のワークスペース外にあるブラウザーサーフェスを閉じたり、移動したり、フォーカスしたりしないでください。
  • サポートされていないスタンドアロンブラウザーを前提とした使い方はしないでください。cmux では WKWebView ベースのブラウザーサーフェスを使用します。

コメント

Markdown 対応