MCP Servers · callstack

agent-device

agent-device is a CLI tool that lets AI coding agents inspect and interact with real iOS, Android, and desktop apps—taking screenshots, reading UI structure, tapping buttons, and collecting debugging evidence. It bridges the gap between agents and actual mobile devices, simulators, and emulators so verification happens on real hardware, not just in code.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/callstack/agent-device

3.2k

GitHub stars

173

Forks

TypeScript

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	callstack/agent-device
Owner	callstack
Primary language	TypeScript
License	MIT — OSI-approved
Stars	3.2k
Forks	173
Open issues	26
Latest release	v0.19.0 (2026-07-07)
Last updated	2026-07-08
Source	https://github.com/callstack/agent-device

What agent-device is

TypeScript-based device automation CLI using XCTest for iOS/tvOS, ADB for Android, and platform-specific backends (macOS Accessibility, AT-SPI for Linux). Exposes accessibility trees as structured JSON with interactive refs (@e1, @e2, etc.), supports screenshot/video/log/trace/network capture, and exports workflows as replayable .ad scripts or Maestro YAML.

Quickstart

Get the agent-device source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/callstack/agent-device.git2cd agent-device3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

AI-Assisted Mobile Development & Testing

Embed agent-device in Cursor, Codex, or Claude Code workflows to give coding agents live feedback loops on real iOS/Android apps. Agents can verify changes before review, catch regressions, and help debug issues with screenshots and accessibility data.

Automated Mobile CI/CD & Verification

Record replayable .ad scripts or export to Maestro YAML for repeatable e2e checks in CI pipelines (EAS Workflows, GitHub Actions). Capture evidence artifacts—screenshots, logs, performance samples—for post-run analysis without flaky waits.

Regression & Performance Debugging on Real Devices

Use snapshot inspection, network traffic capture, CPU/memory profiling, and crash context collection to pinpoint regressions on physical iOS/Android devices or emulators. Structured accessibility data guides agents to identify UI-level failures faster than visual inspection alone.

Implementation considerations

Platform-specific setup is mandatory: Node.js 22+ (24+ for web), Xcode + Xcode CLI tools for iOS/tvOS/macOS, Android SDK + ADB for Android. macOS Accessibility permission required for desktop automation. Budget 2–4 hours per new platform target.
Accessibility data quality directly impacts agent reliability. Audit target apps for proper semantics (labels, roles, test IDs); poor accessibility will force agents to rely on fragile visual/coordinate-based actions.
Session management and replay scripts (.ad format) require careful handling in CI: ensure reproducible app state, network conditions, and device startup; cloud runners (Agent Device Cloud, EAS Workflows) reduce variability but add latency.
For physical device testing, USB connectivity, provisioning profiles (iOS), and device unlock state must be stable. Emulator/simulator runs are faster and more reproducible; reserve physical device tests for final validation.
Evidence artifacts (screenshots, videos, logs, traces) can grow large in CI; implement retention policies and only capture when failures occur to reduce storage and runtime overhead.

When to avoid it — and what to weigh

You Need Thick Web Automation — agent-device has minimal web support (reuses agent-browser); if your workflow is primarily web-based, use agent-browser or Puppeteer directly instead.
You Require Cross-Platform UI Testing at Scale Without Setup — agent-device depends on platform-specific toolchains (Xcode, Android SDK, ADB) and accessibility framework setup. Cloud runners simplify this, but on-prem local execution requires non-trivial infrastructure.
Your Team Needs Non-Technical Visual Test Recording — agent-device is designed for agents and engineers reading accessibility trees and snapshots. If non-technical stakeholders need point-and-click record/replay, tools like Maestro Studio may be more approachable.
You Cannot Rely on Accessibility Framework Quality — agent-device leverages iOS Accessibility, Android A11y APIs, and Flutter semantics. Apps with poor labels, roles, or test IDs will yield low-quality snapshots; you'll fall back to fragile coordinate-based actions and screenshots.

