macos-computer-use

Automates macOS desktop interactions via screenshots, element indexing, and background input control.

Updated Jul 3, 2026
One-click install
npx skills add https://github.com/CHENHUI-X/toolbox --skill macos-computer-use-chenhui-x
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: macos-computer-use
Source: https://github.com/CHENHUI-X/toolbox/tree/main/custom-skills/apple/macos-computer-use
Command: npx skills add https://github.com/CHENHUI-X/toolbox --skill macos-computer-use-chenhui-x

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Driving a Mac's GUI programmatically usually means hijacking the user's cursor, keyboard focus, and active Space, which interrupts real work. This Skill lets an AI operate macOS apps in the background using accessibility-tree element indices and scoped screenshots, so automation runs without disturbing the user. ## Core Features & Use Cases - Background GUI automation: Capture screens, click, type, scroll, and drag in any app without raising windows, stealing focus, or switching Spaces. - Element-index targeting: SOM capture mode overlays numbered indices on interactable elements from the accessibility tree, making clicks far more reliable than raw pixel coordinates for any tool-capable model. - Built-in safety guardrails: Hard rules block interacting with permission dialogs, password fields, payment UI, and dangerous typed commands, and treat on-screen content as untrusted. - Use Case: Ask the agent to open Safari in another Space, navigate to a site, fill a search field, and report back the results — all while you keep typing in your editor uninterrupted. ## Quick Start Use the computer_use tool to capture Safari with element overlays, then click element 7 and show me a screenshot of 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 with mode="som" to get numbered element indices, then click by index — no cursor movement, focus theft, or Space switching occurs.

How do I click UI elements reliably with an AI model on macOS?

Capture the screen in SOM mode first, which returns a screenshot with numbered overlays plus an accessibility-tree index. Then call click with the element number instead of pixel coordinates, which works reliably across Claude, GPT, Gemini, and local models.

Does macOS computer use automation work with any AI model?

Yes, it works with any tool-capable model including Claude, GPT, Gemini, and open models on local OpenAI-compatible endpoints. There is no Anthropic-native schema; element-index clicking is the recommended pattern for non-Claude models.

When should I use computer_use instead of browser automation tools?

Use browser_* tools for web tasks since headless Chromium is more reliable than driving a GUI browser. Reserve computer_use for tasks requiring the user's actual native Mac apps like Mail, Messages, Finder, Figma, or games.

Why did my computer_use click have no effect?

Element indices go stale when the UI changes after the last capture, or a hidden modal may be blocking input. Re-capture the screen, dismiss any dialog with escape or its close button, then retry the click with the fresh index.

What permissions does macOS computer use automation require?

cua-driver must be installed (via hermes tools setup) and granted macOS Accessibility and Screen Recording permissions. Without these, capture and input actions will fail with a driver-not-installed or permission error.