{"skill":{"slug":"agent-device","displayName":"Agent Device","summary":"Automates interactions for iOS simulators/devices and Android emulators/devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scr...","description":"---\nname: agent-device\ndescription: 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.\n---\n\n# Mobile Automation with agent-device\n\nFor exploration, use snapshot refs. For deterministic replay, use selectors.\n\n## Start Here (Read This First)\n\nUse this skill as a router, not a full manual.\n\n1. Pick one mode:\n   - Normal interaction flow\n   - Debug/crash flow\n   - Replay maintenance flow\n2. Run one canonical flow below.\n3. Open references only if blocked.\n\n## Decision Map\n\n- No target context yet: `devices` -> pick target -> `open`.\n- Normal UI task: `open` -> `snapshot -i` -> `press/fill` -> `diff snapshot -i` -> `close`\n- Debug/crash: `open <app>` -> `logs clear --restart` -> reproduce -> `logs path` -> targeted `grep`\n- Replay drift: `replay -u <path>` -> verify updated selectors\n\n## Canonical Flows\n\n### 1) Normal Interaction Flow\n\n```bash\nagent-device open Settings --platform ios\nagent-device snapshot -i\nagent-device press @e3\nagent-device diff snapshot -i\nagent-device fill @e5 \"test\"\nagent-device close\n```\n\n### 2) Debug/Crash Flow\n\n```bash\nagent-device open MyApp --platform ios\nagent-device logs clear --restart\nagent-device logs path\n```\n\nLogging is off by default. Enable only for debugging windows.\n`logs clear --restart` requires an active app session (`open <app>` first).\n\n### 3) Replay Maintenance Flow\n\n```bash\nagent-device replay -u ./session.ad\n```\n\n## Command Skeleton (Minimal)\n\n### Session and navigation\n\n```bash\nagent-device devices\nagent-device open [app|url] [url]\nagent-device open [app] --relaunch\nagent-device close [app]\nagent-device session list\n```\n\nUse `boot` only as fallback when `open` cannot find/connect to a ready target.\n\n### Snapshot and targeting\n\n```bash\nagent-device snapshot -i\nagent-device diff snapshot -i\nagent-device find \"Sign In\" click\nagent-device press @e1\nagent-device fill @e2 \"text\"\nagent-device is visible 'id=\"anchor\"'\n```\n\n`press` is canonical tap command; `click` is an alias.\n\n### Utilities\n\n```bash\nagent-device appstate\nagent-device get text @e1\nagent-device screenshot out.png\nagent-device trace start\nagent-device trace stop ./trace.log\n```\n\n### Batch (when sequence is already known)\n\n```bash\nagent-device batch --steps-file /tmp/batch-steps.json --json\n```\n\n## Guardrails (High Value Only)\n\n- Re-snapshot after UI mutations (navigation/modal/list changes).\n- Prefer `snapshot -i`; scope/depth only when needed.\n- Use refs for discovery, selectors for replay/assertions.\n- Use `fill` for clear-then-type semantics; use `type` for focused append typing.\n- iOS `appstate` is session-scoped; Android `appstate` is live foreground state.\n- iOS settings helpers are simulator-only; use faceid `match|nonmatch|enroll|unenroll`.\n- If using `--save-script`, prefer explicit path syntax (`--save-script=flow.ad` or `./flow.ad`).\n\n## Security and Trust Notes\n\n- Prefer a preinstalled `agent-device` binary over on-demand package execution.\n- If install is required, pin an exact version (for example: `npx --yes agent-device@<exact-version> --help`).\n- Signing/provisioning environment variables are optional, sensitive, and only for iOS physical-device setup.\n- Logs/artifacts are written under `~/.agent-device`; replay scripts write to explicit paths you provide.\n- Keep logging off unless debugging and use least-privilege/isolated environments for autonomous runs.\n\n## Common Mistakes\n\n- Mixing debug flow into normal runs (keep logs off unless debugging).\n- Continuing to use stale refs after screen transitions.\n- Using URL opens with Android `--activity` (unsupported combination).\n- Treating `boot` as default first step instead of fallback.\n\n## References\n\n- [references/snapshot-refs.md](references/snapshot-refs.md)\n- [references/logs-and-debug.md](references/logs-and-debug.md)\n- [references/session-management.md](references/session-management.md)\n- [references/permissions.md](references/permissions.md)\n- [references/video-recording.md](references/video-recording.md)\n- [references/coordinate-system.md](references/coordinate-system.md)\n- [references/batching.md](references/batching.md)\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":1601,"installsAllTime":60,"installsCurrent":10,"stars":3,"versions":2},"createdAt":1771754483475,"updatedAt":1778491608600},"latestVersion":{"version":"1.0.1","createdAt":1771787632486,"changelog":"- Added new logs and debug reference: logs-and-debug.md replaces logs.md.\n- Updated documentation to improve clarity, guidance, and flow structure.\n- \"Logs\" references in core docs now point to logs-and-debug.md.\n- Streamlined main README: more concise starting guide, clarified canonical flows, and improved guardrails section.","license":null},"metadata":null,"owner":{"handle":"okwasniewski","userId":"s176bsb5j4ja3r57dfz4qe3wvd83nvrn","displayName":"Oskar Kwaśniewski","image":"https://avatars.githubusercontent.com/u/52801365?v=4"},"moderation":null}