agent-deviceby CallstackGet started

Give your agent eyes and hands. On the real app.

agent-device lets coding agents run, read and operate real iOS, Android, TV and desktop apps. Ask for a change, and your agent builds it, checks it on the device and brings back evidence you can review.

Get started
npm i -g agent-device
agent-devicezsh
$ npm i -g agent-device
# for you: the CLI and the MCP server
$ npx skills add callstack/agent-device
# for your agent: the skill
You

Implement the onboarding screen, run it on the iOS simulator and Android emulator, and attach screenshots.

  1. agent-deviceopen MyApp --platform ios
  2. agent-devicesnapshot -i
  3. agent-devicescreenshot ./onboarding-ios.png
  4. agent-deviceopen MyApp --platform android
  5. agent-devicesnapshot -i
  6. agent-devicescreenshot ./onboarding-android.png
  7. agent-deviceclose

Works with iOS, Android, HarmonyOS, tvOS, Android TV, Fire TV, Vega OS, macOS, Linux, Web, React Native, Expo, Flutter.

Used by teams at

See how they use it 1M+npm downloads in the last 30 days

[01] Why agent-device

Agents write the code now. Verification is what slows shipping.

Coding agents turn out changes faster than anyone can check them on a phone. A mobile change only proves itself on a simulator or a device, and that is the one place agents could not go.

So the checking falls back on people: review rounds to ask whether it was run, QA passes on test builds, regressions found by users. agent-device moves that check to the agent, with evidence attached.

[02] The loop

Where agent-device fits in shipping with agents.

The same loop runs on every change. agent-device is the step where the agent checks its work on the real app, and leaves proof for the people who ship it.

  1. 01

    Task

    You, or an issue, describe the change.

  2. 02

    Code

    The agent writes and reviews the change.

  3. 03

    Verify

    The agent runs the app, checks the change on the device and records what it saw.

    agent-device
  4. 06

    Feedback

    Crashes, bugs and slow screens come back as the next task, with a repro.

    agent-device
  5. 05

    Review and ship

    People review proof instead of a description, and merge.

  6. 04

    Evidence

    Screenshots, video, logs and a replay script land on the pull request.

    agent-device

[03] While the agent builds

It checks its own work. Before you see it.

Ask for a change and the agent runs it on the simulator, reads the screen, taps through the flow and fixes what it finds. You get a change that already ran, and fewer rounds of review.

An agent skill reproduces each bug, records before and after video, replays an .ad script, measures Sentry spans and profiles React renders, as evidence on the pull request.

Read the case study
Set up your agent
Pull requestVerified on the device
  • Screenshotcontact-form.pngscreenshot
  • Videorecording.mp4record stop
  • Replaycontacts.ad--save-script

[04] On every pull request

Verification that runs itself. On every pull request.

Save a run that worked as an .ad script and replay it in CI with no model in the loop, or run a QA agent against each build. Reviewers get screenshots, logs and a JUnit report, on simulators or hosted devices.

Start fromThe EAS Workflows QA agent template
Replay and E2E testing
agent-devicecheckout-form.ad
context platform=ios timeout=60000
env APP_TARGET="Agent Device Tester"
open "${APP_TARGET}" --relaunch
click "label=\"Form\""
fill id="field-name" "Ada Lovelace"
fill id="field-email" "ada@example.com"
click id="submit-order"
wait "Order summary" 5000
CIagent-device test ./workflows --reporter junit:./tmp/junit.xml

[05] From production back to the agent

When something breaks, the agent brings a repro.

Hand the agent the crash or the slow screen. It reproduces it on the device, captures the logs and network from that moment, and profiles the renders, so the fix starts from evidence.

Debugging and profiling

React profile 8.3s: 8 commits, 1303ms rendering, 8 over 16ms (worst #6 188ms)

memo-defeatedContactRow

memo bypassed on 480/480 updates; new highlight (object) 480x, onSelect (function) 480x from ContactList

Fix wrap those props in useCallback/useMemo in ContactList

[06] Who uses it

In their repos, on their apps.

  1. An agent skill reproduces each bug, records before and after video, replays an .ad script, measures Sentry spans and profiles React renders, as evidence on the pull request.

  2. Simulator and emulator support in T3 Code is built on agent-device.

  3. The mobile engine of the e2e testing agent, @e2e-dev/mobile, runs on agent-device.

All 16 teams and projects

[07] Run anywhere

Same commands. Any device, anywhere.

Your agent keeps the same agent-device workflow when it leaves your laptop: replay in CI, run from Linux against a Mac that hosts the simulators, or drive hosted devices in a device cloud.

  1. 01

    On your machine

    Simulators, emulators and physical devices on your Mac or Linux box. Sessions follow your git worktree, so parallel agents don’t take over each other’s devices.

    agent-device open MyApp --platform ios
  2. 02

    On every pull request

    Replay saved .ad scripts with agent-device test, keep screenshots and logs as artifacts, and report to JUnit.

    agent-device test ./workflows
  3. 03

    On a device host

    Run the agent on Linux or in a cloud workspace and execute on the Mac or Linux host that has the devices, through the remote proxy.

    agent-device proxy --port 4310
  4. 04

    On hosted devices

    The same commands drive BrowserStack, AWS Device Farm, TestMu AI and Limrun devices through provider plugins.

    agent-device connect limrun --platform ios
Run agent-device anywhere

[08] Watch and learn

Closing the loop, from the people building it.

[09] FAQ

Frequently asked questions

Is there an MCP server?
Yes. agent-device mcp starts the official stdio MCP server. It is one entry point to the same runtime as the CLI and the typed Node.js API, so sessions, evidence and replay behave the same in all three.
Does it work with React Native, Expo, Flutter and native apps?
Yes. It drives native iOS and Android apps and React Native, Expo and Flutter apps on supported targets. The commands and evidence vary by target; agent-device capabilities --platform lists them.
How is it different from Appium, Detox or Maestro?
With agent-device an agent reads the app and chooses each command at run time. Appium, Detox and Maestro run suites people write and maintain. agent-device complements them: save a run as an .ad script or export it as strict Maestro YAML.
Can it run in CI?
Yes. Record a run as an .ad script, replay it in CI with agent-device test, and keep the screenshots and logs as artifacts. The EAS Workflows template is a working example.
Can I build my own agent or QA product on it?
Yes. The typed Node.js client is a public surface over the same runtime, with AI SDK tools and an Eve integration on top. TesterArmy e2e and T3 Code build on it.
Can several agents share one machine?
Yes. Sessions are scoped to the git worktree, and device claims stop parallel agents from taking over each other’s simulators and emulators. agent-device device status shows who holds what.

Read more

Get started