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
TypeScriptMITCreated 2026-01-30agent-device.dev
下载:v0.21.37 🍰v0.21.37 ↓0.21.372026-11-12
+12
日增长
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": ["mc

Top issues

Discussions

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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON