{"slug": "how-to-control-a-real-iphone-with-claude-code-or-codex", "title": "How to control a real iPhone with Claude Code or Codex", "summary": "A developer released iphone-cli (iph), a Rust-built single binary that acts as both a CLI and a stdio MCP server to control a real iPhone over USB or Wi-Fi on macOS and Windows. The tool reads Apple's accessibility tree and drives apps without Xcode or any runner app installed on the phone, targeting iOS 27 or later, and is registered in the Official MCP Registry as io.github.HyunSeob/iphone-cli. It lets agents like Claude Code and Codex read the screen and tap controls by name, such as opening Settings and selecting General.", "body_md": "I wanted Claude Code to open Settings on my iPhone and tap General by name.\n\nOn a real iPhone, the usual options each come with a catch. Appium with WebDriverAgent gives you an element tree, but you need a signed WDA runner on the phone (typically built with Xcode; on Windows, Appium needs a preinstalled or externally managed WDA). Tools built on macOS iPhone Mirroring skip WDA, but require macOS 15+ on Apple silicon or T2, aren't available in the EU, and depend on screenshots or OCR instead of Apple's accessibility tree.\n\nSo I built **[iphone-cli (`iph`)](https://github.com/HyunSeob/iphone-cli)** in Rust: a single binary that works as both a CLI and a stdio MCP server on macOS and Windows. It reads Apple's accessibility tree and drives apps on a real iPhone over USB or Wi-Fi, without Xcode or any runner app installed on the phone.\n\n`iph` targets real iPhones running **iOS 27 or later**. Plug the phone in over USB, unlock it, and tap **Trust** before running setup.\n\n`iph`\n**macOS (Apple silicon & Intel universal binary):**\n\n```\ncurl -fsSL https://raw.githubusercontent.com/HyunSeob/iphone-cli/main/install.sh | sh\niph setup\n```\n\nThe installer verifies the checksum and puts `iph` in `~/.local/bin` (and prints the `PATH` line if needed). Release binaries for macOS are ad-hoc signed in CI, and you don't need to sign or install a runner app on the phone.\n\n**Windows 10/11 (x64):**\n\nPair over USB first. After that, the Windows PC can stay on Ethernet as long as the iPhone is on the same LAN.\n\n`winget install Apple.AppleMobileDeviceSupport`.` iph-windows-x86_64.zip` from `iph.exe`, and add its folder to your `PATH`.` iph setup`.\n**Build from source with stable Rust:**\n\n```\ncargo install iphone-cli\n```\n\n*(Windows builds need Visual Studio C++ Build Tools.)*\n\n`iph setup` runs `iph doctor`, walks through any failed checks, and lets you press Enter to re-check in an interactive terminal. It verifies pairing, Developer Mode (you toggle it on the phone and reboot), the Developer Disk Image, screen lock, accessibility reading, and touch input. For the touch check, it brings Settings to the front and scrolls one step and back.\n\nIf developer services are missing, `iph doctor` prefers Xcode's copy of the Developer Disk Image and also checks its cached download, fetching and SHA-256-verifying it if needed. My test phone already had the image mounted, so I haven't verified the auto-download path on a clean device yet.\n\nOnce USB works, run `iph doctor --fix-wifi` while the cable is still plugged in to enable Wi-Fi, or register the phone's IP directly with `iph --udid <UDID> connect --ip <IP>`.\n\nRegister the built-in stdio MCP server:\n\n```\nclaude mcp add iph -- iph mcp\ncodex mcp add iph -- iph mcp\n```\n\n`iphone-cli` is also on the Official MCP Registry as `io.github.HyunSeob/iphone-cli`.\n\nTo test the whole path regardless of your phone's language, ask your agent:\n\nUse `iph_read` to tell me which app is open and name three controls on screen.\n\nIf you'd rather have agents invoke the `iph` CLI directly in the shell instead of MCP, clone the repo on macOS/Unix and symlink the bundled skill (`skills/iph/SKILL.md` isn't included in the standalone release archive):\n\n```\nln -s \"$PWD/skills/iph\" ~/.claude/skills/iph   # Claude Code\nln -s \"$PWD/skills/iph\" ~/.agents/skills/iph   # Codex\n```\n\nHere is a trimmed terminal session:\n\n``` bash\n$ iph read --human\nSettings  430x932  15 elements\napplication   \"Settings\"  @0,0 430x932\n  header        \"Settings\"  @20,119.3 53.7x37\n  switch        \"Airplane Mode\" = \"0\"  @20,489.3 390x49.3\n  button        \"Wi-Fi, HomeNet\"  @20,538.7 390x49.3\n  button        \"General\"  @20,700 390x49.3\n\n$ iph find 'role=button label~=\"General\"'\n$ iph tap \"General\"\n```\n\nScreen reads and input from the CLI and MCP share a per-device daemon (`iph daemon`), started on demand over a Unix socket on macOS or a named pipe on Windows and exiting after 30 minutes of idle time by default. Local commands like `iph scripts` or MCP `tools/list` never spawn it.\n\n```\niph (CLI) ─┐\niph mcp  ──┼─ unix socket / named pipe ─ iph daemon ─ lockdown → CoreDeviceProxy → userspace TCP → RSD\n           ┘                                           ├ com.apple.accessibility.axAuditDaemon.remoteAXService\n                                                       ├ displayservice + hid.universalhidservice  (touch, keyboard)\n                                                       ├ pasteboardservice                         (clipboard / text)\n                                                       ├ appservice                                (launch, app list)\n                                                       └ screencaptureservice                      (PNG screenshots)\n```\n\n*(All services above except `axAuditDaemon.remoteAXService` live under `com.apple.coredevice.`.)*\n\nBecause the tunnel runs a userspace TCP stack inside the daemon, `iph` needs no root privileges and creates no host TUN interface.\n\n`com.apple.accessibility.axAuditDaemon.remoteAXService` speaks DTX and sends back two nested binary plists (`bplist00`) encoded with `NSKeyedArchiver`. Unpacking `resultData.treeDump` gives visible elements with their roles, states (`enabled`, `selected`, and `focused` from `IS_EDITING`), and optional `label`, `value`, `hint`, `frame`, and `identifier` fields. `--full` waits for the extra pass that populates identifiers, and `--raw` dumps every numbered attribute.\n\nBecause the agent gets structured labels and coordinates instead of pixels, it can target controls by name without burning vision tokens on a screenshot every turn.\n\nReading the tree needs no media session. Sending synthetic HID touch or keyboard events through `hid.universalhidservice` does: iOS ignores them unless the phone has an active screen-sharing session via `com.apple.coredevice.displayservice` (you'll see the screen-sharing indicator on the phone while input is active).\n\nStreaming full screen video over Wi-Fi just to tap a button clogs the tunnel. By default (`screen_video = false`), `iph` opens the media session with an **audio stream only** and drops the incoming packets. If starting audio fails with error `9022` (during a call or screen recording, for example), it falls back to video. Touch coordinates are normalized to `0..=65535` per axis, and multi-touch gestures like `iph pinch` pack two fingers into a single HID report with independent axis scaling so circles don't stretch on tall screens.\n\nFor non-ASCII text, Korean, and emoji, `iph type` locates the single editing field, attaches a temporary HID keyboard, and pastes through `pasteboardservice` (`⌘V`, preceded by `⌘A` and delete when `--clear` is set). It then reads the field back and restores supported clipboard contents in parallel.\n\n*Credits: I built `iph` from the documented behavior of [Poki](https://github.com/JosssphZhou/poki) and direct device experiments, without using Poki's code. Device communication uses [idevice](https://github.com/jkcoxson/idevice) (MIT, with media-session setup adapted from an `idevice` example), and the tunnel embeds a modified `jktcp` 0.1.8 TCP stack (MIT).*\n\nAfter `iph` sends a tap, iOS never confirms that the button actually fired. Writing HID bytes only proves packets left the host; the phone might have dropped the tap mid-animation or switched apps right before it arrived. Retrying blindly on a checkout button can double-submit an order.\n\nSo every action reports an explicit `outcome` field:\n\n| `outcome` | Meaning | CLI exit code | \n|---|---|---|\n| `done` | Command finished (or `scroll --until` stopped without finding the target, with`ok: false` and`found: false` ) | `0` (`1` when`ok: false` ) | \n| `not_sent` | That failing step did not send input to the phone | `1` | \n| `unknown` | Input may have reached the phone. Read the screen before trying again | `2` | \n\nThe exit codes above apply to JSON-returning CLI commands (CLI argument parsing errors can also exit with `2`, and MCP tool calls return the same JSON without exit codes).\n\nBefore retrying a batch, check which steps already ran:\n\n`iph tap` where the selector wasn't found, `not_sent` means nothing left the host, so retrying is safe.`iph batch`, a later step can fail with `scroll --until`, which can return `scrolls` count if multiple matches show up after scrolling.`iph script`, if a later error stops the script after it has sent input, the script reports `unknown`.\nResponses also separate `sent`, `verified`, and `screen_changed`. A tap whose post-tap screen read fails can still return `done` with `sent: true`, `verified: false`, and `screen_changed: false`.\n\n`try/catch`, so a script can't blindly keep tapping after an ambiguous failure.`type --submit`:` verified: true` on `iph type` only means the original field was read back, not that the app kept your exact string (apps mask passwords, reformat numbers, or clear fields). If `--submit` skips Return and exits with `outcome: \"unknown\"` (`type_not_verified`, `submit_sent: false`, exit `2`). Without `ok: true` and `outcome: \"done\"`.\nWhen you already know the sequence of taps, burning one MCP round trip per tap is slow. `iph` embeds a sandboxed QuickJS runtime with no host filesystem, network, or process access (timeout and memory default to 300 s and 64 MiB, both configurable).\n\nSave this as `flow.js` and run `iph script flow.js`:\n\n```\nlaunch(\"com.apple.Preferences\", { restart: true });\nscroll(\"down\", { until: \"General\" });\ntap(\"General\");\ntap(\"About\");\nreturn {\n  ios_version: readField({ selector: { label: \"iOS Version\" }, take: \"value\" }),\n};\n```\n\nYou can also save reusable flows under `~/.config/iph/scripts/` on macOS or `%APPDATA%\\iph\\scripts\\` on Windows and run them with `iph run <name>`. (The built-in `settings-version` example was written against my Korean phone, using `일반` → `정보` → `iOS 버전`, so on an English phone use a script like `flow.js` above.)\n\nInside scripts, selector-based `tap()` waits up to 5 seconds for the element and checks whether its frame has settled before tapping (if it's still moving once checks run out, it attempts the tap anyway). `launch()` waits until the target app's PID is in front and re-checks before later input, `readField`, or `readList` calls. For scrolling lists, `readList()` looks for two overlapping rows across scroll steps and reports why it stopped, or reports `list_uncertain` if it can't line up the rows during its final end-of-list check. The full script API is in the [README](https://github.com/HyunSeob/iphone-cli#scripts).\n\n|  | `iphone-cli` (`iph` ) | iPhone Mirroring + OCR tools | Appium / WebDriverAgent | \n|---|---|---|---|\n| **Supported hosts** | macOS, Windows 10/11 (x64) | macOS 15+ (Apple silicon / T2; unavailable in EU) | macOS (Windows is limited; needs a preinstalled or externally managed WDA) | \n| **Runner app on device** | None (iOS 27+) | None (iOS 18+) | Signed WDA runner installed on phone | \n| **How UI is read** | Native accessibility tree (JSON) | Screenshots / OCR | Native accessibility tree via WDA | \n\nUse `iph` if you want an agent on macOS or Windows (including in the EU, since it doesn't touch iPhone Mirroring) to read an iOS 27+ iPhone's accessibility tree without WDA. For iOS simulators or older iPhones, Appium can read the tree through WDA; for Android, it uses a driver such as UiAutomator2.\n\nMeasured on 2026-11-11 on my iPhone 15 Pro Max (`iPhone16,2`, iOS 27.0.1) over Wi-Fi with the daemon already connected:\n\n`iph read` (Settings home, 10 runs): `iph scroll` (one step with verification): On a still screen on this phone, iOS itself waited about **1.1 s** after receiving a dump request before sending the tree back, which sets the floor for read latency.\n\n`com.apple.coredevice.displayservice`. Earlier versions haven't been tested.` iPhone16,2`), iOS 27.0.1` iPhone19,4`, iOS 27.2` iPhone14,2`, iOS 27.2.1 (direct IP registration)` iph read --raw`).` iph dnd on` / `iph dnd off` toggles Do Not Disturb via Control Center (see the `clipboard_restored: false`), and leaves anything you copied in the meantime alone.\nIf you run this on Windows or another iPhone model, I'd love to hear which model, iOS version, and connection (USB or Wi-Fi) you used.\n\nIf something breaks, `iph diagnose` writes a local report without pairing records or private keys. Check the file before posting it in a public issue, since it still includes device identifiers, network addresses, and logs (plus command arguments and output if you run `iph diagnose -- <cmd>`).\n\n`io.github.HyunSeob/iphone-cli`", "url": "https://wpnews.pro/news/how-to-control-a-real-iphone-with-claude-code-or-codex", "canonical_source": "https://dev.to/hyunseob/how-to-control-a-real-iphone-with-claude-code-or-codex-43eb", "published_at": "2026-11-19 12:09:13+00:00", "updated_at": "2026-11-19 12:13:53.430774+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools"], "entities": ["iphone-cli", "Claude Code", "Codex", "Apple", "Appium", "WebDriverAgent", "Official MCP Registry", "HyunSeob"], "also_reported_by": [], "takeaway": "iph exposes Apple's accessibility tree over a stdio MCP server so agents can read and tap real iPhone controls by name without Xcode or a signed WebDriverAgent runner, requiring iOS 27+ and a one-time trust and Developer Mode setup.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/how-to-control-a-real-iphone-with-claude-code-or-codex", "markdown": "https://wpnews.pro/news/how-to-control-a-real-iphone-with-claude-code-or-codex.md", "text": "https://wpnews.pro/news/how-to-control-a-real-iphone-with-claude-code-or-codex.txt", "jsonld": "https://wpnews.pro/news/how-to-control-a-real-iphone-with-claude-code-or-codex.jsonld"}}