Introduction

    agent-device is an agent-native CLI for app verification and QA from coding agents. Across iOS, Android, HarmonyOS, tvOS, Android TV, Amazon Vega OS TV apps in the Vega Virtual Device, macOS, Linux desktop targets, and a minimal managed web browser surface, it provides the interactions and target-dependent structured UI, evidence, performance, and replay capabilities each backend supports.

    Use it when an agent needs to inspect and operate a real app, not just reason about source code or screenshots.

    agent-device is the agent's hands, eyes, and evidence collector. It does not contain the test intelligence itself: the coding agent, QA agent, or project harness reads the task, interprets the current screen, chooses commands, and judges whether the result meets the scenario. Keeping that boundary clear makes it easier to combine live exploration, deterministic replay, and human review without hiding decision-making inside the device tool.

    Where it shines

    • App verification for agents: run the app, inspect visible UI, act through refs/selectors, and verify expected state.
    • Token-efficient UI context: accessibility snapshots give agents structured UI state instead of screenshot-only reasoning.
    • Runtime evidence: capture screenshots, recordings, logs, network traffic, audio-level probes for browser and host-rendered simulator/emulator audio, traces, CPU/memory/perf snapshots, and crash-related logs when the happy path breaks.
    • Replayable checks: turn stable exploratory sessions into .ad replay scripts that can run again without AI.
    • React Native and Expo workflows: pair device automation with optional React DevTools profiling for component trees, props/state/hooks, slow renders, and rerenders.
    • Local devices and app surfaces: drive simulators, emulators, physical devices, TV targets, desktop apps, and browser sessions through one CLI.

    If you know agent-browser, agent-device brings the same agent-oriented workflow to mobile, TV, desktop, and a narrow managed web browser slice.

    Development loop

    agent-device closes the agentic development loop: agents can write code, run the real app, verify the UI end-to-end, collect screenshots/videos/logs/perf evidence, and feed bugs, crashes, or performance findings back into the next fix iteration before a human reviews the PR.

    Sketch showing agent-device as the live app verification layer in the agentic development loop

    How agents use it

    The normal loop is:

    agent-device apps --platform ios
agent-device open <app-or-url> --platform ios
agent-device snapshot -i
agent-device press @e12
agent-device diff snapshot -i
agent-device close

    Snapshots are accessibility-first: labels, roles, values, and test IDs are the primary signal for choosing refs and selectors. Screenshots and videos are still important evidence, and they are useful fallbacks when a screen exposes poor accessibility data, but durable agent workflows should prefer structured refs/selectors over pixel or OCR guesses.

    Installed CLI help is the version-matched operating guide. Start there before planning device work:

    agent-device help workflow
agent-device help debugging
agent-device help react-devtools
agent-device help cdp
agent-device help dogfood

    Use AI Agent Setup for Cursor, Codex, Claude Code, Windsurf, Cline, Goose, skills, and MCP setup. Use Commands for detailed command groups and platform behavior.

    Where it fits

    agent-device is for agents, but humans still install it, grant permissions, review artifacts, and decide what ships.

    It complements scripted test frameworks such as Appium, Maestro, Detox, XCTest, and Espresso. Keep those for stable human-authored coverage. Use agent-device when an agent needs to explore, reproduce, debug, profile, collect evidence, or record a replay from live app behavior.

    MCP support exposes direct structured tools for installed agent-device commands. Tools use structured input contracts through AgentDeviceClient, so MCP clients can call device workflows directly while the daemon remains the execution source of truth.

    Next steps

    Need React or React Native expertise you can count on?

    Let's talk