agent-device

agent-device is an open-source command-line tool and official MCP server built by Callstack, a European software development company specializing in React and React Native projects. The tool gives AI coding agents a closed feedback loop against real apps: instead of only editing source code, an agent can actually launch an application, inspect its interface, perform interactions, and back up the result with screenshots, video, logs, and traces. Per the project's own description, agent-device is used at Callstack itself as well as at JPMorgan Chase, Expensify, Shopify, and other teams.

What agent-device does

Through the CLI, the MCP server, or a typed Node.js interface, an agent can read an app's state from its accessibility tree as a compact "snapshot" format instead of relying on screenshots alone. Based on these snapshots, elements are addressed through stable references: tapping, filling form fields, scrolling, performing gestures, waiting, and asserting state. For debugging, agent-device offers screenshots, video, logs, network data, performance samples, crash details, and — for React Native apps — React profiling data. Successful runs can be saved as repeatable .ad scripts for later replay or exported as strict Maestro YAML, for example for use in CI pipelines.

Supported platforms and the technology behind them

Per the documentation, agent-device covers iOS and Android simulators, emulators, and physical devices, plus HarmonyOS, tvOS, Android TV, Amazon's Vega OS TV platform (Vega Virtual Device), macOS, Linux, and a basic web mode. Under the hood it uses a different backend per target: a local accessibility bridge and XCTest for iOS simulators, physical iOS devices, and tvOS; ADB and a snapshot helper for Android; HDC and ArkUI uitest for HarmonyOS; the Vega CLI/VDA for Vega OS; a local helper for macOS; and AT-SPI for Linux. Support depth varies by target; the agent-device capabilities --platform <platform> command shows exactly which commands a given target supports. According to the project, the web mode builds on Vercel Labs' separate open-source agent-browser project, which agent-device runs within the same session and replay system for --platform web.

MCP integration and supported clients

The agent-device mcp command starts the official, built-in stdio MCP server, exposing the same commands as the CLI as structured tools. Per the project description, agent-device works with Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any other agent that can run a CLI or connect over MCP; the typed Node.js API additionally lets it serve as the runtime underneath custom-built agents, such as those built with the AI SDK or Vercel's Eve.

Sessions, device coordination, and cloud devices

agent-device keeps device state in sessions scoped to the caller's git worktree. Host-local device claims, per the documentation, stop multiple parallel agents from fighting over the same simulators and emulators; ownership can be inspected without a separate daemon via agent-device device status, and stale claims released via agent-device device release --stale. The same commands, per the project, also drive devices in connected device clouds such as BrowserStack, AWS Device Farm, and Limrun, as well as through a remote proxy for Linux runners and managed cloud devices.

How it differs from Appium, Detox, and Maestro

Unlike classic test frameworks such as Appium, Detox, or Maestro, where teams write and maintain fixed test suites, agent-device lets an agent read app state at run time and choose each step itself. Per the project, it can still complement these frameworks: successful agent runs can be saved as .ad scripts or exported as Maestro YAML.

Cost

agent-device itself is fully open source under the MIT license and free to use, with no account or subscription required from Callstack. Teams that use connected device clouds such as BrowserStack or AWS Device Farm instead of local simulators and emulators pay for that usage under those providers' own, independent pricing — unrelated to agent-device itself. For dedicated team QA setups, the project points to direct contact with Callstack.

Who agent-device is for

The tool suits teams that have AI coding agents such as Claude Code or Cursor work on mobile, TV, or desktop apps — particularly React Native, Expo, Flutter, or native applications — and who want to verify changes not just in source code but in the actually running product. It is especially useful for pull request verification with reviewable visual evidence, for bug reproduction including logs, and for building custom QA agents on top of the open Node.js API. Teams that only need to automate web applications in a browser will find more specialized alternatives in the catalog, such as Playwright and Chrome DevTools, for that narrower use case.

Node.js 22.12 or newer (24 or newer for web mode); depending on the target platform, the matching native toolchain as well — Xcode/iOS Simulator for iOS and tvOS, the Android SDK with ADB for Android and Android TV, the HarmonyOS toolchain with HDC for HarmonyOS, the Vega CLI/VDA for Vega OS, and AT-SPI for Linux; an MCP-capable client (e.g. Claude Code, Cursor, Codex) for the MCP integration.

Install globally via npm install -g agent-device@latest, then run agent-device doctor to validate the local environment. For MCP integration, register the server as a stdio MCP server via agent-device mcp in the respective client; alternatively use the CLI directly or the typed Node.js API.

npm install -g agent-device@latest

No central Callstack account login is required; device access follows the respective platform itself (e.g. iOS developer certificates/simulator access, Android USB debugging/ADB authorization, macOS accessibility permission). Connected device clouds such as BrowserStack or AWS Device Farm use their own separate credentials.

The local process needs platform-specific permissions: macOS accessibility permission for the local helper, enabled USB debugging plus an authorized ADB connection on Android, Xcode-based simulator or developer-device access on iOS, and access to the AT-SPI accessibility bus on Linux. These permissions let agent-device read interfaces and send input to installed apps.

Snapshots, screenshots, video, logs, and other evidence are produced and initially kept locally or within the respective CI run; they are handed to the connecting AI agent and its model provider for evaluation. When connected device clouds are used, device data additionally goes to that cloud provider (BrowserStack, AWS Device Farm, Limrun) under its own terms.

An AI agent with agent-device access can operate real apps on real or simulated devices and capture screenshots and on-screen content — when pointed at production devices or apps holding real user data, this creates a risk that sensitive content ends up in evidence files and is sent to the model provider. Because sessions coordinate parallel agents through device claims, a compromised or poorly instructed agent run should not be left running unsupervised against production devices or devices loaded with real customer data; dedicated test accounts and devices are recommended for sensitive testing.