agent-device

32 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

agent-device purpose and capabilities

agent-device is an open-source, agent-native CLI from Callstack that lets AI coding agents operate a running Expo app and verify the result with UI state, screenshots, video, logs, network activity, traces, and performance data. It enables behavior review alongside implementation changes.

agent-device platform support

agent-device runs from the terminal in Codex, Claude Code, Cursor, and other coding agents. It covers Android Emulators, iOS Simulators, physical devices, Android TV, tvOS, macOS, Linux, and web with one command model. It also supports device clouds and remote proxy connections.

agent-device Node.js requirement

agent-device CLI requires Node.js 22.12 or newer.

agent-device installation command

Install agent-device globally using: npm install -g agent-device@latest, yarn global add agent-device@latest, pnpm add -g agent-device@latest, or bun add -g agent-device@latest. After installation, run agent-device doctor to check local toolchain and devices, agent-device --version to check version, and agent-device help workflow to read the version-matched workflow guide.

agent-device skill installation

If your coding agent supports skills, install the official agent-device skill using npx skills add callstack/agent-device, yarn dlx skills add callstack/agent-device, pnpm dlx skills add callstack/agent-device, or bunx skills add callstack/agent-device. The skill teaches the agent to select the right workflow and read help that matches the installed CLI version. agent-device works without a skill by learning from built-in CLI help.

agent-device does not require library in project

agent-device operates the installed app on a device, so no agent-device library needs to be added to the Expo project. It works on the installed app in a development build or in Expo Go.

agent-device basic workflow

The agent-device workflow is: apps (list apps), open (open app), snapshot (take accessibility snapshot returning compact refs like @e1, @e2), press/type/scroll (act on refs with @e2 notation), settle (wait for interaction to complete), screenshot (capture visual evidence), close (end session). The agent follows workflow guidance bundled with the installed CLI.

agent-device MCP optional configuration

MCP configuration for agent-device requires adding to mcpServers: {"agent-device": {"command": "agent-device", "args": ["mcp"]}}. MCP provides structured tools for device workflows. The CLI should remain available for version-matched help and terminal-only setup commands.

agent-device control and interaction capabilities

agent-device lets agents inspect accessibility labels, roles, values, test IDs, and interactive refs. Agents can launch apps, tap, type, scroll, perform gestures, handle alerts, and open deep links. The same commands work locally or through device clouds and remote proxy across Android, iOS, web, TV, and desktop targets.

agent-device profiling and debugging capabilities

agent-device lets agents inspect React Native components, props, hooks, slow commits, and re-renders. Agents can evaluate targeted JavaScript through Metro's Chrome DevTools Protocol (CDP) and collect focused logs, network requests and responses. Platform-supported native profiling includes CPU, memory, FPS, frame-health, trace, crash, screenshot, video, and audio evidence in the same session.

agent-device testing and replay capabilities

agent-device can record a working session as a deterministic .ad script and replay it or run it with the built-in test command in CI, keeping artifacts for failed runs. Agents can run supported Maestro YAML with agent-device test --maestro and export compatible .ad flows to Maestro YAML.

agent-device accessibility label recommendations

Accessibility labels, roles, and test IDs make agent interactions substantially more reliable. Use screenshots as evidence or as a visual fallback, but prefer refs and selectors for actions.

agent-device session state management

Keep state-changing commands in one session sequential. Close the session when the task finishes. In CI, use agent-device close --shutdown to stop the emulator or simulator.

agent-device React inspection requirements

React Native component inspection and React profiling require a development server and a compatible React DevTools connection, so keep it running. In Expo Go, native CPU, memory, and trace profiling targets the Expo Go host process rather than an app-specific native binary, so use a development build to profile native code.

agent-device logging default state

Logging is off by default. Ask the agent to open a focused log window for a reproduction instead of collecting an unbounded device log.

agent-device physical device setup note

Physical device automation requires platform-specific pairing, signing, permissions, and trust setup. Start with a simulator or emulator, then follow the agent-device installation guide for physical devices.

