callstack/agent-device

What it does

agent-device gives AI coding agents a way to test their own changes inside a running app instead of stopping at code review. Agents can read accessibility snapshots of the current screen, act on elements by ref or selector, and capture screenshots, video, logs, traces, network data, performance samples, and React Native render profiles as reviewable evidence.

The same runtime is exposed three ways: a CLI, a stdio MCP server started with agent-device mcp, and a typed Node.js client. That means the command set, sessions, device ownership, replay, and cloud routing behave consistently whether an agent calls tools over MCP, runs shell commands, or a program calls the API.

Supported targets include iOS, Android, and HarmonyOS simulators, emulators, and physical devices; tvOS, Android TV, Fire TV, and Vega OS TV; plus web, macOS, and Linux. Native, React Native, Expo, and Flutter apps are covered, but the commands and evidence available differ by target.

Quick start

You need Node.js 22.12 or newer; web automation needs Node.js 24 or newer. Start with the CLI and verify the local setup before handing it to an agent:

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

Then drive an app from the command line, for example the iOS Contacts app:

agent-device open Contacts --platform ios
agent-device snapshot -i
agent-device press @e2 --settle
agent-device fill @e7 "Ada" --settle
agent-device screenshot ./contact-form.png
agent-device close

The snapshot -i output lists elements with refs such as @e2 [button] "Add". Refs are only valid in the latest output; after a --settle command, use the refs in its diff and take a new snapshot only if the diff lacks what you need. See the quick start and installation requirements for target-specific setup.

To expose the same commands as MCP tools, add the server to the agent client config:

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

Per-client setup for Claude Code, Codex, Cursor, Windsurf, Cline, and Goose is covered in the AI agent setup guide.

Automation from code

The Node.js client wraps the same runtime for orchestration code or custom agents:

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();
}

Runnable examples live in the SDK examples, with separate guides for the Node.js API, AI SDK, and Eve.

Constraints and limits

• Backend support is uneven. HarmonyOS and Vega OS cover only a subset of commands; agent-device capabilities --platform <platform> and the capabilities matrix show what each target, desktop, web, and cloud provider supports.
• Snapshot quality depends on app accessibility metadata. Clear labels, roles, and test IDs make agent runs more reliable; screenshots and video are evidence or fallbacks when accessibility data is poor.
• Sessions are scoped to the caller's git worktree, and device claims stop parallel agents from taking over each other's simulators and emulators. Use agent-device device status to inspect ownership and agent-device device release --stale to release claims whose owner is no longer running.
• To use remote or hosted devices, set up a remote proxy or connect a supported device cloud such as BrowserStack, AWS Device Farm, TestMu AI, or Limrun.
• Replay scripts are saved as .ad files and can be exported as strict Maestro YAML; for long-lived deterministic suites the README points to a separate TypeScript test framework, e2e.
• The project is MIT licensed.

HotRepo's take

On 13 November 2026 the repository appeared on the TypeScript daily list at rank 15 with 26 new stars in that day's window, reaching 5,368 total stars and 399 forks. That single snapshot shows a maintained project picking up steady attention but is not enough to characterize a trend. The more concrete signal is the design: one runtime shared by CLI, MCP, and a typed client, with session and device-claim handling for parallel agent worktrees, which addresses a real coordination problem rather than just wrapping a single screenshot loop.