VerifiedPlugin
Development
callstackincubator-age…
Callstack Agent Skills give AI coding assistants practical React Native knowledge drawn from our work on production apps.
9 skills
@callstackincubatorTesting
Plugin
agent-device
Let your coding agent verify its changes in the running app. 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.
Plugin Signal73/100Solid
maintained100
capable23
documented100
adopted77
Install
$ npx -y skills add callstackincubator/agent-device --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
4,040
Stars
248
Forks
Active
Maintenance
TypeScript
Language
MIT
License
6m ago
Last commit
6mo ago
Created
Repo: callstackincubator/agent-device
What's inside
Skills
2/agent-deviceAutomates Apple-platform apps (iOS, tvOS, macOS), Android devices, and Amazon Vega OS TV apps in Vega Virtual Devices. Use when navigating apps, taking snapshots/screenshots where supported, driving TV remotes, tapping, typing, scrolling, extracting UI info, collecting evidence,/dogfoodSystematically explore and test a mobile app on iOS/Android with agent-device to find bugs, UX issues, and other problems. Use when asked to dogfood, QA, exploratory test, find issues, bug hunt, or test this app on mobile.
README
1agent-device
Let your coding agent verify its changes in the running app.
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.
agent-device uses the inspect-act-verify process from Vercel's 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. See Installation for target requirements.
npm install -g agent-device@latest
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.
Add a contact in the built-in iOS Contacts app:
# Start a session.
agent-device open Contacts --platform ios
# Inspect the screen. The example below shows the output; refs vary.
agent-device snapshot -i
# @e2 [button] "Add"
# Use the ref and wait for the UI to settle.
agent-device press @e2 --settle
# The diff includes:
# + @e7 [text-field] "First name"
agent-device fill @e7 "Ada" --settle
# The next diff shows changed values and current refs:
# - @e7 [text-field] "First name"
# + @e14 [text-field] "Ada"
# = @e15 [text-field] "Last name"
# Capture evidence and close the session.
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.
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.
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
.adscripts for local use or CI. Export strict Maestro YAML when needed.
See Commands for the commands and evidence each target supports.
Next steps
- Set up your agent: run the CLI from Cursor, Codex, Claude Code, Windsurf, or another agent terminal. See AI 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 covers a guided run with screenshots, replay, and performance data.
- Build repeatable tests: use Replay & E2E to repeat tests. Use Debugging & Profiling to find bugs.
Articles and videos
Articles
- Build an AI QA agent for Expo apps with EAS Workflows
- Agent Device: iOS & Android automation for AI agents
- Building mobile QA agents with Vercel Eve
- How we optimized Agent Device for mobile app automation
Videos
- Verifying mobile apps with agent-device
- Using agent-device in an AI coding workflow
- Cloud agents that test mobile apps on real devices
Where to run agent-device
| 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. GitHub Actions template coming soon. |
| Cloud / remote | Linux runners, managed devices, and remote jobs. | Use Agent Device Cloud, set a remote profile with Commands, or contact Callstack 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.
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.
Does it work with React Native, Expo, Flutter, and native apps?
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?
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 a run as an .ad script, replay it locally or in CI, and save screenshots, logs, and other artifacts for review. See Replay & E2E or start with the EAS workflow template.
Who uses agent-device?
Teams and developers at Callstack, JPMorgan Chase, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow, and others use agent-device.
Documentation
Contributing
See CONTRIBUTING.md.
Made at Callstack
agent-device is open source under the MIT license. Visit agent-device.dev or contact Callstack.
File tree
1787callstackincubator/agent-deviceView on GitHub
.codex/
config.toml
.fallowrc.json
.gitattributes
.github/
actions/
boot-ios-test-simulator/
action.yml
build-docs/
action.yml
setup-android-replay-host/
action.yml
setup-apple-runner-build/
action.yml
setup-fixture-app/
action.yml
fetch-artifact.sh
locate-android-apk.sh
repack-android-apk.sh
resolve-artifact-name.sh
trusted-artifact.mjs
setup-node-pnpm/
action.yml
setup-test-app-dependencies/
action.yml
upload-agent-device-artifacts/
action.yml
FUNDING.yml
renovate.json
workflows/
android.yml
ci.yml
concurrency-torture-nightly.yml
conformance-differential.yml
conformance-regenerate.yml
deploy.yml
ios.yml
linux.yml
macos.yml
mutation-affected.yml
mutation-weekly.yml
perf-nightly.yml
pr-preview-cleanup.yml
pr-preview.yml
publish-mcp-registry.yml
release-android-snapshot-helper.yml
release-ios-runner.yml
replays-nightly.yml
size.yml
test-app-build-cache.yml
.gitignore
.oxfmtrc.json
.oxlintrc.json
.worktreeinclude
AGENTS.md
android/
ime-helper/
AndroidManifest.xml
README.md
res/
xml/
method.xml
src/
main/
java/
com/
callstack/
agentdevice/
imehelper/
TestInputMethodService.java
snapshot-helper/
AndroidManifest.xml
debug.keystore
README.md
src/
main/
java/
com/
callstack/
agentdevice/
snapshothelper/
AccessibilityCaptureStabilizer.java
AccessibilityTreeCapture.java
AccessibilityTreeXml.java
BoundedUiAutomationConnection.java
GestureViewportReader.java
HelperProtocol.java
PointerEventSchedule.java
SessionResponseWriter.java
SnapshotInstrumentation.java
TouchCommandHandler.java
TouchPlan.java
TouchPlanInjector.java
UiAutomationInputDispatcher.java
test/
java/
com/
callstack/
agentdevice/
snapshothelper/
AccessibilityCaptureStabilizerTest.java
BoundedUiAutomationConnectionTest.java
PointerEventScheduleTest.java
SnapshotHelperTestSuite.java
apple/
macos-helper/
Package.swift
Sources/
AgentDeviceMacOSHelper/
AudioProbe.swift
main.swift
SnapshotTraversal.swift
runner/
AgentDeviceRunner/
AgentDeviceRunner/
AgentDeviceRunner.xcodeproj/
project.pbxproj
project.xcworkspace/
contents.xcworkspacedata
xcshareddata/
xcschemes/
AgentDeviceRunner.xcscheme
AgentDeviceRunnerApp.m
AgentDeviceRunnerUITests/
AgentDeviceRunnerUITests.xctestplan
AgentDeviceRunnerUITests-Bridging-Header.h
AgentDeviceRunnerUITests.entitlements
RunnerAXSnapshotBridge.h
RunnerAXSnapshotBridge.m
RunnerObjCExceptionCatcher.h
RunnerObjCExceptionCatcher.m
RunnerSelectorMatchPolicy.swift
RunnerSynthesizedGesture.h
RunnerSynthesizedGesture.m
RunnerSynthesizedTextEntry.h
RunnerSynthesizedTextEntry.m
RunnerTapPointPolicy.swift
RunnerTests.swift
RunnerTests+Alert.swift
RunnerTests+AXSnapshotFallback.swift
RunnerTests+BlockingSystemModalResolution.swift
RunnerTests+CommandExecution.swift
RunnerTests+CommandJournal.swift
RunnerTests+Environment.swift
RunnerTests+Exceptions.swift
RunnerTests+FlatSnapshotFiltering.swift
RunnerTests+Interaction.swift
RunnerTests+Keyboard.swift
RunnerTests+Lifecycle.swift
RunnerTests+LifecycleCacheTests.swift
RunnerTests+Models.swift
RunnerTests+Navigation.swift
RunnerTests+Orientation.swift
RunnerTests+ScreenRecorder.swift
RunnerTests+ScrollGesture.swift
RunnerTests+SelectorMatchPolicyTests.swift
RunnerTests+SequenceExecution.swift
RunnerTests+Snapshot.swift
RunnerTests+SnapshotCapturePlan.swift
RunnerTests+SnapshotTraversalIdentityTests.swift
RunnerTests+SynthesizedGesturePolicy.swift
RunnerTests+SynthesizedTextEntry.swift
RunnerTests+SystemModal.swift
RunnerTests+TextEntry.swift
RunnerTests+TextEntryPolicyTests.swift
RunnerTests+TextTyping.swift
RunnerTests+Transport.swift
RunnerTests+TvRemote.swift
RunnerXCTestEventBridge.h
RunnerXCTestEventBridge.m
RecordingScripts/
recording-overlay.swift
recording-trim.swift
README.md
RUNNER_PROTOCOL.md
bin/
agent-device.mjs
CHANGELOG.md
CONTEXT.md
contracts/
fixtures/
tap-point-policy.json
CONTRIBUTING.md
docs/
adr/
0001-provider-first-integration-scenarios.md
0002-persistent-platform-helper-sessions.md
0003-daemon-command-registry.md
0004-ios-snapshot-backend-strategy.md
0005-ios-runner-interaction-lifecycle.md
0006-daemon-rpc-protocol-version.md
0007-remote-device-leases.md
0008-command-descriptor-registry.md
0009-apple-platform-consolidation.md
0010-error-system.md
0011-interaction-guarantee-contract.md
0012-interactive-replay.md
0013-unified-gesture-plans.md
0014-session-ref-frame-lifetime.md
0015-direct-maestro-engine.md
0016-active-session-script-publication.md
0017-parameterized-recorded-inputs.md
0018-unified-event-journal.md
0019-request-bound-platform-runtime.md
README.md
agents/
cli-flags.md
contract-projection-output-economy-spike.md
device-verification.md
domain.md
issue-tracker.md
oracle-negation-spike.md
pull-requests.md
testing.md
triage-labels.md
web-backend.md
dependency-graph-findings.md
ios-runner-protocol-optimizations.md
node-client-result-types.md
usbmux-runner-transport-experiment.md
examples/
README.md
sdk/
batch-orchestration.ts
client-session.ts
contracts-result.ts
metro-runtime.ts
tsconfig.json
test-app/
.gitignore
accessory-setup.config.json
app/
app.config.js
_layout.tsx
(tabs)/
_layout.tsx
audio.tsx
catalog.tsx
form.tsx
index.tsx
settings.tsx
accessory-setup.tsx
automation.tsx
inert.tsx
product/
[productId].tsx
webview.tsx
maestro/
checkout-form.yaml
helpers/
open-checkout-form.yaml
modules/
accessory-setup-lab/
expo-module.config.json
ios/
AccessorySetupLab.podspec
AccessorySetupLabModule.swift
push-broadcast-lab/
android/
build.gradle
src/
main/
AndroidManifest.xml
java/
expo/
modules/
pushbroadcastlab/
PushBroadcastLabModule.kt
PushBroadcastReceiver.kt
expo-module.config.json
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
replays/
checkout-form-android.ad
checkout-form.ad
drag-android.ad
drag.ad
gesture-lab-android.ad
gesture-lab.ad
src/
accessory-setup.ts
components.tsx
data.ts
lab-state.tsx
screens/
AccessorySetupScreen.tsx
AudioScreen.tsx
AutomationLabScreen.tsx
CatalogScreen.tsx
FormScreen.tsx
gesture-lab-dev-menu.ts
gesture-lab-styles.ts
GestureLab.tsx
HomeScreen.tsx
InertScreen.tsx
ProductScreen.tsx
SettingsScreen.tsx
WebViewScreen.tsx
theme.ts
webview-accessibility-fixture.ts
tsconfig.json
fallow-baselines/
dead-code.json
health.json
fallow-production-exports.json
glama.json
LICENSE
linux/
atspi-dump.py
mutation-baselines/
decision-kernels.json
package.json
packages/
ad-replay/
package.json
src/
index.ts
internal/
__tests__/
plan-digest.test.ts
resume.test.ts
step-loop.test.ts
target-verification.test.ts
canonical-json.ts
inspect.ts
plan-digest.ts
resume.ts
runtime-port-types.ts
step-loop.ts
target-verification.ts
verify-dispatch.ts
tsconfig.json
ad-script/
package.json
src/
index.ts
internal/
__tests__/
script.test.ts
target-annotation-classification.test.ts
target-annotation-identity.test.ts
target-annotation-serde.test.ts
vars.test.ts
open-script.ts
script-formatting.ts
script-utils.ts
script.ts
target-annotation-classification.ts
target-annotation-identity.ts
target-annotation-serde.ts
vars.ts
tsconfig.json
contracts/
package.json
src/
alert-contract.ts
android-input-ownership.ts
android-system-chrome.ts
app-events.ts
app-inventory.ts
app-state.ts
apple-multitouch-support.ts
audio-probe-result.ts
audio-probe-support.ts
back-mode.ts
batch-contract.ts
batch-step.ts
cli-flags.ts
click-button.ts
client-app.ts
client-capture.ts
client-connection.ts
client-device-view.ts
client-gesture.ts
client-lease.ts
client-observability.ts
client-replay.ts
client-request.ts
client-selector-read.ts
client-session.ts
client-settings.ts
client-system.ts
client-target.ts
clipboard.ts
cloud-artifacts.ts
command-flags.ts
companion-tunnel-scope.ts
debug-symbols.ts
device-inventory.test.ts
device-inventory.ts
device-provider.ts
device-rotation.test.ts
device-rotation.ts
device.ts
diff.ts
dispatched-command.ts
doctor.ts
facades/
... 1600 moreShowing a partial view of a very large repo.
More Flows by @callstackincubator.
@callstackincubatorVerifiedPlugin
Development
rozenite
Plug-and-play panels for React Native DevTools. Install, enable, and start debugging in minutes.
2 skills
@callstackincubatorFAQ
agent-device is a Claude Code plugin with 2 hand-picked skills for testing work, indexed on Flowy. Install it with the command on its page. It includes agent-device, dogfood. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is agent-device?
- Let your coding agent verify its changes in the running app. 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.
- How do I install agent-device?
- Run these in Claude Code: npx -y skills add callstackincubator/agent-device --agent claude-code. Then prompt normally.
- Does agent-device auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is agent-device free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.