Skip to content
Back to search

agent-device

Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/callstack/agent-device with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/callstack/agent-device'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/callstack--agent-device/badge.svg)](/listings/callstack--agent-device)

HTML

<a href="/listings/callstack--agent-device"><img src="/api/listings/callstack--agent-device/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the CLI and check setup. It requires Node.js 22.12 or newer; web automation requires Node.js 24 or newer. See [Installation](https://oss.callstack.com/agent-device/docs/installation) for target requirements.

npm install -g agent-device@latest
agent-device doctor
agent-device help workflow

Run `doctor` yourself before handing the CLI to an agent; `help workflow` links to the guides for debugging, replay, and profiling, and the installed help always matches the installed version.

Drive an app from the CLI

Add a contact in the built-in iOS Contacts app:

# Start a session.
agent-device open Contacts --platform ios

# Inspect the screen. The example below shows the output; refs vary.
agent-device snapshot -i
# @e2 [button] "Add"

# Use the ref and wait for the UI to settle.
agent-device press @e2 --settle
# The diff includes:
# + @e7 [text-field] "First name"

agent-device fill @e7 "Ada" --settle
# The next diff shows changed values and current refs:
# - @e7 [text-field] "First name"
# + @e14 [text-field] "Ada"
# = @e15 [text-field] "Last name"

# Capture evidence and close the session.
agent-device screenshot ./contact-form.png
agent-device close

Refs are only valid from the latest output: after a `--settle` command, use the refs in its diff, and take a new snapshot only if the diff omits what you need. Snapshots come from the app's accessibility tree, so clear labels, roles, and test IDs make agent runs more reliable; use screenshots and video as evidence or when accessibility data is poor.

Add MCP tools to your agent

`agent-device mcp` starts the official stdio MCP server, exposing the installed commands as structured tools over the same execution path as the CLI:

{
  "mcpServers": {
    "agent-device": {
      "command": "agent-device",
      "args": ["mcp"]
    }
  }
}

See [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) for per-client setup and when to prefer plain CLI over MCP.

Script it from Node.js

`createAgentDeviceClient()` gives Node.js code typed access to the same commands, as model tools in your own agent or from orchestration code:

import { createAgentDeviceClient } from 'agent-device';

const client = createAgentDeviceClient({ session: 'qa-run' });
try {
  await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });
  const snapshot = await client.capture.snapshot({ interactiveOnly: true });
  const button = snapshot.nodes.find((node) => node.role === 'button');
  if (button) await client.interactions.press({ ref: button.ref });
} finally {
  await client.sessions.close();
}

