agent-device

Device automation CLI for AI agents. Mobile, TV, and desktop apps.

agent-device lets coding agents run real apps, inspect UI state, interact with visible elements, and collect debugging evidence through one CLI.

It is built around token-efficient accessibility snapshots, not pixel-first screenshots. Agents read compact UI trees, locate elements through refs like @e3, perform touch and text actions, and capture screenshots, video, logs, network, CPU/memory/perf, crash-related logs, and React profiles only when evidence is needed.

Agents can ingest the current docs from llms-full.txt. The installed CLI help remains authoritative for exact command syntax.

Agentic QA And Development

- Quality Assurance: dogfood flows, validate PR builds, check accessibility coverage, and turn stable explorations into .ad e2e tests.
- Development: build from specs, inspect real runtime behavior, and iterate until the UI matches the work.

agent-device closes the agentic development loop: agents can write code, run the real app, verify the UI end-to-end, collect screenshots/videos/logs/perf evidence, and feed bugs, crashes, or performance findings back into the next fix iteration before a human reviews the PR.

If you know Vercel's agent-browser, this is the same idea for apps and devices.

Use it for AI mobile testing, AI QA for React Native and Expo apps, iOS Simulator automation, Android Emulator automation, tvOS/Android TV checks, and desktop app verification from coding agents. Humans install and configure agent-device; agents run the workflows.

Demo: Codex uses agent-device to inspect iOS Contacts through accessibility snapshots, interact with visible UI, and create a contact from a simple prompt.

Quick Start

Install the CLI first:

npm install -g agent-device@latest
agent-device --version
agent-device help workflow

The CLI help is the source of truth for agents and is shipped with the installed version. Skills are optional but recommended when your agent runtime supports them: they auto-route device, React DevTools, and dogfood tasks to the right agent-device help <topic> page and verify the CLI is new enough before acting.

If you install skills separately, keep the CLI on agent-device >= 0.14.0. Older CLIs do not include the workflow help topics that the router skills expect.

AI Agent Entry Points

- Agent + terminal: in Cursor, Codex, Claude Code, Windsurf, and similar clients, run agent-device in the integrated terminal. Start planning with agent-device help workflow; CLI help is authoritative.
- Skills or rules: install the skill with npx skills add callstackincubator/agent-device, use the bundled agent-device skill, or mirror it as a thin project rule, so the agent checks the installed version and reads agent-device help workflow before acting. Use agent-device help react-native for React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence.
- MCP router: use agent-device mcp when an MCP-aware client needs to discover the CLI package, install command, version check, and first help command. MCP is discovery-only; device automation still runs through terminal CLI commands.

For client-specific setup, see AI Agent Setup. For agent-readable docs, use llms-full.txt.

MCP Router

agent-device ships an official stdio MCP router for discovery-oriented clients. It exposes only a status tool that returns structured CLI handoff guidance: npm package name, installed version, CLI command name, install command, verify command, starting help command, and an explicit note that automation happens through the CLI.

MCP clients must not use this server as a device automation surface or generic shell runner. If the CLI is missing, agents should ask a human before installing or updating packages, then verify with agent-device --version and start with agent-device help workflow.

Paste one of these into clients that accept mcpServers, such as Cursor project .cursor/mcp.json or user-level MCP settings.

<details>
<summary>Global install MCP config</summary>

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

</details>

<details>
<summary>No global install MCP config</summary>

{
  "mcpServers": {
    "agent-device": {
      "command": "npx",
      "args": ["-y", "agent-device@<reviewed-version>", "mcp"]
    }
  }
}

</details>

Registry metadata uses MCP name io.github.callstackincubator/agent-device, npm package agent-device, stdio transport, mcpName package verification, server.json, and smithery.yaml.

npm install -g agent-device@latest
agent-device --version
agent-device help

agent-device performs a lightweight background upgrade check for interactive CLI runs and, when a newer package is available, suggests a global reinstall command. Updating the package also refreshes the bundled skills/ shipped with the CLI.

Prerequisites: Node.js 22+, Xcode for iOS/tvOS/macOS targets, Android SDK + ADB for Android, and macOS Accessibility permission for desktop automation. See Installation.

Try the loop.

```bash