callstack/agent-device

Open source device layer for AI coding agents. Let coding agents control mobile, web, TV, and desktop apps on devices and simulators, locally or in the cloud, 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, Fire TV (Fire OS), 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.
agent-device powers mobile automation in
e2e
and
T3 Code .
## 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.
bash
npm install -g agent-device@latest
agent-device doctor
agent-device help workflow
Run doctor yourself before you hand the CLI to an agent. help workflow links to the guides for debugging, replay, and profiling.
### Drive an app from the CLI
Add a contact in the built-in iOS Contacts app:
bash
# 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 valid only in 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:
json
"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:
ts
import { createAgentDeviceClient } from 'agent-device';
const client = createAgentDeviceClient({ session: 'qa-run' });
try {
await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });