Give your agent a body.

Eyes and hands for Codex and Claude Code on a real iPhone.

What is iPhone-use?

iPhone-use, formerly AgentSoma, is a local Swift CLI. Standard mode observes through Apple PNG and executes native HID; optional Runner mode uses XCTest and available accessibility elements. Your external agent plans and interprets results. There is no built-in model or silent switch between modes.

Start here

1. Install the CLI

   Get the complete macOS CLI and Runner package.

2. Add your client plugin

   Connect the workflow to Codex or Claude Code.

3. Prepare your iPhone

   Use Xcode, device trust and Developer Mode; signing is optional for Runner.

4. Run your first task

   Navigate Settings, read the screenshot and disconnect.

Observe, act, verify

Observe: capture an Apple PNG; Runner also offers available accessibility text. Act: use current references to open an app, tap, swipe or enter text. Verify: read the next screenshot and decide whether the task is complete.

A successful input is an execution fact. It does not establish that the app reached the intended business result. See execution outcomes.

Supported scope

Standard mode currently targets Apple Silicon / macOS 27, Xcode 27 and iOS 27. Runner requires your development signing. Release 0.2.1 passed host/package checks; prior candidate device evidence covers iPhone 12 Pro / iOS 27.0.1 and is not a test of the exact published archive. Fresh-Mac, free Personal Team provisioning and renewal, and browser first-run installation remain unverified. See the release evidence.

Data and license

Device control runs on your Mac and iPhone. Your chosen AI client may send screenshots and UI text to its model provider under its data settings. Review the screen before working in private apps. iPhone-use is MIT licensed.