macos-harness
The simplest, thinnest harness that gives an LLM complete freedom to control a Mac.
What is it?
What it is
A minimal Python harness that gives an LLM direct, low‑level control of macOS via six primitives (see, key, type, click, ax, script) while also providing access to a real logged‑in browser, the local filesystem, and shell commands—all within a single persistent process.
Why it exists
To eliminate the need for app‑specific tools or frameworks, allowing agents to write missing automation logic in ordinary Python and interact with any macOS app or service using raw system primitives.
Who should use it
AI agents and developers building autonomous AI systems that need to control macOS applications directly, including those working on computer-use agents, accessibility automation, or research involving LLM-driven desktop interactions
Who should avoid it
Users seeking pre-built automation tools for specific applications, developers wanting high-level abstractions for common tasks, or those needing cross-platform solutions beyond macOS
How it works
A quick walkthrough in plain English
How macos-harness works in 4 steps
Step 1 of 4
Something triggers the flow
A schedule, webhook, or manual click tells macos-harness to start.
Features
Advantages
- Complete LLM task autonomy
- No external dependencies
- Transparent input/output
- Cross-app compatibility
- Real browser integration
- Local filesystem access
- Permission-aware operation
- Lightweight architecture
- Open-source transparency
- Customizable scripting
Disadvantages
- macOS-only compatibility
- Complex permission requirements
- Coordinate-based interaction
- Telemetry dependency
- No built-in error handling
- Limited cross-platform support
- Requires Python expertise
- No GUI visualization
- Potential security risks
- Experimental telemetry system
Installation
native
**Your agent now has a Mac.** ## Give it to your agent Paste this into Codex or Claude Code:
FAQ
How do I install macOS Harness and set it up for use?
Install or upgrade macOS Harness from https://github.com/browser-use/macos-harness with uv using Python 3.12. Register the skill printed by `macos-harness skill`, then run `macos-harness doctor` to check permissions. Explain any missing macOS permissions and ask before requesting them. Finally, verify the harness by capturing one already-running app without bringing it to the foreground.
What are the six core primitives provided by macOS Harness?
The six primitives are `see`, `key`, `type`, `click`, `ax`, and `script`. These allow the agent to capture screenshots, send keyboard input, type text, click coordinates, interact with Apple Accessibility, and run AppleScript, respectively.
How does macOS Harness handle macOS permissions and privacy?
Use `macos-harness doctor` to report required macOS permissions. The harness never activates or raises a target app and never moves the physical pointer. Anonymous telemetry is enabled by default but can be disabled with `macos-harness telemetry disable`.
How does macOS Harness integrate with the browser?
macOS Harness uses Browser Harness for the real, logged-in browser. It connects directly to macOS, your real browser, and your files within one persistent Python process, exposing `browser.*` methods alongside `mac.*` primitives.
Can I extend macOS Harness with custom Python code?
Yes. The agent writes missing logic in ordinary Python. There are no app-specific tools—models get raw primitives and write the rest. `Path`, `subprocess`, and standard Python are available in the same process.
How do I verify macOS Harness is working correctly?
Run `macos-harness doctor` to check permissions and connectivity. Verify by capturing an already-running app's window without bringing it to the foreground using `mac.see("AppName")`.
Featured in Videos
YouTube tutorials and walkthroughs for macos-harness
Alternatives
Similar projects ranked by category, topics, and text overlap.
