Agent Device
Drive real iOS, tvOS, macOS, and Android devices from the terminal for UI automation, evidence collection, and agent-driven QA.
Overview
agent-device is an agent skill most often used in Ship (also Build) that routes CLI plans for automating iOS, Android, and macOS apps with evidence-grade device control.
Install
npx skills add https://github.com/callstackincubator/agent-device --skill agent-deviceWhat is this skill?
- Router skill: verify agent-device CLI with --version before any automation plan
- Requires agent-device >= 0.14.0; blocks outdated CLIs without autonomous global npm upgrades
- Version-matched help via agent-device help workflow plus optional debugging, React Native, remote, macOS topics
- Automates tap, type, scroll, screenshots, UI extraction, logs, network, and perf evidence
- Resolves binary path from user shell/PATH when Codex PATH differs from the developer terminal
Adoption & trust: 6k installs on skills.sh; 2.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need repeatable device automation and debugging evidence but your agent keeps guessing wrong agent-device commands or outdated CLI flags.
Who is it for?
Mobile indie devs dogfooding native or React Native apps who want terminal-driven UI tests and log capture.
Skip if: Pure unit-test-only backends, web-only SPAs with no native shell, or environments where installing agent-device is not approved.
When should I use this skill?
Navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, extracting UI info, collecting logs/network/perf evidence, or planning agent-device CLI commands.
What do I get? / Deliverables
The agent validates the installed CLI version, loads version-matched help, and produces safe device automation plans without unsanctioned global upgrades.
- Version-checked CLI invocation plan
- Device automation command sequence
- Captured screenshots, UI dumps, or log excerpts
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Device automation is canonical on Ship when you validate builds before release, but the same CLI supports iterative Build debugging. Navigation, snapshots, taps, and logs are test-and-verification workflows, not feature implementation.
Where it fits
Reproduce a React Native navigation bug by scripting taps and scrolls on a connected device.
Run a pre-release pass that screenshots critical flows and attaches logs for a one-person release checklist.
Harvest performance signals during dogfood sessions before App Store submission.
Capture on-device logs and UI state after a production crash report lands from a beta user.
How it compares
Device CLI orchestration skill—not a cloud emulator farm or a Playwright-for-web substitute.
Common Questions / FAQ
Who is agent-device for?
Solo builders shipping Apple-platform or Android apps who want agents to plan real device interactions and debugging sessions.
When should I use agent-device?
In Ship for pre-release QA and perf/log evidence; in Build when navigating apps, reproducing UI bugs, or drafting agent-device command sequences.
Is agent-device safe to install?
Treat the CLI as privileged local software; review Prism Security Audits for the skill and only install agent-device from sources you trust.
SKILL.md
READMESKILL.md - Agent Device
# agent-device Router only. Private setup before using this skill: ```bash agent-device --version ``` If that fails but the user may have installed `agent-device` globally, check the user's configured login/interactive shell and environment before using `npx`. Resolve the command the same way the user would from a normal terminal session, then run the absolute binary path if found. This may require inspecting shell startup behavior or package-manager/global bin locations; do not assume the Codex process `PATH` is the user's `PATH`. Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, stop and tell the user to upgrade the trusted install or approve an exact-version npm command. Do not run `npm install -g agent-device@latest` or `npx -y agent-device@latest` autonomously, and do not include version/upgrade commands in final plans. Before your first agent-device command or plan, read the version-matched CLI guide: ```bash agent-device help workflow ``` Escalate only when relevant: ```bash agent-device help debugging agent-device help react-native agent-device help react-devtools agent-device help remote agent-device help macos agent-device help dogfood ``` Default loop: `open -> snapshot/-i -> get/is/find or press/fill/scroll/wait -> verify -> close`. Use this skill only to route into version-matched CLI help. Let `help workflow` provide exact command shapes, platform limits, and current workflow guidance. For precise location workflows, read the installed `settings` help before planning so coordinate support and platform limits come from the active CLI version.