How to Use Phone Harness: The Beginner's Guide (Let Your Coding Agent Control Your Real Phone)

CodexFuse Team · 2026-11-03T10:40:29.189Z · 10 min read min read

Learn how to use Phone Harness: install it with uv, register the phone-harness skill, pair your iPhone or Android, and let Claude Code or Codex see the screen, tap, type, and read the result — no jailbreak, no Xcode.

Learning how to use Phone Harness hands your coding agent the one device it has never been able to touch: your phone. Phone Harness is an open-source Python tool that lets Claude Code, Codex, or any agent use your real phone. As its GitHub README puts it, "The agent can scroll, tap, type, and read your phone with no jailbreak, no Xcode, and nothing installed on the phone." The agent sees the screen, taps, types, and reads the result — and you never leave your terminal.

This phone harness tutorial walks you from a fresh shell to your first agent-driven phone task: installing with uv, registering the phone-harness skill, pairing an iPhone or an Android over adb, running the first task, and using cloud phones when you do not want to touch a physical device. If you have never driven a coding agent from your terminal, the Claude Code beginner guide is the right warm-up; everything here assumes you can launch at least one supported agent. One disambiguation up front: this is ShawnPana's open-source phone-harness (the repository moved to the phone-harness org on GitHub), not a chest-strap phone tether, not "Harness by Autonomous" (a different coding-agent product), and not DeepSeek-phone-harness, an unrelated community project that turns a phone into a remote for a DeepSeek agent running on a computer.

What Is Phone Harness, Exactly?

