Read or replace persistent notes for one bundle id about app navigation and quirks. Resolve bundle with phone_apps; without text, read the existing Markdown. With text, replace it entirely (not append), at most 16 KiB UTF-8; read first to preserve useful notes. An empty text clears the notes. The first screen read in an app also includes them in its registry block. Use phone_flow_draft for executable task replay, not these notes. Writes affect future sessions; never store passwords, codes or personal data. Errors do not prove a write was delivered: read back before retrying.

Find an app's bundle id by name instead of guessing it. Read-only: it never touches the screen and takes no owner lease. Searches the phone's own app list, then a bundled catalog of popular apps (bundle ids verified against Apple's lookup API, plus Apple's built-in apps), then the App Store only when neither matched. Exact name/alias matches hide partial ones. Each candidate carries name, bundle_id, source (installed|catalog|apple), installed_verified, and publisher when known; installed_verified=false with installation_checked=false means unknown, not absent. Pick the candidate whose name and publisher fit, then launch it with launch_app bundle — or give launch_app app the exact name and let the daemon resolve it (it refuses ambiguous names with candidates instead of guessing).

Inspect supported UI operations and cached readiness before choosing an action. Unlike phone_status (device/setup/owner diagnostics), this names the backend's single-step, batch and perform vocabularies, observation support and accepted modes. Read-only: no device connection, wake or owner lease. supported is static; available is cached with blocked_by naming locked, released, reconnecting, human_handoff, owned_by_other or offline. ok:null is unknown, never proof of readiness. This describes UI control only, not app installation or other device management. If blocked, follow phone_status guidance instead of probing with actions.

Read a scrolling list across pages in ONE call instead of scroll + read turns: reads the rows of one kind (default Cell) on screen, swipes one page, reads again, and stops when the exposed page repeats (duplicate_page), end_label is on screen, or max_pages (default 6, max 10) is reached. Rows are deduplicated on (kind, identifier, label, value): different exposed identifiers preserve identical-looking rows. Absent or reused identifiers with identical content may still collapse, so reconcile counts the user cares about. complete is true ONLY when end_label was seen (complete_scope=end_label_visibility); business_complete is always false. duplicate_page is not proof the list ended. Changed pages continue even with no new deduplicated rows. Only what the accessibility tree exposes is collected. It swipes the live list, so the screen is left where the last page was; snapshot is that last page. Optional snapshot (from a read of the target app; never filled in for you): a known foreground app mismatch refuses before any swipe (app_changed; setup may already have affected the device). Results name the app. Owner/privacy changes stop further reads and scrolling. swipes_confirmed counts Native ACKs, swipes_uncertain may have reached the device; never replay uncertain scrolling. Requires phone_status drivable=true.

Crash reports on the phone: without name, list them (name, process, time, size; filter with process); with a name from the list, read that report — exception, crashed thread and backtrace. Read-only: it never touches the screen.

The current screen as text — use this instead of screenshots (an order of magnitude cheaper). Rows carry kind, label, identifier, value, rect and state, plus a snapshot token for phone_tap_element; indexes and snapshot tokens are valid for this read only. query keeps only rows containing that text (label, identifier, value, placeholder) and limit caps the rows. selector ANDs exact kind/identifier/name/label/value/enabled fields and case-sensitive label_contains; optional selector.index (integer0..199) selects one match after scope/query and before limit, retaining the original snapshot row index. Unknown earlier candidates or incomplete tree scope refuse the ordinal. name matches a non-empty identifier, otherwise the label; value_present checks whether the snapshot supplies a string value (including empty/truncated); false means omitted/null on non-secure rows, not a complete AX null; protected SecureTextField rows match neither boolean. It filters AX rows, not OCR. Queries preserve each row's index and the snapshot, so taps still work. Screen text shows at most 200 rows and 32 KiB of row text; an omission notice means a partial view, not absence or list completion. Narrow with query when needed. include_hidden=true expands off-screen/not-drawn rows instead of summarizing five labels; these rows are marked hidden and must be scrolled into view before acting. On the first read in a newly entered app a registry block lists saved flows for it: if one does the task, phone_flow_run it instead of tapping step by step. An alert block means a system alert is up: answer it with an alert step, taps on alerts do not act. ocr=auto adds text read from pixels when the tree has no interactive rows (games, canvases), ocr=force always; such rows have no element, tap their x/y with phone_tap. value_truncated marks an incomplete preview; use phone_read_value for the bounded full AX value. Requires phone_status drivable=true.

