# Phone Harness

Control the user's phone - an iPhone through the Mac's iPhone Mirroring window, an...

- Repository: https://github.com/ShawnPana/phone-harness (4052 stars)
- Category: Mobile
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ShawnPana/phone-harness --skill phone-harness -g -a claude-code -y`
Codex: `npx skills add ShawnPana/phone-harness --skill phone-harness -g -a codex -y`
Cursor: `npx skills add ShawnPana/phone-harness --skill phone-harness -g -a cursor -y`
Gemini CLI: `npx skills add ShawnPana/phone-harness --skill phone-harness -g -a gemini-cli -y`

## Description

Control the user's phone - an iPhone through the Mac's iPhone Mirroring window, an Android over adb, a rented cloud Android, or a cloud iPhone over HTTPS: open apps, tap, type, swipe, read the screen.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# phone-harness

The main helpers are listed in [Helpers](#helpers).

Direct control of a phone from Python scripts. The same helpers drive every
kind of phone below; what differs is how each one sees and touches the screen,
and that is what the per-phone sections below are for. Read **Which phone**, the
shared **Working method**, and then only the section for the phone in front
of you.

## Setup

Check what this machine can do (OS, shell, install rights, network,
attached phones; `phone-harness doctor` does the phone part), tell the user
in a sentence or two which phone you can drive with what is here, and use
the best one that actually runs. A phone on the desk wins; the cloud needs
no hardware and is always the fallback.

| Mode | Needs |
| --- | --- |
| Personal iPhone | macOS 15+, iPhone Mirroring paired to an iOS 18+ iPhone, Accessibility + Screen Recording for the app that runs Python |
| Android on the desk | macOS, Linux or Windows; adb; USB debugging (or Wireless debugging, Android 11+) |
| Cloud iPhone | HTTPS to phone-harness.com hosts; a signed-in account. No adb, any OS |
| Cloud Android | the cloud iPhone list, plus adb and outbound TCP to the phone's adb port |
| No install possible | HTTPS and an HTTP client: the API directly |

- If something is missing, name it and the one step the user can take.
- Ask the user only to approve sign-in and to pick a phone.
- Detail: [iPhone](https://github.com/ShawnPana/phone-harness/blob/main/setup/ios.md), [Android](https://github.com/ShawnPana/phone-harness/blob/main/setup/android.md),
  [Cloud](https://github.com/ShawnPana/phone-harness/blob/main/setup/cloud.md), [API](https://github.com/ShawnPana/phone-harness/blob/main/setup/api.md).

## Helpers

The rest: https://github.com/ShawnPana/phone-harness/blob/HEAD//SKILL.md