New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

macOS Harness

by Zfinix in Zfinix/aster

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…

Apache-2.0Auto-check passedFrontend & Design

Install macOS Harness

skills CLI
$ npx skills add Zfinix/aster --skill macos-harness -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Zfinix/aster macos-harness --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/Zfinix/aster.git skills-src && mkdir -p .claude/skills && cp -r skills-src/crates/aster-skills/optional-skills/macos-harness .claude/skills/macos-harness && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
macos-harness
GitHub stars
118
Token cost
~1.3k tokens
SKILL.md length
629 words
Files
1
Skills in repo
19
Repo updated
First seen
Licence
Apache-2.0

At a glance

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…

  • Works in 5 steps: When identity depends on local context… → Use mac.script() for a known exact,… → Otherwise use mac.see(app) and vision. → …
  • Cross-app tasks without moving the physical cursor
  • SKILL.md covers Setup, Surface, Minimize round trips and Use the small surface, plus 3 more sections
  • Calls uv

What it does

macOS Harness is an agent skill from Zfinix/aster. 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.

Its SKILL.md is about 1.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Frontend & Design. It works with macOS and Python. The repository describes itself as: An open-source agent harness for software work. The licence is Apache-2.0.

When your agent uses it

  • Cross-app tasks without moving the physical cursor
  • Forcing apps into the foreground

Example prompts

  • “/macos-harness”

