Skip to content
Skills Library
AI & agents · Automation

agent-mac

/agent-mac

Use when you need to run, click through, screenshot or record a Mac app's UI and the host's screen, mouse or keyboard belong to a person, the host may be locked, or a person wants to watch or take over the run in a browser.

Repository
agent-mac ↗
Licence
MIT
Last repository change
11.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when you need to run, click through, screenshot or record a Mac app's UI and the host's screen, mouse or keyboard belong to a person, the host may be locked, or a person wants to watch or take over the run in a browser.

Triggers from the description

s UI and the host
Original author description

Use when you need to run, click through, screenshot or record a Mac app's UI and the host's screen, mouse or keyboard belong to a person, the host may be locked, or a person wants to watch or take over the run in a browser.

How it works

  1. Bring the guest up
  2. Install, run, drive
  3. Reaching services on the host
  4. When a person watches or takes over
  5. Finishing
Original SKILL.md headings · 90 lines, 645 words
SKILL.md preview
---
name: agent-mac
description: Use when you need to run, click through, screenshot or record a Mac app's UI and the host's screen, mouse or keyboard belong to a person, the host may be locked, or a person wants to watch or take over the run in a browser.
---

# Driving a Mac app in an agent-mac guest

The guest is a headless macOS VM. You reach it only through `vm`: `./vm` in
an agent-mac checkout, or `agent-mac` when it's installed with Homebrew
(`command -v agent-mac`). The commands below use `./vm`. Never drive the
host's own screen for a UI check when a guest will do: the host's display,
pointer and keyboard belong to the person.

## Bring the guest up

```sh
./vm status                 # is it created, provisioned, running?
./vm up                     # idempotent; resumes an interrupted setup
```

`vm up` needs host sudo for provisioning a new guest and fails at once if sudo
would prompt. Then ask the person to run `sudo -v` in your terminal, or to set
`SUDO_ASKPASS`. Don't retry with guesses. The first `vm up` on a machine
downloads about 25 GB and takes 10–20 minutes; tell the person before you
start it, and confirm the connection isn't metered.

The first `vm up` on a machine also builds a prepared guest with the Command
Line Tools, Homebrew and voxl (about 10 minutes once); new guests copy it and
are up in about 20 seconds. `brew install` works in the guest (`./vm ssh 'zsh -lc "brew …"'`).
`VM_BREW=0` skips that. After updating agent-mac, `./vm prepare --rebuild`.

For runs that must compare, fix the environment once; it sticks for later
`vm up`:

```sh
./vm up --display 1440x900 --appearance dark --locale de_DE   # points, HiDPI
```

`./vm save <name>` keeps the running guest (memory and disks) and stops it;
`./vm restore <name>` resumes it exactly there, as often as you like, so a
snapshot taken after logging in or seeding data is a clean start for each
run. Saving fails while the host screen is locked; say so rather than
retrying.

At most two macOS guests run at once. Use `VM_NAME=<name>` for a separate
guest, and `vm down` the ones you're done with.

## Install, run, drive

```sh
./vm install path/to/App.app "<commit> built <time>"   # always label the build
./vm run [--env K=V]... [-- args...]                    # waits for the first window
./vm ad find --app App --name Open --first              # agent-desktop: returns a ref_id
./vm ad click <ref_id>
./vm shot <dir> [name]                                  # one PNG
./vm quit
```

- `vm ad` passes everything to agent-desktop in the guest. For clicking,
  typing, waiting and stale refs, follow agent-desktop's guide:
  `./vm ad skills get desktop`. Don't reuse refs or coordinates from an
  earlier run.
- Report which build is in the guest (the label you gave `vm install`).
- Keep screenshots and recordings in a gitignored directory of the project
  you're working on, never `/tmp`: a reboot wipes it.

## Reaching services on the host

A guest app reaching a host service under its certificate's name needs
`./vm forward-host <name>` once per guest. Without it, TLS fails on the
gateway IP.

## When a person watches or takes over

`./vm view` prints a link to a live view of the guest desktop; give the
person that link. `--control` lets them use the mouse and keyboard;
`--remote` serves it over the host's tailnet so they can open it from a phone
or another machine.

- Start in watch mode unless the person asks to take control.
- `--control` puts a hold on the guest. Input through `vm ad`, and `vm run`,
  `quit`, `install`, `save` and `restore`, exit 3 until the person hands
  back with `./vm view` or `./vm view stop`. Exit 3 means wait, not fail:
  tell the person you're waiting, and don't end the hold yourself. Reading
  the screen (`snapshot`, `find`, `screenshot`) still works.
- The first `vm view` on a guest builds voxl (about 10 minutes). Say so
  before you start it.
- `./vm view stop` when they're done.

## Finishing

`./vm quit`, then `./vm down` unless the person wants the guest left up.
For recording and judging motion, use the `record-and-verify` skill.

Versions

The database has no other skills named agent-mac.

Database snapshot: 13.11.2026 · package version fbf2e6fcb770 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100agent-desktop-setup
    Set up a dedicated macOS user account that an AI agent can log into and control with computer use, while a human watches and takes over. Covers provisioning the account, installing the agensis-cu computer-use host, granting Screen Recording and Accessibility, wiring it into an…
  • 90drive-mac-apps
    Use when a web page or macOS app must be operated via its UI (clicking, typing, dragging, reading the screen) and no CLI, API or dedicated tool covers it. sleight drives apps in the background with the ChatGPT app's engine. Your pointer is untouched. Prefer its tools…
  • 95seeu
    Use SeeU to see and operate apps on the user's Mac in the background — look at the screen, click, type, scroll — without taking the mouse or switching the frontmost app. Use it when the user asks you to operate a Mac app (TextEdit, Notes, VS Code…), a Safari/Chrome page, iPhone…
  • 88claude-environment-deploy
    为 Windows 或 Mac 配置并验证 Claude 使用环境,Windows 走 Hyper-V,Mac 按芯片走 Fusion 与 Windows ARM64/x64;保存并打开目标 AdsPower 环境后必须同窗口先检测当前网络,再打开和登录 Claude 网页,随后打开所选桌面端;登录和付款由本人完成。
  • 100browser-use
    Control a real browser to navigate pages, click, type, fill forms, inspect rendered UI, take screenshots, or record video. Load only when the user asks to open or automate a browser, interact with or test rendered page UI, scrape a site that needs browser execution, or capture a…
  • 100clone
    Walk through any existing app (native Mac app with computer use, web app with a browser), screenshot every screen, menu, and dialog, write a screen index, and turn it into user stories. Use when the user wants to clone, rebuild, replace, or copy the design of an app, or says…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.