peekaboo

Peekaboo

ネイティブ macOS のキャプチャ、UI の検査、自動化には Peekaboo を使用します。Peekaboo が操作に対応している場合は、AppleScript や osascript よりも、ネイティブのアプリ、ウィンドウ、アクセシビリティ、入力コマンドを優先してください。

バイナリ

• ~/bin/peekaboo がある場合は、Peter の署名済みローカルリリース版であるため、こちらを優先してください。
• ない場合は、PATH にある peekaboo を使用してください。
• 構文やインストール状態を前提とする前に、選択したバイナリを確認してください。

PB="${PEEKABOO_BIN:-$HOME/bin/peekaboo}"
[ -x "$PB" ] || PB="$(command -v peekaboo)"
"$PB" --version

実行時のホストと権限

• GUI Bridge ホストが必要な場合は、フォーカスを奪わずに Peekaboo.app を起動します： open -gj -a Peekaboo。
• アプリは自身の TCC 権限を所有し、 ~/Library/Application Support/Peekaboo/bridge.sock を提供します。再利用可能なデーモンには 個別の権限があり、daemon.sock を提供します。daemon start はアプリの起動ではありません。
• 通常の実行時選択では、健全な再利用可能デーモン、GUI ホストの順に優先し、その後にデーモンを起動します。一方、暗黙的な画面キャプチャによる観察、AX ツリーの検査、 ブラウザー、スナップショット状態の各コマンドでは、GUI ホストより先に、現在の CLI ビルドと完全に一致するビルドスコープのデーモンを優先し、必要に応じて自動起動することがあります。候補の確認には bridge status --verbose --json を使用します。ただし、操作の要件によって順序が変わる場合がある点に注意してください。アプリが保持する TCC 権限が必要な場合は、 --bridge-socket "$HOME/Library/Application Support/Peekaboo/bridge.sock" を渡し、アプリが選択されたと思い込まずに hostKind: gui を確認してください。
• permissions status --all-sources --json を確認してください。画面収録、アクセシビリティ、イベント生成の権限は、呼び出し元のターミナルだけではなく、選択されたソースとして報告されたプロセスに付与してください。
• SSH、LaunchAgent、Codex、その他のバックグラウンドセッションでは、Bridge キャプチャを優先してください。--no-remote --capture-engine cg はローカルデバッグ用のオーバーライドであり、アクティブな Aqua セッション外では壁紙だけのピクセルを返すことがあります。
• 保存済みの TCC または Keychain の状態に対して、未署名ビルドまたはアドホックビルドを実行しないでください。

バックグラウンド優先の安全性

• デフォルトでは、ユーザーのフォアグラウンドアプリ、キーボードフォーカス、物理カーソルに触れないようにしてください。正確な --app、--pid、--window-id、または最新のスナップショットターゲットを指定し、Peekaboo のバックグラウンド配信を使用してください。
• コマンドを試しに動作させるためだけに --foreground を追加しないでください。ユーザーがフォアグラウンドでの操作を許可した場合、またはターゲットがバックグラウンド配信を明らかに拒否した場合に限り、追加してください。
• 共有カーソルを使う入力と、ターゲットを指定しないグローバル入力には、明示的なフォアグラウンドモードが必要です。これには move、drag、ターゲットを指定しないスクロールまたはスムーズスクロール、ターゲットを指定しないキーボード入力が含まれます。click --long-press はフォアグラウンド専用です。フォアグラウンドモードはユーザーの操作を妨げる可能性があります。
• バックグラウンドでの入力と貼り付けには、解決可能なアプリまたは PID、対象となるウィンドウが最大 1 つの完全なインベントリ、イベント生成の権限が必要です。生の press にはさらに、正確なウィンドウセレクターまたは最新の正確なウィンドウスナップショットが必要です。アプリまたは PID のみを指定したキーの組み合わせには、明示的なフォアグラウンドモードが必要です。
• ユーザーから依頼された場合、またはターゲットが管理されたテストである場合を除き、クリック、入力、貼り付け、終了、その他の UI の変更を行わないでください。変更後は必ず再観察し、結果が不確かな入力を確認せずに再実行しないでください。

v4 のコマンド名

• インベントリ：app list、window list、screen list を使用します。トップレベルの list コマンドはありません。
• スクリーンショットと UI の検査：ピクセルには see --no-elements、AX のテキストのみには see --tree --no-screenshot を使用します。削除された CLI コマンドの image や inspect-ui は使用しないでください。
• キーの組み合わせ：press を使用します。削除されたコマンド hotkey は使用しないでください。
• 名前付きのアクセシビリティアクション：action を使用します。perform-action は使用しないでください。
• 座標を指定したクリック：click --at x,y を使用します。--coords は使用しないでください。

