leeguooooo/iphone-use

iPhone용 컴퓨터 사용 경험을 구현합니다 — AI 에이전트(및 브라우저)가 실제 휴대폰 화면을 보고 제어할 수 있게 합니다.

English · 简体中文

현재 장치 백엔드: v0.14.0부터 WebDriverAgent를 대체한 자체 XCTest 러너를 사용합니다. API는 WDA와 호환되며, 현재의 제어 기능은 iPhone Mirroring에 의존하지 않습니다.

AI 에이전트가 실제 iPhone을 사용하도록 합니다: 화면을 텍스트로 읽고, 터치하고, 스와이프하며, 타이핑할 수 있으며, 어떤 동작이 실패했는지 명확하게 알려줍니다.

curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh

iphone-use-promo-en.mp4

2분 데모 · 中文版

준비물

• Xcode가 설치되어 있고 Apple ID에 로그인된 Mac (macOS 15 이상) — 무료 계정으로도 가능합니다.
• 개발자 모드가 활성화된 iPhone (설정 → 개인정보 보호 및 보안 → 개발자 모드).
• USB 케이블. 설치하기 전에 iPhone을 연결하고 잠금을 해제하세요.

설치 프로그램은 휴대폰을 설정하고, 에이전트가 '설정' 앱을 열고 내용을 읽는 과정을 보여주며, MCP 서버를 Claude Code에 등록하고, 일회성 로그인(비밀번호 복사할 필요 없음)과 함께 브라우저에서 제어 페이지를 엽니다. 누락된 것이 있으면 무엇인지 그리고 어떻게 수정해야 하는지 알려줍니다.

iphone-use status # 에이전트가 휴대폰을 사용할 준비가 되었는지 확인합니다?
iphone-use doctor # 무엇이 빠졌고, 어떻게 고쳐야 하는지 확인합니다?
iphone-use setup # 휴대폰을 다시 설정합니다 (새 iPhone 또는 Xcode 사용 후).
...

iphone-use는 은행 및 결제 앱처럼 화면 캡처로부터 자체를 숨기는 앱에서도 작동합니다. Mac의 데몬이 iPhone에서 자체 XCTest 기반 장치 러너를 실행하고(WebDriverAgent를 대체했으며 동일한 API를 사용함), 이를 다음과 같이 노출합니다:

