Repository navigation
Release Notes
Released 17 November 2026.
phonedriver initadds phonedriver to the agents installed on this machine (Claude Code, Codex, Cursor, VS Code and Gemini CLI) and then runs the doctor checks.phonedriver boot <name>starts an iOS Simulator or an Android virtual device that is off and waits until it has booted. With nothing connected, the error names what can be started.- Saved runs:
phonedriver save run.stepswrites what the session did, andphonedriver replay run.stepsdoes it again with no model. It stops at the first step that fails and shows the screen. - A GitHub Action:
uses: hridaya423/phonedriver@v0.1.5starts an Android emulator or an iOS Simulator, installs your app and replays saved runs on every commit. Each run is a row in the job summary, and its reply, the screen where it stopped and a video go in an artifact. - Screen checks in a replay:
replay run.steps --screens screens/runkeeps a screenshot after each step the first time, and later stops at the first step whose screen shows different text, with the text that changed (~ "General" → "About"). The status bar is left out, with its clock, notification icons and battery, and a screen still moving is looked at again until it stops, so an animation or a notification does not fail a job. The Action takes the folder asscreens. phonedriver pageprints the web page in front as text, whole, without scrolling. On Android, it works in Chrome and in the web views of debug builds.phonedriver record startandrecord stopsave an MP4 of the screen on Android and on the iOS Simulator, with a file of the actions done during it.- Settings by key on Android 17:
phonedriver setting find,getandsetchange a setting without opening its screen. - App permissions:
phonedriver apps grant <app> <permission>andrevokework without launching the app. - Crashes: an action during which the app crashed says so in its reply, and
phonedriver logsprints the app's last lines and its last crash. - Several agents on one Android phone: a device id that ends in
+a,+band so on gives each agent a hidden screen of its own (Android 13 and later). - An Android phone in use stays awake: while phonedriver has used a phone in the last 10 minutes it resets the phone's screen timeout every 10 seconds, on the phone's own screen and with
PHONEDRIVER_DISPLAY=hidden, so the phone no longer locks while an agent thinks. The screen still dims on its usual schedule.phonedriver releasestops it. Tested on a HONOR X8 and the emulator. - The emulator's console: on an Android emulator,
phonedriver shell "emu geo fix -122.41 37.77"sets the location, and any other console command works the same way (emu sms send,emu power capacity). On the iOS Simulator,shell "simctl location set 37.77,-122.41"does it. - Fingerprint and Face ID:
press fingerprintandpress wrong-fingerprinton an Android emulator and on an iOS Simulator. press landscapeandpress portraitturn the screen.- Accessibility audit:
phonedriver snapshot --audit(MCP:audit: true) adds the screen's controls that have no name a screen reader can say and its tap targets under 44 by 44 points on iOS or 48 by 48 on Android. phonedriver compare a.png b.pngsays in text what changed between two screenshots, in 0.3 to 1.2 s on a Mac. The status bar's clock is left out.- Screens with no element list are read from the screenshot on Windows hosts too, and on Linux hosts with Tesseract installed (the
tesseract-ocrpackage), not only on a Mac. - Reading a screenshot on a Mac starts at once: the first read in a process used to wait 21 to 31 s while macOS built the model for Vision's Accurate level, and on some Macs that level failed after 12 to 17 s every time. phonedriver now reads at Vision's Fast level, which needs no such model: about 20 ms a screen on an M4 Pro.
- An iPhone's signature renews itself: when the runner's signing has run out (7 days with a free Apple ID), the next command signs it again and installs it.
doctorshows when it runs out. - Passwords: text typed with
secretis masked as•••in every later reply, error and trace line. An MCPbatchcan now carry atypestep withsecret, so one call fills a sign-in form and submits it. - Fewer tokens: a reply says each thing once. A snapshot's header names the keyboard only when it is up and the settle time only when the screen did not settle; the keyboard coming up is one line (
keyboard shown over @e8); a verifiedtypedoes not repeat the text it typed; a tap's point is in the JSON reply'sat, not its text. On iOS a snapshot no longer starts with a line naming the app, buttons that get their identifier late keep their refs, and a row whose text changes is one~line. On simulator-use's sign-in benchmark phonedriver reads the screen in 59 tokens and signs in step by step with 173 (it was 300); simulator-use took 71 and 192 in the same run (benchmarks). - Fixed:
wait "hello"andscroll --until "hello"did not find text typed into a field, though the screen showed it astextbox "hello". They now look in what fields hold, never in a password field. - Fixed on iOS: a system permission prompt over the home screen was listed twice, so
tap "Don’t Allow"matched two elements. - Fixed on iOS:
launchof an app that asks for a permission as it starts, such as Maps, waited 13 s and said the app was not in front, because the system's prompt was. It now answerslaunched Mapswith the prompt on the screen, 5 s sooner. - The iOS Simulator needs only Xcode: the runner's Xcode project comes with phonedriver, so XcodeGen is no longer needed, and
doctorno longer asks for it. - Fixed on iOS: Xcode recorded a video of every phonedriver session on a Simulator, as it does for UI tests, and kept it in the Simulator: 1.2 GB on the Mac that ran the tests, up to 209 MB a session. The runner now records nothing.
- A faster iOS Simulator: a tap goes to the Simulator's own touch input instead of through XCTest, and the settle watches the Simulator's screen as it is drawn instead of asking XCTest for screenshots. On simulator-use's sign-in benchmark a tap takes 0.32 s (it was 0.84), a read 29 ms (117), the sign-in step by step 1.76 s (3.63) and in one batch 1.78 s (4.35). Typing still goes through XCTest, which types exactly; sent as hardware keys instead, quotes came out curled and capitals lowercase. Taps with several fingers, in an app on its side, and under a notification banner still go through XCTest.
- Faster swipes on iOS: the runner looked up the screen's size and the orientation again for every point of a gesture. It now does so once, and a swipe on the Simulator takes about 0.24 s less (1.27 s against 1.51 s at the median, a debug build); a tap's input took 0.06 s less.
- Fixed on iOS: with the device on its side and an app that stays upright, taps landed where the screen would have been had the app turned. They are now turned by the app's orientation.
- Fixed on iOS: on a CI machine with a Simulator just booted, the first command could fail after 60 s waiting for the runner, because SpringBoard took 41 s to answer its first question. The runner now asks it once before it says it is ready, and phonedriver waits up to 3 minutes for a Simulator's runner. The Action keeps the daemon's log with the runner's when a run stops.
- Fixed on iOS: every start of the runner left a folder in Xcode's DerivedData, and a runner that was stopped left 120 to 250 MB of the Simulator's system logs in it; 84 such folders took 940 MB on the Mac that ran the tests. The runner's logs now stay under
~/.phonedriver/runner, replaced at each start, and no system logs are gathered. Delete~/Library/Developer/Xcode/DerivedData/PhonedriverRunner-*to get back what earlier versions left. - Fixed on iPhone:
launch Settingsmatched CarPlay's hidden settings app as well on iOS 27. Apps that iOS hides from the home screen are no longer listed. - Fixed on Android: when the connection to the phone broke during an action, the reconnect could be refused with
lane the phone's own screen of this device is already open from this daemon. It now waits up to 5 s for the phone to let go of the old connection. - Fixed on Android: a screenshot taken right after an action could show the screen from before it.
- Fixed on Android: with
PHONEDRIVER_DISPLAY=hiddenon a locked phone,launchwaited 9 s and blamed the app, and opening the hidden screen turned the phone's screen on. It now says the phone is locked and leaves it asleep. The hidden screen works only while the phone is unlocked. Tested on a HONOR X8. - Fixed on Android: a request the phone never answered waited ten minutes. It now ends as a lost device.
- The third action in a row that changes nothing says so and tells the agent to stop repeating it.
launchwaits for an app that is slow to start, and a submit that left the keyboard up says so.- Every MCP tool refuses an argument it does not know, so a misspelled argument is an error, not silently ignored.
phonedriver screenshot shot.pngtakes its file as a plain argument.
Install phonedriver 0.1.5
Install prebuilt binaries via shell script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/hridaya423/phonedriver/releases/download/v0.1.5/phonedriver-installer.sh | shInstall prebuilt binaries via powershell script
powershell -ExecutionPolicy Bypass -c "irm https://github.com/hridaya423/phonedriver/releases/download/v0.1.5/phonedriver-installer.ps1 | iex"Install prebuilt binaries via Homebrew
brew install hridaya423/tap/phonedriverDownload phonedriver 0.1.5
| File | Platform | Checksum |
|---|---|---|
| phonedriver-aarch64-apple-darwin.tar.gz | Apple Silicon macOS | checksum |
| phonedriver-x86_64-apple-darwin.tar.gz | Intel macOS | checksum |
| phonedriver-x86_64-pc-windows-msvc.zip | x64 Windows | checksum |
| phonedriver-aarch64-unknown-linux-gnu.tar.gz | ARM64 Linux | checksum |
| phonedriver-x86_64-unknown-linux-gnu.tar.gz | x64 Linux | checksum |