Community이미지github.com

steipete/vm-lab

Parallels macOS VM 실습: GUI 자동화, Peekaboo, TCC, Ghostty.

vm-lab란 무엇인가요?

이 스킬은 Parallels macOS 가상 머신 내에서 GUI 자동화, TCC 프롬프트, 스크린샷 캡처, 클릭, 타이핑 및 Peekaboo와 같은 도구의 '양방향 검증'을 테스트하기 위한 완전한 환경을 제공합니다. 핵심 아이디어는 게스트 내부에서 테스트 중인 도구를 실행하지만, Parallels 스크린샷 및 호스트 측 관찰을 통해 게스트 외부에서 결과를 검증하는 것입니다. 이 접근 방식은 실제 하드웨어 오버헤드 없이 권한 대화 상자, 입력 모니터링 및 시스템 무결성 보호와 같은 macOS 특정 동작을 테스트하는 데 특히 유용합니다. 이 스킬은 Claude Code, Cursor 및 Codex와 같은 AI 에이전트 플랫폼에서 사용할 수 있으며, 게스트 VM, Parallels CLI 명령, Ghostty 터미널 및 Peekaboo 도구와 상호 작용하는 명령줄 지침을 제공합니다. 또한 호스트 상태를 수정하지 않고 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를 다시 결합할 수 있습니다. 복잡한 페이로드의 경우 완전히 셸 인용된 명령 문자열 하나를 전달하거나 작은 Python 작성기로 파일을 만듭니다.
  • Parallels send-key-event --key는 Parallels 키 값을 사용하며 macOS 가상 키 코드를 사용하지 않습니다.
  • 일반 입력의 경우 --event 없이 prlctl send-key-event <vm> --key <key>를 보냅니다. 명시적인 press/release는 반복되거나 고정될 수 있습니다. Return은 예외입니다: press 다음 release를 사용합니다.
  • 많은 개별 send-key-event 프로세스보다 하나의 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 작업에 대해 두 가지 독립적인 신호를 통해 검증합니다:

  • 테스트 중인 도구 출력: 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 빌드.
  • 테스트된 repo 커밋.
  • 권한 상태.
  • 통과/실패한 명령.
  • 독립적인 검증자 결과.
  • 발견된 제품 버그.

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.

관련 스킬