Phone Harness 📱

phone-harness · 에이전트가 사용자의 휴대폰을 제어하도록 하세요.

Claude Code, Codex 또는 모든 에이전트를 실제 휴대폰에 연결하세요. Mac의 iPhone Mirroring 창을 통한 iPhone, macOS, Linux 또는 Windows에서 adb를 통한 Android, 또는 Phone Harness Cloud 휴대폰(adb를 통한 Android 또는 HTTPS를 통한 iPhone)을 통해 가능합니다. 탈옥(jailbreak) 필요 없음, Xcode 불필요, 휴대폰에 설치할 것 없음. 에이전트는 화면을 보고, 터치하고, 타이핑하며, 결과를 읽습니다.

  ● agent: 날씨 앱 열기 원함
  │
  ● find_text("Weather") → (400, 468)
...

Phone Harness Cloud를 사용해 보세요 → 은닉성(stealth), 실제 번호, 2FA 및 무제한 장치가 제공되는 호스팅된 iPhone 및 Android.

setup prompt를 코딩 에이전트에게 보내 시작하세요.

데모

작업: "현재 위치에서 Waymo가 Delah Coffee까지 저를 태워다 주세요."

설정

Claude Code 또는 Codex에 붙여넣으세요:

Install or upgrade phone-harness to the latest stable version with uv using Python 3.12, register the skill from `phone-harness skill`, then read https://github.com/ShawnPana/phone-harness/blob/main/onboarding.md and walk me through it. Follow https://github.com/ShawnPana/phone-harness/blob/main/install.md if setup or connection fails.

에이전트는 어떤 휴대폰이 기본값인지 물어보고, 사용자의 손이 필요한 부분(iPhone Mirroring 페어링 및 접근성(Accessibility)과 화면 녹화(Screen Recording) 부여, 또는 Android 개발자 옵션 켜기 및 adb 승인)을 안내합니다. 또한 클라우드 Android도 제공하며 — 아무것도 페어링할 필요가 없고 첫 100분은 무료입니다 — 따라서 iPhone 사용자도 Android에서 테스트할 수 있습니다.
phone-harness --doctor는 체인을 확인합니다. 자세한 내용은 install.md를 참고하세요.

Hermes Agent: hermes plugins install ShawnPana/phone-harness/integrations/hermes를 추가하면 phone_exec 도구와 이 스킬이 추가됩니다. 자세한 내용은 integrations/hermes를 참조하세요.

사용법 (Usage)

phone-harness <<'PY'
open_app("Notes")
tap_text("New Note")
...

phone-harness --version (또는 -V)을 실행하면 phone-harness <버전>이 출력됩니다.

도움말(Helpers)은 기본적으로 가져와집니다. SKILL.md는 에이전트의 일상 가이드이며, helpers.py에 전체 목록이 있습니다. 작업별 도움말은 ~/.phone-harness/agent-workspace에 위치합니다 (자세한 내용은 install.md 참조). 첫 실행 시 이 폴더가 패키징된 기본값으로 생성되며 기존 폴더를 덮어쓰지 않습니다. 새로운 기본값을 사용하려면 해당 폴더를 삭제하세요. 다음 실행 시 폴더가 다시 생성됩니다. 체크아웃(checkout)의 경우 대신 자체 agent-workspace/를 사용합니다.

책상 위에 전화기가 없나요? 대여하세요 (No phone on your desk? Rent one)

phone-harness cloud login            # 최초 1회: 브라우저에서 승인 필요
phone-harness cloud ls               # 계정의 전화기 목록 및 활성 세션 확인
phone-harness cloud start            # 설정된 경우 cloud.phone, 아니면 임시 Android 기기를 사용합니다; 15분 (예: --for 90s, 15m)
...

