README

terminal-mac





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

terminal-mac is an early release candidate for Apple silicon. 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. Agent commands use the same helper without moving the physical Mac's pointer or changing its clipboard.

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. The VM still consumes host CPU, memory and storage.

 Requirements

- Apple silicon Mac, macOS 14 or later.
- No development tools are needed for a prebuilt release. Maintainers need Xcode 16 or later / Swift 6 to build.
- Internet on first run to download macOS directly from Apple, or an existing compatible .ipsw.
- Space for the cached restore image and a growing VM disk (64 GiB logical size by default).
- Ghostty, Kitty or iTerm2 for the inline viewer. Other terminals can use the native VM window and agent CLI. tmux passthrough and automatic terminal splits are not implemented.

 Install and run

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


The installer downloads the latest release and verifies its SHA-256 before installing. You can also extract a release ZIP and run bash install.sh from it.

The installer places one launcher in ~/.local/bin and the bundled runtime under ~/.local/lib/terminal-mac. Add ~/.local/bin to your PATH to use simply terminal-mac. It needs no administrator rights and does not edit your shell configuration. bash install.sh --prefix /absolute/path selects another location.

Running terminal-mac in an interactive terminal starts the guided flow. terminal-mac up does the same explicitly. It automatically downloads/caches a compatible Apple restore image, installs a virtual Mac, boots it and checks the guest helper. Later runs reuse the existing VM and reconnect. Unsupported terminals get the native desktop window.

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

 Use with agents

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.

Claude Code, with the MCP server and skill in one plugin:

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


Or add them separately:

sh
claude mcp add terminal-mac -- terminal-mac mcp
terminal-mac skills install                  → ~/.claude/skills/terminal-mac/SKILL.md


Other MCP clients (Cursor, VS Code, Codex, Windsurf…): paste the output of terminal-mac mcp --config into the client's MCP settings. Use terminal-mac mcp NAME for a VM other th