agent-device
bycallstack· 1 MCP server
---
How to install agent-device?
callstack/agent-device
$git clone https://github.com/callstack/agent-deviceInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Install agent-device by running `git clone https://github.com/callstack/agent-device`, then use it for the current task and follow its documentation at https://github.com/callstack/agent-device.
README.md
| 1 | <a href="https://www.callstack.com/open-source?utm_campaign=generic&utm_source=github&utm_medium=referral&utm_content=agent-device" align="center"> |
| 2 | <picture> |
| 3 | <img alt="agent-device: device automation CLI for AI agents" src="website/docs/public/agent-device-banner.jpg"> |
| 4 | </picture> |
| 5 | </a> |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | # agent-device |
| 10 | |
| 11 | [](https://www.npmjs.com/package/agent-device) |
| 12 | [](https://github.com/callstack/agent-device/actions/workflows/ci.yml) |
| 13 | [](LICENSE) |
| 14 | [](https://glama.ai/mcp/servers/callstack/agent-device) |
| 15 | |
| 16 | Let your coding agent verify its changes in the running app. |
| 17 | |
| 18 | `agent-device` lets coding agents inspect, control, and verify apps on iOS, Android, TV, web, macOS, and Linux. Agents can read token-efficient accessibility snapshots, find elements by ref or selector, run device actions, and save evidence for review. |
| 19 | |
| 20 | Your coding agent or QA tool reads each result and chooses the next command. `agent-device` runs the command and saves evidence when asked. |
| 21 | |
| 22 | `agent-device` uses the inspect-act-verify process from Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) for mobile, TV, and desktop apps. Basic `--platform web` support runs `agent-browser` in the same session and replay system. |
| 23 | |
| 24 | ## Quick start |
| 25 | |
| 26 | Install the CLI and check setup. It requires Node.js 22.12 or newer; web automation requires Node.js 24 or newer. See [Installation](https://oss.callstack.com/agent-device/docs/installation) for target requirements. |
| 27 | |
| 28 | ```bash |
| 29 | npm install -g agent-device@latest |
| 30 | agent-device doctor |
| 31 | agent-device --version |
| 32 | agent-device help workflow |
| 33 | ``` |
| 34 | |
| 35 | Run `agent-device doctor` yourself before handing the CLI to an agent. The installed CLI help defines current behavior. `agent-device help workflow` links to guides for debugging, replay, React Native profiling, and other tasks. |
| 36 | |
| 37 | Add a contact in the built-in iOS Contacts app: |
| 38 | |
| 39 | ```bash |
| 40 | # Start a session. |
| 41 | agent-device open Contacts --platform ios |
| 42 | |
| 43 | # Inspect the screen. The example below shows the output; refs vary. |
| 44 | agent-device snapshot -i |
| 45 | # @e2 [button] "Add" |
| 46 | |
| 47 | # Use the ref and wait for the UI to settle. |
| 48 | agent-device press @e2 --settle |
| 49 | # The diff includes: |
| 50 | # + @e7 [text-field] "First name" |
| 51 | |
| 52 | agent-device fill @e7 "Ada" --settle |
| 53 | # The next diff shows changed values and current refs: |
| 54 | # - @e7 [text-field] "First name" |
| 55 | # + @e14 [text-field] "Ada" |
| 56 | # = @e15 [text-field] "Last name" |
| 57 | |
| 58 | # Capture evidence and close the session. |
| 59 | agent-device screenshot ./contact-form.png |
| 60 | agent-device close |
| 61 | ``` |
| 62 | |
| 63 | Use refs only from the latest output. Do not assume an earlier `@eN` still identifies the same element. After a command with `--settle`, use the refs in its diff. Take another snapshot only if the diff omits what you need. |
| 64 | |
| 65 | Snapshots use the app's accessibility tree. Clear labels, roles, and test IDs make agent runs more reliable. Use screenshots and videos as evidence or when accessibility data is poor. Use refs and selectors for actions and assertions when you can. |
| 66 | |
| 67 |  |
| 68 | |
| 69 | ## What agents can do |
| 70 | |
| 71 | - **Inspect app state** through accessibility snapshots, refs, selectors, and React Native component trees. |
| 72 | - **Act on visible UI** by tapping or pressing elements, filling fields, scrolling, making gestures, waiting, asserting state, and handling alerts. |
| 73 | - **Diagnose failures** with screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles. |
| 74 | - **Repeat workflows** by saving working steps as `.ad` scripts for local use or CI. Export strict Maestro YAML when needed. |
| 75 | |
| 76 | See [Commands](https://oss.callstack.com/agent-device/do |
Related
6 picksType
- xcodebuildmcpXcodeBuildMCP provides tools for Xcode project management, simulator management, and app utilities.Jul 2026
- mobile-mcpMCP server for iOS and Android Mobile Development, Automation and TestingJul 2026
- android-mcp-serverAn MCP server for android automationMay 2025
- android-mcpLightweight MCP Server for Android Operating SystemJul 2026
- mobile-mcpA MCP server to control your mobile devicesApr 2025
- weapp-agent-mcpAgent-first MCP server for WeChat Mini Program debugging & automation via WeChat DevTools.Jul 2026
