macOS Harness
macOS Harness is a minimal Python-based tool that gives an LLM agent direct control over a Mac via six primitives (see, key, type, click, ax, script), enabling it to complete tasks across native apps, the browser, and the filesystem. It solves the problem of rigid, app-specific automation frameworks by letting the agent write its own logic mid-task. It is for developers using coding agents like Codex or Claude Code who want their agent to operate a real Mac.
✨ Key features
- Six primitives: see, key, type, click, ax, script
- Captures background app windows without foregrounding
- Sends keyboard and coordinate input directly to app PID
- Draws animated click-through pointer without moving cursor
- Exposes raw Apple Accessibility and Apple Events
- Integrates with Browser Harness for real logged-in browser
🎯 Use cases
- Automate tasks in native macOS apps like Spotify
- Control the real browser with user's logged-in sessions
- Manipulate files and run shell commands in same process
- Let agent write custom logic for any unforeseen task
📦 Installation
🧰 Requirements: macOS only, Python 3.12, requires macOS permissions (check with doctor), anonymous telemetry on by default.
To install, paste the following into Codex or Claude Code:
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`. 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.
Manual setup is available at install.md.
🚀 Usage
macos-harness <<'PY'
frame = mac.see("Spotify")
mac.key("cmd+k", app="Spotify")
mac.type("Alessia Cara", app="Spotify")
mac.click(640, 420, app="Spotify")
item = mac.ax.at(640, 420, app="Spotify")
mac.script('tell application "Spotify" to play')
print(browser.page_info())
print(list(Path.home().iterdir()))
PY
⚠️ Good to know
Experimental, macOS only, and requires macOS permissions; telemetry is on by default but can be disabled.
❓ FAQ
What macOS permissions does it need?
Run macos-harness doctor to see the permissions actually needed. The harness never activates or raises a target app and never moves the physical pointer.
Does it work with any app?
It works with native and Electron apps via CGWindow, CGEvent, AX, and Apple Events. It also uses Browser Harness for the real browser.
How do I disable telemetry?
Run macos-harness telemetry disable. Telemetry records only CLI command category, success, duration, package version, OS/architecture, and agent client—never prompts, app names, screenshots, UI text, scripts, paths, or window titles.
What Python version is required?
The installation instructions specify using Python 3.12 with uv.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.