macos-harness README

The project's README from github.com/browser-use/macos-harness. As one markdown file: README.md.

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

                              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

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.

macos-harness (browser-use/macos-harness)

Searching Database…

956 ·GitHub
Macos-harness
这是什么？macos-harness 是一个轻量的 Python harness，它通过少数几个原始原语（而不是预构建的应用专用工具）让 LLM 代理直接控制一台 Mac。
这是一个内置各种现成方案的框架，还是更简单的东西？它刻意不做框架：没有 Spotify、Slack 或 Final Cut 工具，也没有预定义的工作流。它只是在单个 Python 进程中暴露六个原语（see、key、type、click、ax、script），其余都交给模型来写。
怎么让它跑起来？你把一段简短的提示词粘贴到 Codex 或 Claude Code 中，代理会自行安装软件包、学习工作流、检查权限并验证连接。也提供手动安装的途径。
它支持哪些编程代理？它设计为交给 Codex 或 Claude Code 使用，由它们自行安装并引导启动；harness 本身作为 Python 进程与你的真实浏览器并行运行。
它适合日常生产使用了吗？不适合。README 将该项目标注为实验性且仅限 macOS，因此应把它视为早期工具，而不是为日常使用打磨成熟的东西。
它也能在其他操作系统上工作吗？不能。它专门围绕 macOS 的辅助功能和 Apple Events API 构建，因此只能在 Mac 上运行。
它会上报哪些数据？匿名遥测默认开启，但只记录 CLI 命令类别、成功与否、耗时、软件包版本、操作系统/架构以及检测到的代理客户端；它绝不会记录提示词、应用名称、截图、UI 文本、脚本、路径或窗口标题。
代理工作时它会移动我真实的鼠标指针吗？不会。它会绘制一个可点击穿透的动画指针覆盖层，并把输入直接发送到目标应用的进程，因此你真实的指针和窗口的层叠顺序都保持不变。
它能看见后台运行的应用并与之交互吗？可以。它可以在不把后台应用窗口带到前台的情况下捕获它们，并将键盘和坐标输入直接发送到应用的 PID。
它如何处理真实已登录的浏览器？它通过 CDP 使用 Browser Harness 来控制你真实已登录的浏览器会话，而不是另起一个单独的自动化浏览器。
代理获得的六个原语是什么？see、key、type、click、ax（辅助功能/Apple Events）和 script，另外还有普通的 Python 环境，browser、Path 和 subprocess 在同一进程中可用。
What are similar projects?typesafe-computer-use, hermes-jev-skills, lcu, browser-use-pi, agent-desktop, browser-use, browser, open-dot
Which topics is it in?cdp, telemetry, computer-use, accessibility, apple, macos-app, browser-automation, agent, privacy, automation, ai-agents, tool
Creator
browser-use
Size
6 MB
Stars
956
Updated
CommitOct 15Releasev0.2.1Oct 15
Age
2mo
Commits · 90 Days