# terminal-mac Adopt this skill: https://proskills.md/skills/other/govijr-terminal-mac-skills-terminal-mac Page: https://proskills.md/skills/other/govijr-terminal-mac-skills-terminal-mac This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required. ## File: skills/terminal-mac/SKILL.md size: 2853 sha: 67153ef2c033dfe57b1dd9f7fbacdd9c389892b5 upstream: https://github.com/govijr/terminal-mac/blob/main/skills/terminal-mac/SKILL.md ````text --- name: terminal-mac description: Operate a separate virtual Mac (macOS VM) with screenshots, clicks, typing and shortcuts, without touching the user's own desktop. Use when a task needs a real macOS GUI — testing a Mac app, using a website or desktop app, or any computer-use task the user wants sandboxed. --- # terminal-mac `terminal-mac` runs a real macOS guest on Apple silicon. A helper inside the guest captures its screen and posts input, so everything you do happens in the VM. It never controls the user's own desktop. ## Prefer the MCP tools If tools named `screenshot`, `click`, `type`, `key` and so on from the `terminal-mac` MCP server are available, use them: 1. `status`: the VM is running and both guest permissions are `true`. 2. `screenshot`: every x/y you pass to other tools is a pixel in this image (top-left origin). 3. Act with `click` (`clicks: 2` double-clicks, `button: "right"`), `move`, `drag`, `scroll` (negative `dy` scrolls down), `type` (literal text) or `key` (`return`, `tab`, `escape`, `cmd+space`, `cmd+c`, `cmd+shift+4`…). 4. Look again: pass `screenshot: true` to an action, or call `screenshot`, before deciding the next step. Opening an app: `key cmd+space`, `type "Safari"`, `key return`. Prefer keyboard shortcuts over hunting for small targets. ## Without MCP: the CLI Every command prints JSON and exits nonzero on failure. `NAME` defaults to `default`. ```bash terminal-mac status NAME # stopped → terminal-mac start NAME terminal-mac action NAME status terminal-mac action NAME screenshot --output /tmp/guest.png # then view the PNG terminal-mac action NAME click X Y [--double] [--button right] terminal-mac action NAME move X Y terminal-mac action NAME drag X Y X2 Y2 terminal-mac action NAME type 'literal text' terminal-mac action NAME key cmd+space terminal-mac action NAME scroll --dy -300 --x X --y Y ``` Text is sent as Unicode keyboard events, not through the clipboard. No shell-execution action exists. ## When to stop and ask the user - The guest is at its login screen, or the helper is not running (tools report "no logged-in session"): ask the user to sign in, for example `terminal-mac view NAME` then Ctrl+O. Automatic login in the guest avoids this on later boots. - A macOS permission prompt, password, two-factor code or payment appears in the guest. - The VM does not exist: `terminal-mac up NAME` downloads macOS from Apple (several GB) and needs the user for first-time setup. ## Safety - Do not run `terminal-mac guest` on the host, and never fall back to host screenshots or host input tools. - Apps, files and accounts inside the VM are separate from the user's Mac. Do not move secrets into it unless the user asks. - `stop` requests shutdown; `stop --force` can lose guest work, so use it only when a normal shutdown cannot complete. ```` ## File: README.md upstream: https://github.com/govijr/terminal-mac/blob/main/README.md ````text # terminal-mac [![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/govijr) Buy Me A Coffee 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 than `default`. **Any agent with a skills folder:** `terminal-mac skills install --dir PATH`, or `npx skills add govijr/terminal-mac --skill terminal-mac`. In an `AGENTS.md`, a line like "Before using the virtual Mac, run `terminal-mac skills get`" gives the agent instructions that match the installed version. The tools only drive the guest helper. They never touch your own desktop. When the guest is at its login screen, they say so, so the agent can ask you to sign in. ## One-time guest setup The first run opens the virtual Mac's window. Complete macOS setup and create its user account. Inside the guest, open Finder → `/Volumes/My Shared Files/tools` → `TerminalMacGuest.app` once. The helper installs itself in the guest's `~/Applications`, launches that installed copy and registers for future guest logins, subject to macOS approval. Use its two buttons to grant **Screen Recording** and **Accessibility** inside the guest. Reopen it if macOS asks. If needed, its **Guest Login Items** button opens the startup setting. The host needs neither privacy permission. Once both guest permissions are ready, the CLI automatically continues to the terminal desktop. 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. See [Apple's provisioning documentation](https://developer.apple.com/documentation/virtualization/vzmacguestprovisioningoptions). ```sh terminal-mac up work # another virtual Mac terminal-mac up --ipsw /path/mac.ipsw # use a local image terminal-mac up --no-view # wait for agent readiness, then return JSON terminal-mac up --detach # install/boot, return without waiting for guest setup terminal-mac up --plan # show steps without network access or disk changes ``` The first download may take time; packaging cannot eliminate downloading and installing macOS. The image cache is reused, and URLSession resume data is retained after recoverable network failures. A hard process kill may require the current download to restart. An incomplete installation with recorded hardware can be retried by `up` using a compatible restore image; an already installed VM is never reinstalled by `up`. ## Build from source ```sh bash scripts/build.sh ./dist/terminal-mac doctor ``` The build creates `dist/TerminalMac.app`, including `TerminalMacGuest.app`, and the `dist/terminal-mac` launcher. Virtualization needs the host executable's `com.apple.security.virtualization` entitlement; use the packaged launcher instead of the unsigned Swift build product. It is signed with the self-signed "Govijr Code Signing" identity when your keychain has it (`bash scripts/create-signing-identity.sh` makes one), and ad-hoc otherwise. A stable identity keeps the guest helper's permissions across rebuilds; ad-hoc builds need them granted again. [RELEASING.md](RELEASING.md) covers signing and publishing. ## Create your first Mac ```sh # Show the URL and version without downloading anything: ./dist/terminal-mac image # Explicitly download Apple's latest supported restore image (several GB): ./dist/terminal-mac image --output /tmp/RestoreImage.ipsw # Install macOS. The disk is sparse, and the IPSW is not copied into the VM bundle. ./dist/terminal-mac create default --ipsw /tmp/RestoreImage.ipsw ./dist/terminal-mac start default --window ``` Complete macOS Setup Assistant in the VM window and create a guest account. Inside the guest: 1. Open Finder → `/Volumes/My Shared Files/tools`. 2. Open `TerminalMacGuest.app`. It installs itself to the guest's `~/Applications` and opens the installed copy. 3. Use the helper's buttons to grant **Screen Recording** and **Accessibility** in the guest's System Settings. Reopen the helper if macOS asks. The host does not need either permission. 4. Keep the guest logged in and the helper running. It registers itself for guest login; approve that setting if macOS requests it. On the host: ```sh ./dist/terminal-mac action default status ./dist/terminal-mac hide default ./dist/terminal-mac view default ``` The viewer supports typing, left/right clicks, double and triple clicks, dragging, scrolling, arrows and common control keys. **Ctrl+G** opens a palette of Mac shortcuts (Spotlight, Mission Control, copy/p ````