See the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api), the [runnable examples](https://github.com/callstack/agent-device/tree/main/examples/sdk), and the [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk) and [Eve](https://oss.callstack.com/agent-device/docs/eve) integration guides.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 229 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <a href="https://www.callstack.com/open-source?utm_campaign=generic&utm_source=github&utm_medium=referral&utm_content=agent-device" align="center">
  2. <picture>
  3. <img alt="agent-device: open source device layer for agents" src="website/docs/public/agent-device-banner.jpg">
  4. </picture>
  5. </a>
  6. ---
  7. # agent-device
  8. [![npm version](https://img.shields.io/npm/v/agent-device.svg)](https://www.npmjs.com/package/agent-device)
  9. [![CI](https://github.com/callstack/agent-device/actions/workflows/ci.yml/badge.svg)](https://github.com/callstack/agent-device/actions/workflows/ci.yml)
  10. [![License: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE)
  11. [![Glama MCP server](https://glama.ai/mcp/servers/callstack/agent-device/badges/score.svg)](https://glama.ai/mcp/servers/callstack/agent-device)
  12. **Open source device layer for AI coding agents.** Let coding agents control mobile, web, TV, and desktop apps on devices and simulators, locally or in the cloud, through a CLI, built-in MCP server, or typed Node.js API.
  13. <!-- Intro rule: category line, job pitch with the platform list, works-with/proof lines, nothing else. Per-platform transports, tool names, vendor lists, and support caveats belong in "How it works" and website/docs, never here. Every name in the proof lines must link to public evidence. -->
  14. Let your coding agent verify its changes in the running app. `agent-device` lets agents inspect, control, debug, and verify apps on iOS, Android, and HarmonyOS (simulators, emulators, and physical devices), plus tvOS, Android TV, Fire TV (Fire OS), Amazon Vega OS TV (Vega Virtual Device), web, macOS, and Linux. Agents read token-efficient accessibility snapshots instead of reasoning over screenshots alone, act through refs and selectors, and save evidence for review. It also coordinates device access across parallel agent worktrees and connects to remote device clouds.
  15. Works with Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any agent that can run a CLI or connect over MCP, or as the runtime under agents you build with the [AI SDK](https://agent-device.dev/docs/ai-sdk) or [Eve](https://agent-device.dev/docs/eve). Developers at [Expensify](https://www.callstack.com/blog/how-expensify-uses-agent-device-for-mobile-bug-evidence-and-profiling), [Shopify](https://x.com/mustafa01ali/status/2036577353178943826), and [others](#who-uses-agent-device) use it to verify their apps.
  16. <p>
  17. agent-device powers mobile automation in
  18. <a href="https://e2e.com/?utm_source=github&utm_medium=organic&utm_campaign=agent-device-readme-202610&utm_content=readme-powered-by">
  19. <img src="docs/assets/e2e-favicon.svg" width="24" height="24" align="middle" alt="">
  20. e2e</a>
  21. and
  22. <a href="https://github.com/pingdotgg/t3code">
  23. <img src="docs/assets/t3-code-logo.svg" width="24" height="24" align="middle" alt="">
  24. T3 Code</a>.
  25. </p>
  26. ## Quick start
  27. Install the CLI and check setup. It requires Node.js 22.12 or newer; web automation requires Node.js 24 or newer. See [Installation](https://agent-device.dev/docs/installation) for target requirements.
  28. ```bash
  29. npm install -g agent-device@latest
  30. agent-device doctor
  31. agent-device help workflow
  32. ```
  33. Run `doctor` yourself before you hand the CLI to an agent. `help workflow` links to the guides for debugging, replay, and profiling.
  34. ### Drive an app from the CLI
  35. Add a contact in the built-in iOS Contacts app:
  36. ```bash
  37. # Start a session.
  38. agent-device open Contacts --platform ios
  39. # Inspect the screen. The example below shows the output; refs vary.
  40. agent-device snapshot -i
  41. # @e2 [button] "Add"
  42. # Use the ref and wait for the UI to settle.
  43. agent-device press @e2 --settle
  44. # The diff includes:
  45. # + @e7 [text-field] "First name"
  46. agent-device fill @e7 "Ada" --settle
  47. # The next diff shows changed values and current refs:
  48. # - @e7 [text-field] "First name"
  49. # + @e14 [text-field] "Ada"
  50. # = @e15 [text-field] "Last name"
  51. # Capture evidence and close the session.
  52. agent-device screenshot ./contact-form.png
  53. agent-device close
  54. ```
  55. Refs are valid only in the latest output: after a `--settle` command, use the refs in its diff, and take a new snapshot only if the diff omits what you need. Snapshots come from the app's accessibility tree, so clear labels, roles, and test IDs make agent runs more reliable; use screenshots and video as evidence or when accessibility data is poor.
  56. ![agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt](./website/docs/public/agent-device-contacts.gif)
  57. ### Add MCP tools to your agent
  58. `agent-device mcp` starts the official stdio MCP server, exposing the installed commands as structured tools over the same execution path as the CLI:
  59. ```json
  60. {
  61. "mcpServers": {
  62. "agent-device": {
  63. "command": "agent-device",
  64. "args": ["mcp"]
  65. }
  66. }
  67. }
  68. ```
  69. See [AI agent setup](https://agent-device.dev/docs/agent-setup) for per-client setup and when to prefer plain CLI over MCP.
  70. ### Script it from Node.js
  71. `createAgentDeviceClient()` gives Node.js code typed access to the same commands, as model tools in your own agent or from orchestration code:
  72. ```ts
  73. import { createAgentDeviceClient } from 'agent-device';
  74. const client = createAgentDeviceClient({ session: 'qa-run' });
  75. try {
  76. await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });
  77. const snapshot = await client.capture.snapshot({ interactiveOnly: true });
  78. const button = snapshot.nodes.find((node) => node.role === 'button');
  79. if (button) await client.interactions.press({ ref: button.ref });
  80. } finally {
  81. await client.sessions.close();
  82. }
  83. ```
  84. See the [Node.js API](https://agent-device.dev/docs/client-api), the [runnable examples](https://github.com/callstack/agent-device/tree/main/examples/sdk), and the [AI SDK](https://agent-device.dev/docs/ai-sdk) and [Eve](https://agent-device.dev/docs/eve) integration guides.
  85. ## What agents can do
  86. - **Inspect app state** through accessibility snapshots, refs, and selectors, and profile React Native renders to find what makes an interaction slow.
  87. - **Act on visible UI** by tapping or pressing elements, filling fields, scrolling, making gestures, waiting, asserting state, and handling alerts.
  88. - **Diagnose failures** with screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles.
  89. - **Repeat workflows** by saving working steps as `.ad` scripts for local use or CI. Export strict Maestro YAML when needed.
  90. See [Commands](https://agent-device.dev/docs/commands) for the commands and evidence each target supports.
  91. ![Diagram of the agentic development loop: humans assign tasks, agents write and review code, agent-device verifies mobile apps, pull requests receive evidence, and bugs or performance issues lead to fixes](./website/docs/public/agentic-development-loop.svg)
  92. ## What to ask your agent
  93. With the CLI installed, prompts like these work end to end:
  94. - "Implement the onboarding screen, run it on the iOS simulator and Android emulator, and attach screenshots."
  95. - "Reproduce this crash and capture the logs that lead up to it."
  96. - "Check whether this change causes unnecessary React Native re-renders."
  97. - "Explore the checkout flow once, save it as a replay script, and run it in CI."
  98. - "Verify this pull request on a physical device and attach reviewable evidence."
  99. ## Next steps
  100. - [AI agent setup](https://agent-device.dev/docs/agent-setup): skills, project rules, and per-client setup for Cursor, Codex, Claude Code, Windsurf, and others.
  101. - [Quick start](https://agent-device.dev/docs/quick-start): open an app, read its UI, and interact with it from the command line.
  102. - [Replay and E2E testing](https://agent-device.dev/docs/replay-e2e) and [Debugging and profiling](https://agent-device.dev/docs/debugging-profiling): repeatable tests and bug hunting.
  103. ## Where to run agent-device
  104. The same session and evidence model works at every step: the agent explores the app, captures evidence, saves a replay, runs it in CI, and moves onto remote devices.
  105. | Path | Best for | Start with |
  106. | --- | --- | --- |
  107. | Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. |
  108. | CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). |
  109. | Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://agent-device.dev/docs/remote-proxy), connect a [device cloud](https://agent-device.dev/docs/device-clouds) (BrowserStack, AWS Device Farm, TestMu AI, Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. |
  110. ## How it works
  111. `agent-device` keeps device state in sessions. It uses a local accessibility bridge for iOS Simulator snapshots and XCTest for iOS interactions, physical iOS, and tvOS; ADB and the snapshot helper on Android, Android TV, and Fire OS; HDC and ArkUI `uitest` on HarmonyOS; Vega CLI/VDA on the Vega Virtual Device; a local helper on macOS, including Electron and other Chromium-based apps through the accessibility tree; and AT-SPI on Linux.
  112. Support depth varies by target. Some backends, such as HarmonyOS and Vega OS, cover a subset of commands; run `agent-device capabilities --platform <platform>` to see what a target supports. The [capabilities matrix](https://agent-device.dev/docs/capabilities) shows which commands each target, desktop, web, and cloud provider supports.
  113. Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. Run `agent-device device status` to inspect ownership without a daemon, and `agent-device device release --stale` to release claims whose owner is provably no longer running. The same commands drive hosted devices on [BrowserStack, AWS Device Farm, TestMu AI, and Limrun](https://agent-device.dev/docs/device-clouds).
  114. `agent-device` uses the inspect-act-verify process from Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) for mobile, TV, and desktop apps. Basic `--platform web` support runs `agent-browser` in the same session and replay system.
  115. ## FAQ
  116. ### What is agent-device?
  117. `agent-device` is a command-line tool and MCP server that lets AI coding agents inspect, control, and verify mobile apps and save evidence for review. It supports iOS, Android, HarmonyOS, TV, web, macOS, and Linux.
  118. ### Is there an MCP server for mobile app automation?
  119. Yes. `agent-device mcp` starts the official stdio MCP server. The Quick start above has the client config, and [AI agent setup](https://agent-device.dev/docs/agent-setup) covers per-client details.
  120. ### Does it work with React Native, Expo, Flutter, and native apps?
  121. Yes. `agent-device` supports native iOS and Android apps, plus React Native, Expo, and Flutter apps on supported targets. The commands and evidence vary by target.
  122. ### How is it different from mobile MCP servers?
  123. The MCP server is one entry point to the same runtime used by the CLI and typed Node.js API. Sessions, device ownership, selectors, evidence, replay, CI workflows, and cloud routing stay consistent across all three.
  124. ### Can I build my own agent or QA product on agent-device?
  125. Yes. The typed Node.js client is a public surface over that same runtime, so an agent you build inherits everything above. Start from the [Node.js API](https://agent-device.dev/docs/client-api), [AI SDK](https://agent-device.dev/docs/ai-sdk), or [Eve](https://agent-device.dev/docs/eve) guides.
  126. ### How is it different from Appium, Detox, or Maestro?
  127. With `agent-device`, an agent reads app state and chooses each command at run time. For stable, repeatable test suites, use [e2e](https://e2e.com/), a TypeScript testing framework for web and mobile apps. `agent-device` can also save its runs as `.ad` scripts or export them as strict Maestro YAML.
  128. ### Can agent-device run in CI?
  129. Yes. Record a run as an `.ad` script, replay it in CI, and keep the screenshots and logs as artifacts; the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml) is a working example.
  130. ## Articles and videos
  131. ### Articles
  132. - [Build an AI QA agent for Expo apps with EAS Workflows](https://expo.dev/blog/build-an-ai-qa-agent-for-expo-apps-with-eas-workflows-in-minutes-today)
  133. - [Agent Device: iOS & Android automation for AI agents](https://www.callstack.com/blog/agent-device-ai-native-mobile-automation-for-ios-android)
  134. - [Building mobile QA agents with Vercel Eve](https://www.callstack.com/blog/building-reviewable-mobile-qa-agents-with-vercel-eve)
  135. - [How we optimized Agent Device for mobile app automation](https://www.callstack.com/blog/how-we-optimized-agent-device-for-mobile-app-automation)
  136. ### Videos
  137. - [Verifying mobile apps with agent-device](https://youtu.be/kZDU-k5r9kE)
  138. - [Using agent-device in an AI coding workflow](https://youtu.be/dfVG_aNPkW4)
  139. - [Cloud agents that test mobile apps on real devices](https://youtu.be/r5P0detC4bs?is=_KB6SZbLFRB1au_z)
  140. ## Who uses agent-device?
  141. Teams and developers at Callstack, JPMorgan Chase, [Expensify](https://www.callstack.com/blog/how-expensify-uses-agent-device-for-mobile-bug-evidence-and-profiling), [Shopify](https://x.com/mustafa01ali/status/2036577353178943826), Kindred, [Total Wine & More](https://www.callstack.com/podcasts/how-ai-is-changing-react-native-development-and-testing), [LegendList](https://x.com/jmeistrich/status/2036398735698305178), HerLyfe, App & Flow, and others use `agent-device`.
  142. ## Documentation
  143. - [Docs](https://agent-device.dev/)
  144. - [Agent-readable docs](https://agent-device.dev/llms-full.txt)
  145. ## Contributing
  146. See [CONTRIBUTING.md](CONTRIBUTING.md).
  147. <p align="center">
  148. <a href="https://blacksmith.sh/">
  149. <img src="docs/assets/blacksmith-ci.png" width="280" height="96" alt="CI powered by Blacksmith">
  150. </a>
  151. </p>
  152. ## Made at Callstack
  153. `agent-device` is open source under the MIT license. Visit [agent-device.dev](https://agent-device.dev/) or [contact Callstack](mailto:hello@callstack.com).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.