cloud ls는 카탈로그(GET /me → available)입니다. 여기에는 각 전화기의 레이블, 플랫폼 및 ID가 포함되며, 해당 행에 실시간 세션이 표시됩니다 (장치 ID, 프로필 ID 또는 임시 행으로 일치). 클라우드 iPhone 세션은 자체 카탈로그 ID를 반향하지 않습니다 (device는 "iPhone"이며, profile은 어떤 카탈로그 행과도 일치하지 않는 iphone-… ID입니다). 해당 세션은 같은 플랫폼 및 종류의 단 하나의 카탈로그 행 중 state가 running인 경우에만 기록됩니다. 이때 그 행이 유일한 그러한 행이며, 해당 플랫폼 및 종류의 유일한 미매칭 세션이어야 합니다. 아무것도 일치하지 않는 세션은 자체적인 행을 가집니다. 이름 없이 실행하는 cloud start는 설정된 경우 이 기계의 cloud.phone 설정을 시작하며, 그렇지 않으면 서비스가 임시 Android를 할당하여 이름을 지정하지 않고 시작합니다. 이름은 카탈로그 ID 또는 레이블이거나, 해당 플랫폼에 대한 항목이 하나만 있는 경우 ios / android입니다. 클라우드 Android는 adb를 통해 도달하므로 모든 헬퍼가 변경 없이 작동합니다. 클라우드 iPhone은 셸을 가지고 있지 않습니다: 헬퍼들은 HTTPS를 통해 POST 작업을 수행하고, OCR은 호스트에서 실행되며, 구동은 SKILL.md에 있습니다. phone-harness cloud는 저장된 Android의 watch, open, history, 그리고 phone을 포함하여 나머지를 나열합니다. --session SID (또는 PHONE_HARNESS_SESSION)은 이 프로세스를 위해 임대된 전화기 하나를 고정합니다.

업데이트

phone-harness update는 uv 도구(uv tool upgrade phone-harness) 또는 git 체크아웃(git pull --ff-only)을 업그레이드합니다. 다른 모든 설치는 pip install -U phone-harness를 출력하고 사용자가 실행하도록 남겨둡니다. 이 도구는 스스로 업데이트하지 않습니다. 터미널에서 하루에 한 번, PyPI에 새 버전이 있으면 표준 오류(stderr)에 한 줄을 출력합니다. 해당 알림을 무음으로 설정하려면 PHONE_HARNESS_NO_UPDATE_CHECK=1를 설정하십시오.

작동 방식

iPhone. iPhone 미러링은 전화기를 Mac 창처럼 렌더링하고 마우스 및 키보드를 터치로 전달합니다. 이 하네스(harness)는 해당 창을 캡처하고, Apple의 Vision 프레임워크를 사용하여 텍스트와 터치 준비 좌표로 OCR을 수행하며, 터치, 스와이프 및 타이핑에 대한 HID 레벨 이벤트를 게시합니다.

Android. adb가 전송(transport)을 담당하고, screencap이 캡처를, 휴대폰의 접근성 트리(accessibility tree)가 텍스트 소스를 제공하며, input이 사용자의 손 역할을 합니다. USB 또는 Wi-Fi를 통해 작동하며, 별도의 창이 필요하지 않습니다.

클라우드 iPhone. 해당 휴대폰의 카탈로그 ID, 레이블 또는 유일한 경우 ios로 phone-harness cloud start 명령을 사용하여 어떤 OS에서도 HTTPS를 통해 구동할 수 있습니다. 호스트가 OCR을 실행하며, 탭(taps)은 휴대폰 화면의 좌표를 사용합니다. adb나 접근성 트리가 필요하지 않습니다. 일상적인 단계는 SKILL.md에 나와 있습니다.

어떤 경우에도 동일한 도우미가 작동합니다. phone-harness config set platform ios|android 명령으로 기본 플랫폼을 설정할 수 있습니다.

제한 사항 (Limits)

• iPhone 잠금 해제는 미러링(mirroring)을 일시 중지시키며, PIN으로 잠긴 Android의 경우 사용자 개입이 필요합니다.
• OCR은 텍스트만 인식하며 아이콘은 인식하지 못합니다. 레이블이 지정되지 않은 컨트롤은 스크린샷과 시각 능력이 있는 모델이 필요합니다.
• 멀티터치(multi-touch), 카메라 또는 Face ID 흐름은 지원하지 않습니다. DRM 비디오는 검게 처리됩니다.
• 휴대폰 연결은 항상 사용자의 몫입니다.

스폰서 (Sponsor)

phone-harness는 무료이며 제가 개인적인 시간에 유지보수하고 있습니다. 스폰서하기를 통해 이 상태를 유지할 수 있습니다.