Ade Apple

ADE Apple Development

This skill is for iOS and SwiftUI apps. For a macOS app, a dev Electron app or a web page, the ade-computer-use skill picks the right surface.

Drive the lane's Apple simulator with "$ADE_CLI_PATH" apple <command>. $ADE_CLI_PATH is the CLI of the ADE that launched you and already targets its brain, so your calls and the desktop's Apple Development tool share one session. A bare ade goes through PATH and can reach a different ADE.

The pixels come from a vendored Swift helper (ade-sim-helper) reading the device framebuffer. There is no Screen Recording grant, no Simulator window to keep open, and no backend to choose. If you find advice about idb, window capture, live-start or a --backend flag, it is describing a version of this feature that no longer exists.

Four rules before your first command

• Always call "$ADE_CLI_PATH", never a bare ade. A bare ade can be an older install or another ADE's CLI. That shows up as "Unknown command 'apple'", "Domain 'apple' is unavailable", or a runtime version mismatch. Do not add --socket: "$ADE_CLI_PATH" already names the right one.
• Never open or script the Simulator app. No open -a Simulator, no AppleScript or System Events. ADE drives the device directly; the Simulator window is not needed and adds nothing.
• Never capture proof with xcrun simctl io … screenshot or recordVideo. apple screenshot and apple record-start / record-stop file proof to the lane automatically. See below for why the owner matters.
• Check each step before you report it. A tap, swipe, button or type that returns ok only means ADE sent the input. It does not mean the app did what you wanted. After each step that matters, confirm it: apple foreground (which app is in front), apple assert-visible or apple wait-for-element (what is on screen), or apple snapshot. Report only what you confirmed. If a step failed, say which step, and do not describe the result you meant to get. Before record-stop, confirm the final state, so the video ends on it.

Common tasks

Use these directly; you do not need --help for them. A="$ADE_CLI_PATH".

• Right after relaunch, foreground can still say null for a moment. Wait for an element of that app instead of checking at once.
• A simulator signed in to an Apple Account can show an "Apple Account Verification" alert over every app. Dismiss it with tap-element --label "Not Now", then continue.

Start here: ask what you can do

"$ADE_CLI_PATH" apple status --text

status is the gate and the map.

• supported: false means the runtime is not a Mac. Stop and say so.
• capabilities lists every action you may call on this device, by name. Read it instead of guessing verbs or reading source.
• device tells you whether this lane already owns a simulator, its origin (created or the older clone for ADE's own, attached for the user's), and its laneId.
• tools.helper (present, path, version) is the check when every device call fails at once.

"Start the app on a simulator" is one command

"$ADE_CLI_PATH" apple launch --follow --open-drawer --text

launch does the whole chain: find or make the lane's device, boot it, resolve the target, build it with xcodebuild, install it, start it, and claim the drawer session. Add --open-drawer when a human asked to watch. --follow announces the wait up front for a cold build.

So you do not run xcodebuild by hand to put an app on a screen, and you do not need to know the scheme. Run "$ADE_CLI_PATH" apple apps --text first only when you must choose between several targets, then pass --target <id>.

Use --no-build when the app is already installed and you only want it in front. Use relaunch or terminate for an app that is already there.

Use this lane's own device

Use this lane's own device. ade apple start (or device-create) gives the lane its own; do it without asking.

start with no arguments does this for you: when the lane has no device it makes a new, empty one from the newest installed runtime, boots it, and streams it. Other simulators in apple devices belong to someone else: another lane, an xcodebuild test run, or the user.

• You may make the lane's ONE device without asking. You may not make a second one, and you never make a simulator with xcrun simctl create or simctl clone — ADE cannot see or delete a device made that way.
• You may attach an installed simulator only when the user names it (device-attach --simulator <name> or start --udid <udid>). ADE refuses a simulator another lane holds, with APPLE_DEVICE_NOT_LANE_OWNED.
• --device <udid> on any other command must be this lane's device. With no device yet, the command tells you to run ade apple start.

A busy device is not a blocker, and it is not a reason to ask a human. Make the lane's own with start. It takes seconds (see "The lane's device").

Tests run on the lane's device

"$ADE_CLI_PATH" apple test --scheme <scheme> --text
"$ADE_CLI_PATH" apple test --target <id> --only ADETests/SyncTests --text

apple test runs xcodebuild test on this lane's device, with parallel testing off and DerivedData in the lane's cache (.ade/cache/ios-simulator/DerivedData), which ADE deletes with the lane. One test run goes at a time on the Mac (APPLE_TEST_RUN_BUSY: wait, then run again). A failing test comes back as passed: false with the failures and the log path; it is not an error.

Do not run xcodebuild test by hand against a simulator you made. If you must run xcodebuild yourself, pass -derivedDataPath .ade/cache/ios-simulator/DerivedData from the lane worktree, never /tmp or ~/Library/Developer/Xcode/DerivedData.

This is worth saying plainly because the failure looks reasonable from the inside: you find a booted simulator, the guard tells you another chat owns it, and stopping to ask seems polite. It is not. It blocks the work for no reason and hands the human a decision they should never have been given.

And when the request was for simulator proof, simulator proof is what you owe. A passing unit test is not a substitute for a screen. If you cannot reach the screen, say exactly what stopped you rather than offering evidence of a different kind and calling it done.

The lane's device

