terminal-mac — Claude Code skill: what it does, how to install
The terminal-mac Claude Code skill controls a separate virtual macOS with screenshots, clicks, and keyboard input. It runs GUI tasks in a Mac environment apart from the user's desktop.
MIT ★ 2,917 updated 2026-11-10
/plugin marketplace add govijr/terminal-mac
/plugin install terminal-mac@terminal-macWhat terminal-mac does
terminal-mac operates a macOS virtual machine by capturing its screen and sending clicks, keystrokes, and text. All interaction stays inside the guest system, away from the user's desktop. This lets an agent test a Mac app or use a website through a graphical interface.
Control is available through MCP tools or the terminal-mac CLI, whose commands return JSON. The VM runs on Apple silicon. If it has not been created, terminal-mac up NAME downloads macOS from Apple, and the user handles first-time setup. The agent must pause and ask the user if macOS requests a permission, password, two-factor code, or payment.
What it helps with
- test a Mac app through its graphical interface
- navigate a website inside a virtual macOS session
- enter text and use keyboard shortcuts in a separate system
- keep GUI tasks away from the user's desktop
Example prompts for the agent
- Test whether the app opens in virtual macOS and capture a screenshot.
- Open Safari in the virtual machine and check this page.
- Enter text in the app through virtual macOS without touching my desktop.
How to install terminal-mac
1Plugin marketplace
/plugin marketplace add govijr/terminal-mac/plugin install terminal-mac@terminal-macThis installs the whole terminal-mac plugin with all its skills
2Skills CLI (Vercel)
npx skills add govijr/terminal-mac --skill terminal-mac -a claude-code3Manually: put the files in place
~/.claude/skills/terminal-mac/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/terminal-mac/
1Skills CLI (Vercel)
npx skills add govijr/terminal-mac --skill terminal-mac -a codex2Manually: put the files in place
.agents/skills/terminal-mac/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add govijr/terminal-mac --skill terminal-mac -a cursor2Manually: put the files in place
.cursor/skills/terminal-mac/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install govijr/terminal-mac skills/terminal-mac2Manually: put the files in place
.github/skills/terminal-mac/SKILL.md1Skills CLI (Vercel)
npx skills add govijr/terminal-mac --skill terminal-mac -a gemini-cli2Platform CLI
gemini skills install https://github.com/govijr/terminal-mac --path skills/terminal-macManually: put the files in place
.devin/skills/terminal-mac/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about terminal-mac
How do I install terminal-mac in Claude Code?
For the marketplace method, run these commands in order: /plugin marketplace add govijr/terminal-mac, then /plugin install terminal-mac@terminal-mac.
What does terminal-mac do?
It controls a separate macOS virtual machine through screenshots, clicks, text entry, and keyboard input. The user's desktop remains untouched.
What does terminal-mac need to run?
It needs a macOS virtual machine on Apple silicon. If one does not exist yet, terminal-mac up NAME downloads macOS from Apple and requires the user to complete the initial setup.
Source text
SKILL.md · MIT
--- 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.
© Govijr · MIT · govijr/terminal-mac