{ "markdown": "\n

\n \"Hunch\"\n

\n\n# Hunch\n\n**Drive your Mac with any LLM: focus-free, in the background, over [MCP](https://modelcontextprotocol.io).**\n\nHunch is an MCP server that gives an LLM agent hands on *your* Mac: your installed apps, your\nlogged-in sessions, your files, without taking over your screen. While you keep working in the\nforeground, an agent can read a background app's UI, click its buttons, drive Mail or Music by\nAppleScript, fill a web form, or move files. It works on real native apps, not just a browser.\n\n> **Works best with modern LLMs.** Hunch ships a detailed playbook as MCP server instructions;\n> capable tool-using models (Claude Sonnet/Opus-class and up) follow it well. Smaller models may\n> pick clumsier paths (screenshots and keystrokes instead of tree reads and clicks).\n\n## The four layers\n\nHunch always prefers the most direct layer. It's faster, more reliable, and (except the last)\nnever touches your screen:\n\n| Layer | Tools | What it's for |\n|---|---|---|\n| **OS-API** | `trash` `file_op` `open_file` `clipboard_*` `launch_app` … | files, clipboard, app lifecycle, via direct API calls |\n| **AppleScript** | `applescript` | scriptable apps: Mail, Messages, Notes, Calendar, Music, Finder, Safari … |\n| **Web / CDP** | `web_open` `web_snapshot` `web_act` `web_login` … | any browser page or Electron app, driven in the background |\n| **Accessibility** | `snapshot` `act` | any native app's UI: read the tree, click/select/type by reference |\n\nA gated last resort (`screenshot` + coordinate clicks/keystrokes) exists for apps whose\naccessibility tree is truly empty. It steals focus, so it asks you first.\n\n## How it works (no server, no cloud)\n\n\"MCP server\" undersells how local this is. `hunch serve` is a plain Python process that your\nMCP host (Claude Desktop, Cursor, …) spawns as a **child process** and talks to over\n**JSON-RPC on stdin/stdout** (MCP's stdio transport). There is no HTTP endpoint, no port\nHunch listens on, no daemon, and no telemetry. When your host quits, Hunch is gone.\n\nThe tools are direct macOS API calls in-process: the Accessibility framework via pyobjc,\n`osascript` for AppleScript, OS APIs for files/clipboard, and, for the web layer, a local\nWebSocket to Chrome's DevTools port on `127.0.0.1`. The only thing that ever touches the\nnetwork is Chrome itself, doing ordinary browsing. What the model sees is whatever the tools\nreturn through your host; nothing else leaves the machine.\n\n## Benchmarks\n\nHunch is measured against other macOS computer-use agents on a real, logged-in Mac in\n[mac-agent-bench](https://github.com/PrithviSeran/mac-agent-bench) — *same brain, different hands*:\nidentical `claude -p` per task, only the MCP adapter differs. It scores task success with programmatic\ncheckers **and** disturbance: how much the agent hijacks your cursor and foreground while it works.\n\nAcross 5 complex multi-step tasks (n=3):\n\n| Tool | Success | Cost | Disturbance (focus·cursor) | Timeouts |\n|---|---|---|---|---|\n| **Hunch** | **15/15** | **$1.52** | **1·0** | **0** |\n| [Peekaboo](https://github.com/steipete/Peekaboo) | 13/15 | $14.60 | 22·16 | 2 |\n| [cua-driver](https://github.com/trycua/cua) | 15/15 | $17.70 | 22·0 | 0 |\n\nPerfect reliability, ~10x cheaper, ~5–10x faster, and it essentially never touches your screen (`0`\ncursor moves, `1` focus switch across 15 trials). Full methodology and per-task tables are in the\n[benchmark repo](https://github.com/PrithviSeran/mac-agent-bench).\n\n## Install\n\nmacOS 13+. From PyPI (the distribution is `hunch-sdk`; the import and CLI are `hunch`):\n\n```\npipx install hunch-sdk # or: pip install hunch-sdk\npip install 'hunch-sdk[subscription]' # + the agent loop on Claude (provider=\"claude\")\npip install --pre 'hunch-sdk[codex]' # + the agent loop on OpenAI Codex (provider=\"codex\")\n```\n\nOr via Homebrew — best if you don't manage Python environments; it bundles an isolated\nPython at a stable path, which makes the macOS permission grants the most predictable:\n\n```\nbrew install prithviseran/hunch/hunch\n```\n\nThen, one time:\n\n```\nhunch setup # walk the macOS permission grants\nhunch doctor # verify every layer; fix anything it flags\nhunch connect claude-desktop # or: claude-code, cursor\n```\n\nRestart your MCP host and ask it to *\"use hunch to …\"*.\n\n### The permissions, honestly\n\nmacOS trust attaches to the **app that runs the server**, meaning your MCP host (Claude Desktop,\nCursor, your terminal), not \"hunch\" itself. `hunch setup` walks you through it:\n\n- **Accessibility** (required): lets Hunch read app UIs and click focus-free. Grant it to your MCP\n host app in System Settings → Privacy & Security → Accessibility.\n- **Automation** (per-app, automatic): the first time Hunch scripts an app, macOS shows a one-time\n \"allow control\" prompt.\n- **Screen Recording** (optional): only for the screenshot/vision fallback.\n\n`hunch doctor` reports what's granted. Note: its Accessibility line reflects the *terminal* you ran\nit from; the server inherits the *host's* grant.\n\n## Python SDK (library use)\n\nHunch is also an importable library — the same focus-free primitives as the MCP tools, driven\ndeterministically from your own Python (a cron job, a test harness, your own agent loop), no LLM\nrequired. The distribution is `hunch-sdk`; the import is `hunch`:\n\n```python\nfrom hunch import Hunch\n\nmac = Hunch() # your machine, your logged-in apps\nprint(mac.snapshot(\"Mail\")) # accessibility tree, focus-free\nmac.act([{\"action\": \"click\", \"ref\": \"e12\"}])\nmac.web.open(url=\"https://github.com\") # real persistent Chrome profile over CDP\nprint(mac.web.snapshot())\nmac.files.trash([\"~/Downloads/old.zip\"]) # reversible delete, no Finder\nmac.applescript('tell application \"Music\" to play')\n```\n\nConstructor knobs: `app` (initial snapshot target), `confirm=\"dialog\"|\"off\"` (see below),\n`check_permissions` (Accessibility check up front), `simultaneous` (never touch the\nforeground/cursor/keyboard), `cdp_port`.\n\n- **Permissions**: for library use it's *whatever runs your script* — your terminal or IDE — that\n needs Accessibility (the MCP server instead uses the host app's grant). The constructor checks\n and raises `AccessibilityNotGranted` with instructions. `screenshot()` additionally needs\n Screen Recording.\n- **Safety gates default ON**: the same one-click \"Go ahead\" dialogs and `~/.hunch/config.json`\n gates as the MCP server. `Hunch(confirm=\"off\")` auto-approves for that instance only — for\n unattended scripts, with the same caveats as `auto_approve_all`.\n- **Errors**: methods return status strings (check for `REFUSED`); the SDK raises only\n `ApprovalDenied` (user declined a dialog), `AccessibilityNotGranted`, `WebNotOpen`\n (`.web` before `.web.open()`), `StaleRef` (re-snapshot), and `HunchError` when a CDP\n browser can't be opened (`web.restart()` recovers a stale instance).\n- **Credentials**: `mac.web.fill_login(service)` / `fill_secret(service, ref)` type Keychain\n values straight into the page and never return them; domain binding is enforced.\n- **Coexistence**: the SDK and the MCP server share the CDP port (9337) and the persistent Hunch\n browser profile — whichever opened it first is reused, but `web.restart()`/`web.login()` kill\n whatever holds the port.\n\nRunnable scripts live in [`examples/`](examples/).\n\n## Agent loop (`mac.agent`)\n\nThe instance SDK gives you deterministic primitives. The **agent loop** puts an LLM in the driver's seat:\nyou hand it a task in plain English and it drives the Mac through those same primitives — on *your*\nmachine with *your* logged-in apps. Pick your **provider** — Anthropic **Claude** or OpenAI **Codex** —\nonce at construction; everything after is provider-agnostic. It's an optional extra (keeps the base\ninstall free of the model SDKs):\n\n```bash\npip install 'hunch-sdk[subscription]' # Claude\n# or, for Codex (the SDK is beta): pip install --pre 'hunch-sdk[codex]'\npython -c 'import hunch; hunch.provider(\"claude\").login()' # sign-in (browser OAuth) — no API key\n```\n\n```python\nfrom hunch import Hunch\n\nmac = Hunch(provider=\"claude\") # or Hunch(provider=\"codex\")\nresult = mac.agent.run(\"reply to Sarah's latest email, but don't send it\")\nprint(result.text) # the model's final summary\nprint(result.turns, result.usage)\n```\n\n### Signing in\n\nAuth is an explicit, provider-scoped surface — nothing is scavenged silently. You choose the vendor\nonce, then the same prefix-free methods act on it:\n\n```python\nmac = Hunch(provider=\"codex\") # or \"claude\" (the default)\nmac.login() # codex: ChatGPT browser sign-in · claude: Claude sign-in\nmac.status() # -> AuthStatus(provider, logged_in, method, email, plan)\nmac.logout()\nmac.agent.run(task) # runs on the configured provider\n```\n\nOr drive auth standalone, without a Mac instance (e.g. an onboarding script):\n\n```python\nimport hunch\n\nst = hunch.provider(\"codex\").status()\nif not st.logged_in:\n hunch.provider(\"codex\").login() # browser OAuth (blocks until done)\n # headless/remote box instead:\n # h = hunch.provider(\"codex\").device_login()\n # print(h.verification_url, h.user_code); h.wait()\n```\n\n| Provider | Sign in with | Cost |\n|---|---|---|\n| `claude` | `mac.login()` / `hunch.provider(\"claude\").login()` — the same browser OAuth Claude Code uses. Already signed into Claude Code on this Mac? You're done; Hunch reuses that. | your Claude plan (no per-token cost) |\n| `codex` | `mac.login()` / `codex login` — a ChatGPT/Codex browser sign-in. | your ChatGPT/Codex plan |\n\nBoth run on a subscription/login — metered API keys are intentionally not exposed. With no valid\nsign-in, `run()` surfaces an error that points you back to `login()` — it never guesses.\n\n- **Watch it work** with an `on_event(kind, data)` callback — `kind` is one of `text` (reasoning),\n `tool` (`{name, input}`), `tool_result` (preview), `done` (final text), `error`.\n- **Continuation**: follow-up `run()` calls keep the conversation (the model still knows which email\n is Sarah's); `mac.agent.reset()` starts a fresh task.\n- **Mix layers freely**: call `mac.snapshot(...)` / `mac.clipboard.get()` deterministically around\n `mac.agent.run(...)` — the thing a cloud sandbox can't do on your real machine.\n- **Knobs**: `run(task, model=None, max_turns=40, effort=None, on_event=None, system_suffix=\"\")` —\n `model=None` uses the provider's own default model. `AgentResult` has `text`, `turns`,\n `stop_reason`, `usage`, `aborted`.\n- **Safety**: the instance's gate config governs the loop. The default `confirm=\"dialog\"` pops a\n real \"Go ahead?\" dialog before any focus-stealing or risky step — good when you're at the\n machine, but a gated action can stall an unattended run for the dialog's timeout. For cron jobs\n use `Hunch(confirm=\"off\")` and accept the risk; the model still asks *you* (via `notify_user`)\n before irreversible or outward actions. A declined gate comes back as a `REFUSED` result, so the\n loop adapts instead of crashing.\n- **Cost**: runs draw on your provider plan's usage limits — no per-token bill. `max_turns` caps it.\n\n> **Codex note:** the `codex` provider drives an OpenAI Codex agent that reaches Hunch's tools over\n> MCP (a separate `hunch serve` process), so its dangerous-verb approvals use Hunch's own\n> click-to-approve dialogs rather than a host `can_use_tool` callback.\n\nOther models: the instance-SDK primitives are provider-agnostic — wire `mac.snapshot()` /\n`mac.act()` into your own OpenAI/Gemini/etc. agent loop as tools.\n\n## Building an app on Hunch\n\nThe SDK is developer-first: **one uniform semantics, everything instance-owned, nothing ambient\nunless you opt in.** The MCP server above is itself just the first app built on it — its\n\"personal\" behavior (the `~/.hunch/config.json` policy, \"Hunch\"-branded dialogs, shared browser\nprofile) is nothing but constructor arguments.\n\n```python\nfrom hunch import Hunch, ConsentRequest, OAuthToken\n\nmac = Hunch(\n provider=\"claude\", # which LLM vendor drives mac.agent (\"claude\" | \"codex\")\n app_id=\"com.acme.mailbot\", # pure namespacing — own Keychain slots, browser\n # profile, and CDP port; never a behavior switch\n app_name=\"Acme Mailbot\", # what consent dialogs + notifications say\n confirm=my_consent_callback, # ConsentRequest -> bool, rendered in YOUR UI\n notify=my_toast_handler, # callback, or True for native macOS banners (default: off)\n policy={\"gates\": {\"shell\": True}}, # instance-owned safety; the user's personal\n # config can never disarm your app\n auth=OAuthToken(token), # the exact Claude subscription token YOUR app manages\n can_use_tool=my_approver, # optional: route every tool through your Approve/Deny UI\n)\n```\n\nWhat this buys you:\n\n- **Coexistence** — two apps with different `app_id`s get disjoint Keychain services, credential\n stores, browser profiles, and CDP ports. They can't read each other's logins, log each other\n out, or kill each other's browser sessions. Structurally, not by convention.\n- **Your brand, your UX** — every dialog, refusal, and notification says your `app_name`;\n `confirm=` and `notify=` route consent and alerts through your app instead of osascript\n dialogs and macOS banners. A broken consent callback fails **closed**.\n- **Isolated safety posture** — the machine's `hunch config` (and `HUNCH_NO_INTERNAL_GATE`)\n govern only the personal MCP server, never your instance.\n- **Explicit auth** — `provider=\"claude\"` with `auth=hunch.OAuthToken(...)` uses exactly that\n subscription token (reprs are redacted), so your app never silently rides on the end user's own\n Claude sign-in. (The `codex` provider authenticates via `mac.login()` / `codex login`.)\n\nProgrammatic credential management uses the same namespacing: `hunch.creds.set_credential(name,\nuser, pw, namespace=your_app_id)` etc. A runnable walkthrough lives in\n[`examples/embedded_app.py`](examples/embedded_app.py).\n\n## Credentials: agents use them, never see them\n\n```\nhunch creds add github --domain github.com\nhunch creds list\n```\n\nValues go straight into the **macOS Keychain**. An agent signs in by calling\n`web_fill_login(\"github\")` with only the service *name*; Hunch reads the secret from the Keychain\nand types it into the page over CDP. The value never enters the model's context, its logs, or its\nprovider's servers.\n\n**Domain binding**: a credential added with `--domain github.com` will only ever be typed into\n`github.com` (and its subdomains). If a confused or prompt-injected agent lands on a look-alike\npage, the fill is refused. Bind every credential; blank (any-site) exists only for compatibility.\n\nNo stored credential? Agents fall back to `web_login`, which opens a tagged browser window where\n*you* sign in yourself; the session then persists in Hunch's dedicated browser profile.\n\n## Confirmation gates\n\nYour MCP host's tool approvals are the primary permission layer. Hunch adds a content-aware second\ngate, a one-click macOS dialog, for the catastrophic cases:\n\n| Gate | Fires on |\n|---|---|\n| `gates.focus_steal` | actions that take over your keyboard/cursor (`key`, `click_xy`, ref-less typing) |\n| `gates.app_to_front` | an app being brought to the front (a focus switch, even mid-fullscreen) |\n| `gates.shell` | AppleScript containing `do shell script` |\n| `gates.destructive_applescript` | delete / send / empty trash / shut down / … |\n\nOne approval covers its follow-through: clicking \"Go ahead\" (on `request_focus`, a gated `act`,\nor the app-to-front dialog) authorizes the switch it announced for ~15 s: no second dialog, and\nthe focus-switch notification is suppressed. A switch is either *asked about* or *announced*,\nnever both, and never silent (turn `gates.app_to_front` off and switches fall back to the\nnotification).\n\nAll on by default. For the **MCP server**, `hunch config show` / `hunch config set gates.shell off`\nadjusts them; changes apply immediately, even to a running server. `auto_approve_all` disables\neverything and makes you confirm you understand the [risk](SECURITY.md).\n\nFor **SDK instances** the gates are instance-owned: `Hunch()` defaults to all gates on and never\nreads the config file — pass `policy={\"gates\": {...}}`, a `callable(category) -> bool`, or\n`policy=\"personal\"` to opt into the live config-file behavior for your own scripts.\n\nHunch also refuses to let the agent edit anything under `~/.hunch/` (its own policy and credential\nmetadata) via its file tools; permission changes are for humans in a terminal.\n\n## Env vars\n\n| Var | Effect |\n|---|---|\n| `HUNCH_NO_INTERNAL_GATE=1` | suppress all internal dialogs (for host apps that run their own approval UX) |\n| `HUNCH_FORCE_SANDBOX=1` | web layer uses a throwaway, logged-out browser profile |\n| `HUNCH_NOTIFY_FOCUS=0` | silence the \"Hunch is switching apps\" notifications (they fire only for switches no dialog asked about) |\n\nUser-attention desktop notifications are opt-in. For the personal MCP server, enable them with\n`hunch config set notifications.user_attention on`. SDK apps can pass `notify=True` for native\nmacOS banners or a `notify(message, title)` callback for their own UI; the default is disabled.\n\n## FAQ\n\n**Every tree read returns \"(no window for …)\" and AppleScript fails with \"-25211 not allowed\nassistive access\".** One cause: the app hosting Hunch is missing the **Accessibility** grant.\nWithout it the AX API silently returns nothing, so apps look windowless even when they're open.\nGrant it to the *host* (see next question), and if it's already listed, toggle it off and on:\nmacOS silently invalidates grants when an app updates. Restart the host afterwards.\n\n**Which app do I grant permissions to?** The one that *launches* `hunch serve`: Claude Desktop,\nCursor, or your terminal app (for Claude Code). Grants attach to that app's identity, never to\n\"hunch\" itself. This is also why `hunch doctor` can be misleading: it reports the grants of the\nterminal you ran it in, which may differ from your MCP host's.\n\n**Only `screenshot` fails; everything else works.** That's the **Screen Recording** permission,\nwhich only the screenshot/vision fallback needs. Grant it to the host in System Settings →\nPrivacy & Security → Screen Recording, or just let agents use `snapshot`, which doesn't need it.\n\n**It worked yesterday and broke today.** An update to your host app (or macOS) likely reset its\npermission grants. Toggle the host off and on under Accessibility (and Screen Recording, if you\nuse it), then restart the host.\n\n**An app's tree reads empty or shows only a sidebar.** Two different situations. Electron/CEF\napps (Discord, Slack, Spotify, VS Code) need an accessibility flag; `snapshot` relaunches them\nonce, in the background, to set it. Master-detail and Catalyst apps (WhatsApp, Mail) expose only\nthe pane you're in: the agent should click into an item by ref and re-snapshot; the detail pane\nthen appears. Also check the app actually has a window open.\n\n**The web layer won't connect.** Chrome 136+ blocks the CDP debug port on your default profile, so\nHunch drives its own Chrome (a separate data dir at `~/.hunch/chrome-cdp`), not your everyday one.\nSign that profile into your Google account once (via `hunch setup` or `web_login`) and Chrome Sync\nbrings your logins with it; from then on it's already signed in.\n\n**My host shows the server instructions truncated.** Cosmetic: some host UIs shorten the playbook\nin their server-info display; the model receives it in full.\n\n## Security\n\nRead [SECURITY.md](SECURITY.md): threat model (prompt injection, mainly), what the gates do and\ndon't cover, and how to report vulnerabilities.\n\n## Project status\n\nHunch is currently maintained as a personal open-source project. It controls real apps, files,\nbrowser sessions, and credentials on your Mac, so review the source, keep approvals enabled, and\nuse least-privilege credentials. The software is provided on an **“AS IS”** basis, without\nwarranties or conditions, under the Apache License 2.0.\n\n## License\n\nApache-2.0; see [LICENSE](LICENSE).\n", "bytes": 20419, "sha": "230412243fc08521e222d79de1d07179fe7684d492c02c1b47b19b8b58cc080f", "repo_slug": "prithviseran/hunch-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_prithviseran_hunch_ebf6ba5c/readme" }