agent-device

Overview

agent-device is an open source device layer for AI coding agents from Callstack. It lets agents inspect, control, debug, and verify apps on devices and simulators through a CLI, MCP server, or typed Node.js API. It supports iOS, Android, HarmonyOS, tvOS, Android TV, Fire TV, Vega OS, web, macOS, and Linux, and can run locally or with remote device hosts.

Key Features

• Accessibility snapshots, refs, and selectors let agents inspect app state instead of relying on screenshots alone.
• Agents can tap or press elements, fill fields, scroll, make gestures, wait, assert state, and handle alerts.
• Debugging evidence includes screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles.
• Working runs can be saved as .ad replay scripts for local use or CI, with strict Maestro YAML export when needed.
• A built-in MCP server and typed Node.js API expose the same runtime as the CLI.
• Sessions are scoped to git worktrees, and device claims stop parallel agents from taking over each other's simulators and emulators.

Use Cases

• Let a coding agent implement a screen, run it on the iOS simulator and Android emulator, and attach screenshots.
• Reproduce a crash or slow screen, capture logs and network data, and profile React Native renders.
• Explore a checkout flow, save it as a replay script, and run it in CI.
• Verify a pull request on a physical device and attach reviewable evidence.

Getting Started

• Install with npm install -g agent-device@latest.
• Run agent-device doctor before handing the CLI to an agent, then use agent-device help workflow for guides.
• For MCP, start the official stdio server with agent-device mcp.
• Use CLI commands such as agent-device open Contacts --platform ios, agent-device snapshot -i, agent-device press @e2 --settle, and agent-device screenshot ./contact-form.png.

Deployment & Requirements

• Requires Node.js 22.12 or newer; web automation requires Node.js 24 or newer.
• Run agent-device capabilities --platform <platform> to see what a target supports.
• Can run locally on simulators, emulators, physical devices, macOS, and Linux, or through a remote proxy, device clouds, and hosted devices.
• Hosted device support includes BrowserStack, AWS Device Farm, TestMu AI, Limrun, and Expo Simulators on EAS.

Before You Adopt

• License: MIT. Review its terms before using, modifying, or distributing the project.
• Target support is not uniform; some backends cover only a subset of commands.
• Web automation has a higher Node.js runtime requirement than the core CLI.
• Hosted device execution depends on external device-cloud providers or Expo Simulators on EAS.