Skip to content
Get packs

VM Lab for macOS GUI Testing

Drives a Parallels macOS VM to test GUI automation tools like Peekaboo with independent verification

Source Download skill
Repository
steipete/agent-scripts
Stars
7,433
Licence
MIT
Files
4 files

What it does

This skill teaches an AI agent how to use a clean, disposable macOS virtual machine running in Parallels to test software that clicks, types, and captures the screen. The agent runs the tool under test inside the virtual machine, then checks the result from outside using Parallels screenshots and host-side observations. It also includes safety rules that protect other virtual machines and snapshots, and it avoids closing apps the user does not own.

Great for

  • Developers building or testing macOS GUI automation or screenshot tools such as Peekaboo
  • Engineers validating macOS permission prompts (TCC), Screen Recording, and Accessibility behavior in a clean VM
  • Maintainers who need repeatable cold/warm performance runs of macOS command-line tools inside a guest

Skip it if

  • Users without Parallels Desktop and a prepared macOS guest VM, since the workflow depends on prlctl and a specific VM setup
  • Anyone wanting to run it on production machines or VMs they do not own, because it issues reset and revert-style operations and types keystrokes into live guests
  • Teams needing Windows or Linux VM testing, since the skill is specific to macOS guests

Try asking

  • “Test whether a Peekaboo screenshot command works inside a clean macOS Tahoe VM and compare it with a Parallels capture”
  • “Validate that a test button click in a controlled app updates both the guest app state and a host screenshot”
  • “Check Screen Recording permission behaviour for a CLI tool by running it from Ghostty in the guest”
  • “Run cold and warm timing benchmarks of a macOS build inside the VM and save outputs to /tmp”
Step-by-step guide: how to use VM Lab for macOS GUI TestingInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 4 original files, the MIT licence and an attribution note.

    vm-lab.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip vm-lab.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip vm-lab.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Confirm the exact task-owned VM UUID and snapshot before any guest action, since the skill's example names are not permission to operate on an existing VM
  • Prefer short launcher scripts typed through scripts/parallels_type.py rather than long typed commands, because Parallels key injection is layout-sensitive
  • Verify every GUI action with two independent signals, such as tool output plus a prlctl capture, rather than trusting one result

What's inside

  • agents/openai.yaml
  • references/bootstrap-diagnostics.md
  • scripts/parallels_type.py
  • SKILL.md

Redistributed unmodified from steipete/agent-scripts under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.