This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Use agent-device to let your AI coding agent verify, debug, profile, and test a running Expo app across local and remote devices.

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

Code inspection and automated tests do not always show what happens in the running app. With agent-device, an agent can check that a screen renders, a flow completes, or a request fires, then report what it observed. This adds behavior review to the same workflow the agent uses to implement the change.

agent-device runs from the terminal in Codex, Claude Code, Cursor, and other coding agents, with optional Model Context Protocol (MCP) integration. One command model covers Android Emulators, iOS Simulators, physical devices, Android TV, tvOS, macOS, Linux, and web.

Routine responses stay compact. Semantic snapshots include actionable references such as @e3, command results explain how to recover when something fails, and larger outputs are saved as artifacts. This keeps more of the agent's context available for working on your app.

agent-device is built and maintained by Callstack and is available under the MIT license. For the complete list of supported platforms and commands, see the agent-device documentation.

Quick start

Use `agent-device` to open the settings screen in my Expo app on iOS, verify it loaded correctly,
and capture a screenshot as evidence.

How the agent-device loop works

The agent opens the app, reads a compact accessibility snapshot, and acts on refs such as @e2. Settled interactions can include the resulting UI changes in the same response. The agent then verifies the result with an assertion or the evidence that suits the task, such as a screenshot, focused log window, or performance sample.

agent-device apps --platform ios
agent-device open MyApp --platform ios
agent-device snapshot -i
# @e1 [heading] "Welcome"
# @e2 [button] "Get Started"
agent-device press @e2 --settle
agent-device screenshot ./artifacts/get-started.png
agent-device close

Your agent chooses and runs these commands by following the workflow guidance bundled with the installed CLI.

What agent-device lets your agent do

• Control and interact: Inspect accessibility labels, roles, values, test IDs, and interactive refs. Launch apps, tap, type, scroll, perform gestures, handle alerts, open deep links, and change device state. Use the same commands locally or through device clouds and a remote proxy across Android, iOS, web, TV, and desktop targets.
• Profile and debug: Inspect React Native components, props, hooks, slow commits, and re-renders; evaluate targeted JavaScript through Metro's Chrome DevTools Protocol (CDP); and collect focused logs and available network requests and responses. Add platform-supported native CPU, memory, FPS and frame-health, trace, crash, screenshot, video, and audio evidence in the same session.
• Test and repeat: Record a working session as a deterministic .ad script, replay it or run it with the built-in test command in CI, and keep artifacts for failed runs. Run supported Maestro YAML with agent-device test --maestro, or export compatible .ad flows to Maestro YAML.

This covers routine implementation checks, exploratory QA, bug reproduction, and performance work. When an investigation needs live native breakpoints, variables, memory inspection, or stepping, agent-device can reproduce and document the flow while Xcode or LLDB attaches to the app process. For version-matched diagnostic and profiling guidance, start with agent-device help debugging, agent-device help react-devtools, and agent-device help cdp, or see Debugging and Profiling.

Example prompts

After setup, describe the outcome and evidence you want. For example:

Use agent-device with Expo AI tooling

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

For automated pull request testing, start with Callstack's agent-device EAS Workflow template. It shows how to run an AI QA agent against an Expo app and retain reviewable artifacts.

Optional MCP setup

Most coding agents can use agent-device directly through their integrated terminal. If your client supports MCP and you prefer structured tools, configure it to launch the installed CLI:

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

MCP provides structured tools for the same device workflows. Keep the CLI available so the agent can read version-matched help and use terminal-only setup commands.

Limitations and tips

• 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.
• Keep state-changing commands in one session sequential. Close the session when the task finishes; use agent-device close --shutdown in CI when the emulator or simulator should also stop.
• Device-level UI automation, including snapshots, taps, typing, screenshots, and logs, works on the installed app in a development build or in Expo Go, with no library added to your project.
• 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 your native code.
• Logging is off by default. Ask the agent to open a focused log window for a reproduction instead of collecting an unbounded device log.
• Physical device automation requires platform-specific pairing, signing, permissions, and trust setup. Start with a simulator or emulator, then follow the installation guide for physical devices.
• Run agent-device help react-native, agent-device help debugging, or agent-device help dogfood when a task needs deeper, version-matched guidance.