Hunch로 화면을 건드리지 않고 Mac을 제어하는 LLM agent

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

Hunch는 MCP 서버와 Python SDK를 결합해 Claude나 OpenAI Codex 같은 LLM agent가 사용자의 Mac 앱, 파일, 브라우저를 화면 포커스 없이 제어하도록 합니다. OS API, AppleScript, CDP, Accessibility tree를 직접성 순서로 사용하고, 화면을 빼앗는 좌표 입력은 접근성 정보가 없을 때만 승인과 함께 실행합니다. mac-agent-bench에서 15개 작업을 모두 성공시키며 비용 $1.52, cursor 0회, focus 1회를 기록했고, 기본 승인 게이트와 Keychain 도메인 바인딩으로 위험 동작과 자격 증명 입력을 제한합니다. 프로젝트는 개인 유지 오픈소스이며 실제 앱과 로그인 세션을 제어하므로 소스 검토와 최소 권한 설정이 필요합니다.

섹션별 상세

Hunch는 MCP를 통해 LLM agent가 사용자의 Mac 화면을 빼앗지 않고 설치된 앱, 로그인 세션, 파일을 조작하게 하는 로컬 도구입니다. 파일과 클립보드는 OS API로 처리하고, Mail·Music·Finder 같은 스크립트 가능 앱은 AppleScript로 제어하며, 브라우저와 Electron 앱은 CDP로 연결합니다. Accessibility 트리가 비어 있을 때만 화면 캡처와 좌표 클릭·키 입력을 마지막 수단으로 사용하고 이 경로는 포커스를 가져오기 전에 승인을 요구합니다.

Hunch는 가장 직접적인 제어 계층을 우선해 지연과 실패 가능성을 줄입니다. OS API에서 파일·클립보드·앱 수명주기를 처리한 뒤 AppleScript, 웹 계층, Accessibility 트리 순서로 입력과 상태 읽기를 수행하며, 각 호출의 결과만 MCP 호스트를 거쳐 모델에 전달합니다. 이 구조는 사용자가 foreground에서 계속 작업하는 동안 background 앱을 읽고 웹 폼을 채우는 데 초점을 둡니다.

실행 구조는 HTTP 서버나 클라우드 서비스가 아니라 MCP 호스트가 자식 프로세스로 띄우는 일반 Python 프로세스입니다. hunch serve는 stdin·stdout의 MCP stdio transport를 통해 JSON-RPC를 주고받고, 웹 제어에만 127.0.0.1의 Chrome DevTools Protocol WebSocket을 사용합니다. 서버에는 포트 수신 데몬과 telemetry가 없으며 호스트가 종료되면 Hunch 프로세스도 함께 끝납니다.

bash

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")

Hunch SDK와 Claude 또는 OpenAI Codex용 선택적 agent loop를 설치하는 명령입니다.

mac-agent-bench의 실제 로그인 Mac 실험에서 Hunch는 동일한 Claude 명령과 작업을 사용하고 MCP adapter만 바꾼 비교를 거쳤습니다. 5개 복합 작업을 3회씩 수행한 결과 Hunch는 15/15 성공, 비용 $1.52, focus 1회와 cursor 0회, timeout 0회를 기록했고 Peekaboo는 13/15 성공, $14.60, focus 22회와 cursor 16회, timeout 2회를 기록했습니다. cua-driver는 15/15 성공했지만 비용 $17.70과 focus 22회를 기록해 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')

LLM 없이도 Accessibility, CDP, 파일 API, AppleScript를 Python 코드에서 결정적으로 호출하는 예시입니다.

Hunch SDK는 LLM 없이도 동일한 Mac 제어 원시 기능을 Python에서 호출하도록 구성되어 있습니다. Hunch 인스턴스는 Mail의 Accessibility tree를 snapshot으로 읽고 ref를 이용해 act를 실행하며, persistent Chrome profile을 CDP로 열고 파일 삭제를 Finder 없이 처리할 수 있습니다. confirm="dialog"가 기본값인 승인 게이트, check_permissions 검사, StaleRef와 AccessibilityNotGranted 같은 예외를 통해 자동화 코드의 권한과 상태를 명시적으로 관리합니다.

python

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)

선택한 LLM provider가 Hunch의 도구를 사용해 자연어 작업을 수행하도록 agent loop를 실행합니다.

선택적 agent loop를 사용하면 Claude 또는 OpenAI Codex가 자연어 작업을 받아 같은 SDK primitive를 조작합니다. provider를 생성 시 지정하고 mac.agent.run에 작업을 전달하면 결과 텍스트, turn 수, 사용량, 중단 사유를 얻으며 후속 run 호출은 이전 대화 상태를 유지합니다. 기본 max_turns는 40이고, 승인되지 않은 동작은 오류로 프로세스를 중단하는 대신 REFUSED 결과로 돌아와 loop가 경로를 바꿀 수 있습니다.

python

from hunch import Hunch, ConsentRequest, OAuthToken
mac = Hunch(
    provider="claude",
    app_id="com.acme.mailbot",
    app_name="Acme Mailbot",
    confirm=my_consent_callback,
    notify=my_toast_handler,
    policy={"gates": {"shell": True}},
    auth=OAuthToken(token),
    can_use_tool=my_approver,
)

