# Device App Automation

Automates iOS, macOS, Android and TV apps with snapshots, taps and screenshots.

- Repository: https://github.com/callstack/agent-device (5222 stars)
- Category: Mobile
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add callstack/agent-device --skill agent-device -g -a claude-code -y`
Codex: `npx skills add callstack/agent-device --skill agent-device -g -a codex -y`
Cursor: `npx skills add callstack/agent-device --skill agent-device -g -a cursor -y`
Gemini CLI: `npx skills add callstack/agent-device --skill agent-device -g -a gemini-cli -y`

## Description

Automates Apple-platform apps (iOS, tvOS, macOS), Android devices (including Android TV and Fire TV on Fire OS), and Amazon Vega OS TV apps in Vega Virtual Devices. Use when navigating apps, taking snapshots/screenshots where supported, driving TV remotes, tapping, typing, scrolling, extracting UI info, collecting evidence, or planning agent-device CLI commands.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# agent-device

For a normal app-driving task, start immediately. Do not probe first with `--help`, `--version`, `devices`, `appstate`, `snapshot`, or `screenshot`:

```bash
agent-device open <app> --foreground
```

That starts the session and returns the initial interactive snapshot with `@refs`.

Loop: act with `press|click|fill|longpress <target> ... --settle`, `scroll <direction> --settle`, or `back --settle`; continue from the printed diff, verify the named expectation (`wait text "..."`, `is`, `get`, or `find`), then run `agent-device close`.

Reaching an off-screen target is one command, not a scroll-and-check loop: `scroll down --until <selector>` scrolls until that element is on screen, and `scroll bottom` runs to the end of the content. Repeated bare `scroll down` calls are the slow way to find something.

Copy refs byte-for-byte: `@e12`, `@e12~s4`, keep the `@` and any `~sN`. Prefer current refs, then `id`/`label`/`role` selectors; coordinates are a last resort. If snapshot reports sparse/AX-unavailable, its refs and selectors are invalid: run `agent-device screenshot`, inspect the image, use coordinates, then retry `snapshot -i` after navigating. Otherwise run `snapshot -i` only when the diff lacks the next target.

Error output includes corrective hints; follow them instead of re-planning. Only when the task is specialized (for example gestures, scripting, TV, macOS, remote, or debugging) or a command shape is unclear, run `agent-device help <topic>`. `agent-device --help` lists topics, but is not a startup step.

To capture network traffic on a Limrun session, see `agent-device help remote` or the Limrun docs.