agent-device
installs/mo · npmstarsforks
How to install agent-device?
callstack/agent-device
$git clone 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 |
People who liked this also viewed
6 picksType
- Scrapling🕷️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!MCP ServersJul 2026
- excel-mcp-serverA Model Context Protocol server for Excel file manipulationMCP ServersApr 2026
- Excel-MCP-Server-MasterExcel MCP Server - Manipulate Excel files without Microsoft Excel. Model Context Protocol for XLSX, XLSM with Claude AI integrationMCP ServersJun 2025
- n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you MCP ServersJul 2026
- ha-mcpThe Unofficial and Awesome Home Assistant MCP ServerMCP ServersJul 2026
- cuga-agentCUGA is an open-source generalist agent harness for the enterprise, supporting complex task execution on web and APIs, OpenAPI/MCP integrations, composable architecture, reasoning modes, and policy-aware features.MCP ServersJul 2026
