#AI Agent Setup

agent-device is built for AI agents, but humans usually install it, grant device permissions, and decide which agent client should use it.

Use this page to wire Cursor, Codex, Claude Code, Windsurf, Cline, Goose, or another coding agent into mobile, TV, and desktop app verification. It covers skills, project rules, and MCP setup for React Native QA, Expo app verification, iOS Simulator automation, Android Emulator automation, tvOS checks, Android TV checks, debugging, profiling, and exploratory QA.

The short version: install the CLI, make the agent read version-matched help, and let the agent run CLI commands in a terminal. MCP is available for discovery and help, not broad device control.

#Prerequisite: install the CLI

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

For one-off use without a global install:

npx -y agent-device@latest --version
npx -y agent-device@latest help workflow

Global install is better for normal agent workflows because repeated commands, skills, and terminal sessions resolve to one stable version.

For Node, Xcode, Android SDK, macOS, and iOS device prerequisites, see Installation.

#Install the skill

Install the skill when your agent runtime supports skills:

npx skills add callstackincubator/agent-device

The bundled agent-device skill is the canonical router for skill-aware clients. It intentionally points agents back to installed CLI help instead of duplicating the command manual.

#Recommended agent rule

Add this as a project rule, custom instruction, or skill equivalent when your agent client supports it:

Use agent-device only for app/device automation tasks. Before planning commands, run `agent-device --version` and read `agent-device help workflow`. For exploratory QA, read `agent-device help dogfood`. For logs, network, traces, or runtime failures, read `agent-device help debugging`. For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.

Use the CLI in the integrated terminal. MCP is only a discovery/help router and does not expose device automation tools. Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close`. Use current refs such as `@e3` for exploration and selectors for durable replay. Keep mutating commands against one session serial. Capture screenshots, logs, network, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.

#MCP router

agent-device mcp starts the official stdio MCP router for discovery-oriented clients. It exposes only status, install, and help tools plus workflow prompts/resources. Device automation still runs through the CLI commands returned by version-matched help.

Global install configuration:

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

No global install variant:

{
  "mcpServers": {
    "agent-device": {
      "command": "npx",
      "args": ["-y", "agent-device@latest", "mcp"]
    }
  }
}

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

#Cursor

Use Agent mode with the integrated terminal. Add the recommended rule above as a project rule, then run:

agent-device help workflow
agent-device apps --platform ios
agent-device open <app-or-url> --platform ios
agent-device snapshot -i

Optional: paste the MCP router configuration into .cursor/mcp.json.

#Codex

Put the recommended rule in AGENTS.md or the project instructions. Let Codex run agent-device in the terminal:

agent-device help workflow
agent-device boot --platform ios
agent-device open <app-or-url> --platform ios
agent-device snapshot -i

For reviews or planning-only tasks, tell the agent not to run devices unless explicitly requested.

#Claude Code

Use the bundled skill when your Claude setup supports skills. Otherwise put the recommended rule in CLAUDE.md.

agent-device --version
agent-device help workflow
agent-device help dogfood

If you configure MCP, keep using CLI commands for automation. The MCP router gives Claude install/status/help context only.

#Windsurf, Cline, Goose, and other MCP clients

Use the MCP router configuration when the client supports mcpServers, then tell the agent to run device commands through the terminal.

If the client has project rules or custom instructions, add the recommended agent rule above. If it does not, start the conversation by asking the agent to run agent-device help workflow before planning.

#Why this setup works

The CLI stays the auditable automation surface, installed help stays version-matched with the commands, skills and rules route agents toward the right help topics, and MCP gives discovery-oriented clients a small install/status/help entry point.

For the broader positioning, supported targets, observability features, and how agent-device differs from scripted test frameworks, see Introduction. For exact command groups and platform behavior, see Commands.

For the local execution model, permissions, artifacts, and sensitive data guidance, see Security & Trust.

#Agent-readable docs

Use llms-full.txt when an agent needs a single text bundle of the current docs. The installed CLI remains authoritative for exact command syntax:

agent-device help
agent-device help workflow
agent-device help dogfood