Hunch

Drive your Mac with any LLM: focus-free, in the background, over MCP.

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.

Related MCP server: macinput

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, and, for the web layer, a local WebSocket to Chrome's DevTools port on 127.0.0.1. The only thing that ever touches the network is Chrome itself, doing ordinary browsing. What the model sees is whatever the tools return through your host; nothing else leaves the machine.

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[agent]'  # + the optional LLM agent loop (both backends;
                                #   [api] or [subscription] picks just one)

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 + create the browser profile
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
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.

• 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 Claude drives the Mac through those same primitives — Scrapybara's act(), but on your machine with your logged-in apps. It's an optional extra (keeps the base install free of the model SDKs):

pip install 'hunch-sdk[agent]'
python -c 'import hunch; hunch.login()'   # Claude subscription sign-in (browser OAuth) — no
                                          # API key. Already signed into Claude Code? Skip it.

from hunch import Hunch

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

Signing in

Auth is an explicit, visible surface — nothing is scavenged silently. Two ways to run the loop:

You choose the backend where it suits your code — at construction, or per call:

mac = Hunch(agent_backend="subscription")            # this instance's agent = subscription
mac.agent.run(task)                                  # ...no per-call ceremony
mac.agent.run(other_task, backend="api")             # per-call override still wins

The default backend="auto" picks by credentials, in a fixed documented order (API key → CLAUDE_CODE_OAUTH_TOKEN env → Claude Code sign-in → hunch.login(token=...) token) — inspect it any time with hunch.auth.status() or hunch doctor. With no credentials at all, run() raises a HunchError naming both fixes — it never guesses.

Auth is public Python API (there is no login CLI — the MCP server never needs one, and your app owns its own onboarding):

import hunch

st = hunch.auth.status()           # AuthStatus: .source / .email / .plan / .subscription_ready
if not st.subscription_ready:
    hunch.login()                  # browser OAuth; or hunch.login(token="sk-ant-oat-...") headless
hunch.logout()                     # removes what login() stored, and only that

