macos-computer-use

Automates macOS desktop interactions via screenshots, element indices, and background input routing.

Updated Jul 10, 2026
One-click install
npx skills add https://github.com/AvaTar-ArTs/.Agent-skills --skill macos-computer-use-avatar-arts
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: macos-computer-use
Source: https://github.com/AvaTar-ArTs/.Agent-skills/tree/main/skills/apple/macos-computer-use
Command: npx skills add https://github.com/AvaTar-ArTs/.Agent-skills --skill macos-computer-use-avatar-arts

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Automating the macOS desktop usually means hijacking the user's cursor, keyboard focus, and active Space, which interrupts their work. This Skill drives native Mac apps in the background using accessibility-tree element indices and scoped screenshots, so GUI automation runs without disturbing the user. ## Core Features & Use Cases - Background GUI Automation: Capture screenshots with numbered element overlays (SOM mode), then click, type, scroll, and drag by element index without raising windows or switching Spaces. - Model-Agnostic Operation: Works with any tool-capable model (Codex, GPT, Gemini, or local OpenAI-compatible endpoints) through a single computer_use tool with capture, click, type, key, scroll, and drag actions. - Safety Guardrails: Hard rules against clicking permission dialogs, typing secrets, or following instructions found in screenshots, plus tool-level blocking of dangerous patterns. - Use Case: Ask the agent to fill out a form in a native Mac app like Messages or Finder while you keep typing in your editor; it captures the app's AX tree, clicks elements by index, and verifies each step with follow-up screenshots. ## Quick Start Use the computer_use tool to capture Safari with SOM overlays, then click the sign-in element by its index and show me the result.

Frequently Asked Questions about macos-computer-use

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I automate macOS GUI apps without moving the user's cursor?

Use the computer_use tool, which routes input to apps in the background via cua-driver. Capture the target app with mode="som" to get numbered element overlays, then click by element index without raising windows or switching Spaces.

How to click UI elements reliably with computer vision models on macOS?

Capture with SOM mode first to get an AX-tree index of interactable elements, then call click with the element number rather than pixel coordinates. Element indices are far more reliable across models than raw coordinates.

Does macOS computer use automation work with non-Anthropic models?

Yes, it works with any tool-capable model including Codex, GPT, Gemini, or local models on OpenAI-compatible endpoints. There is no Anthropic-native schema; all actions go through a single generic computer_use tool.

When should I use browser tools instead of computer_use on macOS?

Use browser_* tools for web automation since they run a real headless Chromium and are more reliable than driving the user's GUI browser. Reserve computer_use for native Mac apps like Mail, Messages, Finder, Figma, or games.

Why does computer_use report cua-driver not installed?

The error means the cua-driver dependency is missing. Run the tools setup to enable Computer Use, which installs cua-driver, and grant macOS Accessibility and Screen Recording permissions.

What safety limits exist for macOS desktop automation?

The skill forbids clicking permission dialogs, payment UI, or 2FA prompts, and never types passwords or secrets. Dangerous patterns like log out, lock screen, and piped shell commands are hard-blocked at the tool level.