Community画像github.com

steipete/vm-lab

Parallels macOS VMラボ:GUI自動化、Peekaboo、TCC、Ghostty。

vm-lab とは?

このスキルは、クリーンなmacOS VM内でGUI自動化ツールのテストと検証を行うための包括的なVM Lab環境を提供します。TCCプロンプト、スクリーンショットキャプチャ、クリック、タイピング、パフォーマンステストなど、Peekabooのようなツールの「双方向検証」をゲスト内部で実行し、その結果をホスト側のParallelsスクリーンショットと観察で独立して検証する、というコアアイデアに基づいています。このスキルは、Claude Codeや他のAIエージェントが、VMディスカバリ、ゲストコマンド実行、Ghosttyターミナル経由のコマンド送信、既知の問題(クリップボードAPI障害、キー入力のレイアウト依存性など)の回避方法など、構造化された安全なワークフローに従うことを支援します。各GUIアクションは、ツール自体の出力と外部の `prlctl capture` の2つの独立したシグナルで検証され、高い信頼性を実現します。安全ルールでは、VMスナップショットを消耗品として扱い、ホスト状態の変更を避け、シークレットを出力しないことを徹底します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/vm-lab

Installed? Explore more 画像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

VM Lab

タスクにクリーンなmacOS VMが必要な場合に使用します。GUI自動化、TCCプロンプト、スクリーンショットキャプチャ、クリック、タイピング、パフォーマンス、またはPeekabooライクなツールの「双方向検証」をテストします。

コアアイデア:テスト対象のツールをゲスト内で実行しますが、Parallelsのスクリーンショットとホスト側の観察を使用して、ゲストの外部から検証します。自分が所有していないアプリは閉じないでください。

安全ルール

  • VMスナップショットは消耗品として扱い、ホストは消耗品として扱わないでください。
  • シークレットを出力しないでください。op が必要な場合は、1Passwordスキルに従い、tmux 内でのみ実行してください。
  • 自分で作成した新しいアプリウィンドウ(TextEdit、ローカルHTMLテストページ、または小さなテストアプリ)を優先してください。
  • /tmp 下の一時的なスクリーンショット以外、ホストの状態を変更しないでください。
  • VM内のgitリポジトリには、HTTPSリモートと通常のブランチ規律を使用してください。

VMディスカバリ

VMを一覧表示:

prlctl list --all

VMのステータス/IPを取得:

prlctl list --info "macOS Tahoe"

Peterとしてゲストコマンドを実行:

prlctl exec "macOS Tahoe" \
  'sudo -u steipete -H /bin/zsh -lc '\''source ~/.zprofile 2>/dev/null || true; uname -a'\'''

独立したホスト側スクリーンショットをキャプチャ:

prlctl capture "macOS Tahoe" --file /tmp/vm-reference.png
sips -g pixelWidth -g pixelHeight /tmp/vm-reference.png

TCC / GUI属性

macOSの画面収録とアクセシビリティでは、責任プロセスが重要です。

  • prlctl exec はヘッドレスであり、有用な画面収録属性を生成できない場合があります。
  • 画面収録が関係する場合は、ゲスト内の可視のターミナルアプリからテストコマンドを起動してください。
  • Ghosttyがインストールされていれば、GUIターミナルとして機能します。
  • 最初のキャプチャが失敗した後は、「システム設定 > プライバシーとセキュリティ > 画面収録とシステムオーディオ収録」を確認してください。
  • prlctl exec 経由で実行される permissions status は、Ghosttyが許可された後でも画面収録がfalseと報告する場合があります。Ghosttyからキャプチャを再実行して画面収録を検証してください。

画面収録ペインを開く:

prlctl exec "macOS Tahoe" \
  'sudo -u steipete -H open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"'

Ghosttyを開く:

prlctl exec "macOS Tahoe" 'sudo -u steipete -H open -a Ghostty'

Ghosttyを通じてコマンドを実行する

最適なパス:prlctl exec でゲストスクリプトを作成し、Ghosttyを開いてフォーカスし、短いランチャーパスのみを可視のターミナルに入力します。

ゲストスクリプトのパターン:

prlctl exec "macOS Tahoe" 'sudo -u steipete -H /bin/zsh -lc '\''cat > /tmp/run-vm-lab.zsh <<EOF
#!/bin/zsh
source ~/.zprofile 2>/dev/null || true
cd ~/Projects/Peekaboo || exit 1
Apps/CLI/.build/debug/peekaboo image --path /tmp/peekaboo-vm.png --json
rc=$?
echo "EXIT:$rc"
[ -f /tmp/peekaboo-vm.png ] && sips -g pixelWidth -g pixelHeight /tmp/peekaboo-vm.png
echo "Press return to close..."
read _
exit $rc
EOF
chmod +x /tmp/run-vm-lab.zsh
ln -sf /tmp/run-vm-lab.zsh /tmp/r
open -a Ghostty'\'''