• 에이전트 및 스크립트를 위한 HTTP API (/agent/*)
• Claude Code, Claude Desktop 및 기타 MCP 클라이언트를 위한 26개 도구를 갖춘 MCP 서버
• 사용자들을 위한 웹 페이지와 네이티브 iOS 앱 (실시간 화면, 터치, 타이핑).

Mac 자체의 화면, 커서 또는 포커스에는 아무것도 건드리지 않습니다.

설치 프로그램은 에이전트 스킬을 설치하고, Claude Code가 존재하는 경우 MCP 서버를 등록합니다. 다른 모든 MCP 클라이언트는 명령어만 필요하며, 이 Mac에서는 서버가 데몬과 토큰을 스스로 찾습니다:

{
"mcpServers": {
"iphone-use": {
...

또는 HTTP API를 직접 호출할 수 있습니다:

AUTH="Authorization: Bearer $TOKEN"; CTL="X-Phone-Control: 1"
curl -s -H "$AUTH" $HOST/agent/elements # 화면을 텍스트 + 스냅샷 토큰으로 가져옴
curl -s -H "$AUTH" -H "$CTL" -X POST "$HOST/agent/input?return=delta" \
...

모든 응답은 해당 액션이 적용되었는지, 전송되었는지, 아니면 알 수 없는지, 그리고 재시도가 안전한지에 대해 알려줍니다. 가려지거나 숨겨진 요소에 대한 탭이나 기록되지 않은 쓰기는 조용히 통과되는 대신 거부되거나 보고됩니다.

반복하는 작업은 **플로우(flows)**로 유지됩니다: 모델 없이 재생되는 앱별 스크립트로, 토큰 비용이 들지 않습니다. 공식 레지스트리는 leeguooooo/iphone-use-flows이며, 브라우저의 흐름 패널에서 플로우를 기록하고 PR을 통해 게시할 수 있습니다.

에이전트는 플로우를 스스로 찾습니다: 앱에 진입하면 응답 목록에 해당 앱의 플로우가 나열됩니다. 에이전트가 플로우가 없는 앱에서 다단계 작업을 수행한 후, 이 작업을 플로우로 저장할지 묻고; 데몬은 이미 단계를 초안으로 기록해 두었습니다. 데몬은 스스로 레지스트리를 최신 상태로 유지합니다 (IPHONE_USE_FLOWS_NO_AUTO_UPDATE=1을 사용하면 자동 업데이트를 비활성화하고, IPHONE_USE_FLOWS_NO_SUGGEST=1는 저장 제안을 무음 처리합니다).

MCP=~/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp
$MCP flow update # 레지스트리 동기화 (sha256 검사)
$MCP flow list # 사용 가능한 플로우 목록
...

플로우는 또한 재실행 가능한 테스트 스위트($MCP test suite.yaml로 CI에 적합한 종료 코드를 생성)와 크론 라인에서 시작되는 예약 실행을 가능하게 합니다 ($MCP schedule add: 테스트 및 예약 실행 참조).

iphone-use는 자체 XCTest 러너(runner/)를 통해 휴대폰을 구동합니다. v0.14.0에서 WebDriverAgent를 대체했으며 동일한 HTTP API를 사용하므로 드롭인 백엔드입니다. 속도를 위해 구축되었습니다:

• 이는 요소 트리를 속성별로 순회하는 대신, 고정된 속성 세트의 단일 접근성 스냅샷으로 화면을 읽습니다.
• 터치를 직접 합성하며, 동작하기 전에 앱이 유휴 상태가 될 때까지 기다리지 않습니다. 데몬(daemon)은 그 후에 화면이 안정화되었는지 확인합니다.
• 내장 HTTP 서버와 MJPEG 스트림이 있는 작은 애플리케이션 하나이며, 휴대폰에 추가 종속성이 없습니다.

같은 iPhone 13에서 USB를 통해 agent-device를 대상으로 측정했습니다 (2026년 10월):

전체 agent API를 통해, 레이블로 탭하여 안정화된 변경 사항을 반환하는 작업은 iPhone 17 Pro Max에서 약 1.9초가 걸렸습니다. WebDriverAgent 기반의 릴리스는 4.2초가 걸렸습니다. 라이브 뷰 스트림은 초당 27–28 프레임으로 전송됩니다. 각 휴대폰은 자체 데몬과 러너(runner)를 가지므로, 동시에 구동되는 두 대의 휴대폰은 각각 한 대만 구동할 때와 마찬가지로 빠르게 작동합니다.

• 전체 가이드: 브라우저 및 iOS 앱, 흐름(flows) 및 흐름 레지스트리(flow registry), 생명 주기(lifecycle), 구성, 보안, 개발.
• Agent API 참고 자료 · MCP 도구 · 아키텍처 · 장치 설정 함정 · 장치 러너
• 보안 한 줄 요약: 비밀번호는 포트 44321만 보호합니다. 휴대폰의 러너 자체 포트는 인증되지 않으므로, 신뢰할 수 있는 네트워크를 사용하십시오 (자세히 보기).
• 이슈 및 아이디어: GitHub 이슈.

AI 에이전트에게 실제 한 가지 사물에 대한 손을 쥐여주는 작고 조합 가능한 CLI입니다. 어디서나 같은 형태: curl … install.sh | sh

설치하려면, JSON을 stdout으로 받고, 에이전트가 이를 구동하도록 가르치는 보조 스킬(skill)이 필요합니다 — 각 리포지토리의 README에 해당 스킬을 설치하는 방법이 나와 있습니다. 왜냐하면 올바른 방법은 프로젝트와 릴리스마다 다르기 때문입니다.