Hunch

Hunch

Drive your Mac with any LLM: focus-free, in the background, over [MCP](https://modelcontextprotocol.io).

Hunch is an MCP server that gives an LLM agent hands on *your* Mac: your installed apps, your logged-in sessions, your files, without taking over your screen. While you keep working in the foreground, an agent can read a background app's UI, click its buttons, drive Mail or Music by AppleScript, fill a web form, or move files. It works on real native apps, not just a browser.

Works best with modern LLMs. Hunch ships a detailed playbook as MCP server instructions;

capable tool-using models (Claude Sonnet/Opus-class and up) follow it well. Smaller models may

pick clumsier paths (screenshots and keystrokes instead of tree reads and clicks).

The four layers

Hunch always prefers the most direct layer. It's faster, more reliable, and (except the last) never touches your screen:

A gated last resort (screenshot + coordinate clicks/keystrokes) exists for apps whose accessibility tree is truly empty. It steals focus, so it asks you first.

For focus-free visual work in Safari, open a dedicated extension-owned window with web_open(..., app="Safari", new_window=True). web_screenshot captures that background window, and web_act can use the returned pixel coordinates without moving the shared mouse, keyboard, or foreground window. The extension remains necessary: it owns the isolated Safari window and dispatches renderer-local actions that a physical screen capture cannot.

How it works (no server, no cloud)

"MCP server" undersells how local this is. hunch serve is a plain Python process that your MCP host (Claude Desktop, Cursor, …) spawns as a child process and talks to over JSON-RPC on stdin/stdout (MCP's stdio transport). There is no HTTP endpoint, no port Hunch listens on, no daemon, and no telemetry. When your host quits, Hunch is gone.

The tools are direct macOS API calls in-process: the Accessibility framework via pyobjc, osascript for AppleScript, OS APIs for files/clipboard, a local WebSocket to Chromium's DevTools port, and the signed local Safari extension bridge. The optional Safari companion uses an authenticated loopback connection solely to relay typed commands to Apple's sandboxed extension. Browsing traffic still comes from the selected browser. What the model sees is whatever the tools return through your host; nothing else leaves the machine.

Benchmarks

Hunch is measured against other macOS computer-use agents on a real, logged-in Mac in mac-agent-bench — *same brain, different hands*: identical claude -p per task, only the MCP adapter differs. It scores task success with programmatic checkers and disturbance: how much the agent hijacks your cursor and foreground while it works.

Across 5 complex multi-step tasks (n=3):

Perfect reliability, ~10x cheaper, ~5–10x faster, and it essentially never touches your screen (0 cursor moves, 1 focus switch across 15 trials). Full methodology and per-task tables are in the benchmark repo.

Install

macOS 13+. From PyPI (the distribution is hunch-sdk; the import and CLI are hunch):

pipx install hunch-sdk          # or: pip install hunch-sdk

pip install 'hunch-sdk[subscription]' # + the agent loop on Claude (provider="claude") pip install --pre 'hunch-sdk[codex]' # + the agent loop on OpenAI Codex (provider="codex")

Or via Homebrew — best if you don't manage Python environments; it bundles an isolated Python at a stable path, which makes the macOS permission grants the most predictable:

brew install prithviseran/hunch/hunch

Then, one time:

hunch setup      # walk the macOS permission grants

hunch doctor # verify every layer; fix anything it flags hunch connect claude-desktop # or: claude-code, cursor

Restart your MCP host and ask it to *"use hunch to …"*.

The permissions, honestly

macOS trust attaches to the app that runs the server, meaning your MCP host (Claude Desktop, Cursor, your terminal), not "hunch" itself. hunch setup walks you through it:

• Accessibility (required): lets Hunch read app UIs and click focus-free. Grant it to your MCP host app in System Settings → Privacy & Security → Accessibility.
• Automation (per-app, automatic): the first time Hunch scripts an app, macOS shows a one-time "allow control" prompt.
• Screen Recording (optional): only for the screenshot/vision fallback.

hunch doctor reports what's granted. Note: its Accessibility line reflects the *terminal* you ran it from; the server inherits the *host's* grant.

Python SDK (library use)

Hunch is also an importable library — the same focus-free primitives as the MCP tools, driven deterministically from your own Python (a cron job, a test harness, your own agent loop), no LLM required. The distribution is hunch-sdk; the import is hunch:

from hunch import Hunch

mac = Hunch() # your machine, your logged-in apps print(mac.snapshot("Mail")) # accessibility tree, focus-free mac.act([{"action": "click", "ref": "e12"}]) mac.web.open(url="https://github.com") # real persistent Chrome profile over CDP mac.web.open(url="https://github.com", app="Safari") # user's Safari session via extension print(mac.web.snapshot()) mac.files.trash(["~/Downloads/old.zip"]) # reversible delete, no Finder mac.applescript('tell application "Music" to play')

Constructor knobs: app (initial snapshot target), confirm="dialog"|"off" (see below), check_permissions (Accessibility check up front), simultaneous (never touch the foreground/cursor/keyboard), cdp_port.

To reveal hover menus or tooltips in a Chromium/Electron CDP session, use a ref from the latest web_snapshot:

mac.web.act([{"action": "hover", "ref": "e12"}], detailed=True)

print(mac.web.snapshot()) # verify the revealed UI and get fresh refs before clicking

The MCP equivalent is web_act with the same action. Hover sends a renderer-local mouse-move event, without a click, app activation, or movement of the Mac cursor. Its receipt is performed_unverified unless an explicit postcondition verifies the requested field. Safari returns unsupported (a detailed call returns blocked with zero attempted actions); native act does not advertise hover.

An element's own identity, where the page keeps one (Chromium/Electron CDP only):

mac.web.identity("e12")

{"framework": "react", "keys": ["2026-11-18", "staff_member_1", "7282"],

"attrs": {"data-testid": "draggable-event"}}

keys are the framework's list keys from the root down to the element (React, and Vue where a build exposes vnodes), which apps mostly set to their records' ids and which survive the re-renders that replace DOM nodes; attrs are the element's id, name, data-testid and href as written. It reads in the page's main world and sends no input. Nothing is interpreted: a list position (0, 1) and a record id come back alike.

• Permissions: for library use it's *whatever runs your script* — your terminal or IDE — that needs Accessibility (the MCP server instead uses the host app's grant). The constructor checks and raises AccessibilityNotGranted with instructions. screenshot() additionally needs Screen Recording.
• Safety gates default ON: the same one-click "Go ahead" dialogs and ~/.hunch/config.json gates as the MCP server. Hunch(confirm="off") auto-approves for that instance only — for unattended scripts, with the same caveats as auto_approve_all.
• Errors: methods return status strings (check for REFUSED); the SDK raises only ApprovalDenied (user declined a dialog), AccessibilityNotGranted, WebNotOpen (.web before .web.open()), StaleRef (re-snapshot), and HunchError when a CDP browser can't be opened (web.restart() recovers a stale instance).
• Credentials: mac.web.fill_login(service) / fill_secret(service, ref) type Keychain values straight into the page and never return them; domain binding is enforced.
• Coexistence: the SDK and the MCP server share the CDP port (9337) and the persistent Hunch browser profile — whichever opened it first is reused, but web.restart()/web.login() kill whatever holds the port.

Runnable scripts live in examples/.

Agent loop (mac.agent)

The instance SDK gives you deterministic primitives. The agent loop puts an LLM in the driver's seat: you hand it a task in plain English and it drives the Mac through those same primitives — on *your* machine with *your* logged-in apps. Pick your provider — Anthropic Claude or OpenAI Codex — once at construction; everything after is provider-agnostic. It's an optional extra (keeps the base install free of the model SDKs):

pip install 'hunch-sdk[subscription]'                    # Claude

or, for Codex (the SDK is beta): pip install --pre 'hunch-sdk[codex]'

python -c 'import hunch; hunch.provider("claude").login()' # sign-in (browser OAuth) — no API key

from hunch import Hunch

mac = Hunch(provider="claude") # or Hunch(provider="codex") result = mac.agent.run("reply to Sarah's latest email, but don't send it") print(result.text) # the model's final summary print(result.turns, result.usage)

Signing in

Auth is an explicit, provider-scoped surface — nothing is scavenged silently. You choose the vendor once, then the same prefix-free methods act on it:

mac = Hunch(provider="codex")       # or "claude" (the default)

mac.login() # codex: ChatGPT browser sign-in · claude: Claude sign-in mac.status() # -> AuthStatus(provider, logged_in, method, email, plan) mac.logout() mac.agent.run(task) # runs on the configured provider

Or drive auth standalone, without a Mac instance (e.g. an onboarding script):

import hunch

st = hunch.provider("codex").status() if not st.logged_in: hunch.provider("codex").login() # browser OAuth (blocks until done)

headless/remote box instead:

h = hunch.provider("codex").device_login()

print(h.verification_url, h.user_code); h.wait()

Both run on a subscription/login — metered API keys are intentionally not exposed. With no valid sign-in, run() surfaces an error tha