Device automation CLI for AI agents. Mobile, TV, and desktop apps.
agent-device lets coding agents run real apps, inspect UI state, interact with visible elements, and collect debugging evidence through one CLI.
It is built around token-efficient accessibility snapshots, not pixel-first screenshots. Agents read compact UI trees, locate elements through refs like @e3, perform touch and text actions, and capture screenshots, video, logs, network, perf, and React profiles only when evidence is needed.
- Quality Assurance: dogfood flows, validate PR builds, check accessibility coverage, capture evidence, and turn stable explorations into
.ade2e tests. - Development: build from specs, reproduce crashes and support issues, inspect logs/network/perf data, and iterate until the UI matches the work.
If you know Vercel's agent-browser, this is the same idea for apps and devices.
Install the CLI first:
npm install -g agent-device
agent-device --version
agent-device help workflowThe CLI help is the source of truth for agents and is shipped with the installed version. Skills are optional but recommended when your agent runtime supports them: they auto-route device, React DevTools, and dogfood tasks to the right agent-device help <topic> page and verify the CLI is new enough before acting.
If you install skills separately, keep the CLI on agent-device >= 0.14.0. Older CLIs do not include the workflow help topics that the router skills expect.
npm install -g agent-device@latest
agent-device --version
agent-device helpagent-device performs a lightweight background upgrade check for interactive CLI runs and, when a newer package is available, suggests a global reinstall command. Updating the package also refreshes the bundled skills/ shipped with the CLI.
Prerequisites: Node.js 22+, Xcode for iOS/tvOS/macOS targets, Android SDK + ADB for Android, and macOS Accessibility permission for desktop automation. See Installation.
Try the loop.
# Find the app.
agent-device apps --platform ios
# Start a session.
agent-device open SampleApp --platform ios
# Inspect the current screen. -i returns interactive elements only.
agent-device snapshot -i
# @e1 [heading] "Settings"
# @e2 [button] "Sign In"
# @e3 [text-field] "Email"
# Act, capture a screenshot, and close.
agent-device fill @e3 "test"
agent-device screenshot ./artifacts/settings.png
agent-device closeSnapshots assign refs like @e1, @e2, and @e3 to current-screen elements. Refs from the default snapshot are immediately actionable; for hidden content, scroll and re-snapshot.
| Path | Best for | Start with |
|---|---|---|
| Local | Exploration, debugging, and development loops on simulators, emulators, physical devices, macOS apps, and Linux desktop targets. | Follow the Quick Start. |
| CI/CD | Automated PR and merge validation with replay scripts and captured artifacts. | Start with the EAS workflow template. GitHub Actions template coming soon. |
| Cloud | Linux runners, managed devices, and remote execution. | Use Agent Device Cloud or contact Callstack for team-scale QA. |
- Platforms: iOS, Android, tvOS, Android TV, macOS, and Linux. Real devices and simulators are supported.
- Capture: screenshots, video, logs, network traffic, performance data, accessibility snapshots, and React render profiles.
- Produce: replayable
.adscripts (recorded replay files that run locally or in CI), e2e test runs, snapshot and screenshot diffs, and debugging artifacts. - React Native and Expo: component tree inspection, props/state/hooks, and render profiling.
- License: MIT. Free to use.
agent-device runs session-aware commands through platform backends: XCTest for iOS and tvOS, ADB plus the Android snapshot helper for Android, a local helper for macOS desktop automation, and AT-SPI for Linux desktop targets. See Introduction and Commands for platform details.
Used by teams and developers at Callstack, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow, and more.
Agent integration:
See CONTRIBUTING.md.
agent-device is open source and MIT licensed. Try the EAS workflow template, use Agent Device Cloud, or contact us at hello@callstack.com.