macos-harness

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 added

Your 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()))
PY

Think 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

…

• 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 disable

Experimental. macOS only. MIT licensed.