내장 앱이 자체 동의 UI, 인증 토큰, 정책, 알림 처리기를 사용하도록 Hunch 인스턴스를 구성하는 예시입니다.

Hunch는 실제 앱과 자격 증명을 다루기 때문에 동의와 보안을 인스턴스 단위로 분리합니다. app_id마다 Keychain 슬롯, 브라우저 프로필, CDP 포트를 분리하고 confirm·notify callback으로 앱 자체 UI를 연결하며, provider와 OAuthToken을 명시해야 특정 구독 인증을 사용합니다. Keychain 자격 증명은 서비스명과 도메인에 묶여 페이지에 직접 입력되고 모델 context·로그·provider 서버로 반환되지 않으므로 look-alike 도메인으로의 입력을 거부할 수 있습니다.

승인 게이트는 포커스 탈취, 앱 전면 전환, shell을 실행하는 AppleScript, 삭제·전송·휴지통 비우기·종료 같은 위험 동작에 적용됩니다. 기본 설정에서는 한 번의 Go ahead가 후속 동작을 약 15초 동안 승인하고, 포커스 전환은 대화상자 또는 알림 중 하나로만 사용자에게 전달됩니다. Hunch는 ~/.hunch/ 아래의 정책과 자격 증명 메타데이터를 agent가 파일 도구로 수정하지 못하게 하며, 프로젝트는 개인이 유지하는 Apache License 2.0 오픈소스로 제공됩니다.

용어 해설

Model Context Protocol: — Model Context Protocol은 LLM 호스트가 외부 도구와 데이터에 표준 방식으로 연결되도록 하는 프로토콜입니다. Hunch에서는 MCP 서버가 호스트 프로세스의 자식으로 실행되고 stdin·stdout 기반 JSON-RPC로 도구 호출을 주고받습니다. 별도 HTTP 서버 없이 로컬 Mac의 앱과 파일을 연결하는 기반으로 쓰입니다.
Accessibility API: — Accessibility API는 운영체제가 앱의 UI 요소 트리와 상호작용 기능을 외부 프로그램에 제공하는 인터페이스입니다. Hunch는 pyobjc를 통해 이 트리를 읽고 화면에 포커스를 빼앗지 않은 채 요소 참조로 클릭·선택·입력을 수행합니다. macOS에서는 서버를 실행하는 호스트 앱에 접근성 권한을 부여해야 합니다.
Chrome DevTools Protocol: — Chrome DevTools Protocol은 Chrome의 디버깅 포트에 연결해 브라우저 탭과 웹 페이지를 프로그래밍 방식으로 제어하는 인터페이스입니다. Hunch는 127.0.0.1의 로컬 WebSocket을 통해 별도 Chrome 프로필을 열고 페이지를 읽거나 로그인·입력을 수행합니다. Chrome 136 이상에서는 기본 프로필의 CDP 포트 제약 때문에 Hunch 전용 프로필을 사용합니다.
MCP 서버(MCP server): — MCP 서버는 LLM 호스트가 호출할 수 있는 도구와 실행 지침을 제공하는 로컬 또는 원격 프로세스입니다. Hunch의 서버는 Claude Desktop, Cursor 같은 호스트가 자식 프로세스로 실행하며 OS API, AppleScript, CDP, Accessibility 기능을 도구로 노출합니다. 서버가 종료되면 별도 데몬이나 네트워크 엔드포인트 없이 함께 사라집니다.
AppleScript: — AppleScript는 macOS 앱의 스크립팅 인터페이스를 통해 Mail, Music, Finder, Safari 같은 앱의 동작을 자동화하는 언어입니다. Hunch는 osascript를 호출해 스크립트 가능한 앱을 직접 제어하고, 셸 실행이나 삭제·전송 같은 위험한 동작에는 별도 승인 게이트를 적용합니다. 앱별 Automation 권한은 처음 제어할 때 macOS가 요청합니다.

기술

MCP
Python
pyobjc
Accessibility framework
AppleScript
osascript
Chrome DevTools Protocol
WebSocket
Claude
OpenAI Codex
macOS Keychain
Chrome

활용 사례

로그인된 Mail에서 특정 이메일에 답장을 작성하되 전송하지 않는 작업
Mail, Messages, Notes, Calendar, Music, Finder, Safari 같은 native 앱의 background 제어
Chrome 또는 Electron 앱에서 웹 페이지를 읽고 폼을 채우는 자동화
다운로드 폴더의 파일을 Finder를 열지 않고 휴지통으로 보내는 작업
cron job과 테스트 harness에서 LLM 없이 Mac 제어 primitive를 실행하는 자동화
Keychain에 저장한 GitHub 자격 증명을 지정된 도메인에만 입력하는 로그인 흐름

언급된 리소스

DemoHunch

Hunch로 화면을 건드리지 않고 Mac을 제어하는 LLM agent

TL;DR

섹션별 상세

용어 해설

기술

활용 사례

언급된 리소스

관련 토론

댓글

관련 피드

관련 토론

댓글

관련 피드