Agent Device

What is Agent Device about?

Agent Device provides a live feedback loop for AI coding agents, allowing them to control and validate mobile apps by reading accessibility snapshots, interacting with UI elements, and capturing evidence such as screenshots, logs, and performance data.

How to use Agent Device?

1. Install the CLI – npm install -g agent-device@latest (or npx -y agent-device for a one‑off run). Verify with agent-device doctor.
2. Run commands via CLI – e.g., agent-device open Contacts --platform ios, agent-device press @e2 --settle, agent-device screenshot ./evidence.png.
3. Start the MCP server – agent-device mcp and configure your AI agent to call the exposed tools.
4. Use the typed Node.js client – import { createAgentDeviceClient } from 'agent-device'; const client = createAgentDeviceClient({ session: 'qa-run' }); then call methods like client.apps.open(), client.capture.snapshot(), client.interactions.press().

Key Features of Agent Device

• Cross‑platform support: iOS, Android, HarmonyOS, tvOS, Android TV, Vega OS TV, web, macOS, Linux.
• Accessibility‑based snapshots: token‑efficient UI trees replace heavyweight screenshots for reasoning.
• Rich interaction set: tap, press, fill, scroll, gestures, wait, assert, alert handling.
• Evidence collection: screenshots, video, logs, network traces, crash dumps, React performance profiles.
• Session & device ownership: scoped to git worktrees, preventing parallel agents from colliding.
• Cloud device integration: works with BrowserStack, AWS Device Farm, Limrun, and custom remote proxies.
• Replay & CI: export workflows as .ad scripts or strict Maestro YAML for automated testing.
• Typed Node.js API: full IntelliSense and type safety for programmatic use.

Use Cases of Agent Device

• AI‑driven QA: agents automatically verify UI changes, capture bugs, and generate reviewable evidence.
• Performance profiling: capture React Native re‑render data and system metrics during automated runs.
• CI/CD validation: run recorded .ad scripts on pull requests, storing artifacts for audit.
• Cross‑device testing: execute the same workflow on simulators, emulators, physical devices, and remote clouds.
• Rapid prototyping: developers give natural‑language prompts (e.g., “implement the onboarding screen and attach screenshots”) and let the agent handle build‑run‑verify cycles.

FAQ from Agent Device

What platforms are supported? iOS, Android, HarmonyOS, tvOS, Android TV, Vega OS TV, web browsers, macOS, and Linux.

Do I need a physical device? Both simulators/emulators and physical devices are supported; remote clouds enable testing on real hardware.

How does it differ from Appium/Detox/Maestro? Agent Device is designed for on‑the‑fly AI decision making, providing accessibility snapshots and evidence per action, while traditional frameworks focus on pre‑written test suites.

Can I use it with React Native, Expo, and Flutter apps? Yes—Agent Device reads React Native component trees and works with Expo and Flutter on supported targets.

Is there an MCP server? Yes. agent-device mcp launches the standard stdio MCP server, exposing all CLI commands as structured tools.

Can I run it in CI? Absolutely. Record a session as a .ad script, replay it in CI pipelines, and publish screenshots, logs, and performance data as artifacts.

How do I integrate with a custom AI agent? Use the MCP server configuration or the typed Node.js client (createAgentDeviceClient) to invoke commands directly from your agent logic.

What credentials are required? No API keys are needed for local usage; cloud device integrations may require their own credentials.

---

agent-device

Mobile app automation and verification for AI coding agents. Give coding agents a live app feedback loop through a CLI, built-in MCP server, or typed Node.js API.

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, 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.

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 or Eve. Developers at Expensify, Shopify, and others use it to verify their apps.

Quick start

Install the CLI and check setup. It requires Node.js 22.12 or newer; web automation requires Node.js 24 or newer. See 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 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, the runnable examples, and the AI SDK and Eve integration guides.

What agents can do

• Inspect app state through accessibility snapshots, refs, selectors, and React Native component trees.
• Act on visible UI by tapping or pressing elements, filling fields, scrolling, making gestures, waiting, asserting state, and handling alerts.
• Diagnose failures with screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles.
• Repeat workflows by saving working steps as .ad scripts for local use or CI. Export strict Maestro YAML when needed.

See Commands for the commands and evidence each target supports.

What to ask your agent

With the CLI installed, prompts like these work end to end:

• "Implement the onboarding screen, run it on the iOS simulator and Android emulator, and attach screenshots."
• "Reproduce this crash and capture the logs that lead up to it."
• "Check whether this change causes unnecessary React Native re-renders."
• "Explore the checkout flow once, save it as a replay script, and run it in CI."
• "Verify this pull request on a physical device and attach reviewable evidence."

Next steps

• AI Agent Setup: skills, project rules, and per-client setup for Cursor, Codex, Claude Code, Windsurf, and others.
• Quick Start: a guided run on the bundled Expo test app with screenshots, replay, and performance data.
• Replay & E2E and Debugging & Profiling: repeatable tests and bug hunting.

Where to run agent-device

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.

Path	Best for	Start with
Local	Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux.	Follow the Quick Start.
CI/CD	Automated pull request and merge validation with replay scripts and captured artifacts.	Try the EAS workflow template.
Cloud / remote	Linux runners, managed devices, and remote jobs.	Set up a remote proxy, connect a device cloud (BrowserStack, AWS Device Farm, Limrun), or contact Callstack for team QA.

How it works

agent-device keeps device state in sessions. It sends commands to XCTest on iOS and tvOS, ADB and the snapshot helper on Android, HDC and ArkUI uitest on HarmonyOS, Vega CLI/VDA on the Vega Virtual Device, a local helper on macOS, and AT-SPI on Linux.

Support depth varies by target. Newer backends such as HarmonyOS and Vega OS cover a subset of commands; run agent-device capabilities --platform <platform> to see what a target supports.

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. The same commands drive hosted devices on BrowserStack, AWS Device Farm, and Limrun.

agent-device uses the inspect-act-verify process from Vercel's agent-browser for mobile, TV, and desktop apps. Basic --platform web support runs agent-browser in the same session and replay system.

FAQ

What is agent-device?

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.

Is there an MCP server for mobile app automation?

Yes. agent-device mcp starts the official stdio MCP server. The Quick start above has the client config, and AI Agent Setup covers per-client details.

Does it work with React Native, Expo, Flutter, and native apps?

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.

How is it different from mobile MCP servers?

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.

Can I build my own agent or QA product on agent-device?

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, AI SDK, or Eve guides.

How is it different from Appium, Detox, or Maestro?

With agent-device, an agent reads app state and chooses each command at run time. Teams use Appium, Detox, and Maestro to write and maintain test suites. agent-device can complement them by saving its runs as .ad scripts or exporting them as strict Maestro YAML.

Can agent-device run in CI?

Yes. Record a run as an .ad script, replay it in CI, and keep the screenshots and logs as artifacts; the EAS workflow template is a working example.

Articles and videos

Articles

• Build an AI QA agent for Expo apps with EAS Workflows
• Agent Device: iOS & Android automation for AI agents
• Building mobile QA agents with Vercel Eve
• How we optimized Agent Device for mobile app automation

Videos

• Verifying mobile apps with agent-device
• Using agent-device in an AI coding workflow
• Cloud agents that test mobile apps on real devices

Who uses agent-device?

Teams and developers at Callstack, JPMorgan Chase, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow, and others use agent-device.

Documentation

• Docs
• Agent-readable docs

Contributing

See CONTRIBUTING.md.

Made at Callstack

agent-device is open source under the MIT license. Visit agent-device.dev or contact Callstack.