hunch-mcp

<!-- mcp-name: io.github.PrithviSeran/hunch -->
<p align="center">
  <img src="https://raw.githubusercontent.com/PrithviSeran/hunch-mcp/main/src/hunch/assets/hunch.png" alt="Hunch" width="128">
</p>

# 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:

| Layer | Tools | What it's for |
|---|---|---|
| **OS-API** | `trash` `file_op` `open_file` `clipboard_*` `launch_app` … | files, clipboard, app lifecycle, via direct API calls |
| **AppleScript** | `applescript` | scriptable apps: Mail, Messages, Notes, Calendar, Music, Finder, Safari … |
| **Web / CDP** | `web_open` `web_snapshot` `web_act` `web_login` … | any browser page or Electron app, driven in the background |
| **Accessibility** | `snapshot` `act` | any native app's UI: read the tree, click/select/type by reference |

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.

## 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.

## Benchmarks

Hunch is measured against other macOS computer-use agents on a real, logged-in Mac in
[mac-agent-bench](https://github.com/PrithviSeran/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):

| Tool | Success | Cost | Disturbance (focus·cursor) | Timeouts |
|---|---|---|---|---|
| **Hunch** | **15/15** | **$1.52** | **1·0** | **0** |
| [Peekaboo](https://github.com/steipete/Peekaboo) | 13/15 | $14.60 | 22·16 | 2 |
| [cua-driver](https://github.com/trycua/cua) | 15/15 | $17.70 | 22·0 | 0 |

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](https://github.com/PrithviSeran/mac-agent-bench).

## 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
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`:

```python
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/`](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):

```bash
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.
```

```python
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:

| Backend | Sign in with | Cost |
|---|---|---|
| `subscription` | `hunch.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) |
| `api` | `export ANTHROPIC_API_KEY=sk-ant-...` | metered API tokens |

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

```python
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):

```python
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
  re