一般的なコマンド

"$PB" permissions status --all-sources --json
open -gj -a Peekaboo
"$PB" bridge status --verbose --json

"$PB" screen list --json
"$PB" app list --include-hidden --include-background --json
"$PB" window list --app Safari --json

# Screenshot only; observation does not activate the target app.
"$PB" see --no-elements --mode screen --path /tmp/screen.png --json

# Interactive map plus a directly accessible image artifact.
"$PB" see --app Safari --annotate --path /tmp/safari-see.png --json

# AX-only inspection, with no pixel capture or screenshot artifact.
"$PB" see --app Safari --tree --no-screenshot --json

# Use IDs and the snapshot returned by a fresh `see`.
"$PB" click --on "$ELEMENT_ID" --snapshot "$SNAPSHOT_ID" --json
# Generic `action AXPress` requires explicit foreground consent; use the
# dedicated exact-target `click` route above for background button activation.

# Process-targeted background keyboard delivery.
"$PB" type "text" --app TextEdit --json
"$PB" press Return --app TextEdit --window-id 1234 --json
"$PB" paste "text" --app TextEdit --json

"$PB" tools --json
"$PB" tools describe click --json

クリック座標を安全に扱う

スクリーンショットのピクセル座標が、そのままクリック座標になるわけではありません。click --at では論理ポイントを使用します。ターゲットフラグを指定した場合、座標は解決されたウィンドウを基準とします。指定しない場合は、画面全体を基準とする座標です。ターゲットを指定した座標をグローバルな論理座標系で扱うには、--global を追加します。Retina のピクセル座標を変換するときは、screen list --json を使ってディスプレイの境界とスケール係数を確認します。

バックグラウンドで座標クリックを行うには、最新のウィンドウを正確に指定した観測から得た明示的なスナップショットが必要です。まず正規のウィンドウ ID を解決し、そのウィンドウを正確に観測して、ウィンドウ ID と返されたスナップショット ID の両方を使用します。

"$PB" window list --app Safari --json
"$PB" see --app Safari --window-id 12345 --path /tmp/safari.png --json
"$PB" click --window-id 12345 --at 20,40 --snapshot "$SNAPSHOT_ID" --json

Peekaboo は、入力を送信する前に、キャプチャした PID、プロセスの世代、ウィンドウ ID、境界を再検証します。正確なレシートを確立できない場合、推測するのではなく、バックグラウンド入力を失敗させる必要があります。共有ポインターを可視状態で操作することが意図的な場合に限り、--foreground を使用してください。バックグラウンドでの右クリック／ダブルクリックは、正確なルートに送信できますが、効果を検証することはできません。再試行する前に、新しい see を実行してください。

要素を操作するときは、新しい see で取得した ID を優先し、スナップショットを明示的に渡してください。クエリと暗黙的に使用される最新のスナップショットは便利ですが、決定性は低くなります。操作によって UI が変化した後は、古い ID を再利用せず、新しいスナップショットを取得してください。

ワークフロー

1. PB を解決してバージョンを確認し、アプリが保持する TCC が必要な場合は、署名済み GUI ホストをバックグラウンドで起動します。
2. 選択された Bridge ホストを確認し、複数のソース間で権限を比較します。
3. app list または window list を使ってターゲットを解決します。クリーンアップや変更を正確に行う必要がある場合は、範囲の広い名前やタイトルよりも PID／ウィンドウ ID を優先します。
4. フォーカスを奪わずに観測します。スクリーンショットには see --no-elements、要素 ID には通常の see、AX のみの検査には see --tree --no-screenshot を使用します。呼び出し元が画像ファイルを必要とする場合は、--path を渡します。
5. 正確なターゲットと最新のスナップショットを使って、バックグラウンドで操作します。座標入力よりも、action または要素のクリックを優先します。
6. すべての変更を、新しい see または目的に特化した読み取り専用コマンドで検証します。
7. 明示的に許可された共有カーソル／グローバル入力、または確認済みのアプリケーションの制限に対してのみ、明示的な --foreground に切り替えます。モードを黙って昇格させてはいけません。
8. 変更を検知するキャプチャには capture live、動画フレームのサンプリングには capture video、MCP スキーマの確認には tools describe <name>、現在の CLI 構文の確認には <command> --help を使用します。
9. sips -g pixelWidth -g pixelHeight <path> を使って画像アーティファクトを検証するか、ローカルで表示します。

信頼できる情報源：~/Projects/peekaboo/docs/commands/ と、選択されたバイナリの --help 出力です。