Agent Device

What callstackincubator/agent-device does

callstackincubator/agent-device connects AI coding agents to the agent-device automation runtime through MCP. The runtime lets agents inspect and operate running applications, verify UI changes, investigate failures, and preserve evidence for review. Supported environments include iOS and Android simulators, emulators, and physical devices, along with tvOS, Android TV, Fire TV, Amazon Vega OS TV, web, macOS, and Linux.

The MCP entry point is intended as a discovery router for the CLI. It exposes setup status, installation guidance, help matched to the installed version, prompts, and resources so an agent can determine how to use the available workflows.

How it works

Install the agent-device CLI, check the local setup with agent-device doctor, and start its official stdio MCP server with agent-device mcp. The MCP server follows the same execution path as the CLI, so agent actions and command-line actions use the same session and evidence model.

Agents can read accessibility-tree snapshots containing roles, labels, test identifiers, and short-lived element references. They use those references or selectors to interact with the current UI, then consume updated output after the interface settles. Screenshots and video complement accessibility data when visual evidence or richer diagnosis is needed.

The runtime can also be used directly from Node.js through the typed createAgentDeviceClient() API. This makes the same commands available to custom agents and orchestration code, including integrations built with the AI SDK or Eve.

Setup and configuration

Install the CLI globally with npm and use Node.js 22.12 or newer. Web automation requires Node.js 24 or newer. A basic MCP configuration launches the executable over stdio:

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

Run agent-device doctor before giving the CLI to an agent. The agent-device help workflow command provides links to workflow guidance for debugging, replay, and profiling. Per-client setup guidance is available for clients including Claude Code, Codex, Cursor, and Windsurf.

Tools and capabilities

• Inspect applications through accessibility snapshots, selectors, and element references.
• Press, tap, fill fields, scroll, perform gestures, wait for UI state, and handle alerts.
• Capture screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles.
• Profile React Native rendering to investigate unnecessary or slow renders.
• Save successful workflows as .ad replay scripts for local execution or CI.
• Export strict Maestro YAML when that format is required.
• Coordinate device access across parallel agent worktrees and connect to remote device clouds.

Limitations and notes

Element references are valid only in the latest command output. After a settling interaction, agents should use references from the returned diff and take another snapshot if the diff lacks the needed element. Reliable automation depends on accessible labels, roles, and test IDs in the application under test.

Screenshots should be treated as evidence or as a fallback when accessibility information is insufficient; accessibility snapshots are the primary compact representation for agent reasoning. Device and target requirements vary by platform, so the setup check and target-specific installation guidance should be completed before automation runs.

The project is distributed under the MIT license.