CommunityImagengithub.com

steipete/vm-lab

Laboratorio de macOS VM con Parallels: automatización de GUI, Peekaboo, TCC y Ghostty.

¿Qué es vm-lab?

Este skill proporciona una configuración completa para probar herramientas de automatización de GUI, como Peekaboo, en una máquina virtual limpia de macOS gestionada con Parallels. La idea principal es ejecutar la herramienta bajo prueba dentro de la máquina virtual, pero verificar los resultados desde el anfitrión utilizando capturas de pantalla de Parallels y observaciones externas. Es útil para validar el comportamiento de TCC, la captura de pantalla, los clics, la escritura y el rendimiento en un entorno aislado y desechable. El skill incluye reglas de seguridad, comandos de descubrimiento de la VM, técnicas para manejar la atribución de GUI y TCC, y un método de "validación bidireccional" que compara la salida de la herramienta con una verificación externa independiente para garantizar la precisión.

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

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

VM Lab

Usa esto cuando la tarea requiera una VM limpia de macOS para probar automatización de GUI, solicitudes de TCC, captura de pantallas, clics, escritura, rendimiento o "validación bidireccional" de herramientas similares a Peekaboo.

Idea central: ejecuta la herramienta bajo prueba dentro del invitado, pero verifícala desde fuera del invitado con capturas de pantalla de Parallels y observaciones del anfitrión. No cierres aplicaciones que no sean tuyas.

Reglas de Seguridad

  • Trata la instantánea de la VM como desechable, no el anfitrión.
  • Nunca imprimas secretos. Si se necesita op, sigue el skill de 1Password y ejecútalo solo dentro de tmux.
  • Prefiere ventanas de aplicaciones nuevas que tú mismo crees: TextEdit, una página HTML de prueba local o una pequeña aplicación de prueba.
  • Evita modificar el estado del anfitrión excepto capturas de pantalla temporales en /tmp.
  • Para repositorios git dentro de la VM, usa remotos HTTPS y disciplina normal de ramas.

Descubrimiento de VM

Lista las VMs:

prlctl list --all

Obtén estado/IP de la VM:

prlctl list --info "macOS Tahoe"

Ejecuta comandos en el invitado como Peter:

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

Captura una captura de pantalla independiente del anfitrión:

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

TCC / Atribución de GUI

Para la grabación de pantalla y accesibilidad de macOS, el proceso responsable es importante.

  • prlctl exec es headless y puede fallar al producir una atribución útil de grabación de pantalla.
  • Inicia el comando de prueba desde una aplicación de terminal visible en el invitado cuando esté involucrada la grabación de pantalla.
  • Ghostty funciona como terminal GUI si está instalado.
  • Después de un primer fallo de captura, revisa Configuración del Sistema > Privacidad y Seguridad > Grabación de Pantalla y Audio del Sistema.
  • permissions status ejecutado a través de prlctl exec puede seguir informando que la grabación de pantalla es falsa después de que Ghostty esté permitido; valida la grabación de pantalla volviendo a ejecutar la captura desde Ghostty.

Abre el panel de Grabación de Pantalla:

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

Abre Ghostty:

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

Ejecutando Comandos a Través de Ghostty

Mejor ruta: crea un script invitado con prlctl exec, abre/enfoca Ghostty, luego escribe solo una ruta de lanzador corta en la terminal visible.

Patrón de script invitado:

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 "Presiona retorno para cerrar..."
read _
exit $rc
EOF
chmod +x /tmp/run-vm-lab.zsh
ln -sf /tmp/run-vm-lab.zsh /tmp/r
open -a Ghostty'\'''

Luego vincula el lanzador al directorio personal de Ghostty y escribe ./r con scripts/parallels_type.py. Esto evita caracteres de ruta poco fiables en la inyección de teclas de 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'

Evita escribir comandos largos. La inyección de teclas de Parallels usa su propia tabla de códigos de teclas y puede ser sensible a la disposición.

Problemas Conocidos

  • Las APIs del portapapeles de macOS pueden fallar desde prlctl exec; pbcopy, el portapapeles de AppleScript y el pegado de Peekaboo pueden fallar en el contexto headless del invitado.
  • open -na Ghostty.app --args -e ... puede solo enfocar una ventana existente de Ghostty en macOS; no asumas que ejecuta el comando.
  • prlctl exec puede volver a unir argv a través de un shell invitado; para cargas complejas, pasa una cadena de comando completamente escapada por shell o crea el archivo con un pequeño escritor en Python.
  • send-key-event --key de Parallels usa valores de teclas de Parallels, no códigos de teclas virtuales de macOS.
  • Para escritura normal, envía prlctl send-key-event <vm> --key <key> sin --event; press/release explícitos pueden repetirse o pegarse. Return es una excepción: usa press luego release.
  • Prefiere un lote prlctl send-key-event --json sobre muchos procesos send-key-event separados; las llamadas separadas pueden desviarse bajo enfoque/latencia.
  • Usa PRL_KEY_ENTER = 36, PRL_KEY_SLASH = 61, PRL_KEY_R = 27, PRL_KEY_T = 28, PRL_KEY_M = 58, PRL_KEY_P = 33.
  • Si las pulsaciones producen basura, envía Return para limpiar la línea, crea un lanzador más corto, luego reintenta.
  • Si las sondas de permisos de Peekaboo se cuelgan con grabación de pantalla faltante y emiten SWIFT TASK CONTINUATION MISUSE, regístralo como un error del producto; no lo confundas con el entorno de la VM.

Validación Bidireccional

Para cada acción de GUI, verifica a través de dos señales independientes:

  • Salida de la herramienta bajo prueba: JSON, archivo de captura de pantalla, resultado AX o estado de la aplicación.
  • Verificador externo: prlctl capture, inspección de imagen del anfitrión, contenido de archivo en el invitado o estado de proceso/ventana.

Ejemplos:

  • Captura de pantalla: compara las dimensiones/contenido de la imagen de Peekaboo contra prlctl capture.
  • Clic: usa Peekaboo para hacer clic en un botón de prueba, luego verifica tanto el estado de la aplicación invitada como la captura de pantalla del anfitrión.
  • Escritura: usa Peekaboo para escribir en un campo de texto controlado, luego verifica el valor AX y la captura de pantalla del anfitrión.
  • Rendimiento: envuelve comandos con /usr/bin/time -p; repite ejecuciones en frío/caliente; mantén las salidas en /tmp.

Línea Base de Peekaboo en VM

Dentro del invitado:

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

Captura de referencia del anfitrión:

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

Captura de Peekaboo desde el invitado a través de Ghostty:

/tmp/r

Compara:

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

Informes

Al entregar, incluye solo:

  • Nombre de la VM y versión del sistema operativo.
  • commit del repositorio probado.
  • estado de permisos.
  • comandos que pasaron/fallaron.
  • resultado del verificador independiente.
  • errores del producto descubiertos.

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.

Skills relacionados