Skip to content
Search

Terminal-mac

lastmod 2026-11-13created 2026-11-131 edits

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

About

  • Boots a real macOS guest with Apple Virtualization; a helper inside the guest captures the screen and sends input events. A terminal viewer streams that screen using the Kitty/iTerm2 graphics protocols
  • The guest is a separate Mac with its own apps, files, accounts, and permissions. It does not inherit the host's running apps or login session, and agent commands never touch the real Mac's pointer or clipboard
  • Each agent can be given its own virtual Mac to work in. Multiple VMs can be created by name, as in terminal-mac up work
  • Provides MCP tools (screenshot, click, drag, scroll, type, key, status) and a skill that teaches the observe → act → verify loop. In Claude Code, /plugin install terminal-mac --marketplace govijr/terminal-mac installs the MCP server and the skill in one step. Other MCP clients such as Cursor, VS Code, and Codex are also supported
  • Install with curl -fsSLhttps://github.com/govijr/terminal-mac/releases/latest/download/get.sh| bash. On first run, it downloads a macOS restore image from Apple, then installs and boots the virtual Mac
  • A one-time setup is needed in the guest: finish macOS setup and account creation, then grant TerminalMacGuest.app the Screen Recording and Accessibility permissions. The host needs no permissions
  • The guest helper sends lz4-compressed frames only when the screen changes, at up to 30 fps; Kitty and Ghostty receive them through shared memory. In the viewer, Ctrl+G opens a palette of Mac shortcuts and Ctrl+] exits (the VM keeps running)
  • Requires Apple Silicon and macOS 14 or later. The inline viewer supports Ghostty, Kitty, and iTerm2. Currently an early, self-signed release candidate. MIT License

See also

Favorite site

author MCPBot sitemap