From 7d479f75a44d5ff8f8aa91ab194710cc56d5e858 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 17 Aug 2026 12:19:38 +0200 Subject: [PATCH 1/6] docs: reposition README around mobile app automation for AI agents Lead the README with the category (mobile app automation, testing, and verification for AI coding agents) and the three surfaces (CLI, MCP server, Node.js API) so humans and search engines can classify it, then keep verification and evidence as the differentiator. - Move per-platform transport/caveat sentences (HarmonyOS HDC/uitest, Vega VVD-only) out of the intro into "How it works" and add an inline guard comment plus an AGENTS.md rule so new platforms only add a name to the intro list. - Add MCP and Node.js quick starts next to the CLI walkthrough. - Add a works-with/proof line, a "What to ask your agent" prompt list, a product-ladder sentence, and two AEO-shaped FAQ entries. - Point the cloud/remote row at the remote proxy and device clouds docs. - Align npm, MCP registry, and docs-site descriptions with the same category phrasing. - Remove em dashes and evaluative filler per the humanizer skill. --- AGENTS.md | 4 ++ README.md | 122 ++++++++++++++++++++++++++++---------- package.json | 2 +- server.json | 2 +- website/rspress.config.ts | 2 +- 5 files changed, 97 insertions(+), 35 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8e8fd90aa0..c7c66b667d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -251,5 +251,9 @@ connect errors, retry policy, or command typing, start in help/metadata, README or `website/docs/**` when user-facing, and a help-conformance bench case (`scripts/help-conformance-*.mjs`) when command-planning guidance changes. - State in the final summary whether docs/skills were updated, and why not if they weren't. +- README altitude: the intro is a category line, the job pitch with the platform list, and the + works-with/proof line — nothing else. Per-platform transports, tool names, vendor lists, and + support caveats go in "How it works" and `website/docs/**`. A new platform adds its name to the + intro list and its backend to "How it works", nothing more. When guidance conflicts, Hard Rules win, then scope, then testing, then style. diff --git a/README.md b/README.md index b651b89a91..d315688e4e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ - agent-device: device automation CLI for AI agents + agent-device: mobile app automation and verification for AI coding agents @@ -13,13 +13,24 @@ [![License: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE) [![Glama MCP server](https://glama.ai/mcp/servers/callstack/agent-device/badges/score.svg)](https://glama.ai/mcp/servers/callstack/agent-device) -Let your coding agent verify its changes in the running app. +**Mobile app automation, testing, and verification for AI coding agents.** Available as a CLI, an official MCP server, and a typed Node.js API. -`agent-device` lets coding agents inspect, control, and verify apps on iOS, Android, HarmonyOS, tvOS, Android TV, Amazon Vega OS TV through the Vega Virtual Device (VVD), web, macOS, and Linux. Agents can read token-efficient accessibility snapshots where supported, find elements by ref or selector, run device actions, and save evidence for review. HarmonyOS support uses HDC and ArkUI `uitest` on connected devices and DevEco emulators; use `capabilities --platform harmonyos` to inspect its evidence-backed command subset. Initial Vega OS support is VVD-only and covers discovery, app lifecycle, and complete TV-remote control; physical Fire TV, capture, and selector backends remain unsupported. + -Your coding agent or QA tool reads each result and chooses the next command. `agent-device` runs the command and saves evidence when asked. +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, 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. -`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. +Works with Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any agent that can run a CLI or connect over MCP. Teams at JPMorgan Chase, Expensify, Shopify, and [others](#who-uses-agent-device) use it to verify their apps. + +## What agents can do + +- **Inspect app state** through accessibility snapshots, refs, selectors, and React Native component trees. +- **Act on visible UI** by tapping or pressing elements, filling fields, scrolling, making gestures, waiting, asserting state, and handling alerts. +- **Diagnose failures** with screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles. +- **Repeat workflows** by saving working steps as `.ad` scripts for local use or CI. Export strict Maestro YAML when needed. + +See [Commands](https://oss.callstack.com/agent-device/docs/commands) for the commands and evidence each target supports. + +![Diagram of the agentic development loop: humans assign tasks, agents write and review code, agent-device verifies mobile apps, pull requests receive evidence, and bugs or performance issues lead to fixes](./website/docs/public/agentic-development-loop.svg) ## Quick start @@ -33,6 +44,10 @@ agent-device help workflow 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. +From here, pick how your agent uses it: the CLI in a terminal, MCP tools in an agent client, or the typed client in Node.js code. + +### Drive an app from the CLI + Add a contact in the built-in iOS Contacts app: ```bash @@ -59,65 +74,93 @@ agent-device screenshot ./contact-form.png agent-device close ``` -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. - -`--settle` works the same way on `scroll` and `back`, so scroll-then-observe and back-then-observe are one call too. +Use refs only from the latest output. Do not assume an earlier `@eN` still identifies the same element. After a command with `--settle` (`scroll` and `back` support it too), use the refs in its diff. Take another snapshot only if the diff omits what you need. 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. ![agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt](./website/docs/public/agent-device-contacts.gif) -## What agents can do +### Add MCP tools to your agent -- **Inspect app state** through accessibility snapshots, refs, selectors, and React Native component trees. -- **Act on visible UI** by tapping or pressing elements, filling fields, scrolling, making gestures, waiting, asserting state, and handling alerts. -- **Diagnose failures** with screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles. -- **Repeat workflows** by saving working steps as `.ad` scripts for local use or CI. Export strict Maestro YAML when needed. +`agent-device mcp` starts the official stdio MCP server. It exposes structured tools for the installed commands, backed by the same execution path as the CLI. Add it to Cursor, Claude Code, Windsurf, or another MCP client: -See [Commands](https://oss.callstack.com/agent-device/docs/commands) for the commands and evidence each target supports. +```json +{ + "mcpServers": { + "agent-device": { + "command": "agent-device", + "args": ["mcp"] + } + } +} +``` -![Diagram of the agentic development loop: humans assign tasks, agents write and review code, agent-device verifies mobile apps, pull requests receive evidence, and bugs or performance issues lead to fixes](./website/docs/public/agentic-development-loop.svg) +See [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) for per-client setup and when to prefer plain CLI over MCP. -## Next steps +### Script it from Node.js -- **Set up your agent**: run the CLI from Cursor, Codex, Claude Code, Windsurf, or another agent terminal. See [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) for skills, rules, MCP tools, and setup for each client. -- **Try the sample app**: clone the repo and run the bundled Expo test app. [Quick Start](https://oss.callstack.com/agent-device/docs/quick-start) covers a guided run with screenshots, replay, and performance data. -- **Build repeatable tests**: use [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) to repeat tests. Use [Debugging & Profiling](https://oss.callstack.com/agent-device/docs/debugging-profiling) to find bugs. +`createAgentDeviceClient()` gives Node.js code typed access to the same commands. Expose its methods as model tools or call them from orchestration code: -## Articles and videos +```ts +import { createAgentDeviceClient } from 'agent-device'; -### Articles +const client = createAgentDeviceClient({ session: 'qa-run' }); +await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' }); -- [Build an AI QA agent for Expo apps with EAS Workflows](https://expo.dev/blog/build-an-ai-qa-agent-for-expo-apps-with-eas-workflows-in-minutes-today) -- [Agent Device: iOS & Android automation for AI agents](https://www.callstack.com/blog/agent-device-ai-native-mobile-automation-for-ios-android) -- [Building mobile QA agents with Vercel Eve](https://www.callstack.com/blog/building-reviewable-mobile-qa-agents-with-vercel-eve) -- [How we optimized Agent Device for mobile app automation](https://www.callstack.com/blog/how-we-optimized-agent-device-for-mobile-app-automation) +const snapshot = await client.capture.snapshot({ interactiveOnly: true }); +const button = snapshot.nodes.find((node) => node.role === 'button'); +if (button) await client.interactions.press({ ref: button.ref }); -### Videos +await client.sessions.close(); +``` -- [Verifying mobile apps with agent-device](https://youtu.be/kZDU-k5r9kE) -- [Using agent-device in an AI coding workflow](https://youtu.be/dfVG_aNPkW4) -- [Cloud agents that test mobile apps on real devices](https://youtu.be/r5P0detC4bs?is=_KB6SZbLFRB1au_z) +See the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api) and the [runnable examples](https://github.com/callstack/agent-device/tree/main/examples/sdk) for typed error handling, batching, and the other public entry points. + +## What to ask your agent + +With the CLI installed, prompts like these work end to end: + +- "Implement the onboarding screen, run it on the iOS simulator and Android emulator, and attach screenshots." +- "Reproduce this crash and capture the logs that lead up to it." +- "Check whether this change causes unnecessary React Native re-renders." +- "Explore the checkout flow once, save it as a replay script, and run it in CI." +- "Verify this pull request on a physical device and attach reviewable evidence." + +## Next steps + +- **Set up your agent**: run the CLI from Cursor, Codex, Claude Code, Windsurf, or another agent terminal. See [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) for skills, rules, MCP tools, and setup for each client. +- **Try the sample app**: clone the repo and run the bundled Expo test app. [Quick Start](https://oss.callstack.com/agent-device/docs/quick-start) covers a guided run with screenshots, replay, and performance data. +- **Build repeatable tests**: use [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) to repeat tests. Use [Debugging & Profiling](https://oss.callstack.com/agent-device/docs/debugging-profiling) to find bugs. ## Where to run agent-device +The same session and evidence model works at every step: the agent explores the app, captures evidence, saves a replay, runs it in CI, and moves onto remote devices. + | Path | Best for | Start with | | --- | --- | --- | | Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. | | CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). GitHub Actions template coming soon. | -| Cloud / remote | Linux runners, managed devices, and remote jobs. | Use [Agent Device Cloud](https://agent-device.dev/cloud), set a remote profile with [Commands](https://oss.callstack.com/agent-device/docs/commands), or [contact Callstack](mailto:hello@callstack.com) for team QA. | +| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://oss.callstack.com/agent-device/docs/remote-proxy), connect a [device cloud](https://oss.callstack.com/agent-device/docs/device-clouds) (BrowserStack, AWS Device Farm, Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. | ## How it works `agent-device` keeps device state in sessions. It sends commands to XCTest on iOS and tvOS, ADB and the snapshot helper on Android, HDC and ArkUI `uitest` on HarmonyOS, Vega CLI/VDA on the Vega Virtual Device, a local helper on macOS, and AT-SPI on Linux. -Node.js apps can use the typed client or public subpaths. `agent-device/android-adb` provides the Android ADB provider interface, helpers for logcat, the clipboard, the keyboard, and apps, and port reverse management. +Support depth varies by target. Newer backends such as HarmonyOS and Vega OS cover a subset of commands; run `agent-device capabilities --platform ` to see what a target supports. + +Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. The same commands drive hosted devices on [BrowserStack, AWS Device Farm, and Limrun](https://oss.callstack.com/agent-device/docs/device-clouds). + +`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. ## FAQ ### What is agent-device? -`agent-device` is a command-line tool that lets coding agents inspect, control, and verify apps and save evidence for review. It supports iOS, Android, HarmonyOS, TV, web, macOS, and Linux. +`agent-device` is a command-line tool and MCP server that lets AI coding agents inspect, control, and verify mobile apps and save evidence for review. It supports iOS, Android, HarmonyOS, TV, web, macOS, and Linux. + +### Is there an MCP server for mobile app automation? + +Yes. `agent-device mcp` starts the official stdio MCP server. The Quick start above has the client config, and [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) covers per-client details. ### Does it work with React Native, Expo, Flutter, and native apps? @@ -131,6 +174,21 @@ With `agent-device`, an agent reads app state and chooses each command at run ti Yes. Record a run as an `.ad` script, replay it locally or in CI, and save screenshots, logs, and other artifacts for review. See [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) or start with the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). +## Articles and videos + +### Articles + +- [Build an AI QA agent for Expo apps with EAS Workflows](https://expo.dev/blog/build-an-ai-qa-agent-for-expo-apps-with-eas-workflows-in-minutes-today) +- [Agent Device: iOS & Android automation for AI agents](https://www.callstack.com/blog/agent-device-ai-native-mobile-automation-for-ios-android) +- [Building mobile QA agents with Vercel Eve](https://www.callstack.com/blog/building-reviewable-mobile-qa-agents-with-vercel-eve) +- [How we optimized Agent Device for mobile app automation](https://www.callstack.com/blog/how-we-optimized-agent-device-for-mobile-app-automation) + +### Videos + +- [Verifying mobile apps with agent-device](https://youtu.be/kZDU-k5r9kE) +- [Using agent-device in an AI coding workflow](https://youtu.be/dfVG_aNPkW4) +- [Cloud agents that test mobile apps on real devices](https://youtu.be/r5P0detC4bs?is=_KB6SZbLFRB1au_z) + ## Who uses agent-device? Teams and developers at Callstack, JPMorgan Chase, [Expensify](https://www.callstack.com/blog/how-expensify-uses-agent-device-for-mobile-bug-evidence-and-profiling), [Shopify](https://x.com/mustafa01ali/status/2036577353178943826), Kindred, [Total Wine & More](https://www.callstack.com/podcasts/how-ai-is-changing-react-native-development-and-testing), [LegendList](https://x.com/jmeistrich/status/2036398735698305178), HerLyfe, App & Flow, and others use `agent-device`. diff --git a/package.json b/package.json index c20545dd4b..0c071d5d5d 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "agent-device", "version": "0.20.8", - "description": "Agent-native CLI for AI app automation across iOS, Android, tvOS, Android TV, macOS, Linux, and web.", + "description": "Mobile app automation, testing, and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.", "mcpName": "io.github.callstack/agent-device", "license": "MIT", "author": "Callstack", diff --git a/server.json b/server.json index acd4481ef0..4ecd9def49 100644 --- a/server.json +++ b/server.json @@ -2,7 +2,7 @@ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.callstack/agent-device", "title": "agent-device", - "description": "Let AI agents inspect, control, and debug real iOS, Android, desktop, and TV apps", + "description": "MCP server for mobile app automation: verify, control, and debug iOS, Android, TV, and desktop apps", "repository": { "url": "https://github.com/callstack/agent-device", "source": "github" diff --git a/website/rspress.config.ts b/website/rspress.config.ts index b35d27843d..ff8d75df67 100644 --- a/website/rspress.config.ts +++ b/website/rspress.config.ts @@ -7,7 +7,7 @@ export default withCallstackPreset( docs: { title: 'agent-device', description: - 'Agent-native CLI for AI mobile testing, React Native QA, Expo app verification, simulator and emulator automation, app observability, and replayable device workflows.', + 'Mobile app automation and verification for AI coding agents: CLI, MCP server, and Node.js API for mobile testing, React Native QA, Expo app verification, simulator and emulator automation, and replayable device workflows.', editUrl: 'https://github.com/callstack/agent-device/edit/main/website', rootUrl: 'https://oss.callstack.com/agent-device', rootDir: 'docs', From 5993e078f0a6ac90b831f180384f7cfc9f6fe7da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 17 Aug 2026 12:38:25 +0200 Subject: [PATCH 2/6] docs: tighten README hero, link proof points, move install above capabilities --- README.md | 28 ++++++++++++++-------------- package.json | 2 +- website/rspress.config.ts | 2 +- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index d315688e4e..524f42b2c0 100644 --- a/README.md +++ b/README.md @@ -13,24 +13,13 @@ [![License: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE) [![Glama MCP server](https://glama.ai/mcp/servers/callstack/agent-device/badges/score.svg)](https://glama.ai/mcp/servers/callstack/agent-device) -**Mobile app automation, testing, and verification for AI coding agents.** Available as a CLI, an official MCP server, and a typed Node.js API. +**Mobile app automation and verification for AI coding agents.** Inspect, control, debug, and test apps through the 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, 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. Teams at JPMorgan Chase, Expensify, Shopify, and [others](#who-uses-agent-device) use it to verify their apps. - -## What agents can do - -- **Inspect app state** through accessibility snapshots, refs, selectors, and React Native component trees. -- **Act on visible UI** by tapping or pressing elements, filling fields, scrolling, making gestures, waiting, asserting state, and handling alerts. -- **Diagnose failures** with screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles. -- **Repeat workflows** by saving working steps as `.ad` scripts for local use or CI. Export strict Maestro YAML when needed. - -See [Commands](https://oss.callstack.com/agent-device/docs/commands) for the commands and evidence each target supports. - -![Diagram of the agentic development loop: humans assign tasks, agents write and review code, agent-device verifies mobile apps, pull requests receive evidence, and bugs or performance issues lead to fixes](./website/docs/public/agentic-development-loop.svg) +Works with Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any agent that can run a CLI or connect over MCP. Developers at [Expensify](https://www.callstack.com/blog/how-expensify-uses-agent-device-for-mobile-bug-evidence-and-profiling), [Shopify](https://x.com/mustafa01ali/status/2036577353178943826), and [others](#who-uses-agent-device) use it to verify their apps. ## Quick start @@ -116,6 +105,17 @@ await client.sessions.close(); See the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api) and the [runnable examples](https://github.com/callstack/agent-device/tree/main/examples/sdk) for typed error handling, batching, and the other public entry points. +## What agents can do + +- **Inspect app state** through accessibility snapshots, refs, selectors, and React Native component trees. +- **Act on visible UI** by tapping or pressing elements, filling fields, scrolling, making gestures, waiting, asserting state, and handling alerts. +- **Diagnose failures** with screenshots, video, logs, traces, network data, performance samples, crash details, and React profiles. +- **Repeat workflows** by saving working steps as `.ad` scripts for local use or CI. Export strict Maestro YAML when needed. + +See [Commands](https://oss.callstack.com/agent-device/docs/commands) for the commands and evidence each target supports. + +![Diagram of the agentic development loop: humans assign tasks, agents write and review code, agent-device verifies mobile apps, pull requests receive evidence, and bugs or performance issues lead to fixes](./website/docs/public/agentic-development-loop.svg) + ## What to ask your agent With the CLI installed, prompts like these work end to end: diff --git a/package.json b/package.json index 0c071d5d5d..ecc4a0ac31 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "agent-device", "version": "0.20.8", - "description": "Mobile app automation, testing, and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.", + "description": "Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.", "mcpName": "io.github.callstack/agent-device", "license": "MIT", "author": "Callstack", diff --git a/website/rspress.config.ts b/website/rspress.config.ts index ff8d75df67..c8a3f5b8d2 100644 --- a/website/rspress.config.ts +++ b/website/rspress.config.ts @@ -7,7 +7,7 @@ export default withCallstackPreset( docs: { title: 'agent-device', description: - 'Mobile app automation and verification for AI coding agents: CLI, MCP server, and Node.js API for mobile testing, React Native QA, Expo app verification, simulator and emulator automation, and replayable device workflows.', + 'Mobile app automation and verification for AI coding agents through a CLI, MCP server, and typed Node.js API.', editUrl: 'https://github.com/callstack/agent-device/edit/main/website', rootUrl: 'https://oss.callstack.com/agent-device', rootDir: 'docs', From 2bcd3606991f046ef9748e77e6cc4dc20ccb015f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 17 Aug 2026 12:49:41 +0200 Subject: [PATCH 3/6] docs: add mobile-MCP FAQ distinction, sharpen hero support line, drop coming-soon --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 524f42b2c0..cff98ad59c 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ [![License: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE) [![Glama MCP server](https://glama.ai/mcp/servers/callstack/agent-device/badges/score.svg)](https://glama.ai/mcp/servers/callstack/agent-device) -**Mobile app automation and verification for AI coding agents.** Inspect, control, debug, and test apps through the CLI, built-in MCP server, or typed Node.js API. +**Mobile app automation and verification for AI coding agents.** Give coding agents a live app feedback loop through a CLI, built-in MCP server, or typed Node.js API. @@ -139,7 +139,7 @@ The same session and evidence model works at every step: the agent explores the | Path | Best for | Start with | | --- | --- | --- | | Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. | -| CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). GitHub Actions template coming soon. | +| CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). | | Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://oss.callstack.com/agent-device/docs/remote-proxy), connect a [device cloud](https://oss.callstack.com/agent-device/docs/device-clouds) (BrowserStack, AWS Device Farm, Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. | ## How it works @@ -166,6 +166,10 @@ Yes. `agent-device mcp` starts the official stdio MCP server. The Quick start ab Yes. `agent-device` supports native iOS and Android apps, plus React Native, Expo, and Flutter apps on supported targets. The commands and evidence vary by target. +### How is it different from mobile MCP servers? + +The MCP server is one entry point to the same runtime used by the CLI and typed Node.js API. Sessions, device ownership, selectors, evidence, replay, CI workflows, and cloud routing stay consistent across all three. + ### How is it different from Appium, Detox, or Maestro? With `agent-device`, an agent reads app state and chooses each command at run time. Teams use Appium, Detox, and Maestro to write and maintain test suites. `agent-device` can complement them by saving its runs as `.ad` scripts or exporting them as strict Maestro YAML. From 987f42cbf24ba7546f2da2c7eb42f50b0aecb4df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 17 Aug 2026 13:12:33 +0200 Subject: [PATCH 4/6] docs: make the build-on-top audience explicit in README --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cff98ad59c..66d110dfe8 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ 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, 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. Developers at [Expensify](https://www.callstack.com/blog/how-expensify-uses-agent-device-for-mobile-bug-evidence-and-profiling), [Shopify](https://x.com/mustafa01ali/status/2036577353178943826), and [others](#who-uses-agent-device) use it to verify their apps. +Works with Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any agent that can run a CLI or connect over MCP. Build your own agents and QA tools on the same runtime with the Node.js client and the [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk) and [Eve](https://oss.callstack.com/agent-device/docs/eve) guides. Developers at [Expensify](https://www.callstack.com/blog/how-expensify-uses-agent-device-for-mobile-bug-evidence-and-profiling), [Shopify](https://x.com/mustafa01ali/status/2036577353178943826), and [others](#who-uses-agent-device) use it to verify their apps. ## Quick start @@ -88,7 +88,7 @@ See [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) fo ### Script it from Node.js -`createAgentDeviceClient()` gives Node.js code typed access to the same commands. Expose its methods as model tools or call them from orchestration code: +`createAgentDeviceClient()` gives Node.js code typed access to the same commands. Expose its methods as model tools in your own agent (the [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk) and [Eve](https://oss.callstack.com/agent-device/docs/eve) guides show how) or call them from orchestration code: ```ts import { createAgentDeviceClient } from 'agent-device'; @@ -170,6 +170,10 @@ Yes. `agent-device` supports native iOS and Android apps, plus React Native, Exp The MCP server is one entry point to the same runtime used by the CLI and typed Node.js API. Sessions, device ownership, selectors, evidence, replay, CI workflows, and cloud routing stay consistent across all three. +### Can I build my own agent or QA product on agent-device? + +Yes. The CLI, MCP server, and typed Node.js client are public surfaces over one runtime, so an agent you build gets the same sessions, selectors, evidence, replay, and device-cloud routing as a coding agent using the CLI. Start from the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api), [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk), or [Eve](https://oss.callstack.com/agent-device/docs/eve) guides. + ### How is it different from Appium, Detox, or Maestro? With `agent-device`, an agent reads app state and chooses each command at run time. Teams use Appium, Detox, and Maestro to write and maintain test suites. `agent-device` can complement them by saving its runs as `.ad` scripts or exporting them as strict Maestro YAML. From a56c1f7a3c1ea32d29f6baa7435234c75cd340c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 17 Aug 2026 13:17:42 +0200 Subject: [PATCH 5/6] docs: trim README repetition and signposting --- README.md | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 66d110dfe8..9ccabdb047 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ 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, 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. Build your own agents and QA tools on the same runtime with the Node.js client and the [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk) and [Eve](https://oss.callstack.com/agent-device/docs/eve) guides. Developers at [Expensify](https://www.callstack.com/blog/how-expensify-uses-agent-device-for-mobile-bug-evidence-and-profiling), [Shopify](https://x.com/mustafa01ali/status/2036577353178943826), and [others](#who-uses-agent-device) use it to verify their apps. +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](https://oss.callstack.com/agent-device/docs/ai-sdk) or [Eve](https://oss.callstack.com/agent-device/docs/eve). Developers at [Expensify](https://www.callstack.com/blog/how-expensify-uses-agent-device-for-mobile-bug-evidence-and-profiling), [Shopify](https://x.com/mustafa01ali/status/2036577353178943826), and [others](#who-uses-agent-device) use it to verify their apps. ## Quick start @@ -31,9 +31,7 @@ agent-device doctor agent-device help workflow ``` -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. - -From here, pick how your agent uses it: the CLI in a terminal, MCP tools in an agent client, or the typed client in Node.js code. +Run `doctor` yourself before handing the CLI to an agent; `help workflow` links to the guides for debugging, replay, and profiling, and the installed help always matches the installed version. ### Drive an app from the CLI @@ -63,15 +61,13 @@ agent-device screenshot ./contact-form.png agent-device close ``` -Use refs only from the latest output. Do not assume an earlier `@eN` still identifies the same element. After a command with `--settle` (`scroll` and `back` support it too), use the refs in its diff. Take another snapshot only if the diff omits what you need. - -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. +Refs are only valid from 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](./website/docs/public/agent-device-contacts.gif) ### Add MCP tools to your agent -`agent-device mcp` starts the official stdio MCP server. It exposes structured tools for the installed commands, backed by the same execution path as the CLI. Add it to Cursor, Claude Code, Windsurf, or another MCP client: +`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 { @@ -88,7 +84,7 @@ See [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) fo ### Script it from Node.js -`createAgentDeviceClient()` gives Node.js code typed access to the same commands. Expose its methods as model tools in your own agent (the [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk) and [Eve](https://oss.callstack.com/agent-device/docs/eve) guides show how) or call them from orchestration code: +`createAgentDeviceClient()` gives Node.js code typed access to the same commands, as model tools in your own agent or from orchestration code: ```ts import { createAgentDeviceClient } from 'agent-device'; @@ -103,7 +99,7 @@ if (button) await client.interactions.press({ ref: button.ref }); await client.sessions.close(); ``` -See the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api) and the [runnable examples](https://github.com/callstack/agent-device/tree/main/examples/sdk) for typed error handling, batching, and the other public entry points. +See the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api), the [runnable examples](https://github.com/callstack/agent-device/tree/main/examples/sdk), and the [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk) and [Eve](https://oss.callstack.com/agent-device/docs/eve) integration guides. ## What agents can do @@ -128,9 +124,9 @@ With the CLI installed, prompts like these work end to end: ## Next steps -- **Set up your agent**: run the CLI from Cursor, Codex, Claude Code, Windsurf, or another agent terminal. See [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) for skills, rules, MCP tools, and setup for each client. -- **Try the sample app**: clone the repo and run the bundled Expo test app. [Quick Start](https://oss.callstack.com/agent-device/docs/quick-start) covers a guided run with screenshots, replay, and performance data. -- **Build repeatable tests**: use [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) to repeat tests. Use [Debugging & Profiling](https://oss.callstack.com/agent-device/docs/debugging-profiling) to find bugs. +- [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup): skills, project rules, and per-client setup for Cursor, Codex, Claude Code, Windsurf, and others. +- [Quick Start](https://oss.callstack.com/agent-device/docs/quick-start): a guided run on the bundled Expo test app with screenshots, replay, and performance data. +- [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) and [Debugging & Profiling](https://oss.callstack.com/agent-device/docs/debugging-profiling): repeatable tests and bug hunting. ## Where to run agent-device @@ -172,7 +168,7 @@ The MCP server is one entry point to the same runtime used by the CLI and typed ### Can I build my own agent or QA product on agent-device? -Yes. The CLI, MCP server, and typed Node.js client are public surfaces over one runtime, so an agent you build gets the same sessions, selectors, evidence, replay, and device-cloud routing as a coding agent using the CLI. Start from the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api), [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk), or [Eve](https://oss.callstack.com/agent-device/docs/eve) guides. +Yes. The typed Node.js client is a public surface over that same runtime, so an agent you build inherits everything above. Start from the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api), [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk), or [Eve](https://oss.callstack.com/agent-device/docs/eve) guides. ### How is it different from Appium, Detox, or Maestro? @@ -180,7 +176,7 @@ With `agent-device`, an agent reads app state and chooses each command at run ti ### Can agent-device run in CI? -Yes. Record a run as an `.ad` script, replay it locally or in CI, and save screenshots, logs, and other artifacts for review. See [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) or start with the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). +Yes. Record a run as an `.ad` script, replay it in CI, and keep the screenshots and logs as artifacts; the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml) is a working example. ## Articles and videos From 46ddfb8b1fedcebf5a39f477750e9f06d503948b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 17 Aug 2026 15:31:08 +0200 Subject: [PATCH 6/6] docs: close the session in finally in the README Node.js snippet --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 9ccabdb047..c95693f227 100644 --- a/README.md +++ b/README.md @@ -90,13 +90,14 @@ See [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) fo import { createAgentDeviceClient } from 'agent-device'; const client = createAgentDeviceClient({ session: 'qa-run' }); -await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' }); - -const snapshot = await client.capture.snapshot({ interactiveOnly: true }); -const button = snapshot.nodes.find((node) => node.role === 'button'); -if (button) await client.interactions.press({ ref: button.ref }); - -await client.sessions.close(); +try { + await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' }); + const snapshot = await client.capture.snapshot({ interactiveOnly: true }); + const button = snapshot.nodes.find((node) => node.role === 'button'); + if (button) await client.interactions.press({ ref: button.ref }); +} finally { + await client.sessions.close(); +} ``` See the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api), the [runnable examples](https://github.com/callstack/agent-device/tree/main/examples/sdk), and the [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk) and [Eve](https://oss.callstack.com/agent-device/docs/eve) integration guides.