callstack /agent-device
Open source device layer for AI coding agents: a CLI, MCP server, and typed Node.js API to control mobile, web, TV, and desktop apps on devices and simulators, locally or in the cloud.
★ 5,405⑂ 406👁 6⑃ 3,177● 1,222▤ 156
+12
Daily
5,405
stars
406
forks
6
watchers
3,177
prs
1,222
issues
156
releases
README
---
agent-device
Open source device layer for AI coding agents. Let coding agents control mobile, web, TV, and desktop apps on devices and simulators, locally or in the cloud, through a CLI, built-in MCP server, or typed Node.js API.
Let your coding agent verify its changes in the running app. agent-device lets agents inspect, control, debug, and verify apps on iOS, Android, and HarmonyOS (simulators, emulators, and physical devices), plus tvOS, Android TV, Fire TV (Fire OS), Amazon Vega OS TV (Vega Virtual Device), web, macOS, and Linux. Agents read token-efficient accessibility snapshots instead of reasoning over screenshots alone, act through refs and selectors, and save evidence for review. It also coordinates device access across parallel agent worktrees and connects to remote device clouds.
Works with Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any agent that can run a CLI or connect over MCP, or as the runtime under agents you build with the AI SDK or Eve. Developers at Expensify, Shopify, and others use it to verify their apps.
agent-device powers mobile automation in
e2e
and
T3 Code.
Quick start
Install the CLI and check setup. It requires Node.js 22.12 or newer; web automation requires Node.js 24 or newer. See Installation for target requirements.
bash
npm install -g agent-device@latest
agent-device doctor
agent-device help workflow
Run doctor yourself before you hand the CLI to an agent. help workflow links to the guides for debugging, replay, and profiling.
Drive an app from the CLI
Add a contact in the built-in iOS Contacts app:
bash
Start a session.
agent-device open Contacts --platform ios
Inspect the screen. The example below shows the output; refs vary.
agent-device snapshot -i
@e2 [button] "Add"
Use the ref and wait for the UI to settle.
agent-device press @e2 --settle
The diff includes:
+ @e7 [text-field] "First name"
agent-device fill @e7 "Ada" --settle
The next diff shows changed values and current refs:
- @e7 [text-field] "First name"
+ @e14 [text-field] "Ada"
= @e15 [text-field] "Last name"
Capture evidence and close the session.
agent-device screenshot ./contact-form.png
agent-device close
Refs are valid only in the latest output: after a --settle command, use the refs in its diff, and take a new snapshot only if the diff omits what you need. Snapshots come from the app's accessibility tree, so clear labels, roles, and test IDs make agent runs more reliable; use screenshots and video as evidence or when accessibility data is poor.
!agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt
Add MCP tools to your agent
agent-device mcp starts the official stdio MCP server, exposing the installed commands as structured tools over the same execution path as the CLI:
json
{
"mcpServers": {
"agent-device": {
"command": "agent-device",
"args": ["mcTop issues
#4368Repository audit remediation for 10 November 2026201 comments · 2026-11-10#4045Architecture quality: runtime ownership, collocated teardown, trustworthy impact and test evidence (umbrella)30 comments · 2026-10-29#4441Align artifact transfer deadlines and stall budgets29 comments · 2026-11-11#4060test(provider): fix recording timeout reproduced by the related-test gate on unchanged base13 comments · 2026-10-29#4456Pre-dispatch admission: one owner, budget and evidence path for resolved-target input checks7 comments · 2026-11-12#4426Drive Android boot polling with typed observations instead of error text7 comments · 2026-11-11#4388iOS: resolved presses can hit a fading overlay while reporting success7 comments · 2026-11-10#4107iOS physical device over Wi‑Fi: every tap fails with "lost its transport response" while snapshots work (USB works)7 comments · 2026-10-30
Discussions
#4170(iOS/Android) Foldable devices splitview0 comments · 2026-11-02#3228Idea: parity runs — replay one flow in two sessions and compare at named checkpoints0 comments · 2026-10-05#2655Interested in a PR for iPhone Action Button support?1 comments · 2026-09-17#2024Can connect (BrowserStack) ever produce "did not finish booting in time", or is that open-only?1 comments · 2026-08-25#812Comparisons with https://mobilenext.ai/#products1 comments · 2026-06-16#638Porting to Dart and benchmarking a bit2 comments · 2026-05-30#506Welcome to agent-device Discussions!0 comments · 2026-05-13
Latest release
v0.21.37 🍰 v0.21.37 2026-11-12🍰 Highlights - TV apps on LG webOS and Samsung Tizen: new optional provider plugins @agent-device/webos (4098) and @agent-device/tizen (4168) drive web apps on TVs. They support open, snapshot, remote keys, pointer, text, scroll, screenshot and logs. - Limrun iOS runs on the shared XCTest runner (4224, 4182). It uses the same snapshot and interaction paths as a local Simulator. Local app installs sync to the instance (4225), and boot and shutdown map to instance leases (4275). - Parallel web sessions (4191): each web session is its own device, so sessions with different --session names run si