次に、ランチャーをGhosttyのホームディレクトリにリンクし、scripts/parallels_type.py で ./r と入力します。これにより、Parallelsのキーインジェクションにおける信頼性の低いパス文字を回避できます。

prlctl exec "macOS Tahoe" \
  "sudo -u steipete -H /bin/zsh -lc 'ln -sf /tmp/run-vm-lab.zsh ~/r'"
python3 skills/vm-lab/scripts/parallels_type.py "macOS Tahoe" $'./r\n'

長いコマンドのタイピングは避けてください。Parallelsのキーインジェクションは独自のキーコードテーブルを使用し、レイアウトの影響を受けやすい可能性があります。

既知の落とし穴

  • macOSのクリップボードAPIは prlctl exec から失敗する可能性があります。pbcopy、AppleScriptクリップボード、Peekabooのペーストはすべてヘッドレスゲストコンテキストで失敗する可能性があります。
  • open -na Ghostty.app --args -e ... は、macOS上で既存のGhosttyウィンドウをフォーカスするだけの場合があります。コマンドが実行されるとは想定しないでください。
  • prlctl exec はゲストシェルを通じてargvを再結合する場合があります。複雑なペイロードの場合は、完全にシェルクォートされたコマンド文字列を1つ渡すか、小さなPythonライターでファイルを作成してください。
  • Parallelsの send-key-event --key は、macOSの仮想キーコードではなく、Parallelsのキー値を使用します。
  • 通常のタイピングでは、 --event なしで prlctl send-key-event <vm> --key <key> を送信してください。明示的な press/release は繰り返したり固着したりする可能性があります。Returnは例外で、pressの後にreleaseを使用してください。
  • 多くの別々の send-key-event プロセスよりも、1つの prlctl send-key-event --json バッチを優先してください。個別の呼び出しはフォーカス/レイテンシの影響でずれる可能性があります。
  • PRL_KEY_ENTER = 36、PRL_KEY_SLASH = 61、PRL_KEY_R = 27、PRL_KEY_T = 28、PRL_KEY_M = 58、PRL_KEY_P = 33 を使用してください。
  • キーストロークが文字化けを生成する場合は、Returnを送信して行をクリアし、より短いランチャーを作成してから再試行してください。
  • Peekabooの権限プローブが画面収録不足でハングし、SWIFT TASK CONTINUATION MISUSE を出力する場合は、製品バグとして記録してください。VMハーネスと混同しないでください。

双方向検証

各GUIアクションについて、2つの独立したシグナルで検証します:

  • テスト対象ツールの出力:JSON、スクリーンショットファイル、AX結果、またはアプリの状態。
  • 外部検証器:prlctl capture、ホスト側の画像検査、ゲスト内のファイル内容、またはプロセス/ウィンドウの状態。

例:

  • スクリーンショット:Peekabooの画像の寸法/内容を prlctl capture と比較します。
  • クリック:Peekabooを使用してテストボタンをクリックし、ゲストアプリの状態とホストのスクリーンショットの両方を検証します。
  • タイピング:Peekabooを使用して制御されたテキストフィールドに入力し、AX値とホストのスクリーンショットの両方を検証します。
  • パフォーマンス:コマンドを /usr/bin/time -p でラップします。コールド/ウォームランを繰り返します。出力は /tmp に保持します。

Peekaboo VMベースライン

ゲスト内:

cd ~/Projects/Peekaboo
git pull --recurse-submodules
swift build --package-path Apps/CLI
Apps/CLI/.build/debug/peekaboo --version
Apps/CLI/.build/debug/peekaboo permissions status --json

ホスト側のリファレンスキャプチャ:

prlctl capture "macOS Tahoe" --file /tmp/vm-prlctl-reference.png

Ghosttyを通じたゲスト側のPeekabooキャプチャ:

/tmp/r

比較:

prlctl exec "macOS Tahoe" \
  'sudo -u steipete -H /bin/zsh -lc '\''sips -g pixelWidth -g pixelHeight /tmp/peekaboo-vm.png'\'''
sips -g pixelWidth -g pixelHeight /tmp/vm-prlctl-reference.png

報告

引き継ぐ際は、以下のみを含めてください:

  • VM名とOSビルド。
  • テストしたリポジトリのコミット。
  • 権限の状態。
  • 成功/失敗したコマンド。
  • 独立した検証器の結果。
  • 発見された製品バグ。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

関連スキル