govijr/terminal-mac

Claims below include README evidence. A matching quote or worker agreement does not establish that a claim is correct. Category majority among 2 workers. Version 1.

terminal-mac is a CLI tool that runs a separate macOS desktop in a virtual machine for computer-use agents, viewed and controlled from a terminal.

A separate macOS desktop for computer-use agents, viewed and controlled from a terminal.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Provides a separate macOS desktop environment for computer-use agents, allowing them to view and control the system from a terminal without affecting the host machine.

A separate macOS desktop for computer-use agents, viewed and controlled from a terminal.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Uses Apple Virtualization to run a real macOS guest with a bundled helper that captures the screen and posts input events, streaming the display to a terminal viewer via Kitty or iTerm2 graphics.

Apple Virtualization runs a real macOS guest. A bundled helper inside that guest captures its screen and posts input events. A terminal viewer streams that screen using Kitty or iTerm2 graphics.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Provides MCP tools for computer use including screenshot, click, drag, scroll, type, key, and status, along with a skill for the observe-act-verify loop.

terminal-mac gives agents computer use in a separate virtual Mac, through MCP tools (screenshot, click, drag, scroll, type, key, status) and a skill that teaches the observe → act → verify loop.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Runs a separate macOS guest with its own apps, files, accounts, and permissions, isolated from the host's running apps and sessions.

The guest is a separate Mac: it has its own apps, files, accounts and permissions. It does not inherit your running host apps or signed-in sessions.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Streams screen updates using ScreenCaptureKit, sending frames only when the screen changes at up to 30 fps as lossless lz4-compressed pixels.

The guest helper keeps a ScreenCaptureKit stream open while a viewer is watching. It sends a frame only when the screen changes (up to 30 fps), already sized to the pixels the terminal draws, as lossless lz4-compressed pixels.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Uses a 2x HiDPI display by default (e.g., 2560x1600 pixels at 220 ppi) to keep text sharp on Retina terminals.

New VMs use a 2x HiDPI display (for example 2560×1600 pixels at 220 ppi for the default 1280×800 points), so text stays sharp on Retina terminals.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Supports interactive input including typing, various clicks, dragging, scrolling, arrows, and common control keys.

The viewer supports typing, left/right clicks, double and triple clicks, dragging, scrolling, arrows and common control keys.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Agent commands return JSON and a nonzero exit status on failure, with screenshots returning a local host PNG path.

Commands return JSON and a nonzero exit status on failure. Screenshots return a local host PNG path.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Includes a safety check where the helper refuses to run unless the hardware model starts with VirtualMac to prevent accidental host execution.

The helper refuses to run unless hw.model starts with VirtualMac. That check prevents accidental host execution; it is not hardware attestation or a defense against a compromised host.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Uses a secure flat mailbox for host-guest communication that rejects symlinks, hardlinks, and nonregular files, bounds message sizes, and expires pending actions.

There is no remote-control network listener. The flat mailbox pins its directory, rejects symlinks, hardlinks and nonregular files on reads, bounds message sizes, checks request IDs, and expires pending actions.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

The guest helper can self-update within 30 seconds of a newer build appearing in the shared tools folder.

From build 4 on, the guest helper updates itself: within 30 seconds of a newer build appearing in the shared tools folder, it installs that build and relaunches.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Allows customization of VM resources including CPUs, memory, disk size, and display dimensions via command-line arguments.

Customize a new VM with --cpus 4 --memory 4 --disk 64 --width 1280 --height 800 (width and height are in points; add --standard for a 1x display).

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Provides a separate macOS desktop for computer-use agents, allowing them to be viewed and controlled directly from a terminal interface.

A separate macOS desktop for computer-use agents, viewed and controlled from a terminal.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Runs a separate virtual Mac with its own apps, files, accounts, and permissions, ensuring no inheritance of host apps or signed-in sessions.

The guest is a separate Mac: it has its own apps, files, accounts and permissions. It does not inherit your running host apps or signed-in sessions.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Enables agents to use a separate virtual Mac via MCP tools like screenshot, click, drag, scroll, type, key, and status, teaching an observe-act-verify loop.

terminal-mac gives agents computer use in a separate virtual Mac, through MCP tools (screenshot, click, drag, scroll, type, key, status) and a skill that teaches the observe → act → verify loop.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Supports typing, left/right clicks, double/triple clicks, dragging, scrolling, arrows, and common control keys within the terminal viewer.

The viewer supports typing, left/right clicks, double and triple clicks, dragging, scrolling, arrows and common control keys.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Keeps a ScreenCaptureKit stream open, sending frames only when the screen changes up to 30 fps, sized for the terminal and compressed losslessly with lz4.

