skills/callstack__agent-device
1
0
Fork 0
mirror of https://github.com/callstack/agent-device.git synced 2026-09-14 20:06:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: simplify README language (#1352)

Browse Source 
* docs: simplify README language

* docs: restore README technical details
This commit is contained in:
Michał Pierzchała
2026-07-20 20:25:05 +02:00
committed by GitHub
parent b3b9ff59b0
commit 52e306082f
1 changed files with 33 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+33 -33
View File
@@ -15,15 +15,15 @@
Let your coding agent verify its changes in the running app.
`agent-device` is an agent-native CLI for inspecting, interacting with, and verifying real apps on supported iOS, Android, TV, web, and desktop targets. It gives coding agents a live feedback loop through token-efficient accessibility snapshots, semantic refs and selectors, device actions, and reviewable evidence.
`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.
Your coding agent or QA harness interprets the current state and chooses each next step. `agent-device` provides the session-aware device execution and captures evidence when the task needs it.
Your coding agent or QA tool reads each result and chooses the next command. `agent-device` runs the command and saves evidence when asked.
If you know Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser), `agent-device` brings the same inspect-act-verify model to mobile, TV, and desktop apps. Minimal `--platform web` support reuses `agent-browser` inside the same session and replay workflow.
`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.
## Quick start
Install the CLI and check setup. It requires Node.js 22.12 or newer; web automation requires Node.js 24 or newer. Target-specific prerequisites are covered in [Installation](https://oss.callstack.com/agent-device/docs/installation).
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.
```bash
npm install -g agent-device@latest
@@ -32,25 +32,25 @@ agent-device --version
agent-device help workflow
```
Run `agent-device doctor` yourself before handing the CLI to an agent. The installed CLI help is the source of truth; `agent-device help workflow` routes agents to guidance for debugging, replay, React Native profiling, and other tasks.
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.
Run a short form flow in the built-in iOS Contacts app:
Add a contact in the built-in iOS Contacts app:
```bash
# Start a session.
agent-device open Contacts --platform ios
# Inspect the screen. Example output is shown below; refs vary.
# Inspect the screen. The example below shows the output; refs vary.
agent-device snapshot -i
# @e2 [button] "Add"
# Use the ref from the snapshot and continue from the settled diff.
# Use the ref and wait for the UI to settle.
agent-device press @e2 --settle
# The settled diff includes:
# The diff includes:
# + @e7 [text-field] "First name"
agent-device fill @e7 "Ada" --settle
# The next settled diff includes changed values and current refs:
# The next diff shows changed values and current refs:
# - @e7 [text-field] "First name"
# + @e14 [text-field] "Ada"
# = @e15 [text-field] "Last name"
@@ -60,28 +60,28 @@ agent-device screenshot ./contact-form.png
agent-device close
```
Refs belong to the snapshot or settled diff that returned them. Continue with refs from the latest output; do not assume an earlier `@eN` still identifies the same element. A successful settled diff is the next observation, so take another snapshot only when the diff lacks the next target or evidence.
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.
Snapshots come from the app's accessibility tree, so high-quality labels, roles, and test IDs make agent runs far more reliable. Use screenshots and videos as evidence or visual fallback, but prefer refs and selectors for actions and assertions whenever the UI exposes enough structure.
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
- **Inspect app state** through structured accessibility snapshots, interactive refs, selectors, and React Native component trees.
- **Act on visible UI** by tapping or pressing elements, filling fields, scrolling, performing gestures, waiting, asserting state, and handling alerts.
- **Diagnose failures** with evidence including screenshots, video, logs, traces, network traffic, performance samples, crash context, and React profiles.
- **Repeat successful workflows** by recording `.ad` scripts for local runs and CI, with strict Maestro YAML export when a flow belongs in Maestro.
- **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.
Command and evidence support varies by target. See [Commands](https://oss.callstack.com/agent-device/docs/commands) for the current platform-specific surface.
See [Commands](https://oss.callstack.com/agent-device/docs/commands) for the commands and evidence each target supports.
![Sketch showing agent-device as the live app verification layer in the agentic development loop](./website/docs/public/agentic-development-loop.svg)
![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)
## Next steps
- **Set up your agent**: run the CLI from Cursor, Codex, Claude Code, Windsurf, or another agent terminal. For skills, rules, direct MCP tools, and client-specific setup, see [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup).
- **Try the sample app**: clone the repo and run the bundled Expo fixture for a guided dogfood run with screenshots, replay, and performance evidence. See [Quick Start](https://oss.callstack.com/agent-device/docs/quick-start).
- **Build production workflows**: use [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) and [Debugging & Profiling](https://oss.callstack.com/agent-device/docs/debugging-profiling).
- **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.
## Articles and videos
@@ -102,37 +102,37 @@ Command and evidence support varies by target. See [Commands](https://oss.callst
| Path | Best for | Start with |
| --- | --- | --- |
| Local | Exploration, debugging, and development loops on simulators, emulators, physical devices, macOS apps, and Linux desktop targets. | Follow the Quick Start. |
| CI/CD | Automated PR 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 execution | Linux runners, managed devices, and remote execution. | Use [Agent Device Cloud](https://agent-device.dev/cloud), see [Commands](https://oss.callstack.com/agent-device/docs/commands) for remote profiles, or [contact Callstack](mailto:hello@callstack.com) for team-scale QA. |
| 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. |
## How it works
`agent-device` runs session-aware commands through platform backends: XCTest for iOS and tvOS, ADB plus the Android snapshot helper for Android, a local helper for macOS desktop automation, and AT-SPI for Linux desktop targets.
`agent-device` keeps device state in sessions. It sends commands to XCTest on iOS and tvOS, ADB and the snapshot helper on Android, a local helper on macOS, and AT-SPI on Linux.
Node consumers can use the typed client and public subpaths for bridge integrations. `agent-device/android-adb` exposes the Android ADB provider contract, logcat/clipboard/keyboard/app helpers, and port reverse management.
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.
## FAQ
### What is agent-device?
`agent-device` is a device automation CLI for AI mobile app testing and verification. It lets coding agents inspect real UI state, interact through semantic refs and selectors, and capture reviewable evidence on supported iOS, Android, TV, web, and desktop targets.
`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, TV, web, macOS, and Linux.
### Does it work with React Native, Expo, Flutter, and native apps?
Yes. `agent-device` works with native iOS and Android apps and apps built with React Native, Expo, and Flutter, as long as they run on a supported target. Available commands and evidence vary by target.
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 Appium, Detox, or Maestro?
`agent-device` is optimized for an agent that inspects runtime state and chooses each next step through structured CLI output. Appium, Detox, and Maestro remain strong fits for teams with authored test suites and existing framework infrastructure; agent-device can complement them by recording explorations as `.ad` scripts or exporting strict Maestro YAML.
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.
### Can agent-device run in CI?
Yes. Record explorations as `.ad` scripts, replay them locally or in CI, and keep 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 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).
## Used by
## Who uses agent-device?
Used by 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 more.
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`.
## Documentation
@@ -145,4 +145,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
## Made at Callstack
`agent-device` is open source and MIT licensed. Visit [agent-device.dev](https://agent-device.dev/), try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml), read the [docs](https://oss.callstack.com/agent-device/), or contact us at hello@callstack.com.
`agent-device` is open source under the MIT license. Visit [agent-device.dev](https://agent-device.dev/) or [contact Callstack](mailto:hello@callstack.com).