- name
- agent-device
- description
- Automates interactions for iOS simulators/devices and Android emulators/devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, or extracting UI info on mobile targets.
Mobile Automation with agent-device
For exploration, use snapshot refs. For deterministic replay, use selectors.
Start Here (Read This First)
Use this skill as a router, not a full manual.
- Pick one mode:
- Normal interaction flow - Debug/crash flow - Replay maintenance flow
- Run one canonical flow below.
- Open references only if blocked.
Decision Map
- No target context yet:
devices-> pick target ->open. - Normal UI task:
open->snapshot -i->press/fill->diff snapshot -i->close - Debug/crash:
open <app>->logs clear --restart-> reproduce ->logs path-> targetedgrep - Replay drift:
replay -u <path>-> verify updated selectors
Canonical Flows
1) Normal Interaction Flow
agent-device open Settings --platform ios
agent-device snapshot -i
agent-device press @e3
agent-device diff snapshot -i
agent-device fill @e5 "test"
agent-device close2) Debug/Crash Flow
agent-device open MyApp --platform ios
agent-device logs clear --restart
agent-device logs pathLogging is off by default. Enable only for debugging windows. logs clear --restart requires an active app session (open <app> first).
3) Replay Maintenance Flow
agent-device replay -u ./session.adCommand Skeleton (Minimal)
Session and navigation
agent-device devices
agent-device open [app|url] [url]
agent-device open [app] --relaunch
agent-device close [app]
agent-device session listUse boot only as fallback when open cannot find/connect to a ready target.
Snapshot and targeting
agent-device snapshot -i
agent-device diff snapshot -i
agent-device find "Sign In" click
agent-device press @e1
agent-device fill @e2 "text"
agent-device is visible 'id="anchor"'press is canonical tap command; click is an alias.
Utilities
agent-device appstate
agent-device get text @e1
agent-device screenshot out.png
agent-device trace start
agent-device trace stop ./trace.logBatch (when sequence is already known)
agent-device batch --steps-file /tmp/batch-steps.json --jsonGuardrails (High Value Only)
- Re-snapshot after UI mutations (navigation/modal/list changes).
- Prefer
snapshot -i; scope/depth only when needed. - Use refs for discovery, selectors for replay/assertions.
- Use
fillfor clear-then-type semantics; usetypefor focused append typing. - iOS
appstateis session-scoped; Androidappstateis live foreground state. - iOS settings helpers are simulator-only; use faceid
match|nonmatch|enroll|unenroll. - If using
--save-script, prefer explicit path syntax (--save-script=flow.ador./flow.ad).
Security and Trust Notes
- Prefer a preinstalled
agent-devicebinary over on-demand package execution. - If install is required, pin an exact version (for example:
npx --yes agent-device@<exact-version> --help). - Signing/provisioning environment variables are optional, sensitive, and only for iOS physical-device setup.
- Logs/artifacts are written under
~/.agent-device; replay scripts write to explicit paths you provide. - Keep logging off unless debugging and use least-privilege/isolated environments for autonomous runs.
Common Mistakes
- Mixing debug flow into normal runs (keep logs off unless debugging).
- Continuing to use stale refs after screen transitions.
- Using URL opens with Android
--activity(unsupported combination). - Treating
bootas default first step instead of fallback.