macos-harness 0.1.0__tar.gz

macos_harness-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run pytest

macos_harness-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

macos_harness-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+dist/
+tmp/
+
+# Local task artifacts can contain private workspace data.
+slack-*.json
+slack-*.md

macos_harness-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+macOS Harness is intentionally small. Prefer exposing a raw macOS primitive over
+adding an app-specific helper or workflow.
+
+```bash
+uv sync
+uv run ruff check .
+uv run pytest
+```
+
+Pull requests should preserve three invariants: never move the physical pointer,
+never activate or raise a target app, and never send user data through telemetry.

macos_harness-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Browser Use
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

macos_harness-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: macos-harness
+Version: 0.1.0
+Summary: The simplest, thinnest harness that gives an LLM complete freedom to control a Mac.
+Project-URL: Homepage, https://github.com/browser-use/macos-harness
+Project-URL: Repository, https://github.com/browser-use/macos-harness
+Project-URL: Issues, https://github.com/browser-use/macos-harness/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accessibility,agent,automation,cdp,computer-use,macos
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: browser-harness>=0.1.9
+Requires-Dist: pillow>=11.3
+Requires-Dist: pyobjc-framework-applicationservices>=12.0; sys_platform == 'darwin'
+Description-Content-Type: text/markdown
+
+<img src="static/banner.png" alt="macOS Harness" width="100%" />
+
+# 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.
+
+```text
+● 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:
+
+```text
+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](install.md) is available too.
+
+## Six primitives. The whole Mac.
+
+```bash
+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
+
+```text
+                              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.
+
+```bash
+macos-harness telemetry disable
+```
+
+Experimental. macOS only. [MIT licensed](LICENSE).

macos_harness-0.1.0/README.md

@@ -0,0 +1,97 @@
+<img src="static/banner.png" alt="macOS Harness" width="100%" />
+
+# 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.
+
+```text
+● 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:
+
+```text
+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](install.md) is available too.
+
+## Six primitives. The whole Mac.
+
+```bash
+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
+
+```text
+                              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.
+
+```bash
+macos-harness telemetry disable
+```
+
+Experimental. macOS only. [MIT licensed](LICENSE).

macos_harness-0.1.0/SECURITY.md

@@ -0,0 +1,9 @@
+# Security
+
+Please report vulnerabilities privately through GitHub Security Advisories for
+`browser-use/macos-harness`.
+
+macOS Harness can control applications and read visible UI content with the
+permissions the user grants it. Treat agent instructions and third-party UI as
+untrusted input, review irreversible actions, and grant the minimum permissions
+needed for the task.

macos_harness-0.1.0/install.md

@@ -0,0 +1,37 @@
+# Install macOS Harness
+
+## Let your agent do it
+
+Paste this into Codex or Claude Code:
+
+```text
+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.
+```
+
+## Or install it yourself
+
+```bash
+uv tool install --python 3.12 --upgrade --force macos-harness
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/macos-harness"
+macos-harness skill > "${CODEX_HOME:-$HOME/.codex}/skills/macos-harness/SKILL.md"
+macos-harness doctor
+```
+
+Grant only the permissions reported by `doctor`. macOS may request Accessibility,
+Screen Recording, and Automation access. Input Monitoring is not required.
+
+Verify without focusing the target app:
+
+```bash
+macos-harness <<'PY'
+print(mac.see("Finder"))
+PY
+```
+
+Anonymous telemetry contains only the CLI command category, success, duration,
+package version, OS/architecture, and detected agent client. It never includes
+prompts, app names, screenshots, text, scripts, paths, or window titles.
+
+```bash
+macos-harness telemetry disable
+```

macos_harness-0.1.0/macos-harness

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+
+if [ -x "$ROOT/.venv/bin/python" ]; then
+  exec "$ROOT/.venv/bin/python" -m macos_harness.cli "$@"
+fi
+
+exec uv --directory "$ROOT" run python -m macos_harness.cli "$@"

macos_harness-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "macos-harness"
+version = "0.1.0"
+description = "The simplest, thinnest harness that gives an LLM complete freedom to control a Mac."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["agent", "automation", "computer-use", "macos", "accessibility", "cdp"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: MacOS X",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Desktop Environment",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "browser-harness>=0.1.9",
+  "pillow>=11.3",
+  "pyobjc-framework-ApplicationServices>=12.0; sys_platform == 'darwin'",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.4",
+  "pyyaml>=6.0",
+  "ruff>=0.12",
+]
+
+[project.scripts]
+macos-harness = "macos_harness.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/browser-use/macos-harness"
+Repository = "https://github.com/browser-use/macos-harness"
+Issues = "https://github.com/browser-use/macos-harness/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/macos_harness"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills/macos-harness/SKILL.md" = "macos_harness/SKILL.md"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

