agent-device skill: let Claude drive and test iOS, Android and TV apps

Callstack's skill that teaches your coding agent to run apps on simulators and devices, tap through them and check the result.

Installs: 19.6K; on skills.sh
Stars: 5.2K; on GitHub
Updated: Nov 2026; last repo commit

agent-device is a usage guide for the agent-device command-line tool. It tells Claude to start with agent-device open <app> --foreground, act on the numbered element references the tool prints, check what changed, and close the session. It triggers when you ask Claude to navigate an app, tap, type, scroll, take screenshots or collect evidence.

The skill is one short file and does not install the tool. You need the agent-device CLI on your computer first, and the README asks for Node.js 22.12 or newer. The README says to run agent-device doctor yourself before you hand the CLI to an agent.

Good for

Mobile developers who want Claude to check its own changes in a running iOS or Android app
QA engineers who want screenshots and logs as evidence for a pull request
Teams building Android TV, Fire TV or tvOS apps

Install agent-device

Claude Code

Copy this prompt.

Install the agent-device skill in Claude Code. Run this command:

npx skills add https://github.com/callstack/agent-device --skill agent-device

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js 22.12 or newer, agent-device CLI.

The skill only teaches the agent. The agent-device command-line tool does the work, so install it first.

From the vendor's docs. Source.

What's in the skill

When it loads

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.

Key facts

Author: Callstack, per the README ("Made at Callstack")
License: MIT
Needs: The agent-device CLI (npm install -g agent-device@latest) and Node.js 22.12 or newer
Works in: The README names Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any agent that can run a CLI or connect over MCP
Files: 1 file: SKILL.md. No scripts.
Installs on skills.sh: 19,616 as of 2026-11-02
GitHub stars: 5,222 for the whole callstack/agent-device repo, 2026-11-02
Last repo commit: 2026-11-01
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass

What it includes

Start a session and get the first snapshot with element refs
The skill says to start here for a normal task, without probing first with --help, --version, devices, appstate, snapshot or screenshot.
Try: “Open the Settings app on the iOS simulator and turn on dark mode.”
Runs code · agent-device open <app> --foreground
Act on a screen element, then settle
Acts on a target with --settle, then continues from the printed diff. Refs like @e12 must be copied exactly.
Runs code · press, click, fill, longpress
Scroll, jump to the end, or go back
scroll <direction> --settle, back --settle, scroll down --until <selector> to reach an off-screen target, and scroll bottom to reach the end.
Runs code · scroll and back
Check text and state with wait, is, get or find
After acting, Claude checks the named expectation, for example wait text "...".
Runs code · Verify
Read the screen again, or fall back to an image
Run snapshot -i only when the diff lacks the next target. If the snapshot is sparse, take a screenshot and use coordinates as a last resort.
Files · snapshot -i and screenshot
End the session
The last step of the loop.
Runs code · agent-device close
Look up specialised topics only when needed
For gestures, scripting, TV, macOS, remote or debugging, or when a command shape is unclear.
Read · agent-device help <topic>
Points to help remote for network traffic on a Limrun session
The skill refers to agent-device help remote or the Limrun docs for this.
Read · Limrun network capture

From the official docs

Permissions

Medium risk

Claude runs a command-line tool that can tap, type and capture screens on simulators, emulators and physical devices. Start on a simulator with test accounts and read the commands Claude proposes.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It acts inside real apps on your devices
Taps and typed text go to whatever app is open, including physical devices you connect. Use a simulator and test accounts first. github.com
You install a global npm tool first
The README installs the CLI with a global npm command and asks you to run agent-device doctor yourself before handing it to an agent. Check the setup output before you continue. github.com
Cloud and remote setups are separate
The README lists a remote proxy and device clouds (BrowserStack, AWS Device Farm, TestMu AI, Limrun) as other ways to run. Read their docs before you point the tool at one. github.com

Technical details

Scopes	Runs the agent-device CLI on your computer Taps, types, scrolls and navigates apps on connected devices Saves screenshots and other evidence files

Questions

What does the agent-device skill do?

It tells your coding agent how to drive apps through the agent-device CLI: open an app, tap and type using element refs, check the result and close the session. The CLI covers iOS, Android, TV and desktop targets, according to its README.

Do I need to install anything besides the skill?

Yes. Install the agent-device CLI with npm install -g agent-device@latest, which the README says needs Node.js 22.12 or newer, then run agent-device doctor. The install box on this page lists that step.

Does it work in Claude Code, Codex or Cursor?

The README says agent-device works with Claude Code, Codex, Cursor, Windsurf, Cline and Goose, and with any agent that can run a CLI or connect over MCP. It needs the CLI on your computer, so the skill is for agents that can run shell commands.

Is it safe to run?

The agent can tap, type and navigate real apps on simulators and physical devices you connect, so use test accounts and a simulator first. The tool also keeps sessions per git worktree and claims devices so parallel agents do not take over each other's simulators.

How is the skill different from the agent-device MCP server?

The skill is instructions only: it teaches your agent the CLI loop (open, act, verify, close) and the agent then runs agent-device commands in a shell. The agent-device MCP server is the other route: agent-device mcp starts the official stdio MCP server, which the README says exposes the installed commands as structured tools over the same execution path as the CLI. Both need the same agent-device CLI. The README links an agent setup guide on when to prefer plain CLI over MCP. Pick the skill if your agent can run shell commands, or the MCP server if you want the commands as tools in the client.

How is it different from Appium, Detox or Maestro?

The README says that with agent-device an agent reads the app state and chooses each command at run time. It can also save runs as .ad scripts or export them as strict Maestro YAML.

Information

updated Nov 2, 2026

Repository: callstack/agent-device
Folder: skills/agent-device

callstack/agent-device skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3

agent-device · skills.sh
README.md · github.com
SKILL.md · github.com