phone-harness: driving a real iPhone or Android from an agent loop
let your agent control your phone
At a glance
- What is it?
- phone-harness is a Python command-line tool that exposes a real phone to a coding agent as a set of pre-imported helpers: screenshot, OCR, tap, swipe, type. It picks between iPhone Mirroring on macOS and adb on Android, and it ships an install prompt rather than a package. The core judgement: the helper surface is small enough to reason about, but the OCR-only text model and the manual pairing steps define the real ceiling.
- Who is it for?
- Adopt phone-harness if you already run a coding agent on macOS with a paired iPhone, or on any host with an Android device reachable over adb, and your task is text-driven navigation of app screens. Skip it if your flow depends on icons without labels, multi-touch gestures, camera or Face ID, or DRM video, because the README states those are outside the tool's reach.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap phone-harness fills: a phone as a tool call
Most agent tooling stops at the browser. Anything behind an app login, a native settings pane or a push notification is out of reach, and the usual workarounds are emulators that do not match the device or a manual script per task. phone-harness takes a different position: the phone is already there, so treat it as an input and output surface. The README states the pitch plainly, "let your agent control your phone", and the target reader is someone running Claude Code, Codex or another coding agent who wants that agent to operate a physical handset. Two constraints shape the design. Nothing is installed on the phone, and there is no jailbreak and no Xcode involved. The audience is therefore developers and automation builders who own the device and are comfortable granting Accessibility and Screen Recording permissions on a Mac, or enabling developer options on Android. It is not aimed at remote device farms; the repository points at a separate hosted product for that.
Two transports, one helper vocabulary
The mechanism differs by platform but the surface the agent sees does not. On iPhone, the README explains that iPhone Mirroring renders the handset as a Mac window and forwards mouse and keyboard input as touches. The harness captures that window, runs OCR through Apple's Vision framework to get text with tap-ready coordinates, and posts HID-level events for taps, swipes and typing. On Android, adb is the transport: screencap for capture, the phone's accessibility tree as the text source, and input for the gestures. That distinction matters more than it first appears. iOS text comes from pixels through OCR, so it is only as good as the rendering. Android text comes from the accessibility tree, so it is structured data that happens to be exposed by the running app. Both paths converge on the same helper names, which is why a script written against one platform can be retargeted with a single config change. The default is chosen with phone-harness config set platform ios|android.
The heredoc usage pattern and what is pre-imported
There is no library import ceremony in the documented flow. The README shows the tool invoked with a heredoc, where the Python body runs with helpers already in scope. The example calls open_app("Notes"), tap_text("New Note"), type_text("hello from the harness") and then prints the first ten OCR results via [o["text"] for o in ocr()][:10]. That last line is the important one for anyone building a loop: ocr() returns objects carrying a text field and coordinates, which is what makes find_text and tap_text possible. The README points to two files for depth. SKILL.md is described as the agent's day-to-day guide, and src/phone_harness/helpers.py is given as the full list of helpers. If you are evaluating the tool, helpers.py is the file to read first, because the README only names a handful of the available calls and the rest are unlisted in the material available here.
Installation is delegated to the agent, not to pip
The setup path is unusual and worth reading carefully. Rather than a package install command, the README gives a prompt to paste into Claude Code or Codex. That prompt instructs the agent to clone the repository into ~/.phone-harness, read install.md first, install it so phone-harness is a command on PATH, and register it as an agent skill named phone-harness using phone-harness skill as the body. The agent is then told to read onboarding.md and walk the user through it. This is a deliberate choice: the remaining steps cannot be automated because they need human hands. The README lists them as pairing iPhone Mirroring and granting Accessibility and Screen Recording, or turning on Android developer options and approving the adb prompt. A single command, phone-harness --doctor, checks the chain. The README does not enumerate the individual config keys beyond platform, so treat the config surface as largely undocumented in the supplied material.
Where the harness stops: OCR, icons and locked screens
The limits section is unusually candid and should drive the adoption decision. Unlocking an iPhone pauses mirroring, and a PIN-locked Android needs the user, so any flow that begins at a lock screen is not fully autonomous. OCR sees text, not icons, which means unlabeled controls require a screenshot plus a vision-capable model, adding a second inference step to every ambiguous tap. There is no multi-touch, so pinch-to-zoom and two-finger gestures are out. Camera and Face ID flows are excluded, which rules out anything needing a live capture or a biometric prompt. DRM video renders black, so media verification tasks will read an empty frame. Finally, connecting the phone is always the user's job. Read together, these constraints describe a tool for text-shaped tasks inside already-unlocked apps, not a general device automation framework. A task like the README's Waymo-to-coffee demo fits because the app surfaces are text-heavy. A task built on an icon-only canvas does not.
How it compares to Appium and adb scripting
The obvious alternative for Android is Appium, which drives apps through WebDriver and expects instrumented builds or a driver server on the device. The difference in approach is structural. Appium targets app internals through a test-oriented protocol and gives you element selectors tied to the app's view hierarchy. phone-harness targets the screen as a user sees it, through OCR or the accessibility tree, and gives you coordinates and text matches. That makes phone-harness weaker at asserting on specific widgets and stronger at operating apps you did not build and cannot instrument. Against a hand-rolled adb script, the difference is the helper layer and the iOS path: adb alone gives you screencap and input with no text extraction and no iPhone story at all. If your work is regression testing your own Android app, Appium's selectors will be more precise. If your work is having an agent complete a task in someone else's app on a phone you own, the harness is the closer fit.
Maintenance, releases and the MIT licence
The project is MIT licensed, which permits commercial use, modification and redistribution provided the licence text is retained. This is not legal advice; check the LICENSE file in the repository for the exact terms before shipping anything derived from it. On versioning, the releases listed are 0.1.0 and 0.2.0, the latter tagged with Android, and the last push is dated 2026-09-10, after the 0.2.0 release on 2026-08-18. Pre-1.0 numbering means the helper signatures and config keys can change between minor versions, so pinning to a specific clone rather than tracking main is the safer posture if you build on top of it. The README states the project is free and maintained in the author's own time, with sponsoring as the support channel. There is no published deprecation policy or compatibility table in the supplied material, so upgrade cost is genuinely unknown; the practical check is to re-read helpers.py after any version bump and confirm the calls your scripts use still exist.
Editorial conclusion
Adopt phone-harness if you already run a coding agent on macOS with a paired iPhone, or on any host with an Android device reachable over adb, and your task is text-driven navigation of app screens. Skip it if your flow depends on icons without labels, multi-touch gestures, camera or Face ID, or DRM video, because the README states those are outside the tool's reach. Before you commit, run phone-harness --doctor and confirm the whole chain reports healthy, then read install.md and onboarding.md to see exactly which steps still require your hands.
Community notes