macOS Harness ⌘
The simplest, thinnest harness that gives an LLM complete freedom to complete virtually any task on a Mac.
The agent writes what is missing, mid-task. No framework, no recipes, no rails. One Python process connected directly to macOS, your real browser, and your files.
● agent: wants to do something no helper exists for
│
● sees the app and uses raw macOS primitives
│
● writes the missing logic in ordinary Python
│
✓ task complete no app-specific tool addedYour agent now has a Mac.
Give it to your agent
Paste this 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.That is it. The agent installs the package, teaches itself the workflow, checks permissions, and verifies the connection. Manual setup is available too.
Six primitives. The whole Mac.
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()))
PYThink in see, key, type, click, ax, and script. browser, Path, and
subprocess are ready in the same Python process.
There are no Spotify tools, Slack tools, or Final Cut tools. The model gets raw primitives and writes the rest.
How it works
one persistent Python process
│
┌──────────────────────┼──────────────────────┐
│ │ │
mac.* browser.* Path / subprocess
│ │ │
┌───────────┼───────────┐ Browser Harness files + shell
│ │ │ │
CGWindow CGEvent AX + Apple CDP
screenshots to PID Events │
│ │ │ real Chrome
└───────────┴───────────┘
│
native + Electron apps- Captures background app windows without bringing them forward
- Sends keyboard and coordinate input directly to an app PID
- Draws an animated, click-through pointer without moving your real cursor
- Exposes raw Apple Accessibility and Apple Events when vision is not enough
- Uses Browser Harness for the real, logged-in browser
- Keeps ordinary Python and the local filesystem within reach
Permissions and privacy
macos-harness doctor reports the macOS permissions actually needed. The harness
never activates or raises a target app and never moves the physical pointer.
Anonymous telemetry is enabled by default. It records only the CLI command category, success, duration, package version, OS/architecture, and detected agent client. It never records prompts, app names, screenshots, UI text, scripts, paths, or window titles.
macos-harness telemetry disableExperimental. macOS only. MIT licensed.