VM Peek

VM Peek shows the Mac test environment your coding agents use. The included testvm command copies builds there and controls them. VM Peek watches the screen and command history, so you can see what happened.

Install the app and CLI

Connect your GitHub account in Polar after buying, accept the invitation, then open the customer releases.

Download the Mac app ZIP, unzip it, and move VM Peek to Applications. The app needs macOS 15 or later. Running a local Tart VM needs an Apple silicon Mac, even though the viewer app also has an Intel build.

The release provides testvm as a separate executable. With the GitHub CLI signed in to your authorized account, you can install it like this:

mkdir -p ~/Downloads/vm-peek-cli ~/.local/bin
gh release download --repo flaviocodes/vm-peek --pattern testvm --dir ~/Downloads/vm-peek-cli
install -m 755 ~/Downloads/vm-peek-cli/testvm ~/.local/bin/testvm.new
mv ~/.local/bin/testvm.new ~/.local/bin/testvm

Make sure ~/.local/bin is on your shell’s PATH. The temporary file and rename avoid overwriting a script while another command is reading it.

For combined source, clone the repository’s current main branch. The old v1.2.0 automatic source archive predates the CLI merge; current source keeps the CLI in testvm/.

Create the test VM

Install Tart, then run the included setup command:

brew install cirruslabs/cli/tart
testvm setup

Setup downloads and configures a macOS VM. Allow enough disk space for the image and your test apps. The default VM uses four cores and 8 GB of memory. It runs in the background.

The VM is a separate test Mac. Files, accounts and application data inside it are separate from your normal Mac unless you explicitly copy them.

Test your first build

Build your own app normally. Suppose the build produced dist/Recipe Box.app. Open that build in the VM:

testvm note 'Checking the recipe search'
testvm open 'dist/Recipe Box.app'
testvm shot 'Recipe Box'
testvm ui 'Recipe Box'

open copies the app, replaces its running test copy and waits for a window. shot prints a screenshot path. ui lists controls and their coordinates. Use those current coordinates for testvm click, then testvm type or testvm key as needed.

Run testvm help for command syntax. Install the bundled agent skill from the combined source, or copy its instructions into your agent setup. Tell agents to test in the VM so their clicks do not take over your working desktop.

Watch the session

Open VM Peek’s Live view while a test is running. It shows the VM screen and recent agent sessions. The screen refreshes while the window is visible.

The activity list describes commands in plain language. Select a command to inspect its screenshot, command line and output. Search finds earlier commands. The chat and app timelines help answer which agent installed a build and what it checked.

An overlap warning means multiple chats are using the same test environment. Their clicks go to whichever app has focus there. Let one test finish before another starts.

Logs and connection problems

The command log lives in ~/Library/Logs/testvm. It can contain agent prompts, command output and screenshots. Treat it as project data when backing it up or sharing it.

VM Peek uses the same test connection as testvm. If the screen is unavailable, run a simple testvm operation first and read its error. Check that Tart is installed, setup completed and the VM can start. VM Peek observes the VM; it does not perform the test clicks itself.

Download app and CLI updates manually from customer Releases. Replace both when the release instructions call for it.