phone-harness

Mobile app automation has historically meant jailbreaking a phone, wiring up Appium or XCUITest, or installing an SDK on the device just to let a script tap around. phone-harness sets out to remove all three requirements. It connects an existing coding agent, such as Claude Code or Codex, to a real phone the same way a human would use one: it looks at the screen and taps, types and scrolls. iPhone control runs through macOS's built-in iPhone Mirroring feature, so the phone is mirrored as a window and inputs are forwarded as touches; Android control goes over adb from macOS, Linux or Windows. Nothing is installed on the phone itself, and no jailbreak or Xcode toolchain is required.

Every platform is driven through one shared set of Python helpers (open_app, tap_text, type_text, ocr, scroll and similar), so the same automation script works whether the connected device is an iPhone or an Android phone. Behind that interface, the project handles a long list of real-world edge cases documented in its commit history: driving the phone in the background without stealing window focus, distinguishing scroll gestures per app, detecting a dead mirroring session structurally rather than by matching UI text, and reading focus live to confirm an app activation actually worked. For people without a spare device, a paid Phone Harness Cloud add-on rents an Android phone by the minute over the same adb interface, so every existing helper keeps working unchanged.

The obvious audience is developers who want an agent to exercise a real mobile app: testing a checkout flow, filing a support ticket that requires 2FA, or automating a task an official API does not expose. Because setup is a single paste-in prompt that a coding agent executes itself (cloning the repo, installing the CLI, registering it as an agent skill and walking through pairing), it is aimed at people already comfortable handing agents shell access rather than configuring a device farm by hand. The cloud rental option extends that to anyone without a spare iPhone or Android device to dedicate to automation.

Development is effectively a one-person effort: of roughly 98 commits, 97 come from a single author, with just one external contributor fixing a scroll-detection bug. Telemetry via PostHog is on by default and opt-out rather than opt-in, sending one event per CLI run. The README is built around driving usage toward the paid Phone Harness Cloud service, with UTM-tagged links in nearly every section, a legitimate but worth-noting commercial angle for an otherwise MIT-licensed open-source tool. Full iPhone automation is also tied to macOS specifically, since iPhone Mirroring is a Mac-only feature; there is no path to drive an iPhone from Linux or Windows.

phone-harness solves a real, previously awkward problem, letting an agent operate a genuine phone without jailbreaking it or shipping a companion app, and its 40 open issues and three shipped releases in six weeks suggest people are actually using it rather than just starring it. It is worth adopting if you want agent-driven phone automation today and are fine with a single maintainer, default-on telemetry, and a cloud upsell woven through the docs. It is too early if you need a project with distributed maintainership, want telemetry off unless explicitly enabled, or need iPhone automation from something other than a Mac.