Turn what you just did on the phone into a flow. The daemon records every action it applied in the current app (single actions and phone_run_steps batches, not flow runs); this returns that trail as a flow v1 document (snapshot taps become label/identifier locators, typed text becomes named inputs and is never included) plus a todo list of what to fix. Call it when a response carried flow_suggestion, or after any multi-step task with no matching flow — but ASK THE USER before saving. With save_as, the draft is written to that new file and validated; fix the todo items, prove it with phone_flow_run(id=), then publish only with the user's OK.

Inspect an installed flow before phone_flow_run: returns metadata, declared inputs and step templates with placeholders, never runtime input values. Use an id from phone_flow_list, such as health/export-all: exactly two lowercase app/flow slugs, not a local file path. Check app, locale, verification and side effects before execution. Invalid or missing ids return an error without running or downloading anything; use phone_flow_update if the registry store is empty. To inspect a new local draft, validate its file instead of guessing a registry id.

Find installed deterministic per-app flows before exploring a task: a matching phone_flow_run can replay it without model decisions or screenshots. Filters category, app and verified combine; app is a registry app directory or bundle id, not a display-name search. Compact rows report id, description, inputs, risk and compatibility with this phone's app version; detail=true returns full JSON. verified means a recorded hardware run, not a guarantee for every current version. Use phone_flow_info to inspect effects before running. An empty store needs phone_flow_update once; a filter with no matches is not proof that the whole store is empty.

Publish a working flow to the official registry through the user's GitHub CLI login: forks if needed, writes the flow and any new app.json, rebuilds index.json, pushes a branch and opens a public pull request. Requires confirm=true only after the user agrees to that publication. First create a draft with phone_flow_draft and prove it with phone_flow_run; use phone_flow_report to report an existing flow problem. Put device/iOS/date in verified_on; unverified flows open a draft PR. source is a local file or installed flow id; aliases are foreground-app labels by language. Returns id, repo, branch, head and pr_url; inspect the URL before retrying a failed publication.

File an issue on the official flow registry for an installed flow that failed (label changed, app updated, wrong locale). Uses the failure captured by the last phone_flow_run of that id — failed step, redacted daemon result, daemon version — so you only add a short note. Screen labels, typed text, and element lists are stripped. OUTWARD-FACING: requires confirm=true after the user agreed. Do not file for a phone that was simply locked/offline, or for a flow you ran on the wrong app/locale.

