govijr/terminal-mac

What it does

traceslm is a macOS app that uses Apple's Virtualization framework to run a real macOS guest in a virtual machine. A helper installed inside the guest captures the screen and posts input events, while a host-side CLI streams the guest display into Ghostty, Kitty, or iTerm2 and forwards agent actions without touching the physical Mac's pointer or clipboard. It is aimed at developers who want an isolated Mac desktop for computer-use agents rather than giving an agent control of their own machine.

Agents connect over MCP with tools for screenshot, click, drag, scroll, type, key, and status, plus a skill that describes an observe → act → verify loop. The CLI also exposes lifecycle commands such as up, start, stop, pause, and resume.

Requirements

• Apple silicon Mac running macOS 14 or later.
• Internet on first run to download a compatible macOS restore image from Apple, or an existing .ipsw; allow several GB of cache plus a growing VM disk (64 GiB logical size by default).
• Ghostty, Kitty, or iTerm2 for the inline terminal viewer. Other terminals fall back to the native VM window and agent CLI; tmux passthrough and automatic terminal splits are not implemented.
• Building from source needs Xcode 16+ and Swift 6. Prebuilt releases need no development tools.

Install and run

The release installer downloads the latest release and verifies its SHA-256 before installing. It needs no administrator rights and does not modify shell configuration; it places a launcher in ~/.local/bin and the runtime under ~/.local/lib/terminal-mac. Add ~/.local/bin to PATH.

curl -fsSL https://github.com/govijr/terminal-mac/releases/latest/download/get.sh | bash
terminal-mac up

up downloads and caches a compatible restore image, creates and boots a virtual Mac, and waits for the guest helper. The first boot opens the VM window for macOS Setup Assistant; create a guest account there. Then, inside the guest, open Finder → /Volumes/My Shared Files/tools → TerminalMacGuest.app once. The helper installs itself, and its buttons open the guest's System Settings so you can grant Screen Recording and Accessibility. Reopen it if macOS asks. The host needs neither permission. Once both are granted, the CLI continues to the terminal desktop automatically.

To use it from Claude Code:

/plugin install terminal-mac --marketplace govijr/terminal-mac

Or register the MCP server and skill separately:

claude mcp add terminal-mac -- terminal-mac mcp
terminal-mac skills install

Other MCP clients can use the output of terminal-mac mcp --config; terminal-mac mcp NAME targets a VM other than default. Agents with a skills folder can run terminal-mac skills install --dir PATH, and the agent documentation describes the command interface.

Terminal viewer and agent control

In the viewer, typing, clicks, dragging, scrolling, arrows, and common control keys are forwarded to the guest. Ctrl+G opens a palette of Mac shortcuts because terminals keep ⌘ for themselves, and Ctrl+] exits the viewer while the VM keeps running. The guest helper streams frames only when the screen changes, at up to 30 fps, and stops the stream 15 seconds after the viewer leaves. Kitty and Ghostty receive frames through shared memory.

Agents drive the guest through the helper, for example:

terminal-mac action default screenshot --output /tmp/guest.png
terminal-mac action default click 640 400
terminal-mac action default type 'Hello from the agent'

Commands return JSON and a nonzero exit status on failure. Screenshots return a local host PNG path; coordinates start at the top-left and use guest display points. snapshot is currently a screenshot alias, not an accessibility-tree snapshot.

Constraints and isolation

• The guest is a separate Mac with its own apps, files, accounts, and permissions. It does not inherit host apps or signed-in sessions, but the VM still consumes host CPU, memory, and storage.
• Default NAT networking lets the guest reach the internet and possibly services on the host or local network. This is not a network-isolated environment; --offline removes the guest network device at the cost of some setup workflows that need networking.
• Only two shares are exposed: a read/write control mailbox and a read-only tools folder. Host home, project folders, clipboard, microphone, and camera are not attached. The helper refuses to run unless hw.model starts with VirtualMac, but that is a guard against accidental host execution, not hardware attestation.
• Guest automation needs the guest logged in, the helper running, and Screen Recording plus Accessibility granted inside the guest. These grants are interactive setup.
• Releases are self-signed without Apple notarization, and live guest acceptance on a clean Mac is still pending according to the README. The project describes itself as an early release candidate.
• At the time of writing, VM cloning, rollback checkpoints, accessibility snapshots, fully unattended guest setup, terminal splits, and tmux transport are listed as future work.

HotRepo's take

traceslm appears on HotRepo's new-project list for 2026-11-04 with 268 stars and 20 forks gained. The collected hourly samples show the count rising from 115 to 268 between 21:45 and 00:45 UTC on 2026-11-03, a steep early ramp. Against the project's own early-release caveat, that reflects initial attention rather than proven guest acceptance. The README is unusually specific about the isolation boundary, the mailbox defenses, and the pending clean-Mac validation, which is the right framing for a tool that hands an agent control of a separate Mac.