To3akaRin/mac-computer-use

Enable any LLM to control your computer with cross-platform support, featuring 3D modeling examples and live demos.

TL;DR

mac‑computer‑use 는 대규모 언어 모델 기반 에이전트가 macOS 데스크탑을 제어할 수 있도록 해주는 오픈소스 에이전트 기술입니다. macOS Accessibility (AX) 또는 Chrome DevTools Protocol (CDP) 를 통해 창과 UI 요소를 관찰하고, 클릭/키 입력을 전송하며, 결과를 검증할 수 있으며, 오픈된 에이전트 기술 사양 을 따르는 로컬 명령줄 도구에서 실행됩니다.

무엇을 할 수 있나요 (간단한 언어로)

관찰 – 열린 앱 목록, 창의 기하학적 정보, UI 컨트롤(버튼, 텍스트 필드 등)을 읽고, Chromium 기반 창의 경우 CDP를 통해 페이지의 DOM을 조사합니다.
작업 – 네이티브 macOS 입력 이벤트(클릭, 호버, 스크롤, 타이핑) 또는 CDP 입력 명령을 보내 타겟 UI와 상호작용합니다.
검증 – UI 상태를 다시 읽고, ScreenCaptureKit을 통해 스크린샷을 캡처하고, 구조화된 JSON을 반환하여 에이전트가 작업이 성공했는지 알 수 있게 합니다.

이 모든 워크플로우는 에이전트 기술 사양 을 지원하는 어떤 에이전트 런타임(Claude Code, Codex, Cursor 등)이라도 로드하고 호출할 수 있는 기술 로 패키지화되어 있습니다.

누구에게 유용할까요

macOS 애플리케이션 자동화가 필요한 AI 어시스턴트를 개발하는 개발자 (예: 파일 열기, 폼 채우기, 스크립트 실행 등, 사용자 정의 AppleScript나 Selenium 코드를 작성하지 않고도 가능).
신체화된 AI(embodied AI)를 실험하는 연구자 (LLM이 실제 데스크탑을 조작할 수 있는 재현 가능하고 격리된 환경이 필요함).
순수 쉘 명령어로 표현하기 어려운 UI 작업을 스크립트로 만들고 싶은 파워 유저 (즉시 사용 가능한 CLI를 원함).

시작하기 (단계별)

기술 설치: Vercel Skills CLI를 통해 설치:
```
npx skills add To3akaRin/mac-computer-use
```
이 명령어는 mac-computer-use/ 디렉터리를 로컬 기술 저장소에 복사합니다.
맥이 요구 사항을 충족하는지 확인:
- macOS 14 이상, Apple Silicon (Intel은 작동할 수 있지만 테스트되지 않음).
- Xcode Command‑Line Tools (Swift 6) – xcode-select --install.
- Node 22.4+ (CDP 부분만 필요).
- 터미널 또는 실행할 에이전트 앱에 접근성 및 화면 녹화 권한을 부여합니다.
간단한 관찰 명령어 실행: 사용 가능한 창 목록 확인:
```
./.skills/mac-computer-use/scripts/run.sh native windows
```
출력은 각 창의 ID, 제목, 크기, 프로세스를 포함하는 JSON입니다.
창 선택 후 UI 조사 (TextEdit 예시):
```
./.skills/mac-computer-use/scripts/run.sh native ax \
    --window <WINDOW_ID> \
    --snapshot-out ./artifacts/window.json
```
해당 창 내의 모든 Accessibility 요소에 대한 JSON 설명을 파일로 저장합니다.

작업 수행 – 예: 첫 번째 텍스트 필드에 "Hello" 입력:

./.skills/mac-computer-use/scripts/run.sh native type \
    --window <WINDOW_ID> \
    --element "AXTextField" \
    --text "Hello"

검증 – 필드 내용을 다시 읽거나 스크린샷 캡처:
```
./.skills/mac-computer-use/scripts/run.sh native shot \
    --window <WINDOW_ID> \
    --output ./artifacts/after.png
```
JSON 결과로 텍스트가 올바르게 설정되었는지 에이전트가 판단할 수 있습니다.

모든 명령어는 --dry-run 플래그를 지원하며, 실제로 입력을 보내지 않고 파라미터를 검사할 수 있어 안전성에 유용합니다.

핵심 기술 세부사항 (관심 있는 분들을 위해)

요소	구현 방식
언어	네이티브 macOS 도구는 Swift 6, CDP 상호작용은 Node.js 스크립트
UI 관찰	네이티브 앱은 macOS Accessibility (AX) API, Chromium 기반 창은 Chrome DevTools Protocol (CDP)
입력 생성	네이티브 앱은 `CGEvent` 기반 마우스/키보드 이벤트, 웹 페이지는 CDP `Input` 도메인 (`click`, `insertText` 등)
검증	AX 값 읽기, CDP 읽기 전용 확인, ScreenCaptureKit을 통한 스크린샷 캡처
패키징	오픈된 에이전트 기술 사양 준수 – `SKILL.md` 메타데이터 파일과 런타임이 호출하는 `scripts/` 런처
런타임 npm 종속성 없음	CDP 클라이언트는 초소형 자체 포함 스크립트. 별도 서버나 API 키 필요 없음
안전 규칙	• 사용자 비활동 ≥2초 후, ≤15초 대기 후에만 작업. • `--dry‑run` 미리보기 모드. • 오래된 창 스냅샷은 거부.
출력 형식	`target`, `channel` (native 또는 cdp), `status` (`success`, `unknown`, `refused`), 증거(스크린샷, AX 읽기 결과)를 포함하는 JSON 객체

제한 사항 및 미해결 질문

앱 커버리지 – AX 트리가 명확하게 노출되거나 CDP 포트를 제공하는 앱에서는 즉시 작동. 일부 제3자 도구는 사용자 정의 컨트롤로 인해 탐색이 어려울 수 있음.
Intel/macOS 14 – 공식적으로 검증되지 않음. CI는 Apple Silicon/macOS 15에서 실행.
원격 실행 불가 – 기술은 맥에서 로컬로 실행되어야 하며, Linux 사전 환경에서는 데스크탑을 제어할 수 없음.
문서 언어 – 대부분의 가이드(references/*.md)는 현재 중국어로 작성되어 있어 비중국어 기여자에게 장벽이 될 수 있음.

빠른 참조 체크리스트

명령어	목적	예시
`native windows`	모든 창 목록	`run.sh native windows`
`native ax`	창의 Accessibility 트리 덤프	`run.sh native ax --window 123 --snapshot-out out.json`
`native type`	특정 AX 요소에 텍스트 입력	`run.sh native type --window 123 --element AXTextField --text "Hi"`
`native click`	좌표 또는 AX 경로로 UI 요소 클릭	`run.sh native click --window 123 --point 0.5,0.2`
`cdp snapshot`	Chromium 페이지의 DOM과 스크린샷 캡처	`node scripts/cdp.mjs snapshot --endpoint http://127.0.0.1:9222 --target PAGE_ID`
`native doctor`	자기 진단 (권한, Swift, Node)	`run.sh native doctor`

결론

mac‑computer‑use 는 어떤 LLM 기반 에이전트라도 호출할 수 있는 결정론적이고 관찰-작업-검증 가능한 macOS 데스크탑 인터페이스를 제공합니다. 클라우드 서비스 없이 고수준 언어 추론과 저수준 UI 조작 사이의 갭을 메우며, 자율적인 macOS 에이전트를 위한 견고한 빌딩 블록이 됩니다.