Requirements

  • Python 3

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. When identity depends on local context (my, friend, or prior
  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,
  5. Use targeted mac.ax only when semantic identity or state matters. Do

What it can do on your machine

Read from SKILL.md and the folder at commit f77a5b4. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • uv

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use uv, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

macOS Harness loads about 1.3k tokens when it runs. Until then it costs about 91 tokens; SKILL.md has 629 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~91
When it runs · the whole SKILL.md, loaded when a task matches
~1.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Zfinix/aster at commit f77a5b4, republished under its Apache-2.0 licence (© Zfinix). 629 words, ~1,331 tokens.

Download SKILL.mdSave it as .claude/skills/macos-harness/SKILL.md (or your agent's skills folder).
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

Setup

The skill ships with aster; the CLI it drives does not. Install it once with uv tool install macos-harness, then run macos-harness doctor to check permissions without prompting (--request only with user approval).

Surface

The CLI entry points are doctor, apps, see <app>, state <app>, repl, skill, telemetry. The real harness is the Python session: stdin programs preload mac, browser, Path, and subprocess.

bash
macos-harness <<'PY'
print(mac.see("Finder")["path"])
PY

Verified bindings (checked against the installed CLI):

  • mac.see(app) -> dict with path (screenshot file), app, bounds, focus.target_is_frontmost. Captures without focusing the app.
  • mac.key / mac.type / mac.click / mac.drag / mac.scroll / mac.move: PID-targeted input; the physical cursor stays untouched.
  • mac.ax is an object: .dump(app) (dict: app, nodes, text, windows, screenshot), .query, .get, .set, .perform, .actions, .at.
  • mac.script(applescript) for Apple Events; mac.windows(app), mac.list_apps(), mac.snapshot(), mac.get_app_state(app) for discovery and state.
  • browser.connect(name) / browser.wait(name) for CDP into the user's real logged-in browser. Chrome shows an Allow remote debugging? sheet on first connect; approve it once there.
  • Plain Path and subprocess for everything else.

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 model repeatedly ask whether a transition finished.
  • Use the cheapest strong end-state check: one screenshot for visible state or one exact API/AX query for semantic state; 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.

Show full SKILL.md (201 more words)Show less

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.

© Zfinix, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in crates/aster-skills/optional-skills/macos-harness of Zfinix/aster.

Open the folder on GitHubat commit f77a5b4

Compare with similar skills

macOS Harness next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

macOS Harness compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
macOS Harness this skillZfinix/aster118—~1.3kAutomated safety check: PassApache-2.0
Jarvis Setupethanplusai/jarvis846—~2.5kAutomated safety check: NotesCustom licence
UI UX Pro Maxfutureboard/futureboard-studio109—~5.6kAutomated safety check: PassMIT
Gui Debugnatsukium/dotfiles106—~909Automated safety check: PassCC0-1.0
Disk Storage AnalyzerKKKKhazix/khazix-skills21k1 repos~1.4kAutomated safety check: PassMIT
Claude Desktop Chinese Localizationjavaht/claude-desktop-zh-cn7.5k—~1.6kAutomated safety check: PassMIT

Similar skills

  • Jarvis Setup

    ethanplusai/jarvis

    A skill your agent uses when helping someone install, configure, or debug a fresh clone of JARVIS (this repo) — especially "the mic doesn't work", "JARVIS says his language systems are down", any…

    846 GitHub stars~2.5k tokensUpdated 1 mo ago
    Frontend & DesignAuto-check: notes

  • UI UX Pro Max

    futureboard/futureboard-studio

    Comprehensive design guide for web, mobile, and desktop applications.

    109 GitHub stars~5.6k tokensUpdated 3 days ago
    Frontend & DesignAuto-check passed

  • Gui Debug

    natsukium/dotfiles

    Verify a rendering or window-chrome change in any macOS GUI app unattended — find its CGWindowID via JXA, capture that window alone (with per-pixel alpha) using screencapture -l, and read exact RGBA…

    106 GitHub stars~909 tokensUpdated today
    Frontend & DesignAuto-check passed

  • Disk Storage Analyzer

    KKKKhazix/khazix-skills

    Scans a Mac or Windows PC read-only to find what fills the disk, grades each item by how safe it is to clean and builds an interactive HTML report.

    21k GitHub starsUsed in 1 repo~1.4k tokens
    Productivity & AutomationAuto-check passed

  • Claude Desktop Chinese Localization

    javaht/claude-desktop-zh-cn

    Adds missing Simplified and Traditional Chinese translations to the Claude Desktop Chinese patch across three layers, then checks how many mappings actually hit.

    7.5k GitHub stars~1.6k tokensUpdated 5 days ago
    Frontend & DesignAuto-check passed

  • Apple Container Test Runner

    RustPython/RustPython

    Runs RustPython tests inside a Linux container built with Apple's container CLI, so macOS users can compare Linux results with their local ones.

    22k GitHub stars~467 tokensUpdated today
    Testing & QAAuto-check passed

More from Zfinix/aster

All 19 skills in this repo

  • Artifact Design

    Zfinix/aster

    Designing and building any user-facing surface: a web page, landing page, dashboard, report, HTML document, email, or a component inside an existing app.

    118 GitHub stars~2.8k tokensUpdated yesterday
    Auto-check passed

  • Aster Chat Sessions

    Zfinix/aster

    Drive aster chat programmatically and manage sessions and memory: one-shot --print/--json answers, --messages-json for caller-owned history, --continue and --session persistence, --allow-edits…

    118 GitHub stars~591 tokensUpdated yesterday
    Auto-check passed

  • Aster CLI

    Zfinix/aster

    Guidance for using the aster CLI to work in a codebase with an AI agent: chat and edit code, run AI code reviews, apply fixes, and manage sessions, memory, and skills.

    118 GitHub stars~1.2k tokensUpdated yesterday
    Auto-check passed

  • Aster Config

    Zfinix/aster

    Reference for aster.yaml, covering review models, analyzers, focus areas, include/exclude globs, minconfidence, and the permissions block that gates edits.

    118 GitHub stars~1.2k tokensUpdated yesterday
    Auto-check passed

  • Aster Fix Workflow

    Zfinix/aster

    Pipe aster review findings into aster fix to generate and apply patches safely, using review --json, fix --findings-json, dry-run inspection, --apply, and permission gating.

    118 GitHub stars~534 tokensUpdated yesterday
    Auto-check passed

  • Aster Planning

    Zfinix/aster

    Create and execute structured plans for multi-step tasks. An agent skill from Zfinix/aster.

    118 GitHub stars~1k tokensUpdated yesterday
    Auto-check passed

Works with

Categories

Questions about macOS Harness

What does macOS Harness do?

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…. macOS Harness is an agent skill from Zfinix/aster. 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.

When should I use macOS Harness?

macOS Harness fits situations like: cross-app tasks without moving the physical cursor; forcing apps into the foreground.

How do I install macOS Harness in Claude Code?

Run `npx skills add Zfinix/aster --skill macos-harness -a claude-code`. Or copy the skill folder (crates/aster-skills/optional-skills/macos-harness in Zfinix/aster) into .claude/skills/macos-harness in your project. Claude Code loads it when a task matches its description.

How do I install macOS Harness in Codex?

Run `npx skills add Zfinix/aster --skill macos-harness -a codex`. Or copy the skill folder (crates/aster-skills/optional-skills/macos-harness in Zfinix/aster) into .agents/skills/macos-harness in your project. Codex loads it when a task matches its description.

Can I use macOS Harness in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Zfinix/aster --skill macos-harness -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/macos-harness, .gemini/skills/macos-harness, .github/skills/macos-harness and .opencode/skills/macos-harness in your project.

What does macOS Harness need to run?

Going by SKILL.md and its folder, macOS Harness needs the command-line tools its instructions call (uv). Our summary lists: Python 3.

Does macOS Harness access the network?

SKILL.md contains no URLs. Its commands use uv, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is macOS Harness safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does macOS Harness use?

macOS Harness is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does macOS Harness use?

About 1.3k tokens (SKILL.md is roughly 5.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to macOS Harness?

Skills that share tags, products or a category with macOS Harness: Jarvis Setup (ethanplusai/jarvis, 846 stars), UI UX Pro Max (futureboard/futureboard-studio, 109 stars), Gui Debug (natsukium/dotfiles, 106 stars) and Disk Storage Analyzer (KKKKhazix/khazix-skills, 21k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains macOS Harness?

Zfinix (a GitHub user) maintains it in Zfinix/aster, which has 118 GitHub stars. The repository holds 19 skills in this directory. The repository was last updated on October 9, 2026.

Source: Zfinix/aster on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.