Peekaboo

Peekaboo は macOS UI オートメーション用の包括的な CLI ツールです。スクリーンキャプチャ・検査、UI 要素の対象化、入力駆動、アプリ・ウインドウ・メニューの管理ができます。すべてのコマンドはスナップショットキャッシュを共有し、--json/-j をサポートしているのでスクリプト化に対応しています。peekaboo または peekaboo <cmd> --help でフラグを確認できます。peekaboo --version ではビルドメタデータを表示します。ヒント：polter peekaboo 経由で実行すると新規ビルドが確保されます。

機能（agent/MCP を除くすべての CLI 機能）

コア

• bridge: Peekaboo Bridge ホスト接続を検査
• capture: ライブキャプチャまたはビデオ取り込み＋フレーム抽出
• clean: スナップショットキャッシュと一時ファイルを削除
• config: 初期化・表示・編集・検証、プロバイダー、モデル、認証情報
• image: スクリーンショットをキャプチャ（スクリーン・ウインドウ・メニューバー領域）
• learn: 完全な agent ガイドとツールカタログを表示
• list: アプリ、ウインドウ、スクリーン、メニューバー、パーミッション
• permissions: スクリーン録画・アクセシビリティステータスを確認
• run: .peekaboo.json スクリプトを実行
• sleep: 指定期間実行を一時停止
• tools: 利用可能なツールをフィルタリング・表示オプション付きで一覧表示

インタラクション

• click: ID・クエリ・座標で対象化、スマートウェイト対応
• drag: 要素・座標・Dock 間でドラッグ＆ドロップ
• hotkey: cmd,shift,t などの修飾キーコンボ
• move: オプションのスムージング付きカーソルポジショニング
• paste: クリップボード設定→貼り付け→復元
• press: リピート対応の特殊キーシーケンス
• scroll: 方向指定スクロール（対象化＋スムーズ）
• swipe: 対象間のジェスチャースタイルドラッグ
• type: テキスト＋制御キー（--clear、遅延対応）

システム

• app: アプリの起動・終了・再起動・非表示・表示・切り替え・一覧表示
• clipboard: クリップボード読み取り・書き込み（テキスト・画像・ファイル）
• dialog: システムダイアログのクリック・入力・ファイル・消去・一覧表示
• dock: Dock アイテムの起動・右クリック・非表示・表示・一覧表示
• menu: アプリケーションメニューとメニューエクストラのクリック・一覧表示
• menubar: ステータスバーアイテムの一覧表示・クリック
• open: アプリ対象化＋JSON ペイロード対応の拡張 open
• space: Space の一覧表示・切り替え・ウインドウ移動
• visualizer: Peekaboo ビジュアルフィードバックアニメーションを実行
• window: ウインドウのクローズ・最小化・最大化・移動・リサイズ・フォーカス・一覧表示

ビジョン

• see: 注釈付き UI マップ、スナップショット ID、オプション分析

グローバルランタイムフラグ

• --json/-j, --verbose/-v, --log-level <level>
• --no-remote, --bridge-socket <path>

クイックスタート（基本的な流れ）

peekaboo permissions
peekaboo list apps --json
peekaboo see --annotate --path /tmp/peekaboo-see.png
peekaboo click --on B1
peekaboo type "Hello" --return

一般的な対象化パラメーター（ほとんどのインタラクションコマンド）

• アプリ・ウインドウ: --app, --pid, --window-title, --window-id, --window-index
• スナップショット対象化: --snapshot（see からの ID、デフォルトは最新）
• 要素・座標: --on/--id（要素 ID）、--coords x,y
• フォーカス制御: --no-auto-focus, --space-switch, --bring-to-current-space, --focus-timeout-seconds, --focus-retry-count

一般的なキャプチャパラメーター

• 出力: --path, --format png|jpg, --retina
• 対象化: --mode screen|window|frontmost, --screen-index, --window-title, --window-id
• 分析: --analyze "prompt", --annotate
• キャプチャエンジン: --capture-engine auto|classic|cg|modern|sckit

一般的なモーション・タイピングパラメーター

• タイミング: --duration（ドラッグ・スワイプ）、--steps, --delay（タイプ・スクロール・プレス）
• 人間らしい動き: --profile human|linear, --wpm（タイピング）
• スクロール: --direction up|down|left|right, --amount <ticks>, --smooth

例

See -> click -> type（最も信頼性の高い流れ）

peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png
peekaboo click --on B3 --app Safari
peekaboo type "user@example.com" --app Safari
peekaboo press tab --count 1 --app Safari
peekaboo type "supersecret" --app Safari --return

ウインドウ ID で対象化

peekaboo list windows --app "Visual Studio Code" --json
peekaboo click --window-id 12345 --coords 120,160
peekaboo type "Hello from Peekaboo" --window-id 12345

スクリーンショットキャプチャ＋分析

peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png
peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"
peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"

ライブキャプチャ（モーション対応）

peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \
  --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture

アプリ・ウインドウ管理

peekaboo app launch "Safari" --open https://example.com
peekaboo window focus --app Safari --window-title "Example"
peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800
peekaboo app quit --app Safari

メニュー、メニューバー、Dock

peekaboo menu click --app Safari --item "New Window"
peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"
peekaboo menu click-extra --title "WiFi"
peekaboo dock launch Safari
peekaboo menubar list --json

マウス・ジェスチャー入力

peekaboo move 500,300 --smooth
peekaboo drag --from B1 --to T2
peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800
peekaboo scroll --direction down --amount 6 --smooth

キーボード入力

peekaboo hotkey --keys "cmd,shift,t"
peekaboo press escape
peekaboo type "Line 1\nLine 2" --delay 10

注

• スクリーン録画とアクセシビリティのパーミッションが必要です。
• クリック前に peekaboo see --annotate を使用して対象を特定してください。