arul28/ade/ade-apple

ADE Apple Development

This skill is for iOS apps and iOS SwiftUI views. 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.

Detail files

Rarely needed detail lives next to this file. Read one when its topic comes up (or ade skill show ade-apple references/<file>):

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.

Use foreground --wait 10, or wait for an element of that app.

• Tap, drag and scroll coordinates are the screenshot's and the snapshot's

points, upright, whichever way the device is held (the Duo's inner display included): ADE turns them onto the framebuffer for you. Prefer tap-element anyway.

• launch builds Debug. Pass --configuration Release when the app's

configurations differ in more than speed (ADE's own iOS app signs into a test backend in Debug); the summary names the configuration it built. Arguments after -- reach the app, for launch and relaunch.

• One agent should drive the device. Let it do the taps, screenshots and

recordings; other agents hand it work, or wait for its results. That is simpler and faster than several agents taking turns. When agents truly must drive the same device in parallel, take a lease before a run of builds, rotates and shots (it queues behind whoever has it) and release it after. It is advisory, so it only works if every agent uses it. Device commands do not renew it: renew with the token before --ttl ends. It also ends when its chat is archived or deleted. Each device has its own lease. Tokens, renewing, and --holder for subagents: references/devices-and-runtimes.md.

• 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, and you never make a

simulator with xcrun simctl create or simctl clone — ADE cannot see or delete a device made that way.

• Need a second model too (an iPad beside an iPhone Duo)? Give the lane an

extra device: device-create --extra --device-type "<model>" (at most 2), then reach it from any command with --device <udid|name>. An extra cannot stream, record, launch or run tests. Extras, install --device and device-promote: references/devices-and-runtimes.md.

• 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 or one of

its extra devices. 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").

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.

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, one run at a time on the Mac. A failing test comes back as passed: false with the failures; it is not an error. Output, --only names and DerivedData: references/tests.md.

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.

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. Creating a device never downloads anything. With no runtime installed you get APPLE_NO_INSTALLED_SIMULATORS: run ade apple runtimes to see what this Xcode needs, and ade apple runtimes install to fetch it (about 8 GB per runtime, in the background; re-run ade apple runtimes for progress). Tell the user before you start a download. Removing a runtime erases or moves every simulator on it, so it is the user's call, from the Apple Development panel's Runtimes section; agents cannot do it.

A runtime (the iOS image, about 8 GB) is a download; a device made from one is cheap, and a device that is Shutdown only needs a boot. So "no device free" is almost never true. Runtimes and devices in full: references/devices-and-runtimes.md.