The guest helper keeps a ScreenCaptureKit stream open while a viewer is watching. It sends a frame only when the screen changes (up to 30 fps), already sized to the pixels the terminal draws, as lossless lz4-compressed pixels.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Uses macOS virtio-fs for the automounted volume; lacks a fallback guest transport if the volume is absent.

The automounted volume is supplied by macOS virtio-fs. If it is absent, check the guest's macOS version and the VM log; this prototype has no fallback guest transport.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

New VMs use a 2x HiDPI display to ensure text stays sharp on Retina terminals, configurable via display options.

New VMs use a 2x HiDPI display (for example 2560×1600 pixels at 220 ppi for the default 1280×800 points), so text stays sharp on Retina terminals.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Requires no host privacy permissions; once guest Screen Recording and Accessibility permissions are granted, the CLI automatically continues to the terminal desktop.

The host needs neither privacy permission. Once both guest permissions are ready, the CLI automatically continues to the terminal desktop.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

The guest helper automatically updates itself within 30 seconds of a newer build appearing in the shared tools folder and relaunches.

The guest helper updates itself: within 30 seconds of a newer build appearing in the shared tools folder, it installs that build and relaunches.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Commands return JSON and a nonzero exit status on failure, while screenshots return a local host PNG path.

Commands return JSON and a nonzero exit status on failure. Screenshots return a local host PNG path.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Has no remote-control network listener; uses a flat mailbox that rejects symlinks, hardlinks, and nonregular files, bounding message sizes and checking request IDs.

There is no remote-control network listener. The flat mailbox pins its directory, rejects symlinks, hardlinks and nonregular files on reads, bounds message sizes, checks request IDs, and expires pending actions.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Default NAT networking permits guest internet access and may reach host or local network services; it is not a network-isolated or hardened hostile-code environment.

Default NAT networking permits guest internet access and may reach services on the host or local network. This is not a network-isolated or hardened hostile-code environment.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: Requires an Apple silicon Mac running macOS 14 or later.

Apple silicon Mac, macOS 14 or later.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: Requires space for the cached restore image and a growing VM disk, with a default logical size of 64 GiB.

Space for the cached restore image and a growing VM disk (64 GiB logical size by default).

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: Releases are self-signed without Apple notarization, and live guest acceptance on a clean Mac is still pending.

Releases are self-signed (no Apple notarization), which the curl installer doesn't need. Live guest acceptance on a clean Mac is still pending.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: The initial setup is guided and requires manual interaction, not an unattended guest installation.

This is guided setup, not an unattended guest installation.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: Default NAT networking allows guest internet access and is not a network-isolated or hardened hostile-code environment.

Default NAT networking permits guest internet access and may reach services on the host or local network. This is not a network-isolated or hardened hostile-code environment.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: VM cloning, rollback checkpoints, accessibility snapshots, fully unattended setup, terminal splits, and tmux transport are not yet implemented.

VM cloning, rollback checkpoints, accessibility snapshots, fully unattended guest setup, terminal splits and tmux transport remain future work.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: tmux passthrough and automatic terminal splits are not implemented.

tmux passthrough and automatic terminal splits are not implemented.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: The native Virtualization framework does not render a Mac into a terminal or offer an agent input API; this project supplies the guest transport and terminal presentation layers.

The native Virtualization framework does not itself render a Mac into a terminal or offer an agent input API; this project supplies the guest transport and terminal presentation layers.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: This is guided setup, not an unattended guest installation; it targets macOS 26 SDK APIs and does not implement the newer macOS 27 automatic account provisioning flow.

This is guided setup, not an unattended guest installation. Apple documents automatic account provisioning for macOS 27 guests; this build targets the APIs available in the installed macOS 26 SDK and does not implement that newer flow.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: Interrupted or failed installations leave directories and installed: false; they are never silently overwritten, requiring manual cleanup to retry.

An interrupted or failed installation leaves its directory and installed: false for diagnosis. It is never silently overwritten. To retry, ensure no installer/VM is running, move that incomplete directory aside, then create the VM again.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: There is deliberately no destructive VM-delete command yet.

There is deliberately no destructive VM-delete command yet.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

Limitation: A logged-out/locked guest, missing helper, denied guest permissions, or paused VM prevents normal computer use; TCC grants are interactive and not bypassed by the CLI.

A logged-out/locked guest, missing helper, denied guest permissions, or paused VM prevents normal computer use. TCC grants are interactive guest setup, not bypassed by the CLI.

Quote matched the README or GitHub description at extraction. Same claim and quote from 1 worker(s). Interpretation not reviewed by a maintainer.

cli · other