iPhone-use

Open source · Physical iPhone

Give your agent
a body.

Give Codex and Claude Code eyes and hands on your iPhone.

Read the screen. Use real apps. Check what happened. All through a Swift CLI on your Mac.

Get started See it work

Your Mac. Your iPhone. Your choice of agent.

Codex / Claude CodeiPhone-use
  1. ObserveRead the screen
  2. ActUse the app
  3. VerifyCheck the result
Real iPhone Calculator capture: 125 × 8 equals 1,000.
Real iPhone capture
Recorded CLI task · View evidence

Made for the tools you already use.

The task ends
with evidence.

Calculate 125 × 8, then reconnect and verify the saved result in Calculator history.
  1. See what’s there.Discover the app. Read its screenshot and accessibility tree.
  2. Choose the next action.Tap the calculator keys using current references. Keep the screen checks on.
  3. Check the saved result.Read 1,000 on screen. Reconnect, open History, and confirm the same calculation.
Run it on your iPhone
Actual iPhone Calculator history showing the saved calculation 125 × 8 = 1,000 after reconnecting.
Real device capture from CLI 0.1.0 release verification, 7 September 2026. iPhone 12 Pro · iOS 26.6.1.
Open full capture

A recorded CLI task. The first task below checks the client plugin’s Settings workflow.

Small primitives. Real app workflows.

Observe
Apple PNG screenshots; optional Runner accessibility snapshots.
observe · inspect
Act
Discover and open apps. Tap, scroll, drag, and edit text.
apps · open · tap · swipe · type · press
Verify
Know whether input completed, was rejected, or has an uncertain result. Observe before deciding what comes next.
completed · not_dispatched · unknown

Today: physical iPhone. Choose standard screenshot/HID control or optional XCTest Runner. This release operates through the CLI.

From install to your first task.

Use your existing Codex or Claude Code account. iPhone-use is MIT licensed.

Before you begin: Mac, iPhone & Xcode

Standard mode requires Apple Silicon, macOS 27 / iOS 27 and full Xcode, plus a trusted USB-connected iPhone with Developer Mode enabled. Development signing and setup are only required for Runner mode.

Release 0.2.0 passed package checks. Prior candidate device evidence covers iPhone 12 Pro / iOS 27.0.1. Fresh-Mac and free Personal Team setup remain unverified. Check prerequisites.

  1. 1. Install the CLI.

    In Terminal on your Mac:

    brew install HughLee824/tap/iphone-use
iphone-use --version

    Migrating from AgentSoma? Uninstall the old agentsoma formula before installing iphone-use. Local signing data is retained.

    Prefer a download? Follow the manual installation guide. Keep the complete CLI and Runner package.

  2. 2. Add your client’s plugin.

    Codex

    Run in Terminal, then start a new Codex task:

    codex plugin marketplace add HughLee824/iphone-use
codex plugin add iphone-use@iphone-use

    Requires a Codex release with codex plugin support. Command names checked on CLI 0.146.0. Invoke $iphone-use:iphone-use in the new task.

    Claude Code

    Run in Terminal, then start a new Claude Code session:

    claude plugin marketplace add HughLee824/iphone-use
claude plugin install iphone-use@iphone-use

    Invoke /iphone-use:iphone-use in the new session. The plugin adds device instructions; install the CLI and Xcode separately.

    Distributed through this project’s own Git marketplace. Installation and upgrades.

  3. 3. Prepare your iPhone.

    Plug it in, trust the Mac, enable Developer Mode, and keep it unlocked. Copy the device ID returned by devices:

    iphone-use devices
export IOS_UDID='YOUR_DEVICE_ID'
iphone-use config set mode standard

    setup is optional and only prepares Runner mode with your development signing. Standard mode uses Apple PNG and native HID without starting Runner. Mode and signing guide.

  4. 4. Give your agent its first task.

    Invoke the skill in a new client session, then send:

    Open Settings on my iPhone, navigate to General, read the screenshot to verify the page, then disconnect. Do not change any settings.

    You’re done when the agent reads the General screenshot, confirms the page, and reports clean disconnection. A successful tap alone isn’t task completion.

    Read the first-task guide

Know the boundaries.

Local device control.

Commands run on your Mac and iPhone. Screenshots and UI text may be sent to your chosen AI client’s model under its data settings.

Explicit execution facts.

Screen checks and fresh references help the agent act on what it saw. When input is uncertain, it observes again before deciding to retry.

Early, with a tested path.

Compatibility is limited to tested environments. The Mac CLI is ad-hoc signed, without Developer ID notarization. Current limitations.

Help when setup stops.

Check CLI availability, Xcode selection and device trust; check signing only for Runner. Troubleshoot your first task or report a reproducible issue.