phone-harness README

The project's README from github.com/ShawnPana/phone-harness. As one markdown file: README.md.

Phone Harness 📱

phone-harness · let your agent control your phone.

Connect Claude Code, Codex, or any agent to your real phone. iPhone through the Mac's iPhone Mirroring window, Android over adb from macOS, Linux or Windows, or a Phone Harness Cloud phone — an Android over adb, or an iPhone over HTTPS. No jailbreak, no Xcode, nothing installed on the phone. The agent sees the screen, taps, types, and reads the result.

  ● agent: wants to open Weather
  │
  ● find_text("Weather") → (400, 468)
  │
  ● tap(400, 468) → reads the screen → forecast is up
  ✓ done

Try Phone Harness Cloud → Hosted iPhones and Androids with stealth, real numbers, 2FA, and unlimited devices

Get started by sending the setup prompt to your coding agent.

Demo

Task: "Buy me a Waymo to Delah Coffee from my current location."

https://github.com/user-attachments/assets/80b6d38e-0222-481c-93db-9de60d79247a

Setup

Paste into Claude Code or 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.

The agent asks which phone is your default and walks you through the parts that need your hands: pairing iPhone Mirroring and granting Accessibility and Screen Recording, or turning on Android developer options and approving adb. It also offers a cloud Android — the same helpers with nothing to pair, and the first 100 minutes free — so an iPhone user can test on Android too. phone-harness --doctor checks the chain. Details in install.md.

Hermes Agent: hermes plugins install ShawnPana/phone-harness/integrations/hermes adds a phone_exec tool and this skill. See integrations/hermes.

Usage

phone-harness <<'PY'
open_app("Notes")
tap_text("New Note")
type_text("hello from the harness")
print([o["text"] for o in screen()][:10])
PY
phone-harness --version

phone-harness --version (or -V) prints phone-harness <version>.

Helpers are pre-imported. SKILL.md is the agent's day-to-day guide; helpers.py is the full list. Task-specific helpers live in ~/.phone-harness/agent-workspace (see install.md). The first run creates that folder from the packaged defaults and never overwrites an existing one. Delete the folder for a fresh default; the next run recreates it. A checkout uses its own agent-workspace/ instead.

No phone on your desk? Rent one

phone-harness cloud login            # once: approve in your browser
phone-harness cloud ls               # phones on the account, and any live session
phone-harness cloud start            # cloud.phone if set, else a temporary Android; 15 min (--for 90s, 15m)
phone-harness cloud start ios        # the account's iPhone, when only one is listed
phone-harness <<'PY'
print(screenshot())
PY
phone-harness cloud stop             # billing stops; a saved Android is written back

cloud ls is the catalog (GET /me → available): each phone's label, platform, and id, with a live session on that row (matched by device id, profile id, or the temporary row). A cloud iPhone session does not echo its catalog id (device is the word "iPhone", and profile is an iphone-… id that matches no catalog row). That session is written on the one catalog row of the same platform and kind whose state is running, when that is the only such row and the only unmatched session of that platform and kind. A session that matches nothing is its own row. cloud start with no name starts this machine's cloud.phone setting if one is set, else what the service gives an unnamed start, a temporary Android. A name is a catalog id or label, or ios / android when only one entry has that platform. A cloud Android is reached over adb, so every helper works on it unchanged. A cloud iPhone has no shell: the helpers POST ops over HTTPS, OCR runs on the host, and driving it is in SKILL.md. phone-harness cloud lists the rest, including watch, open, history, and phone for the saved Android. --session SID (or PHONE_HARNESS_SESSION) pins one rented phone for this process.

Updates

phone-harness update upgrades a uv tool (uv tool upgrade phone-harness) or a git checkout (git pull --ff-only). Any other install prints pip install -U phone-harness and leaves it for you to run. The tool never updates itself. On a terminal, once a day, it prints one line on stderr when PyPI has a newer version. Set PHONE_HARNESS_NO_UPDATE_CHECK=1 to silence that notice.

How it works

iPhone. iPhone Mirroring renders the phone as a Mac window and forwards mouse and keyboard as touches. The harness captures that window, OCRs it with Apple's Vision framework for text with tap-ready coordinates, and posts HID-level events for taps, swipes, and typing.

Android. adb is the transport. screencap is the capture, the phone's accessibility tree is the text source, input is the hands. Works over USB or Wi‑Fi, no window needed.

Cloud iPhone. phone-harness cloud start with that phone's catalog id, label, or ios when it is the only one, drives it over HTTPS from any OS. The host runs OCR; taps use the phone's screen points. No adb and no accessibility tree. Day-to-day steps are in SKILL.md.

Same helpers throughout. phone-harness config set platform ios|android picks the desk default.

Limits

Sponsor

phone-harness is free and maintained in my own time. Sponsoring keeps it that way.

phone-harness (ShawnPana/phone-harness)

Searching Database…

3.8K ·GitHub
Phone-harness
Что это такое?Phone Harness позволяет ИИ-агентам для программирования, таким как Claude Code или Codex, управлять настоящим телефоном — iPhone через окно iPhone Mirroring на Mac, Android через adb или арендованный облачный телефон — без джейлбрейка и без установки чего-либо на сам телефон.
Это утилита командной строки или на телефон что-то придётся устанавливать?Это консольная утилита, которая запускается на вашем компьютере и удалённо наблюдает за экраном телефона и управляет им: агент видит экран, нажимает, печатает и читает результат, а на сам телефон ничего не устанавливается.
Как его запустить?Вы отправляете промпт для настройки своему агенту для программирования (Claude Code или Codex), он спрашивает, какой телефон у вас основной, и проводит вас через связку — iPhone Mirroring с разрешениями Accessibility и Screen Recording либо Android с настройками разработчика и подтверждением adb.
Для управления iPhone обязательно нужен Mac?Да — управление iPhone идёт через окно iPhone Mirroring на Mac, так что этот путь требует macOS, а управление Android через adb работает на macOS, Linux или Windows.
Чего он не умеет?Телефон с PIN-кодом или разблокировка iPhone во время зеркалирования всё ещё требуют участия человека, OCR читает только подписанный текст, поэтому элементы только с иконками требуют модели с поддержкой зрения, а мультитач, камера и Face ID не поддерживаются, и видео с DRM показывается чёрным экраном.
Что такое Phone Harness Cloud?Это сервис аренды настоящих Android- и iPhone-устройств в облаке, где связка не требуется: доступны скрытый режим, настоящие номера телефонов, 2FA и неограниченное число устройств, причём первые 100 минут бесплатны.
Как агент на самом деле видит, что происходит на экране телефона?На iPhone он снимает окно Mirroring и с помощью фреймворка Apple Vision выполняет OCR, получая координаты текста для нажатий; на Android использует adb screencap и дерево accessibility, а затем отправляет нажатия и ввод как HID- или adb-события.
Он работает только с Claude Code и Codex?Нет, он рассчитан на любой агент для программирования, а кроме того есть отдельная интеграция с Hermes Agent, которая ставится командой 'hermes plugins install ShawnPana/phone-harness/integrations/hermes'.
What are similar projects?mobile-mcp, midscene, happy, deepseek-harness-android-app, self-operating-computer, artemis, skills, brag
Which topics is it in?mobile-automation, gui-automation, remote-control, mobile-development, ocr, cloud, mobile, ios, ai-agent, codex, command-line-tool, android
Creator
ShawnPana
Size
0.7 MB
Stars
3.8K
Updated
CommitOct 17Release0.3.2Oct 12
Age
2mo
Commits · 90 Days