One simulator per lane. ADE creates one on first ask, or binds one you already have. ADE never downloads a runtime. With none installed you get APPLE_NO_INSTALLED_SIMULATORS — tell the user to open Xcode ▸ Settings ▸ Components.

Two facts that decide what you should do:

• A runtime is the iOS image. It is the large download, one per iOS version, and ADE will not fetch one.
• A device is an instance made from a runtime. Creating one copies no iOS, so it is cheap. A new lane device is empty: it copies nothing from any other simulator and grows only with what the lane installs. A device that is Shutdown is installed and ready — it needs a boot, which takes seconds.

So "no device free" is almost never true: one runtime serves any number of devices, and a new one is a folder of app data, not another copy of iOS. A new device has no sign-ins, so the app starts at its first-run state.

"$ADE_CLI_PATH" apple device-list --installed --text   # what a picker shows
"$ADE_CLI_PATH" apple device-list --runtimes --text    # installed runtimes and models
"$ADE_CLI_PATH" apple device-list --text               # the one this lane owns ($ADE_LANE_ID)
"$ADE_CLI_PATH" apple start --text                     # make one if the lane has none, boot, stream
"$ADE_CLI_PATH" apple start --device-type "iPad Air 11-inch (M4)" --text   # a specific model
"$ADE_CLI_PATH" apple stop --text                      # power the device OFF

• start is the one-step bring-up: make a device when the lane has none, boot it if it is off, wait for the boot, then stream. Prefer it. start --udid works only for the device this lane already holds.
• stop powers the device off. shutdown only ends this chat's session and leaves the simulator running — the two are not the same, and a verb named stop that left a booted device behind was a real bug.
• device-create and device-attach never boot. device-delete removes the lane's ADE device and refuses an attached device unless --force, which only detaches. Like stop, it is refused while another chat is driving the device.
• ADE deletes the lane's own device, with all its data and the lane's build cache, when the lane is archived or deleted. An attached device is powered off and loses only the apps ADE installed. ADE never deletes a simulator it did not create.
• An ADE device that nothing uses for 30 minutes is powered off. start boots it again in seconds.
• Deleting an installed simulator from the list is the user's call, made in the desktop picker. ADE refuses it from an agent; do not try.

Drive the app

Name elements, not pixels.

"$ADE_CLI_PATH" apple snapshot --text
"$ADE_CLI_PATH" apple tap-element --label "Sign in" --text
"$ADE_CLI_PATH" apple fill-element --identifier email-field --value ada@example.com --text
"$ADE_CLI_PATH" apple wait-for-element --label Welcome --timeout-ms 8000 --text
"$ADE_CLI_PATH" apple assert-visible --label Welcome --text

• Run snapshot first. Query with --ref, --identifier, --label, --text-match, --role and --index.
• A ref names its own tier. id: and component: survive a re-render; pos: survives nothing, so ask for an accessibility identifier instead.
• wait-for-element replaces a sleep. Add --gone to wait for a disappearance.
• Fall back to coordinates only when no query matches: tap, drag, swipe, scroll, select.
• type and key act on the focused field, so tap the field first.
• foreground reports which app the device has in front, read from the device rather than from what ADE last launched.
• Hardware buttons: button home (also lock, volume-up, volume-down, siri, app-switcher). shake is refused with APPLE_BUTTON_UNSUPPORTED, because neither the helper nor simctl has it. app-switcher is Simulator's own App Switcher command, two home presses 150 ms apart; do not press home twice yourself, the gap between two calls is too long.
• Orientation: rotate landscape-left (also portrait, portrait-upside-down, landscape-right). Read the answer. rotate turns the device and then reads the screen, so applied: true means the framebuffer was seen on the requested axis — not that a request was sent. iOS always accepts the device orientation and then lets the foreground app decide, so applied: false with reason: APPLE_ROTATE_NOT_ADOPTED means that app kept its own orientation. The Home Screen and Settings are portrait-only on an iPhone, and no iPhone supports portrait upside down — put the app you are testing in front before you rotate, and do not treat a refusal as a broken simulator. verification: already-on-axis means the screen was on that axis before you asked; turning within one axis leaves the pixel size unchanged, so the exact side is not confirmed.

Agent launches stay in the background; apple show brings the device up at any time.

Close an app the way a person does

Bottom-edge swipes do not work: the helper sends them as ordinary touches, so iOS never sees the home-indicator gesture, and a swipe from the bottom edge opens nothing. Use the App Switcher instead.

"$ADE_CLI_PATH" apple button app-switcher --text
"$ADE_CLI_PATH" apple screenshot --out switcher.png --text   # check it opened
"$ADE_CLI_PATH" apple swipe 201 480 201 80 --duration-ms 150 --text
"$ADE_CLI_PATH" apple button home --text

• Coordinates are points. Read the screen size from apple stream-status (pointWidth × pointHeight); the example is an iPhone 16 Pro (402 × 874).
• The front app's card sits in the middle of the switcher. Swipe it up from about (W/2, 0.55 H) to (W/2, 0.09 H), fast: 150 ms. A slow drag only lifts the card.
• Take a screenshot after app-switcher. If the switcher is not showing, do not keep swiping: say so, and use apple terminate --bundle-id <id> to stop the app without showing it (Safari is com.apple.mobilesafari).
• While a recording runs, every failed try is in the video. Check the screen after each step instead of repeating a gesture.