iCTRL skill
iPhone automation on XCUITest with a JSON-RPC API: an agent taps, types and reads the screen from a manual served by the device.
- 604 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- A pairing key gives full control of the phone: input, screen and every app.
- An unsupervised agent can take irreversible actions inside apps.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/ictrlDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- A pairing key gives full control of the phone: input, screen and every app.
- An unsupervised agent can take irreversible actions inside apps.
This is third-party code. Review the repository files before installing.
What it does
iCTRL runs a long-lived XCUITest runner on an iPhone and exposes JSON-RPC 2.0 over HTTP on port 8200. An agent or any HTTP client taps, scrolls, types, reads the UI tree, takes screenshots, opens URLs and launches apps. The service is built for model use: `/skill` serves a full manual and `/schema` documents every method. The `SKILL.md` in the repository teaches an agent to pair with the phone and drive it through a client downloaded from the device itself.
Who it is for. Developers and researchers testing mobile apps on their own iPhone who want an agent to drive the device.
Good fit when
- An agent must walk a scenario in an iOS app and verify the screen at each step.
- An automated test uses XCUITest but you want to drive it in natural language.
- You need the UI tree and a screenshot to diagnose a bug.
- App behaviour is studied on a real device.
Not a fit when
- The device is not yours or the accounts are not entitled to you: the author permits only your own devices and accounts.
- The agent would run unsupervised near payments and messages.
- A simulator is enough: ordinary Xcode tools are simpler then.
Example request
Connect to the phone, open settings, find the Wi-Fi section and take a screenshot without changing any setting.Limitations
The author warns that the project is for automated testing and research only. Whoever holds a pairing key gets full control of the phone, including input, screen contents and every app. Setup needs signing through SideStore or Xcode and a mounted developer disk image. Third-party app terms remain the user's responsibility. iOS updates and sideloading rules can break the setup, so check version compatibility.
How to disable. Stop the server on the phone, turn remote access off and remove the runner. Revoke approved pairing keys on the device.
FAQ
Which agents does it work with?
Any that can make HTTP requests: OpenClaw, Hermes, Minis, Claude Code, Codex. Minis has extra optimisation.
Is a Mac required?
Usually for building and signing, but the developer image can be mounted on the device and signing can go through SideStore.
How does the agent learn the methods?
A request to `/skill` returns the manual and `/schema` documents each method and its parameters.
Is it safe to leave the server on?
No. A pairing key gives full control of the phone; keep remote access off when not needed.
Which port does the service use?
JSON-RPC 2.0 over HTTP listens on port `8200`, and requests are encrypted.
Discussion
No questions or reviews yet.
Related
SkillsLets Claude Code and Codex drive a real iPhone: read the screen, tap, type and scroll in any app
A skill with scripts for building iOS apps and driving the simulator through the accessibility tree, with compact output for agents
mobilecli drives iOS and Android devices, emulators and apps from the terminal, and its skill teaches Claude Code how to use it
An MCP server that installs on a jailbroken iPhone and gives an agent 46 tools: taps, screenshots, OCR, apps, files and logs
A CLI that checks SwiftUI screens and runs iOS tests with no Simulator: agents read an accessibility tree and reload views in 2 s.
An MCP server to drive iOS and Android: simulators, emulators and real devices via accessibility trees and screenshots
README in short
The README opens with a risk warning, then covers architecture, device setup, pairing and ways to attach an agent.