• Watch it work with an on_event(kind, data) callback — kind is one of text (Claude's reasoning), tool ({name, input}), tool_result (preview), done (final text), error.

• Continuation: follow-up run() calls keep the conversation (Claude still knows which email is Sarah's); mac.agent.reset() starts a fresh task.

• Mix layers freely: call mac.snapshot(...) / mac.clipboard.get() deterministically around mac.agent.run(...) — the thing a cloud sandbox can't do on your real machine.

• Knobs: run(task, model=None, max_turns=40, effort=None, on_event=None, system_suffix="", backend=None) — model=None means claude-opus-4-8 on the api backend and your subscription's default model otherwise. AgentResult has text, turns, stop_reason, usage, aborted.

• Safety: the instance's gate config governs the loop. The default confirm="dialog" pops a real "Go ahead?" dialog before any focus-stealing or risky step — good when you're at the machine, but a gated action can stall an unattended run for the dialog's timeout. For cron jobs use Hunch(confirm="off") and accept the risk; Claude still asks you (via notify_user) before irreversible or outward actions like sending a message. A declined gate comes back to the model as a REFUSED result, so the loop adapts instead of crashing.

• Cost: on the subscription backend, runs draw on your Claude plan's usage limits — no per-token bill. On the api backend each turn resends the tree-heavy history; prompt caching is on by default, so cached input is ~10× cheaper — but long autonomous runs still add up. max_turns caps it either way.

Other models: the agent loop is Claude-only, but the instance-SDK primitives are provider-agnostic — wire mac.snapshot() / mac.act() into your own OpenAI/Gemini/etc. agent loop as tools.

Building an app on Hunch

The SDK is developer-first: one uniform semantics, everything instance-owned, nothing ambient unless you opt in. The MCP server above is itself just the first app built on it — its "personal" behavior (the ~/.hunch/config.json policy, "Hunch"-branded dialogs, shared browser profile) is nothing but constructor arguments.

from hunch import Hunch, ConsentRequest, OAuthToken

mac = Hunch(
    app_id="com.acme.mailbot",          # pure namespacing — own Keychain slots, browser
                                        #   profile, and CDP port; never a behavior switch
    app_name="Acme Mailbot",            # what consent dialogs + notifications say
    confirm=my_consent_callback,        # ConsentRequest -> bool, rendered in YOUR UI
    notify=my_toast_handler,            # (message, title) -> your surface, not macOS banners
    policy={"gates": {"shell": True}},  # instance-owned safety; the user's personal
                                        #   config can never disarm your app
    auth=OAuthToken(token),             # exactly the credential YOUR app manages —
                                        #   or "none" to forbid ambient pickup entirely
)

What this buys you:

• Coexistence — two apps with different app_ids get disjoint Keychain services, credential stores, browser profiles, and CDP ports. They can't read each other's logins, log each other out, or kill each other's browser sessions. Structurally, not by convention.

• Your brand, your UX — every dialog, refusal, and notification says your app_name; confirm= and notify= route consent and alerts through your app instead of osascript dialogs and macOS banners. A broken consent callback fails closed.

• Isolated safety posture — the machine's hunch config (and HUNCH_NO_INTERNAL_GATE) govern only the personal MCP server, never your instance.

• Explicit auth — hunch.ApiKey(...) / hunch.OAuthToken(...) use exactly that credential (reprs are redacted); auth="none" guarantees your app never silently rides on the end user's own Claude sign-in.

Programmatic credential management uses the same namespacing: hunch.creds.set_credential(name, user, pw, namespace=your_app_id) etc. A runnable walkthrough lives in examples/embedded_app.py.

Credentials: agents use them, never see them

hunch creds add github --domain github.com
hunch creds list

Values go straight into the macOS Keychain. An agent signs in by calling web_fill_login("github") with only the service name; Hunch reads the secret from the Keychain and types it into the page over CDP. The value never enters the model's context, its logs, or its provider's servers.

Domain binding: a credential added with --domain github.com will only ever be typed into github.com (and its subdomains). If a confused or prompt-injected agent lands on a look-alike page, the fill is refused. Bind every credential; blank (any-site) exists only for compatibility.

No stored credential? Agents fall back to web_login, which opens a tagged browser window where you sign in yourself; the session then persists in Hunch's dedicated browser profile.

Confirmation gates

Your MCP host's tool approvals are the primary permission layer. Hunch adds a content-aware second gate, a one-click macOS dialog, for the catastrophic cases:

One approval covers its follow-through: clicking "Go ahead" (on request_focus, a gated act, or the app-to-front dialog) authorizes the switch it announced for ~15 s: no second dialog, and the focus-switch notification is suppressed. A switch is either asked about or announced, never both, and never silent (turn gates.app_to_front off and switches fall back to the notification).

All on by default. For the MCP server, hunch config show / hunch config set gates.shell off adjusts them; changes apply immediately, even to a running server. auto_approve_all disables everything and makes you confirm you understand the risk.

For SDK instances the gates are instance-owned: Hunch() defaults to all gates on and never reads the config file — pass policy={"gates": {...}}, a callable(category) -> bool, or policy="personal" to opt into the live config-file behavior for your own scripts.

Hunch also refuses to let the agent edit anything under ~/.hunch/ (its own policy and credential metadata) via its file tools; permission changes are for humans in a terminal.

Env vars

FAQ

Every tree read returns "(no window for …)" and AppleScript fails with "-25211 not allowed assistive access". One cause: the app hosting Hunch is missing the Accessibility grant. Without it the AX API silently returns nothing, so apps look windowless even when they're open. Grant it to the host (see next question), and if it's already listed, toggle it off and on: macOS silently invalidates grants when an app updates. Restart the host afterwards.

Which app do I grant permissions to? The one that launches hunch serve: Claude Desktop, Cursor, or your terminal app (for Claude Code). Grants attach to that app's identity, never to "hunch" itself. This is also why hunch doctor can be misleading: it reports the grants of the terminal you ran it in, which may differ from your MCP host's.

Only screenshot fails; everything else works. That's the Screen Recording permission, which only the screenshot/vision fallback needs. Grant it to the host in System Settings → Privacy & Security → Screen Recording, or just let agents use snapshot, which doesn't need it.

It worked yesterday and broke today. An update to your host app (or macOS) likely reset its permission grants. Toggle the host off and on under Accessibility (and Screen Recording, if you use it), then restart the host.

An app's tree reads empty or shows only a sidebar. Two different situations. Electron/CEF apps (Discord, Slack, Spotify, VS Code) need an accessibility flag; snapshot relaunches them once, in the background, to set it. Master-detail and Catalyst apps (WhatsApp, Mail) expose only the pane you're in: the agent should click into an item by ref and re-snapshot; the detail pane then appears. Also check the app actually has a window open.

The web layer won't connect. Chrome 136+ blocks CDP on your default profile by design. Hunch uses its own profile at ~/.hunch/chrome-cdp; run hunch setup to create it and sign into your sites there.

My host shows the server instructions truncated. Cosmetic: some host UIs shorten the playbook in their server-info display; the model receives it in full.

Security

Read SECURITY.md: threat model (prompt injection, mainly), what the gates do and don't cover, and how to report vulnerabilities.

License

Apache-2.0; see LICENSE.