Run one flow exactly once — an installed registry id, or a flow file path (*.json, e.g. a phone_flow_draft you are proving before publishing). A flow that declares outputs returns what it read as top-level outputs (e.g. today's steps); verify=true also checks their shape against the recorded fixture. A read_only/navigation flow that misses an element runs its other-language variant once (fallback_from says so): the daemon validates the whole sequence, holds one control lock, and stops at the first failed step. The happy path costs one tool call and zero screenshots. Requires phone_status drivable=true. Pass the flow's declared inputs; a flow declared risk=side_effect is refused unless confirm=true; a flow whose compat is broken or incompatible for the installed app version is refused unless force=true. The result reports completed/applied counts and the failed step; retry_safe=false means DO NOT replay — inspect phone_elements, repair the flow, do not guess. Unverified flows (verified=false in phone_flow_list) may need a checkpoint screenshot afterwards.

Mirror the official iphone-use flow registry (github.com/leeguooooo/iphone-use-flows) into the local store. Every file is checksum-verified and strictly validated before it is written; locally added flows are kept. Call once when phone_flow_list reports an empty store, or to pick up new flows. Network only; the phone is not touched.

Keep the phone for a bounded human-in-the-loop pause inside the current user-requested task (the operator types a PIN, approves a prompt, fetches a code): the idle watchdog will not release it for secs seconds (0 clears the hold; max 14400). When the person signs in (passcode, Face ID, a code), pass private=true: the screen is not read or streamed until you clear the hold; pass private=true again when extending it, since a hold without it lifts the privacy. Not for initialization, health checks, or keeping the phone ready; clear it when the step is done. Fails with device_release_in_progress if the daemon is already releasing, and with phone_owned if another session holds the phone lease.

Read all home-screen pages, Dock, folder pages and widget stacks from the paired iPhone without opening folders, swiping, or taking screenshots. Optional page selects one zero-based page to reduce output. Requires a configured physical target reachable through usbmuxd. This metadata read does not require drivable=true or a running XCTest Runner; never reconnect or open Home solely for this read. Page indexes refer to persisted icon state, including hidden/Focus-filtered pages; they are not the visible page-control indexes. Zero-based row/col positions are derived from icon-state order and grid metrics; null positions or positions_complete=false mean unknown, never safe drag coordinates. Contains no pixel coordinates. An unreadable device returns an error rather than an empty home screen. Writing (action): backup saves the layout as a plist on the Mac; preview compares a plist with the phone by app identifier (added, removed, moved, widgets that would be lost); apply/restore replace the whole layout, only with confirm=true after the person agreed to the preview, and back up the replaced layout first. After a write read again: SpringBoard may bring App Library apps back over a few passes. Undo with action=restore.

Install an app build on the phone: path of an .ipa or .app on the Mac running the daemon, or an https url of an .ipa (up to 2 GB). fresh=true uninstalls the app first, deleting its data. Apps the operator blocked are refused. Answers with the installed bundle id; it can take minutes. Install only what the user asked for.

List installed local iPhone instances and their read-only status. This inventory is not a list of paired/connected devices. For recovery_owner=unconfigured, inspect xcrun devicectl list devices and run iphone-use doctor on the daemon host; ask which phone when ambiguous. Does not start, reconnect or claim a phone. Pass instance in any phone_* call to choose one; omitted instance preserves this MCP server's configured daemon. Missing/invalid instances never fall back to another phone.

Hand ONE whole goal to a fast on-phone agent instead of driving it step by step: TypeSafe's Jev picks each next operation and target from the screen's element table (~1–2 s per step instead of a model turn), a small LLM types field values. Use it for a clear multi-step goal with no saved flow (check phone_flow_list first). It stops with status done / blocked / max_steps and the step history; it answers BLOCKED rather than send, pay, delete or share anything the goal did not explicitly ask for — still confirm such goals with the user first. Verify the end screen yourself. Needs TYPESAFE_API_KEY (or ~/.config/typesafe/key) and, for typing, TEXT_MODEL_API_KEY (or ~/.config/openrouter/key).

Press a navigation or editing key in the foreground app, acting on its current focus. Use phone_type for literal text and phone_tap_element to focus a field first. Check phone_status.drivable and the focused control: delete/backspace can erase content, and return/enter may submit or send it. The schema lists accepted names; unsupported names fail before input is sent. observe defaults on and returns the settled screen change. On an unknown outcome, inspect the screen before another key; repeating a key can change or submit content twice.

Log the app on screen in with the user's OWN account from their password vault (bitwarden-use on the Mac). The daemon reads the vault entry and types it into the phone, so no password or username passes through this conversation. Use it when an app shows its login page during a task the user asked for. The entry is matched to the app; when several match, the answer lists their names: ask the user, then pass item (and user when names repeat). Existing-account login only: never sign-up, password changes or payment. When the answer has needs_code, the app sent a verification code: call again with code_via (sms or mail) and code_from (the sender) once it has arrived; at most two code requests per login. A push approval on another device needs the user. Read the screen afterwards to confirm the login.

Capture and read the paired phone's live system log for app debugging; use phone_crashes for saved crash reports instead. Start capture, reproduce the issue, then read (the default); stop releases the relay, while clear discards the in-memory buffer. Requires a reachable, paired device; connection/auth failures are errors, not an empty log. Capture self-stops after 15 minutes without reads. Filters apply to read results; pass the returned next cursor as since for incremental reads. Output lines are #seq time process[pid] level: message; error includes faults. Logs can contain private app data: collect only what the task needs.

Read task performance aggregates for this MCP client's X-Phone-Owner on the selected instance. Includes recorded HTTP-call counts, batch/flow usage, stale/unknown outcomes, losses and p50/p95 call latency. HTTP calls are not model turns or token usage; model_round_trips remains null without a complete declared trace. Read-only: no phone connection, Runner launch or control lease. Default latest 5 open and recent runs, maximum 20 per section and a shared 12 KiB row budget; omitted counts and truncated state are explicit. Never reconnect solely for metrics. Global cross-owner loss counters are excluded.

Read one current element's AX value without tapping, focusing, waking or taking an owner lease. Give exactly one identifier or exact label from a fresh screen, optionally kind; ambiguity refuses. Use this when phone_elements marks value_truncated or the task needs full field text. Returns one bounded value in text with source/completeness metadata; complete means the AX attribute was not cut by this API, not that the app exposes its full document. A smaller max_utf16 returns truncated:true. Secure fields refuse; old runners without ipu:valueRead refuse rather than promote a preview. Owner/privacy changes withhold the value.

Start/restart on-device automation for the configured phone. This occupies the phone and may require the operator to unlock it. Use only to continue a current user-requested phone operation or screen/UI read that cannot proceed; never reconnect for initialization, status/health checks, a completed task, or to keep the phone ready. Idle release is intentional. Require phone_status released/offline and recovery_owner=daemon; inspect hint/setup_blocked_on first. Do not reconnect while releasing/reconnecting or a blocker remains. Once these conditions are met, call once, then wait for the outcome: pass wait_secs (e.g. 180) to block until drivable=true, a blocker (setup_blocked_on), or the timeout, instead of polling phone_status; wait.outcome is drivable, blocked, stopped or timeout. While it is reconnecting, report setup_phase/setup_message and obey setup_blocked_on. This tool never accepts a UDID and cannot switch devices. An externally managed runner returns an operator-owned recovery error.

Record the iPhone screen to an MP4 on the daemon's Mac: start, perform the requested task, then stop to get path, duration and size. status checks the recording without starting one. Unlike phone_screenshot (one image) or phone_screen (live panel), this persists video under the instance state directory's runs/recordings. Requires a usable device video stream and a writable output directory. Auto-stops after 10 minutes or 200 MB; ended explains why. Video can contain private screens: record only the authorized task, stop when done, and do not treat the returned Mac path as an upload.

Release this session's phone lease when its task ends, so another session can drive immediately. Unlike phone_hold(secs=0), this gives up ownership rather than merely clearing a pause. It sends no phone input and returns ok with owner=null; releasing an already-unowned phone succeeds. A different session's active lease returns phone_owned and is never taken over. Authentication/transport failures are errors; check phone_status.owner before assuming the lease was released.

Close a live task opened with phone_run_start and return its metrics: HTTP calls (not model turns), batches, observed actions, flows, stale/unknown outcomes, failures and p50/p95 call time. Use the same run_id and session; a missing or already-closed run cannot produce a new live summary. Supply turn_ids only for a complete_trace declaration, including every model generation; otherwise model_round_trips remains unknown. This ends accounting only, not a video recording or the owner lease: use phone_record(stop) and phone_release_owner for those.

Open a task boundary for this session's daemon metrics; pair with phone_run_end, not phone_record (video). Later session calls count toward this run; this does not drive or reserve the phone. Optional: without it, idle gaps infer runs. Use a fresh run_id for each task; starting the same still-open id resumes that run rather than resetting its counts. complete_trace is valid only before its first counted call and commits you to supply every model turn id at run_end. Returns a start acknowledgement; report errors rather than claiming metrics were recorded.

THE DEFAULT WAY TO ACT: run a sequence of actions in ONE call and get the screen it ended on back in the same reply (observe, on by default) — one turn instead of one per tap. The daemon validates the whole sequence first, holds one control lock, and stops at the first failure. Use it as soon as a segment is understood; keep single-action tools for exploring an unknown screen. Step kinds: launch_app, open_url, tap_locator, tap_label, tap, type, key, shortcut, scroll, swipe, drag, longpress, multi_longpress (2–5 explicit normalized points held simultaneously), back, alert (system alerts; taps on them do not act), picker, perform (toggle a switch, adjust a slider: element+snapshot from phone_elements), wait_for, pause. Drag points can dwell at an edge while keeping one finger down. Guard every screen change with wait_for; never batch an irreversible step you have not verified. These step objects are exactly a saved flow's steps — when the response carries flow_suggestion, ask the user whether to keep the task as a flow (phone_flow_draft). The result names completed/applied counts and the failed step; retry_safe=false means DO NOT replay.

Open the live iPhone screen panel beside the chat, or reuse the one already open, in hosts that render MCP Apps: the person watches the phone while you work and can press Home or refresh. Read-only: takes no owner lease and wakes nothing. Returns a short status (phone, drivable, owner). Open it once when the person wants to watch; it never replaces phone_elements or phone_screenshot for your own observation. Hosts without MCP Apps show no panel.

Internal frame transport for the iphone-use MCP Apps panel; models use phone_screenshot for a still image and phone_elements for text. Returns structuredContent with status, frame (mime_type=image/png and base64 data), ok and error. A private hold returns frame=null; an empty or failed capture is reported rather than invented pixels. max_side is clamped to 200–1000; fresh bypasses the reusable frame. The panel calls this with visibility app; do not poll it from model turns or use it for health checks.

Read one iPhone screen as an image/png content block when pixels matter; use phone_elements for text and semantic targets, or phone_screen to let the person watch a live MCP Apps panel. It reuses the captured settled frame after an observed action. max_side defaults to 1200; 0 requests full resolution. overlay=true draws interactive frames and their phone_elements indexes. Capture only for the current user task; private holds or offline devices can refuse it. Follow phone_status guidance instead of reconnecting for health checks. An image alone does not prove an action succeeded; check the target state or receipt.

Move the current viewport with one device-side swipe; use phone_scroll_find to locate a known label, or phone_collect_list to read multiple pages. x,y are a normalized anchor in the intended scrollable region. Avoid text fields, sliders and screen edges: a misplaced gesture can edit a control or navigate away. Positive dy reveals content below, negative above; dx reveals right/left. Travel is 1.5 times each delta in points, clamped to 15–75% of that screen dimension. Requires phone_status.drivable=true. observe defaults on and returns the settled screen change; inspect it before repeating a swipe.

Find one exact label, swiping at most max_swipes times (default 1, max 5) when it is not on screen. Stops AT ONCE — no further swipe — when the label is ambiguous (several on-screen matches: candidates with index and frame), covered by another control, or not drawn. Found: target (index, kind, frame) plus a snapshot for phone_tap_element. Not found: on-screen labels containing the text as candidates. No screenshot is taken; absence after the budget is not proof — look at the screen before swiping further. Optional snapshot (from a read of the target app; never filled in for you): a known foreground app mismatch refuses before any swipe (app_changed). Setup may already have affected the device. Stops when ownership or privacy authorization changes and withholds observations. swipes_confirmed counts Native ACKs, not displacement; swipes_uncertain means no ACK and must not be replayed automatically. Requires phone_status drivable=true.

Simulate GPS for testing location-aware apps. Supply both lat (-90–90) and lon (-180–180), in finite decimal degrees, or clear=true without coordinates to restore real location; combining clear with coordinates is refused. Every app sees the simulated position until cleared; it is not a navigation or address lookup tool. Counts as one daemon action and requires authorized device control. Returns the applied location/clear status; on a transport failure the effect is unknown. Inspect the result before proceeding and clear the simulation when the test ends.

Use Home (home), Spotlight (spotlight), physical volume buttons (volume_up, volume_down), or request a system screenshot in Photos (save_screenshot). Volume acknowledgement confirms only a button request, not the volume level; Simulator and older Runners without ipu:volumeButtons refuse before dispatch. save_screenshot is a mutation, unlike phone_screenshot which only returns image bytes. Its receipt means requested, not saved_verified, and requires ipu:systemCaptureRequest. If iOS opens a screenshot preview, inspect the system UI and choose Done/Save to Photos for that existing image; never take another screenshot to complete its save. Check Photos or its picker before claiming it saved. Never replay an uncertain capture or volume request. Navigation leaves the current app or changes its visible state. Use phone_key for field keys, or phone_run_steps with launch_app for a specific app. Requires phone_status.drivable=true. Names are trimmed and case-insensitive. switcher and other names fail before input is sent; the runner cannot synthesize the App Switcher gesture. observe defaults on and returns the settled screen change. Verify it before another action; repeating system navigation may lose the current context.

Read the phone's status without taking control. owner names the session currently driving the phone (this session presents IPHONE_USE_OWNER, else mcp-); if it is someone else, do not drive the phone — control calls will be refused with phone_owned. The JSON preserves backend, target_configured, managed_runner, managed_runner_pending, recovery_owner, device_state, screen_state, runner, runner_actionable, locked, drivable, released, hint, next_step, recovery, setup_blocked_on, setup_phase, and setup_message. Gate actions on drivable=true. If target_configured=false and recovery_owner=unconfigured, phone_instances is only installed instances: inspect xcrun devicectl list devices and run iphone-use doctor on the daemon host; ask which phone if ambiguous, then IPU_RUNNER_UDID= iphone-use setup for the confirmed target only when the task authorizes it. Preserve --instance for named instances. lock_readiness says whether the phone locks on its own when idle (passcode_protected, auto_lock_secs, keep_awake, verdict, hint): will_lock_needs_person means a person must unlock it after a pause; tell the owner the hint instead of retrying. For trust, distinguish Trust This Computer pairing from developer-certificate approval under iPhone Settings > General > VPN & Device Management; use setup_message evidence. A separate passcode/automation prompt may appear later. needs_passcode_on_phone records a possible authorization requirement, not a confirmed visible prompt. Relay next_step; never request a passcode, pause screenshots/elements during sensitive input, and check status after the person finishes. Do not loop reconnect. keep_runner_alive (non-null) means idle release keeps the runner up because its next start would need a person. For status/health checks, report the state and stop. Idle release is intentional: reconnect (phone_reconnect, once) only when a current user-requested task needs the phone, recovery_owner=daemon, and no blocker or reconnect is in progress; then poll until drivable=true.

Tap a pixel target using normalized x,y from 0–1, with (0,0) at top-left. Prefer phone_tap_element for an accessible control; use phone_screenshot to locate a pixel-only target. Requires phone_status.drivable=true and current screen evidence: a tap may send, buy, delete or toggle whatever occupies that point, so authorize its actual effect first. observe defaults on and returns the settled screen change. Read outcome/retry_safe; if delivery is unknown, inspect the current state or receipt before considering another tap.

Tap one element by its zero-based index and snapshot token from the SAME phone_elements response. The daemon re-reads the tree and refuses the action if the UI changed, so a stale element reference cannot silently tap a different control. Use identifier/kind/label/state fields to choose the index. Snapshot refs are ephemeral: never persist them in a flow.

Tap an iPhone UI element by an EXACT visible label (requires drivable=true in phone_status). Reads a fresh phone_elements snapshot, requires exactly one match, then performs a snapshot-bound tap. Zero or multiple matches return an error and send NO action. For duplicate labels, choose by identifier/kind/state from phone_elements and call phone_tap_element with that response's snapshot.

Insert literal Unicode text into the currently focused iPhone field. Use phone_tap_element to focus the intended field first; use phone_key for a navigation or editing key. Requires phone_status.drivable=true. Text can replace a selection or reach the wrong field if focus changed. Long text is chunked. Optional budget_ms (6000..15000) can stop at a safe boundary; continue only with the returned continue_token, without text/clear/budget_ms. Tokens are single-use and scoped to the original field, owner, privacy, lifecycle and session. Unknown outcomes never issue a token. On partial failure inspect characters_confirmed and remaining_text; never resend the whole value blindly. observe defaults on and returns the settled screen change. Verify the resulting field before submitting; an unknown outcome is not evidence that nothing was typed.