Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add govijr/terminal-mac
/plugin install terminal-mac@terminal-mac
Open on GitHub

What 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-mac

This installs the whole terminal-mac plugin with all its skills

2Skills CLI (Vercel)

npx skills add govijr/terminal-mac --skill terminal-mac -a claude-code

3Manually: put the files in place

~/.claude/skills/terminal-mac/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/terminal-mac/

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

Similar skills

SKILL.md skills catalog →

From the same set2

Project sponsors

Companies that keep this analytics open