hunch-mcp AGENTS.md

AGENTS.md — working on Hunch

Context for coding agents modifying this repo. (User-facing "how to use Hunch" lives in README.md; this file is "how the code works and how not to break it.")

Hunch drives a real, logged-in Mac for an LLM focus-free — reading and acting on background apps without stealing the user's screen, cursor, or keyboard. That invariant is the product. Most gotchas below exist to protect it.

Setup & tests

.venv/bin/python -m pytest tests/          # full suite; needs pyobjc (the venv has it)
.venv/bin/python -m pytest tests/test_smoke.py

• Python ≥ 3.11. Depends on pyobjc (AppKit/ApplicationServices/Quartz) — macOS only.
• tests/test_smoke.py::test_tool_count asserts exactly 29 MCP tools. Adding/removing a tool means updating that number in the same commit, on purpose.
• Tests fake all AX/Quartz calls (monkeypatch), so they run headless with no UI and touch no Keychain. Keep new logic unit-testable this way: put the OS call behind a function you can patch, assert on the decision logic.

Architecture — one engine, three faces

The SDK is the product; everything else is an app built on it.

• sdk.py — Hunch, the developer-facing SDK object (instance-owned policy, auth injection ApiKey/OAuthToken/"none", app_id namespacing, notify handler).
• server.py — the MCP server, an app built ON the SDK (the first one). 29 @mcp.tool() functions each call _run(name, ...) → agent._dispatch_core. Its only "personal machine" specialness is constructor args (policy="personal", Hunch branding).
• agent.py — the agent loop (Agent.run), two backends: api (anthropic, metered) and subscription (claude-agent-sdk, the user's Claude sign-in). backend="auto" picks by ambient credentials. _dispatch_core(mac, name, args) is the single tool-execution engine shared by both the server and the agent loop — expected Hunch exceptions become plain content strings so the model can adapt; only unexpected ones set is_error.
• local_mac.py — the macOS backend: MacSession (AX perception + action primitives) and LocalComputer (exposes snapshot/act/screenshot to the loop). The biggest, most delicate file.
• ax_tree_mac.py — low-level AX helpers (get_attr/get_attrs, get_window, get_actions, values_to_bounds, tree walk). One IPC round-trip matters here; huge trees (Mail inbox = one AXRow per email) make naive per-attribute reads take minutes.
• cdp.py — the web/Electron backend (Chrome DevTools Protocol), background-driven.
• gate.py / policy.py — consent. Gate.front_gate / confirm_dialog; confirm="off" or HUNCH_NO_INTERNAL_GATE=1 env = auto-approve (host owns permissions, e.g. the desktop app).
• os_ops.py (files/clipboard/AppleScript), creds.py/auth.py (Keychain), notify.py, errors.py, playbook.py (HUNCH_PLAYBOOK; server.py serves it as FastMCP(instructions=…) so every connected client receives it. Change the model-facing contract here, not the tool docstrings.), cli.py.