License & commercial use

MIT License (callstack/agent-device). Permissive open-source license allowing commercial use, modification, and distribution with attribution and no warranty.

MIT is a permissive OSI-approved license allowing commercial use. However, this project and all supporting tools (platform backends, CI templates, cloud runners) are free/open-source. For team-scale QA and cloud execution, Callstack offers Agent Device Cloud as a commercial service; consult their site or contact them directly for licensing and SLAs.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Moderate
DEV.co fit	Strong
Assessment confidence	High

Security considerations

agent-device runs on local/emulated devices or cloud runners you control; no inherent security posture claims are made. Considerations: ensure ADB, Xcode, and Android SDK are kept updated; physical device testing requires USB security awareness; snapshot and evidence files may contain sensitive UI or app state—treat artifacts as you would production logs. No public CVEs or known exploits cited in data. For production CI, isolate device environments and limit snapshot/log retention. Cloud runners delegate to Callstack; review their security docs before adopting.

Alternatives to consider

Appium

Mature, language-agnostic mobile automation framework. More flexible for native app testing but not AI-agent-native; no built-in accessibility snapshot refs or token-efficient interaction model. Heavier setup and steeper learning curve for agent integration.

Maestro

Flow-based mobile testing with visual and accessibility support. Simpler record/replay and strong for regression testing, but not designed for AI agents. Lacks real-time accessibility snapshots and interactive refs; better for scripted test suites than agentic loops.

Detox

React Native and native iOS/Android testing framework. Excellent for unit and integration testing with deterministic runs, but narrower scope (no tvOS, desktop, or web support) and no AI-agent-centric API. Better for test harnesses than live agent feedback.

Software development agency

Build on agent-device with DEV.co software developers

Install agent-device and integrate it into your agent workflow. Start with the Quick Start guide or explore AI Agent Setup for your favorite coding agent (Cursor, Claude Code, Windsurf).

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

mobile-mcp agent-scan agents-cli

Related on DEV.co

Explore the category and the services that help you build with it.

MCP Servers AI Application Development Mobile App Development & QA Talk to DEV.co

agent-device FAQ

Can agent-device run on a Mac, Linux, or Windows?

Yes. agent-device CLI runs on macOS and Linux. macOS supports iOS/tvOS/macOS automation. Linux supports Android (via ADB) and desktop automation (AT-SPI). Windows support is not clearly stated; likely requires WSL2 or remote execution.

Do I need physical devices, or can I use simulators and emulators?

Both. iOS Simulator, Android Emulator, and tvOS Simulator are fully supported and faster/more reproducible for local development. Physical devices are supported for final validation and edge-case testing. Cloud runners (Agent Device Cloud) manage device pools for CI.

How do I integrate agent-device with my AI coding agent (Cursor, Claude Code, etc.)?

Install agent-device CLI globally, then invoke it from the agent terminal. For tight integration, use MCP (Model Context Protocol) or TypeScript client APIs. Docs include AI Agent Setup guides for Cursor, Codex, Windsurf, and custom setups. See oss.callstack.com/agent-device/docs/agent-setup.

What happens if an app has poor accessibility labels?

Snapshots will contain limited interactive refs; agents will fall back to visual inspection (screenshots) and fragile coordinate-based or selector-based actions. Improve app accessibility (add proper labels, roles, test IDs) to make agent runs reliable. This is a app-side dependency, not a tool limitation.

Work with a software development agency

DEV.co is a software development agency delivering custom software development services to companies building on open source. Our software developers and web developers design, integrate, and ship production systems — spanning web development, APIs, AI, data, and cloud. If agent-device is part of your mcp servers roadmap, our team can implement, customize, migrate, and maintain it.

Ready to automate mobile testing with AI?

Install agent-device and integrate it into your agent workflow. Start with the Quick Start guide or explore AI Agent Setup for your favorite coding agent (Cursor, Claude Code, Windsurf).

Talk to DEV.co Schedule a Consultation