agent-device: a CLI and MCP server that put a running app in front of your coding agent
Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.
At a glance
- What is it?
- Callstack's agent-device gives AI coding agents a live feedback loop on iOS, Android, HarmonyOS, TV, web, macOS and Linux through accessibility snapshots rather than screenshots. It is a good fit when an agent must verify its own change in a real app; it is a poor fit if you want a conventional test framework with assertions and reporters.
- Who is it for?
- Adopt agent-device if your workflow already has a coding agent that edits mobile code and you want that agent to confirm the change in a running app rather than in a diff. Skip it if you need a classic test runner with assertions, retries and JUnit output, or if your app exposes no usable accessibility labels, since the ref-based workflow depends on them.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap agent-device targets: agents that write mobile code but cannot see the result
An agent editing a React Native screen can read the diff, run the type checker and run unit tests. None of that tells it whether the button is reachable, whether the layout collapsed, or whether the flow it just changed still completes on a real device. The README frames the project as giving coding agents a live app feedback loop through a CLI, a built-in MCP server, or a typed Node.js API. The audience is narrow and specific: developers who already run Claude Code, Codex, Cursor, Windsurf, Cline or Goose, and who want those tools to drive a simulator, emulator or physical device. The README also lists Expensify and Shopify as users, with links to a Callstack blog post and a public post respectively. That is a verification tool for an agentic loop, not a replacement for a test suite.
Accessibility snapshots and refs instead of pixels
The mechanism that matters is the snapshot. agent-device reads the app's accessibility tree and returns a token-efficient representation with refs such as @e2 [button] "Add". The agent acts on a ref or a selector rather than guessing tap coordinates from an image. The README is explicit that snapshots come from the accessibility tree, so clear labels, roles and test IDs make runs more reliable, and that screenshots and video are for evidence or for when accessibility data is poor. Refs have a short lifetime: they are valid only from the latest output. After a command run with --settle, you use the refs in that command's diff, and you take a new snapshot only if the diff omits what you need. That diff-based discipline is the design choice that keeps an agent loop from re-reading the whole tree on every step, and it is also the part most likely to trip up a hand-written script.
One execution path behind three interfaces
The CLI, the MCP server and the Node.js client are not three separate implementations. The README states that agent-device mcp starts the official stdio MCP server, exposing the installed commands as structured tools over the same execution path as the CLI. The Node.js client, created with createAgentDeviceClient(), gives typed access to the same commands and is intended for use as model tools inside your own agent or from orchestration code. The client example uses a named session ('qa-run'), opens an app by bundle identifier with an explicit platform, captures an interactive-only snapshot, finds a node whose role is 'button', presses it by ref, and closes the session in a finally block. Sessions are the unit of device ownership, which is how the project coordinates device access across parallel agent worktrees. The README also mentions connecting to remote device clouds, but the supplied material does not describe the transport or configuration for that, so treat it as documented elsewhere.
Getting it running: install, doctor, workflow help
The install path is a global npm package plus two diagnostic commands. The README gives npm install -g agent-device@latest, then agent-device doctor, then agent-device help workflow. It recommends running doctor yourself before handing the CLI to an agent, and notes that the installed help always matches the installed version, which matters because the project releases frequently (v0.20.9, v0.20.10 and v0.21.0 all landed within about three weeks). Version floors are stated plainly: Node.js 22.12 or newer, and Node.js 24 or newer for web automation. For MCP clients, the configuration is a stdio server entry with command agent-device and args ["mcp"]. The CLI session flow in the README is open, snapshot -i, press or fill with --settle, screenshot, close; the Contacts example shows the diff format, where added nodes are prefixed with +, removed nodes with -, and unchanged nodes with =.
Where the ref model breaks down
The limitation follows directly from the mechanism. If an app's accessibility tree is sparse, mislabelled, or full of unlabelled containers, the agent gets a poor map of the screen and falls back to screenshots, which the README itself describes as the weaker mode. Stale refs are the other failure mode: an agent that holds a ref across a UI change and presses it anyway will act on the wrong element or fail, and the README's rule about using refs only from the latest output is a constraint on how you write prompts and scripts, not a suggestion. There is also a platform-cost dimension the README hints at rather than quantifies. It points to an Installation page for target requirements and to a Commands page for what each target supports, which implies that evidence types such as network data, performance samples, crash details and React profiles are not uniformly available across iOS, Android, HarmonyOS, tvOS, Android TV, Vega OS TV, web, macOS and Linux. Verify per target before designing a workflow around a specific evidence type.
agent-device versus Maestro, and why the export exists
Maestro is the closest comparison the material supports, because agent-device exports strict Maestro YAML when needed. The difference in approach is where the intelligence sits. Maestro is a declarative flow runner: you write the YAML, it executes deterministically, and the flow is the artifact you maintain. agent-device is a runtime for an agent: the agent inspects state, chooses an action, and the artifact is a session plus captured evidence. The README describes saving working steps as .ad scripts for local use or CI and exporting to Maestro YAML, which positions agent-device as the exploratory layer and Maestro as the durable regression layer. If your team already has a Maestro suite and wants an agent to author or repair flows, the export path is the bridge. If you want a runner that fails a build with a clear assertion, a snapshot-driven agent loop is more machinery than you need.
Maintenance, licensing and what to verify before you commit
The project is MIT licensed, which permits commercial use and modification; that is a statement about the licence text, not legal advice, and you should read LICENSE and your own obligations. Maintenance signals in the supplied material are the release cadence (three releases in roughly three weeks on the 0.x line) and a CI workflow. The 0.x version number is the honest signal here: command names, ref formats and diff output are the kind of surface that changes between minor releases, and the README's advice that installed help matches the installed version exists precisely because the CLI surface moves. Pin the version in CI rather than tracking @latest, and re-run agent-device doctor after each upgrade, since target requirements are documented separately per platform. The first things to verify on your own hardware are the Node version floor, whether your app's accessibility tree produces usable refs on each target you care about, and which evidence types the Commands page lists for those targets.
Editorial conclusion
Adopt agent-device if your workflow already has a coding agent that edits mobile code and you want that agent to confirm the change in a running app rather than in a diff. Skip it if you need a classic test runner with assertions, retries and JUnit output, or if your app exposes no usable accessibility labels, since the ref-based workflow depends on them. Before committing, run agent-device doctor on each target machine, confirm your Node version meets the 22.12 floor (24 or newer for web), and check the per-target support caveats in the Commands documentation for the evidence types you intend to collect.
Community notes