[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74902":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":22,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":37,"readmeContent":38,"aiSummary":39,"trendingCount":16,"starSnapshotCount":16,"syncStatus":40,"lastSyncTime":41,"discoverSource":42},74902,"agent-device","callstackincubator\u002Fagent-device","callstackincubator","CLI to control iOS and Android devices for AI agents","https:\u002F\u002Fagent-device.dev",null,"TypeScript",2359,129,7,27,0,342,28.34,"MIT License",false,"main",true,[24,25,26,27,28,29,30,31,32,33,34,35,36],"adb","agentic-ai","agents","android-emulator","automation","e2e-testing","expo","ios-simulator","mcp","mobile","react-native","testing","xcuitest","2026-06-12 02:03:29","\u003Ca href=\"https:\u002F\u002Fwww.callstack.com\u002Fopen-source?utm_campaign=generic&utm_source=github&utm_medium=referral&utm_content=agent-device\" align=\"center\">\n  \u003Cpicture>\n    \u003Cimg alt=\"agent-device: device automation CLI for AI agents\" src=\"website\u002Fdocs\u002Fpublic\u002Fagent-device-banner.jpg\">\n  \u003C\u002Fpicture>\n\u003C\u002Fa>\n\n---\n\n# agent-device\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fagent-device.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fagent-device)\n[![CI](https:\u002F\u002Fgithub.com\u002Fcallstackincubator\u002Fagent-device\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fcallstackincubator\u002Fagent-device\u002Factions\u002Fworkflows\u002Fci.yml)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-black.svg)](LICENSE)\n\nDevice automation CLI for AI agents. Mobile, TV, and desktop apps.\n\n`agent-device` lets coding agents run real apps, inspect UI state, interact with visible elements, and collect debugging evidence through one CLI.\n\nIt is built around token-efficient accessibility snapshots, not pixel-first screenshots. Agents read compact UI trees, locate elements through refs like `@e3`, perform touch and text actions, and capture screenshots, video, logs, network, CPU\u002Fmemory\u002Fperf, crash-related logs, and React profiles only when evidence is needed.\n\nAgents can ingest the current docs from [llms-full.txt](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fllms-full.txt). The installed CLI help remains authoritative for exact command syntax.\n\n## Agentic QA And Development\n\n- **Quality Assurance**: dogfood flows, validate PR builds, check accessibility coverage, and turn stable explorations into `.ad` e2e tests.\n- **Development**: build from specs, inspect real runtime behavior, and iterate until the UI matches the work.\n\n`agent-device` closes the agentic development loop: agents can write code, run the real app, verify the UI end-to-end, collect screenshots\u002Fvideos\u002Flogs\u002Fperf evidence, and feed bugs, crashes, or performance findings back into the next fix iteration before a human reviews the PR.\n\n![Sketch showing agent-device as the live app verification layer in the agentic development loop](.\u002Fwebsite\u002Fdocs\u002Fpublic\u002Fagentic-development-loop.svg)\n\nIf you know Vercel's [agent-browser](https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser), this is the same idea for apps and devices.\n\nUse it for AI mobile testing, AI QA for React Native and Expo apps, iOS Simulator automation, Android Emulator automation, tvOS\u002FAndroid TV checks, and desktop app verification from coding agents. Humans install and configure `agent-device`; agents run the workflows.\n\n![agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt](.\u002Fwebsite\u002Fdocs\u002Fpublic\u002Fagent-device-contacts.gif)\n\nDemo: Codex uses `agent-device` to inspect iOS Contacts through accessibility snapshots, interact with visible UI, and create a contact from a simple prompt.\n\n## Quick Start\n\nInstall the CLI first:\n\n```bash\nnpm install -g agent-device@latest\nagent-device --version\nagent-device help workflow\n```\n\nThe CLI help is the source of truth for agents and is shipped with the installed version. Skills are optional but recommended when your agent runtime supports them: they auto-route device, React DevTools, and dogfood tasks to the right `agent-device help \u003Ctopic>` page and verify the CLI is new enough before acting.\n\nIf you install skills separately, keep the CLI on `agent-device >= 0.14.0`. Older CLIs do not include the workflow help topics that the router skills expect.\n\n### AI Agent Entry Points\n\n- **Agent + terminal**: in Cursor, Codex, Claude Code, Windsurf, and similar clients, run `agent-device` in the integrated terminal. Start planning with `agent-device help workflow`; CLI help is authoritative.\n- **Skills or rules**: install the skill with `npx skills add callstackincubator\u002Fagent-device`, use the bundled [agent-device skill](skills\u002Fagent-device\u002FSKILL.md), or mirror it as a thin project rule, so the agent checks the installed version and reads `agent-device help workflow` before acting. Use `agent-device help react-native` for React Native apps, overlays, Metro\u002FFast Refresh blockers, and routing to React DevTools or debugging evidence.\n- **MCP router**: use `agent-device mcp` when an MCP-aware client needs install, status, and version-matched help discovery. MCP is intentionally a thin router; device automation still runs through CLI commands.\n\nFor client-specific setup, see [AI Agent Setup](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Fagent-setup). For agent-readable docs, use [llms-full.txt](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fllms-full.txt).\n\n### MCP Router\n\n`agent-device` ships an official stdio MCP router for discovery-oriented clients. It exposes only `status`, `install`, and `help` tools plus workflow prompts\u002Fresources; it does not expose device automation or generic shell execution over MCP.\n\nPaste one of these into clients that accept `mcpServers`, such as Cursor project `.cursor\u002Fmcp.json` or user-level MCP settings.\n\n\u003Cdetails>\n\u003Csummary>Global install MCP config\u003C\u002Fsummary>\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-device\": {\n      \"command\": \"agent-device\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>No global install MCP config\u003C\u002Fsummary>\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-device\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agent-device@\u003Creviewed-version>\", \"mcp\"]\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\nRegistry metadata uses MCP name `io.github.callstackincubator\u002Fagent-device`, npm package `agent-device`, stdio transport, `mcpName` package verification, `server.json`, and `smithery.yaml`.\n\n```bash\nnpm install -g agent-device@latest\nagent-device --version\nagent-device help\n```\n\n`agent-device` performs a lightweight background upgrade check for interactive CLI runs and, when a newer package is available, suggests a global reinstall command. Updating the package also refreshes the bundled `skills\u002F` shipped with the CLI.\n\nPrerequisites: Node.js 22+, Xcode for iOS\u002FtvOS\u002FmacOS targets, Android SDK + ADB for Android, and macOS Accessibility permission for desktop automation. See [Installation](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Finstallation).\n\nTry the loop.\n\n```bash\n# Find the app.\nagent-device apps --platform ios\nagent-device apps --platform android\n\n# Start a session.\nagent-device open SampleApp --platform ios\n\n# Inspect the current screen. -i returns interactive elements only.\nagent-device snapshot -i\n# @e1 [heading] \"Settings\"\n# @e2 [button] \"Sign In\"\n# @e3 [text-field] \"Email\"\n\n# Act, capture a screenshot, and close.\nagent-device fill @e3 \"test\"\nagent-device screenshot .\u002Fartifacts\u002Fsettings.png\nagent-device close\n```\n\nSnapshots assign refs like `@e1`, `@e2`, and `@e3` to current-screen elements. Refs from the default snapshot are immediately actionable; for hidden content, scroll and re-snapshot.\n\n### First 5 Minutes: Expo Test App\n\nUse the bundled Expo fixture when you want a concrete first agent run with setup checks, screenshots, replay, and performance evidence. This path requires a repo checkout because `examples\u002Ftest-app` and the `pnpm test-app:*` scripts are not included in the published npm package.\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fcallstackincubator\u002Fagent-device.git\ncd agent-device\n```\n\nFirst terminal:\n\n```bash\npnpm test-app:install\ncd examples\u002Ftest-app\nnpx expo-doctor@latest\ncd ..\u002F..\npnpm test-app:ios\n# or: pnpm test-app:android\n```\n\nThen give your agent this prompt:\n\n```text\nUse agent-device to dogfood the bundled Expo app and produce an evidence-backed report.\n\nSetup:\n- Read `agent-device help workflow`, `agent-device help dogfood`, `agent-device help debugging`, and `agent-device help react-devtools` before planning commands.\n- Confirm the test app setup commands were run: `pnpm test-app:install`, `cd examples\u002Ftest-app && npx expo-doctor@latest`, then `pnpm test-app:ios` or `pnpm test-app:android`.\n- If Metro prints an Expo URL, prefer opening the shell with that URL. On iOS use `agent-device open \"Expo Go\" \u003Curl> --platform ios`; on Android use the visible Expo\u002Fdev-client target or URL. Confirm the app UI with `snapshot -i`.\n\nRun:\n- Create `.\u002Fdogfood-output\u002Fscreenshots`, `.\u002Fdogfood-output\u002Fvideos`, `.\u002Fdogfood-output\u002Ftraces`, `.\u002Fdogfood-output\u002Fperf`, and `.\u002Fdogfood-output\u002Freplays`.\n- Open a named session `expo-qa` and save a replay script to `.\u002Fdogfood-output\u002Freplays\u002Fexpo-test.ad`.\n- Use command shapes like `agent-device --session expo-qa open \"Expo Go\" \u003Curl> --platform ios --save-script .\u002Fdogfood-output\u002Freplays\u002Fexpo-test.ad`, `agent-device --session expo-qa screenshot .\u002Fdogfood-output\u002Fscreenshots\u002Fhome.png`, `agent-device --session expo-qa perf --json > .\u002Fdogfood-output\u002Fperf\u002Fbaseline.json`, and `agent-device --session expo-qa record start .\u002Fdogfood-output\u002Fvideos\u002Fcheckout.mp4`.\n- Capture a baseline `snapshot -i`, screenshot, and `perf --json` sample.\n- Exercise Home, Catalog, product detail, Checkout, and Settings. Re-snapshot after each mutation and use refs\u002Fselectors from fresh snapshots.\n- Capture at least one overlay-ref screenshot, one normal screenshot, one short video recording for a meaningful flow, logs marks around any issue, and trace output if a runtime symptom needs diagnostics.\n- Run focused performance checks: compare `perf --json` before and after a navigation or form flow; if React DevTools connects, use one bounded first-pass profile survey (`slow --limit 5`, `rerenders --limit 5`, and `timeline --limit 20` only when timing matters), then drill into a specific `@c` ref with `profile report`. If it cannot connect, include the status and continue.\n- Close the session so the `.ad` replay is written.\n\nReport:\n- Write `.\u002Fdogfood-output\u002Freport.md`.\n- Link every screenshot, video, trace, log path, replay file, and performance artifact you used.\n- Include setup results, platform\u002Fdevice, Expo doctor outcome, coverage, severity counts, findings with repro commands, and a short performance section summarizing startup\u002FCPU\u002Fmemory\u002Fframe-health or React profile findings.\n- If no issues are found, report covered flows and residual risk instead of claiming the app is bug-free.\n```\n\n## Where To Run agent-device\n\n| Path | Best for | Start with |\n| --- | --- | --- |\n| Local | Exploration, debugging, and development loops on simulators, emulators, physical devices, macOS apps, and Linux desktop targets. | Follow the Quick Start. |\n| CI\u002FCD | Automated PR and merge validation with replay scripts and captured artifacts. | Start with the [EAS workflow template](https:\u002F\u002Fgithub.com\u002Fcallstackincubator\u002Feas-agent-device\u002Fblob\u002Fmain\u002F.eas\u002Fworkflows\u002Fagent-qa-mobile.yml). GitHub Actions template coming soon. |\n| Cloud \u002F remote execution | Linux runners, managed devices, and remote execution. | Use [Agent Device Cloud](https:\u002F\u002Fagent-device.dev\u002Fcloud), see [Commands](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Fcommands) for remote profiles, or [contact Callstack](mailto:hello@callstack.com) for team-scale QA. |\n\n## Capabilities\n\n- **Platforms**: iOS, Android, tvOS, Android TV, macOS, and Linux. Real devices and simulators are supported.\n- **Agent-native UI model**: token-efficient accessibility snapshots, current-screen refs for exploration, selectors for durable replay, and skill-tested workflow guidance.\n- **Capture and debug**: screenshots, video, logs, network traffic, CPU\u002Fmemory\u002Fperformance data, crash-related logs, accessibility snapshots, and React render profiles.\n- **Produce**: replayable `.ad` scripts (recorded replay files that run locally or in CI), e2e test runs, snapshot and screenshot diffs, and debugging artifacts.\n- **React Native and Expo**: component tree inspection, props\u002Fstate\u002Fhooks, and render profiling.\n- **MCP boundary**: discovery and help over MCP; app\u002Fdevice control through the CLI for explicit, auditable commands.\n- **License**: MIT. Free to use.\n\n## How It Works\n\n`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. See [Introduction](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Fintroduction) and [Commands](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Fcommands) for platform details.\n\nNode consumers can use the typed client and public subpaths for bridge integrations. `agent-device\u002Fandroid-adb` exposes the Android ADB provider contract, logcat\u002Fclipboard\u002Fkeyboard\u002Fapp helpers, and port reverse management.\n\n## Used By\n\nUsed by teams and developers at Callstack, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow, and more.\n\n## Documentation\n\n- [Installation](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Finstallation)\n- [AI Agent Setup](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Fagent-setup)\n- [Typed Client](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Fclient-api)\n- [Commands](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Fcommands)\n- [Replay & E2E](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Freplay-e2e)\n- [Security & Trust](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Fsecurity-trust)\n- [Known limitations](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fdocs\u002Fknown-limitations)\n- [llms-full.txt](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002Fllms-full.txt)\n\nAgent integration:\n\n- [agent-device skill](skills\u002Fagent-device\u002FSKILL.md)\n- [dogfood skill](skills\u002Fdogfood\u002FSKILL.md)\n- MCP router: `agent-device mcp`\n- [agent-device skill on ClawHub](https:\u002F\u002Fclawhub.ai\u002Fokwasniewski\u002Fagent-device)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Made at Callstack\n\nagent-device is open source and MIT licensed. Visit [agent-device.dev](https:\u002F\u002Fagent-device.dev\u002F), try the [EAS workflow template](https:\u002F\u002Fgithub.com\u002Fcallstackincubator\u002Feas-agent-device\u002Fblob\u002Fmain\u002F.eas\u002Fworkflows\u002Fagent-qa-mobile.yml), read the [incubator docs](https:\u002F\u002Fincubator.callstack.com\u002Fagent-device\u002F), or contact us at hello@callstack.com.\n","`agent-device` 是一个用于控制iOS和Android设备的CLI工具，专为AI代理设计。它支持移动、电视及桌面应用的自动化测试与开发。核心功能包括通过紧凑的UI树进行界面状态检查、元素交互以及调试证据收集（如截图、视频、日志等），而无需依赖像素级截图。该工具基于TypeScript构建，具备高效率的无障碍快照技术，允许AI代理执行触摸、文本输入等操作，并在必要时捕获性能数据或崩溃日志。适用于需要自动化质量保证流程的场景，比如React Native和Expo应用的AI QA、iOS模拟器与Android模拟器的自动化测试、智能电视软件验证等。开发者可以利用`agent-device`来加速从代码编写到真实环境验证的整个闭环过程。",2,"2026-06-01 03:42:11","high_star"]