# Give Codex hands on your iPhone

**ios-agent-bridge** combines native iOS device services with UI automation and exposes them through one MCP interface.

It is an open-source control plane for devices you own or are authorized to administer. It lets Codex and other MCP agents select the best available iPhone provider instead of making the user learn AFC, DTX, WDA, Appium, RemoteXPC, or Web Inspector.

> Status: `v0.1.0` is an initial, installable integration release. Its physical-device support is always reported by live probes; it never claims that a capability works merely because a provider is installed.

## What it can do

- Discover trusted iPhones and report a live capability matrix.
- Use pymobiledevice3 for deep, non-jailbreak device services such as device information, app/container work, diagnostics, and Web Inspector where upstream support and device setup allow it.
- Use Appium + WebDriverAgent for accessible UI automation: screenshots, UI trees, semantic element lookup, taps, gestures, text entry, app activation, URLs, and web contexts.
- Expose one tool surface over MCP and a matching `ios-agent` CLI.
- Execute a bounded server-side multi-step flow so an agent does not need an MCP round trip for every tap.
- Keep risky device actions locked behind an explicit safety policy.

## What it deliberately cannot do

- It does not jailbreak devices, bypass pairing/trust, defeat a passcode, obtain root filesystem access, or circumvent Apple signing/security controls.
- It does not silently erase, restore, enter recovery/DFU, mutate security profiles, or delete an arbitrary tree of user files.
- A UI tree is accessibility data, not a guarantee that every pixel or private element is visible.
- Safari and embedded web inspection require the device/app settings Apple and Appium require; they are not fabricated when unavailable.

## 30-second quick start

```bash
git clone https://github.com/Joe15935/ios-agent-bridge.git
cd ios-agent-bridge
uv sync --all-groups
uv run ios-agent doctor
uv run ios-agent status
uv run ios-agent capabilities
uv run ios-agent setup-codex
```

`doctor` does not ask for, save, or print secrets. It tells you exactly which device-side action is needed when Apple requires one.

## Requirements and setup

- macOS on Apple Silicon or Intel, Python 3.12+, and [uv](https://docs.astral.sh/uv/).
- A USB or paired Wi-Fi iPhone for real-device actions. The phone must be unlocked and trust this Mac.
- For rich UI automation, full Xcode (not Command Line Tools), an Apple development team for WDA signing, iOS Developer Mode, and **Settings → Developer → Enable UI Automation**. Run `ios-agent doctor` for the precise live status.
- For Safari/WebView DOM inspection, enable Web Inspector and Safari Remote Automation. Apps must expose inspectable WKWebViews.

Full Xcode, signing, trust, Developer Mode, and device unlocking are intentional user actions. The bridge never attempts to fake or bypass them.

## Codex setup

`ios-agent setup-codex` uses the locally installed `codex mcp add` command rather than editing a guessed configuration format. It registers a local stdio MCP server named `ios-agent` and verifies it with `codex mcp list`. Start a new Codex task/session afterward so it loads the newly registered tools.

You can also run the server directly:

```bash
uv run ios-agent mcp
```

The project includes [the `ios-agent-operator` skill](.codex/skills/ios-agent-operator/SKILL.md), which teaches an agent to check status/capabilities first and use semantic UI operations before coordinate taps.

## Provider routing

| Provider | Role | Enabled by default |
| --- | --- | --- |
| [pymobiledevice3](https://github.com/doronz88/pymobiledevice3) | Primary deep-device provider | Yes, when installed and paired |
| [Appium XCUITest + WebDriverAgent](https://github.com/appium/appium-xcuitest-driver) | Primary UI provider | Yes, when Appium/WDA are healthy |
| [go-ios](https://github.com/danielpaulus/go-ios) | Fallback for a gap or a more reliable operation | No |
| [libimobiledevice / ifuse](https://libimobiledevice.org/) | Compatibility layer for traditional iDevice utilities | No |

The router records its preferred provider, fallbacks, and selection reason. It never starts competing RemoteXPC/tunnel owners for the same device.

## Capability states

`ios-agent capabilities` returns the following real-time states rather than a generic error:

| State | Meaning |
| --- | --- |
| `READY` | A live probe found a usable provider and required setup. |
| `DEGRADED` | A usable fallback exists with a stated limitation. |
| `BLOCKED_SETUP` | Install/configure a Mac-side dependency, such as full Xcode or Appium. |
| `BLOCKED_USER_ACTION` | The user must connect/unlock/trust the device, enable Developer Mode, or approve an Apple dialog. |
| `UNSUPPORTED` | iOS security or all upstream providers prevent the capability. |
| `DANGEROUS_LOCKED` | Intentionally unavailable in this release. |

## Safety and privacy

- `READ` actions are normal inspection actions.
- `WRITE` actions only run when a caller explicitly invokes the corresponding operation; file deletion also needs an explicit confirmation.
- `DANGEROUS` actions are locked. Version 0.1.0 intentionally exposes no erase/restore/DFU action.
- `apps.uninstall` and `files.delete` are destructive `WRITE` actions, require an exact target and `confirm=true`, and never recurse through a directory tree. File actions may target an app's vended `Documents` container only when that app explicitly permits it.
- Real artifacts are stored beneath ignored `.local/`, `artifacts/`, or `private/` folders. The repository ignores pair records, certificates, keys, provisioning material, backups, logs, crash dumps, screenshots, media, cookies, and tokens.

## Tests and verification

```bash
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest
uv build
uv run python -c "from ios_agent_bridge.server import create_server; create_server()"
uv run ios-agent doctor --json
uv run ios-agent capabilities --json
```

`pytest -m real_device` is opt-in and never runs in public CI. A machine without a real iPhone reports `LIVE_DEVICE_ACCEPTANCE_BLOCKED: NO_PHYSICAL_DEVICE` rather than inventing evidence.

The release's conservative task-coverage evidence is recorded in [the capability scorecard](docs/CAPABILITY_SCORE.md). It distinguishes implemented paths from simulator and physical-device verification.

## Troubleshooting

Start with `ios-agent doctor`. The common remedies are:

1. Install and select full Xcode, then open it once to accept its license.
2. Connect, unlock, and trust the iPhone.
3. Enable Developer Mode and UI Automation on the iPhone for WDA.
4. Sign WDA with your own development team in Xcode.
5. Install the narrow Appium XCUITest driver only after Xcode is ready:

   ```bash
   npm install -g appium@3.6.0
   appium driver install xcuitest@12.3.2
   appium driver doctor xcuitest
   ```

The bridge binds an auto-started Appium server to `127.0.0.1`, uses Appium 3's root base path, and never enables `--relaxed-security`.

## Credits and license

ios-agent-bridge is GPL-3.0-or-later. It integrates upstream projects rather than vendoring or forking their protocol implementations. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for licenses and attribution.

Key upstream projects: pymobiledevice3, Ghost in the Droid, Appium, Appium XCUITest Driver, WebDriverAgent, go-ios, libimobiledevice, ifuse, and the official Model Context Protocol Python SDK.