agent-device help topics

Run agent-device help react-native, agent-device help debugging, or agent-device help dogfood for version-matched guidance on deeper tasks.

Expo MCP Server complement to agent-device

agent-device complements Expo's own agent tooling. Expo Skills teach agents how to implement features, the Expo MCP Server gives agents current Expo and EAS context, and agent-device lets agents verify the result in the running app.

agent-device EAS Workflow template

Callstack provides an agent-device EAS Workflow template at https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml for automated pull request testing, showing how to run an AI QA agent against an Expo app and retain reviewable artifacts.

EAS Simulator start command with agent-device controller

To start a remote iOS device session with agent-device as the controller, run: eas simulator:start --platform ios --type agent-device --non-interactive

EAS Simulator controller types

simulator:start supports three controller types: agent-device (for accessibility-driven device actions and app installation), argent (to run remote device tools through the session), and serve-sim (for browser-only preview).

EAS Simulator availability

EAS Simulator is a limited-access preview and is not included with paid or free plans. It is currently available only to select partners.

EAS Simulator intended for agentic development

EAS Simulator is built for agentic development. It gives coding agents a real device runtime for verifying agent-written code. Agents can fix issues they observe and return evidence from the running app.

Use cases for EAS Simulator

EAS Simulator is especially useful when a background or cloud coding agent needs device access not available in its sandbox, an AI agent needs to verify a change in a running app instead of only inspecting source code, you want a temporary shareable iOS browser preview, or you need to offload simulator compute or test on a remote platform. It is also useful for developers on Linux or Windows who need access to an iOS Simulator, or when local resources are constrained.

EAS Simulator does not replace local development

EAS Simulator does not replace local Xcode or Android Studio workflows when you already have the required local device runtime. Use it when you need remote or shareable access.

Using EAS Simulator with a coding agent

For agentic development, start with the official EAS Simulator skill. Ask your coding agent to use the skill instead of giving it individual EAS CLI and controller commands. The skill covers the access check, build preparation, remote session, controller workflow, evidence collection, and cleanup.

EAS Simulator runtime loop for agents

The agent can complete the runtime loop as follows: (1) Implement or fix the code. (2) Check EAS Simulator access and prepare a compatible app build. (3) Start a remote device and drive the app through agent-device or Argent. (4) Inspect the result and iterate if needed. (5) Return screenshots, recordings, logs, or other evidence and stop the session.

Typical EAS Simulator setup with cloud agent

A common setup is a Cursor cloud agent or another background coding agent working in a cloud project checkout. The environment can edit and build the project, but it cannot launch a local iOS Simulator. With the EAS Simulator skill, the agent starts a remote device on EAS and controls it through agent-device or Argent. The agent then returns the result to the task or pull request, while your computer does not need to host the simulator.

EAS Simulator workflow stages

An EAS Simulator workflow has four stages: (1) Start a session with EAS CLI. EAS boots a remote device and the selected controller. (2) Install your app. The remote device starts blank, so install a local build or an EAS Build artifact. (3) Drive the device. Use agent-device, Argent, or the iOS browser preview. (4) Stop the session. An unattended non-interactive session continues consuming usage until it stops.

EAS Simulator role of EAS CLI and controller

EAS CLI manages the session lifecycle and connection configuration. The controller provides device actions such as opening an app, pressing a button, entering text, inspecting the accessibility tree, and capturing a screenshot.

EAS Simulator available surfaces

EAS Simulator supports the following capabilities: Remote iOS Simulator (available), Remote Android Emulator (available), Programmatic control with agent-device (available), Programmatic control with Argent (available), Live browser preview for iOS (available), Live browser preview for Android (not available), Physical device access (not available), Fast Refresh with a development build and Metro (available).

EAS Simulator overview

EAS Simulator runs a remote iOS Simulator or Android Emulator on EAS infrastructure. You can install an app, inspect its user interface, and interact with it. You can also collect screenshots and recordings or share an iOS browser preview without running the device locally.

Give your agent this brain