Use this plugin's MCP tools to perform repeatable probing, building, starting, and connecting; do not generate a temporary Python client for each task. When a usable PUA already exists, reuse it first to avoid rebuilding or reinstalling for every task.
First determine the current state
When the phone is used for the first time in this conversation and READY has not yet been obtained, first directly call pua_setup(action="status"), reuse the healthy service or active work as described in the next section, and only start once if the service is missing; after the service is ready, call pua_ready(recover=true, screenshot=false), then perform the user's phone task. Do not wait for READY to fail before running setup; do not substitute a previous chat's READY or an installed plugin for the current proof. If this conversation is already READY and the channel has not failed, continue directly, and do not repeat doctor, discover, build, and start for every task. On first-time configuration or when READY returns specific missing items, use pua_doctor and pua_setup(action="discover") to read Xcode, connected devices, signing, ports, and process status. For multiple iPhones, select according to the device provided by the user; when only one meets the conditions, it can be used directly. The device UDID, Team ID, logs, and signing configuration are kept on the user's local machine and are not written into the source code or Git.
For normal tasks, call pua_ready(recover=true) or omit recover to use the default true; do not proactively disable recovery out of precheck caution. For read-only diagnosis or when the user explicitly prohibits restarting, pass recover=falseand keep the restriction. For routine tasks that do not need screenshots, you can pass screenshot=false; use the screenshot capability only when screenshots are actually needed. The proof returned by ready=true, state="ready" includes PUA status, available sessions, the real foreground App, device viewport, unlock state, and the current observation; directly use the nested observation to prepare the next step, without immediately repeating observe or doing another round of navigation testing. If the mirror is occupied and the control tree is empty, the tool returns mirroring_conflict; exit the mirror and re-verify READY. The Runner icon, BUILD SUCCEEDED, or an open port is not sufficient to declare READY. READY is also associated with the phone screen sidebar, which opens by default when the host supports it; to reopen the screen for an existing channel, use pua_screen(), and do not repeat READY. Preview uses an independent USB MJPEG channel (default device port 9100) and does not use XML or screenshot polling; preview being unavailable itself does not negate READY for the control channel, nor does it require repeated restarts. READY proves that the control channel is available; routine App operations are executed optimistically by default, and the observations needed for the next step incidentally determine progress, with only the final key result explicitly verified.
phone_locked will automatically pause preview and record device_locked, so there is no need to explicitly pause again. Wait for the user's actual unlock notification and then re-verify READY; on success, only release the same lock-screen pause, while App authentication and unknown pauses from older versions remain explicitly restored. READY's preview returns the pause reason; do not treat a blank preview as failure of the control channel.
Continue initialization when the service is not started
recover=true For persistent local.pid.0 / XCTest failures, it can queue recovery of services whose ownership has been verified; it does not mean automatically completing first-time configuration or cold start. READY's pua_unreachable, connection refused,not_ready , and other not-started results should enter the following startup branch, and you must not directly finalize and declare the phone task failed:
- Call
pua_setup(action="status"). When it returnsconfigured=true, retain the existing device, signing, and port configuration;configured=falseonly fill the actual missing items according to the first-install process in the next section. - Check the returned
jobsarray. When a start / recover job corresponding to the current configuration / endpoint already exists as queued or running, use itsidto query the same job, do not start again, and do not wait for old unrelated jobs; if a corresponding fetch / build job is running, reuse it first as well.pua_setup(action="status", job_id=...)still returns ajobsarray; do not assume a single job is returned. service.ready=trueindicates the service is probeable, but READY verification of the full channel such as session / foreground / viewport still needs to be redone. If the start job is still running and the service is available, READY can be verified; for a recover job, verify READY afterrecovery_phase="serving", and a long-running Runner does not wait for succeeded.- When it is configured, the service is not running, and there is no corresponding active job, call
pua_setup(action="start")once to reuse a valid build. start waits with a bound of at most 20 seconds by default, and returns early when the service is ready or the job ends; it is not a fixed sleep. Whenservice.ready=trueis returned, go directly to READY without querying status again. When it is not yet ready, usepua_setup(action="status", job_id=..., wait_seconds=20)to wait for the same job; a timeout only means it is still starting, and start must not be called again. When a new job records the returnedjob_id;already_running=true, recordjob.id, and when waiting is needed, usepua_setup(action="status", job_id=..., wait_seconds=20)to query the same job. When start explicitly reports that source code is missing, fetch; when it explicitly reports that a valid build is missing, the signature is expired, or the binary is incompatible, build, then continue start; do not perform a full reinstall or re-sign just because of a cold start. When a job fails, inspect that job's exact logs and next_steps, then handle the real missing items; do not loop start. - After obtaining
ready=true, reuse the current observation and continue the original task. Only real USB / Xcode / signing / permission blockers require corresponding handling; when the user themself must unlock, trust, log in, or confirm, use the host question flow whose first option is "已完成继续". When the user explicitly requires read-only or prohibits start / restart, keep the restriction and do not bypass it through initialization.
When this chat already has a widget, rerunning setup, starting / recovering the channel, and verifying READY again all reuse the existing panel, and pua_screen() is no longer called additionally to open a new tab. When the user only asks to "first open the widget so I can see it" and the panel is not yet open, call pua_screen() to open the preview, then continue initialization and authorized tasks without adding a gate that waits for approval; if the user explicitly asks to wait for confirmation first, do so. When not started, a temporarily blank preview does not prove READY, nor does it mean the entire task has failed.
First install
- Guide the user, based on doctor's specific missing items, to prepare a complete iOS-matched Xcode, accept the first-launch license, and sign in to their own Apple Account in Xcode's account settings. Account login, password, verification code, and device unlock are completed by the user in the system interface; do not ask for credentials.
- Connect the iPhone with a data cable; for first-time pairing, tap "Trust This Computer" on the phone. Confirm from Xcode's Devices and Simulators or the discover response that the device has been recognized; being visible in Finder alone does not mean development pairing is complete.
- Based on the actual system prompts, enable "Settings → Privacy & Security → Developer Mode" and complete the confirmation after restart. If that entry is not present, first let Xcode complete device pairing and development preparation, then check again; do not judge the lack of the entry as permanent lack of support. When needed, check "Settings → Developer → Enable UI Automation".
- Use
pua_setup(action="fetch")to obtain the fixed-version mobile-side execution service used by PUA, thenconfigureconfigure the user'sudid、team_idand signablebundle_id; optionalsource_dir、local_port、device_port, the default local forwarding port is 18100, and the device port is 8100. Local runtime data is by default in~/.local/share/iphone-use. Do not copy the author's UDID, Team ID, or signing. When automatic signing fails, follow the returned logs to check the Runner target's Signing & Capabilities, and select the user's own Team; adjust the bundle ID or provisioning only when an error requires it. - Use
buildto build, thenstartto install and start the Runner test service and local USB forwarding. fetch/build/start are background work; record the job_id, usepua_setup(action="status", job_id=...)to query existing work, find it by id from the returnedjobsarray, and do not assume status returns a single job. For fetch / build, look at the terminal state, and read the exact logs on failure; start is a long-running Runner, and when the work is still running andservice.ready=true, you can call READY, without waiting for succeeded and without repeating start. Query according to status, logs, and the returned retry_after_seconds; do not blind-wait with a fixed long interval or fixed number of attempts. start uses the successful build artifact of the current configuration, and by default keeps the data cable connected and keeps the device available for UI testing. - If the phone or Xcode reports that the developer is not trusted, complete verification via the current device's "Settings → General → VPN & Device Management" and its developer entry; follow the current prompt, and do not apply the enterprise App flow to all development signing. Then run
statusandpua_ready。
When account login, passwords, device unlock, phone confirmation, or Xcode installation truly require the user to complete them, explain the exact page, the blocking reason, and the steps to continue after completion, and you must call an available host question tool (Default prefers functions.request_user_input_async), with the first option fixed as "Completed, continue" and the second allowed to be "Temporarily unable to complete". An asynchronous return, preselection, or the passage of time does not mean the user has completed it; continue relying on that step's configuration only after receiving the user's actual selection of "Completed, continue" or an explicit completion reply. Only when the host has no questioning capability should you use a textual waiting explanation. Other independent configurations can continue to be executed. Do not add a unified confirmation gate for an already authorized local installation. Do not delete the user's existing development apps, revoke shared certificates, or upgrade the account for a fee to bypass errors.
READY acceptance and recovery
READY has returned the device, session, viewport, and current observation; reuse this information to prepare the next step. Do not immediately reread the tree or add a navigation precheck for each task; test only on side-effect-free pages when a specific diagnosis truly requires it. For regular navigation, default to observe=none, verify=false; when the next step needs unknown page information, return tree / screenshot / both in this action, without adding a separate verification round. For the final key operation, explicitly expect / verify or perform one terminal-state read.
After the channel is READY, the target App may still require a password, verification code, or Face ID. Follow authentication takeover and recovery, first call pua_screen(action="pause") to stop the preview and clear the screen, then according to that reference call the question tool to prompt the user to complete it on the iPhone, with the first option "Completed, continue"; pause phone calls during the takeover. After receiving the user's actual selection of "Completed, continue" or an explicit completion notification, call pua_screen(action="resume"), and re-observe the App and the target page. App authentication is not a PUA failure; do not repeat build / start / recover for it; restore READY only when the phone is truly locked or the channel is interrupted.
After a disconnection, restart, stopping the test process, or exiting USB forwarding, query status according to the not-started flow above and reuse the existing work/build; call doctor only when a specific item is missing, restore the connection or start according to the missing layer, and finally get back to READY. After the user takes over the phone, re-observe the current App; do not continue using coordinates from before the takeover or guess at the original page.
XCTDaemonErrorDomain Code=41、local.pid.0 or pua_foreground_unavailable is a PUA / XCTest channel failure and cannot be solved by changing the selector or treating status.ready=true as proof of operability: call pua_ready(screenshot=false). It first rebuilds the session and rereads once; only if the failure persists does it restore in the background the instance of this plugin service that has been verified for configuration, endpoint, worker, and listening port ownership, without replaying the failed navigation, input, or submission.state="recovering" query the same work by recovery.job_id; after recovery_phase reaches serving, re-verify READY, do not start again, and do not wait for succeeded;state="recovery_required" indicates that recovery was disabled this time; use recover=true again only when user instructions permit;pua_recovery_required handle the error according to the cooldown, ownership, or build reason in it, and do not kill processes by port. Neither not-ready state has an error, and still does not mean READY. For the complete handling of each state, see Channel Recovery。
Handle signing, capacity, connection, developer mode, and version issues according to the actual logs, and read Troubleshooting. When recovering, reuse the available build and PUA; rebuild only when the signing has expired, the binary is incompatible, or the build is invalid. Output READY or NEEDS_USER_ACTION, with the already verified layers, the exact missing items, and the next step; if verification is not complete, remain not ready.
Official basis
Apple's developer account documentationstates that a Personal Team can install at most 3 apps per device, and the provisioning profile expires 7 days after self-signing, at which point it needs to be rebuilt and reinstalled. A free account can be used for personal device testing, and permanent operation cannot be promised on that basis.
Apple Developer Modeand Appium real device preparationprovide pairing, developer mode, and signing requirements. The flow is based on the actual prompts and tool diagnostics of the current Xcode/iOS; this plugin does not require jailbreaking.