GitHub - govijr/terminal-mac: Entire MacOS running in your terminal.

Open original

terminal-mac runs a real macOS guest on Apple silicon using Apple's Virtualization framework, then streams its screen into a terminal and lets AI agents click, type and screenshot it through MCP tools. It is an early release candidate, and live acceptance testing on a clean Mac is still pending.

  • The guest is a fully separate Mac with its own apps, accounts and permissions, so agent actions never touch your host desktop or pointer.
  • Setup is guided rather than unattended: you create the guest user account and grant Screen Recording and Accessibility inside the guest by hand.
  • Releases are self-signed, not notarized, and the VM still consumes host CPU, memory and disk (64 GiB sparse by default).
  • Inline viewing needs Ghostty, Kitty or iTerm2; other terminals fall back to the native VM window.

terminal-mac is a macOS tool that runs a separate, real macOS guest in Apple's Virtualization framework on an Apple silicon Mac, and lets you watch and drive it from a terminal. A bundled helper inside the guest captures the screen and posts input events, while a viewer streams that screen inline using Kitty or iTerm2 graphics (Ghostty works too). The guest is a fully separate Mac with its own apps, files, accounts and permissions, so it doesn't inherit your signed-in sessions. It does cost real host resources: CPU, memory, and a sparse disk that defaults to 64 GiB logical size. Requirements are macOS 14 or later on Apple silicon, plus internet on first run to pull a restore image from Apple (or you can point it at a local .ipsw). Installation is a single curl command that verifies a SHA-256 before installing into ~/.local, with no admin rights and no edits to your shell config. Running `terminal-mac` in an interactive terminal walks you through downloading the image, creating the VM, booting it, and checking the helper. The setup is guided rather than unattended: you complete macOS Setup Assistant yourself, then open TerminalMacGuest.app from the shared tools folder inside the guest and grant Screen Recording and Accessibility there. The host needs neither permission. Releases are self-signed, not notarized, and the author notes that live acceptance on a clean Mac is still pending, so this is an early release candidate and should be treated as such. For agents, the project exposes MCP tools (screenshot, click, drag, scroll, type, key, status) plus a skill that teaches an observe-act-verify loop. It installs into Claude Code as a plugin or via `claude mcp add`, and works with other MCP clients by pasting the output of `terminal-mac mcp --config`. The tools only touch the guest, never your own desktop, and report when the guest sits at a login screen so the agent can ask you to sign in. The viewer is careful about efficiency: the helper streams lossless lz4-compressed frames only when the screen changes, up to 30 fps, and stops 15 seconds after the viewer leaves. Ctrl+G opens a palette for Mac shortcuts that terminals would otherwise swallow, and Ctrl+] detaches the viewer while leaving the VM running.

Ask about this article