macos_harness-0.1.0/skills/macos-harness/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: macos-harness
+description: Control a whole Mac from one persistent Python session with screenshots, PID-targeted input, an animated virtual pointer, targeted Apple Accessibility, Apple Events, Browser Harness CDP, and filesystem access. Use for native, Electron, browser, dialog, file, or cross-app tasks without moving the physical cursor or forcing apps into the foreground.
+---
+
+# macOS Harness
+
+Use one CLI call per decision point, not per primitive:
+
+```bash
+macos-harness <<'PY'
+app = "Spotify"
+mac.see(app)
+mac.key("cmd+k", app=app)
+mac.type("Alessia Cara", app=app)
+print(mac.see(app))
+PY
+```
+
+The CLI preloads `mac`, `browser`, `Path`, and `subprocess`. Prefer bounded stdin
+programs; reserve `macos-harness repl` for manual exploration and always exit it.
+
+## Minimize round trips
+
+- Bundle deterministic, reversible steps into one program, then verify once. Opening
+  search, typing a query, and capturing the results is one burst—not three calls.
+- Stop at a genuine decision boundary: ambiguous identity, new coordinates, an
+  irreversible action, or unexpected state. Inspect once, then run the next burst.
+- Do not screenshot merely to confirm that a known shortcut opened a text field
+  before typing. Let the final screenshot verify the whole sequence.
+- Poll exact AX or Apple Events state inside the same Python program when possible;
+  do not make the LLM repeatedly ask whether a transition finished.
+- Use the cheapest strong end-state check. Prefer one screenshot for visible state
+  or one exact API/AX query for semantic state; use both only when they prove
+  different things.
+
+## Use the small surface
+
+Think in six verbs: `see`, `key`, `type`, `click`, `ax`, `script`.
+
+```python
+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.ax.perform(item["element_index"], "AXPress")
+
+mac.script('tell application "Spotify" to play')
+```
+
+Use ordinary Python for local context and one-off logic. Do not add app-specific
+helpers when a short program can resolve the task.
+
+## Choose the lowest useful mode
+
+1. When identity depends on local context (`my`, `friend`, or prior activity),
+   inspect that context and correlate stable fields; a loose text hit is not enough.
+2. Use `mac.script()` for a known exact, focus-safe app command.
+3. Otherwise use `mac.see(app)` and vision.
+4. Prefer a known keyboard route; use a verified coordinate for a visible,
+   low-risk target.
+5. Use targeted `mac.ax` only when semantic identity or state matters. Do not dump
+   a full AX tree before trying the direct route.
+
+After a failed verified burst, switch mode or stop. Never repair uncertainty with
+repeated keys, clicks, deletion loops, or bulk input.
+
+## Keep the invariants
+
+- Input targets an already-running app PID and never requests activation or raise.
+- A background target becoming frontmost raises `FocusChangedError`; never
+  manipulate focus to restore it.
+- `mac.click()` is raw PID-targeted input. It never guesses an AX action.
+- The animated pointer is click-through and never moves the physical cursor.
+- `mac.move()` moves only that pointer; it cannot produce native hover.
+- Inactive apps may reject raw clicks. After one verified failure, switch mode.
+- Never launch a closed app or use a custom URL scheme when focus is forbidden.
+- Screenshot coordinates come from the latest `mac.see()` and preserve window
+  bounds and Retina scaling.
+
+Secondary primitives are `mac.move`, `drag`, `scroll`, `show_pointer`, and
+`hide_pointer`. `mac.ax.query()` returns compact matches and bounds fallback
+traversal; lower `max_nodes` for especially large apps.
+
+## Browser and permissions
+
+Use `browser` for DOM, tabs, network, downloads, and uploads. Do not substitute AX
+for CDP inside a web page. While Browser Harness connects, macOS Harness accepts
+Chrome's exact `Allow remote debugging?` sheet through system-wide AX. It never
+activates Chrome or emits a mouse event.
+
+Run `macos-harness doctor` to inspect permissions without prompting. Run
+`macos-harness doctor --request` only with user approval. Accessibility, screen
+recording, and event posting are global; Apple Events Automation is per target.

macos_harness-0.1.0/skills/macos-harness/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "macOS Harness"
+  short_description: "Simple visual control for the whole Mac"
+  default_prompt: "Use $macos-harness to see and control my Mac without moving my physical cursor or taking focus."

macos_harness-0.1.0/src/macos_harness/__init__.py

@@ -0,0 +1,12 @@
+"""Public Python interface for macOS Harness."""
+
+from .browser import BrowserHarness
+from .macos import AccessibilityPermissionError, FocusChangedError, MacOS, MacOSError
+
+__all__ = [
+    "AccessibilityPermissionError",
+    "BrowserHarness",
+    "FocusChangedError",
+    "MacOS",
+    "MacOSError",
+]