Phone Harness is the most popular open-source harness for phone automation, per its Y Combinator F2026 directory listing, with 4,127 GitHub stars and 415 forks at the time of writing (the YC page's "3,800+ stars" figure is already stale). The repository is MIT-licensed, was created on August 7, 2026, and is maintained by its creator in his own time — "phone-harness is free and maintained in my own time," the README says. It connects to a real phone in three ways: an iPhone through the Mac's iPhone Mirroring window, an Android over adb from macOS, Linux, or Windows, or a Phone Harness Cloud phone — an Android over adb or an iPhone over HTTPS, per the current PyPI page for version 0.3.2.

How Do You Use Phone Harness?

The whole arc fits in five steps. Each step below gets its own section, so you can jump to wherever you are stuck:

1. Install phone-harness with uv on Python 3.12 and make sure the phone-harness command is on your PATH.
2. Register the skill by running phone-harness skill, then feed your agent the onboarding prompt.
3. Pair your phone: iPhone through Mac iPhone Mirroring (macOS 15+, iOS 18+, Accessibility and Screen Recording permission), or Android with adb and USB debugging over USB or Wi-Fi.
4. Run your first task — open an app, tap text, type text, read the screen back.
5. Go further with cloud phones, the MCP endpoint, or the Hermes and OpenClaw plugins.

How to Install Phone Harness

A phone harness install has two routes, and the documented default is the quick one. Install or upgrade phone-harness to the latest stable version with uv using Python 3.12 — that is the README's own setup wording. The fastest path is the setup prompt the project hands your agent:

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/phone-harness/phone-harness/blob/main/onboarding.md and walk me through it. Follow https://github.com/phone-harness/phone-harness/blob/main/install.md if setup or connection fails.

Paste that prompt to your agent and it walks you through the rest. Behind the scenes it does three things: puts the phone-harness command on your PATH, registers phone-harness as an agent skill via phone-harness skill, and has you read the onboarding doc. If you prefer doing it yourself, the manual route is cloning into ~/.phone-harness and following install.md. Upgrades later are one command: phone-harness update (uv tool upgrade, or git pull --ff-only for the clone route). If Codex is the agent you drive, the Codex beginner guide covers launching it; the harness itself is agent-agnostic.

Phone Harness on iPhone

Every phone harness iPhone setup goes through the Mac's iPhone Mirroring window, and iPhone pairing requires a Mac — say it once, because it is the single most common surprise. You need macOS 15 or newer, an iPhone running iOS 18 or newer already paired with the Mac's iPhone Mirroring, plus the Accessibility and Screen Recording permissions granted. The harness captures the iPhone Mirroring window, OCRs it with Apple's Vision framework, and posts HID-level events for taps, swipes, and typing — which is why nothing needs to be installed on the phone itself. Set the platform with phone-harness config set platform ios, then diagnose the connection with phone-harness --doctor. One limit to know: unlocking the iPhone pauses mirroring, and "connecting the phone is always the user's job" — the README's own trust anchor, quoted by the dev.to critique linked in Sources.

Phone Harness on Android

A phone harness Android setup needs only two things: adb and USB debugging enabled on the phone. It works from macOS, Linux, or Windows — no Mac required. The mechanism is refreshingly plain: screencap captures the screen, the phone's accessibility tree is the text source, and input is the harness's hands. Point the harness at your device with phone-harness config set platform android, verify with phone-harness --doctor, and the agent gains the same helpers it has on iPhone: open_app(), tap_text(), type_text(), find_text() for coordinates, tap(x, y), ocr()/screen(), screenshot(), ensure_device(), and wait_stable(). A PIN-locked Android needs the user to unlock it first.

Your First Task: Let the Agent Touch the Phone

Once --doctor is green, the classic first task is Notes. The README's own usage example is the whole API in miniature:

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

That is the pattern for everything: open an app, find text, tap or type, read the screen back. The README's demo section shows the same loop doing something real: Task: "Buy me a Waymo to Delah Coffee from my current location" — a GIF of an agent ordering a Waymo on a real iPhone. Start with harmless tasks before anything that costs money; the dev.to guardrails critique (October 12, 2026) recommends a spare device or secondary account, running --doctor first, and opening Notes before handing the agent anything with a price tag.

Cloud Phones, the MCP Endpoint, and Agent Plugins

Phone harness pricing splits into two parts. The tool itself is free and open source, forever. If you do not want to touch a physical device, Phone Harness Cloud gives you hosted phones: phone-harness cloud login, cloud ls, cloud start, cloud stop. Cloud Androids start as temporary 15-minute sessions by default (--for 90s, 15m sets the length) and every helper works unchanged over adb; cloud iPhones are driven over HTTPS instead, with no adb and no accessibility tree. Pricing from phone-harness.com, current at writing: new accounts start with a $5 credit for Android emulators at 5 cents per minute, cloud iPhones are a flat subscription — $80 per month, $64 per month billed annually, or $100 per month with eSIM — and dedicated reserved phones are custom pricing. Real phones are never billed by the minute, and the harness itself stays free and open source.

Two integration branches are worth knowing. There is an MCP endpoint at https://mcp.phone-harness.com/mcp — cloud phones only for now — plus a Hermes Agent plugin (hermes plugins install phone-harness/phone-harness/integrations/hermes, which exposes a phone_exec tool) and an OpenClaw plugin (openclaw plugins install clawhub:phone-harness). If OpenClaw is your agent, the OpenClaw beginner guide covers the plugin workflow this plugs into.

Phone Harness vs Ghosthand

Ghosthand is the closest commercial alternative, and the comparison is honest rather than lopsided. Per ghosthand.dev, read today: "Control real iPhones from a Mac. Screenshots over USB, taps over Bluetooth. No jailbreak, no Xcode, no app on the phone." It installs with npx ghosthand setup, is Mac-only (macOS 14+, USB + Bluetooth pairing), and is free for one iPhone or $99 per month per Mac for unlimited iPhones — the $99 figure independently corroborated by thetoolnerd's October 27, 2026 roundup. The one-line difference: Ghosthand is a paid, Mac-only, iPhone-only tool; Phone Harness is open source (MIT), covers iPhone and Android plus cloud phones, and registers as a skill inside whatever agent you already run. PhoneCLI from the HKU Data Intelligence Lab is a different beast entirely — a research project that compiles an app's navigation into pre-built callable commands via an offline crawler instead of live GUI exploration.

Five Beginner Mistakes That Break the Harness

These come from the README's limits section, the install docs, and the dev.to critique — all read today:

Phone Harness assumes you already drive an AI coding agent from your terminal — it is a skill your agent loads, not a new agent to learn. The Aider beginner guide covers the agent-driven terminal workflow this tool plugs into, if that pattern is new to you.

Phone Harness Tutorial: Three Harmless First Tasks

A good first session is three tasks, each under a minute: open Notes and type a line (the open_app / tap_text / type_text loop above), take a screenshot and read it back with screen(), then use find_text() to tap a specific label by coordinates. If all three work, ensure_device() and wait_stable() become your guardrails inside longer scripts.

Sources

• Phone Harness on PyPI (version 0.3.2, uploaded Oct 12, 2026) — https://pypi.org/project/phone-harness/0.3.2/
• Phone Harness GitHub repository (phone-harness/phone-harness, MIT) — https://github.com/phone-harness/phone-harness
• phone-harness.com — cloud pricing and the "no jailbreak, no API, no app to install" hero claim
• Y Combinator F2026 company directory listing for Phone Harness
• renolu, "phone-harness gives your agent a real phone, while its README leaves guardrails unspecified," dev.to, Oct 12, 2026
• Hermes Agent plugin catalog — phone-harness integration docs
• Ghosthand — https://ghosthand.dev (free for one iPhone, $99/month per Mac unlimited)
• thetoolnerd.com AI-tools roundup, Oct 27, 2026 (Ghosthand pricing corroboration)
• HKUDS PhoneCLI — https://github.com/HKUDS/PhoneCLI (research project)
• DeepSeek-phone-harness by 2903077918-lgtm (GitHub) — unrelated phone-as-remote project

Frequently Asked Questions

Do I need a Mac to use Phone Harness?

Only for iPhone. iPhone pairing goes through the Mac's iPhone Mirroring window (macOS 15+, iOS 18+, Accessibility and Screen Recording permission), so a Mac is mandatory there. Android works from macOS, Linux, or Windows over adb — USB or Wi-Fi.

Is Phone Harness free?

The tool itself is free and MIT-licensed open source — "phone-harness is free and maintained in my own time," per the README. You only pay for Phone Harness Cloud hosted phones: Android emulators start with a $5 credit at 5 cents per minute, and cloud iPhones are $80 per month ($64 annual, $100 with eSIM).

Does Phone Harness need a jailbreak, Xcode, or an app on the phone?

No to all three. The current claim, verified on both the PyPI page and phone-harness.com: "No jailbreak, no Xcode, nothing installed on the phone. The agent sees the screen, taps, types, and reads the result." It drives iPhone Mirroring and adb — both official, supported channels.

Is it safe to let an agent control my phone?

The README ships no confirmation prompts before purchases, no app allowlist, and no dry-run mode — that is the substance of renolu's October 12, 2026 dev.to critique, and the project's own trust anchor is the limits line "Connecting the phone is always the user's job." The practical answer: start on a spare device or secondary account, run --doctor, open Notes first, and only then graduate to real tasks.

What is the difference between Phone Harness and Ghosthand?

Ghosthand is a commercial, Mac-only, iPhone-only tool (free for one iPhone, $99 per month per Mac for unlimited iPhones) that sends screenshots over USB and taps over Bluetooth. Phone Harness is open source and covers iPhone, Android, and cloud phones, registering as a skill inside the coding agent you already run.