callstack__agent-device/llms.txt

# agent-device

> Mobile app automation and verification for AI coding agents through a CLI, MCP server, and typed Node.js API.

## Docs

- [Introduction](/agent-device/docs/introduction.md): Learn what agent-device is, where it fits in agentic mobile, TV, desktop, and web development, and how agents use it for app verification, debugging, profiling, QA, and replay.

## Others

- [](/agent-device/404.md)
- [AI Agent Setup](/agent-device/docs/agent-setup.md): Configure Cursor, Codex, Claude Code, Windsurf, Cline, Goose, iOS Simulator and Android Emulator skills, and MCP for agent-device app verification.
- [AI SDK](/agent-device/docs/ai-sdk.md): Use agent-device/ai-sdk to give an AI SDK agent a typed set of tools for navigating and inspecting an app. The tools run in-process, share one named session, and default to the focused perceive-and-act surface most agents need. Make an iOS simulator or device available to agent-device, then configure an AI SDK model. String model IDs use AI Gateway by default: Alternatively, pass a model from your configured AI SDK provider. See the AI SDK guide to choosing a provider. Set AI_MODEL to a model available through your configured AI SDK provider. The agent sees the available device tools and chooses the calls needed to complete the prompt. The returned client targets the same session; keep cleanup in finally so the device is released even if generation fails.
- [AWS Device Farm](/agent-device/docs/aws-device-farm.md): Drive AWS Device Farm remote-access sessions with agent-device.
- [Batching](/agent-device/docs/batching.md): Use batch to run multiple commands in a single daemon request. This is useful for agent workflows that already know the next sequence of actions and want to reduce orchestration overhead.
- [BrowserStack](/agent-device/docs/browserstack.md): Drive BrowserStack App Automate sessions with agent-device.
- [Node.js API](/agent-device/docs/client-api.md): Use createAgentDeviceClient() for typed, deterministic device automation from Node.js instead of shelling out to the CLI. Building an agent? Start with the dedicated AI SDK or Eve integration.
- [Commands](/agent-device/docs/commands.md): This page summarizes the primary command groups. For persistent defaults and project-scoped CLI settings, see Configuration. For agent workflow guidance that is matched to the installed CLI, run: Skills are recommended for auto-routing when your agent runtime supports them, but they are not required. The CLI help topics are the version-matched operating contract. For MCP-aware clients that support direct tools, run: The MCP server exposes direct structured tools for installed commands. Tools use structured input contracts through AgentDeviceClient; local-only workflows stay CLI-only rather than subprocess fallbacks. It does not expose generic shell execution over MCP. MCP tools can target platform: "web" after agent-device web setup, but setup and doctor stay CLI-only.
- [Configuration](/agent-device/docs/configuration.md): Use configuration for persistent CLI defaults instead of repeating flags on every command. Repository configuration and operator-controlled configuration have different trust scopes.
- [Debugging & Profiling](/agent-device/docs/debugging-profiling.md): Use agent-device when the task moves past UI automation and you need runtime evidence from the app or device layer.
- [Device Clouds & Farms](/agent-device/docs/device-clouds.md): Choose a hosted device provider for agent and CI workflows.
- [Eve](/agent-device/docs/eve.md): Eve is Vercel's filesystem-first framework for durable agents. Files under agent/tools/ become typed model tools, which makes them a natural place to adapt the agent-device Node.js client. Create an Eve project, then add agent-device: Add agent/tools/agent_device.ts: Eve discovers the file automatically; no tool registry is required. Tell the agent how to use it in agent/instructions.md: For CI or another short-lived host, the outer runner should still close the named agent-device session in its own cleanup path. Model-directed close is useful during the normal tool loop, but it is not a replacement for deterministic cleanup after errors or cancellation.
- [Installation](/agent-device/docs/installation.md): Install agent-device for AI agent app automation, mobile testing, simulator and emulator workflows, desktop app verification, and version-matched CLI help.
- [Known Limitations](/agent-device/docs/known-limitations.md): Platform constraints that affect automation behavior.
- [Limrun](/agent-device/docs/limrun.md): Drive Limrun iOS simulators and Android emulators with agent-device.
- [Migrating Gestures](/agent-device/docs/migrating-gestures.md): agent-device 0.20.0 removed the timed forms of swipe, gesture fling, and gesture swipe, and the velocity argument of gesture rotate. Nothing is silently reinterpreted: every removed form now fails with an INVALID_ARGS error that names its replacement. This page is the migration for all four public surfaces — CLI, Node.js, MCP, and saved .ad recordings — plus the policy that governs the next such removal.
- [Quick Start](/agent-device/docs/quick-start.md): For client-specific setup in Cursor, Codex, Claude Code, Windsurf, Cline, Goose, and other coding agents, see AI Agent Setup. For a single text bundle that agents can ingest, use llms-full.txt. Every device automation follows this pattern: React Native dev or debug builds often show warning or error overlays that can intercept taps or hide the real UI state. Check for them near app open and after major transitions. If they are not the requested behavior, dismiss them and continue, but mention them in your summary if you saw them. Boot target if there is no ready device/simulator:
- [Remote Proxy](/agent-device/docs/remote-proxy.md): Run agent-device on a Mac with simulator or device access and control it from another machine through an HTTP tunnel.
- [Replay & E2E Testing](/agent-device/docs/replay-e2e.md): Agents use refs for exploration and authoring. Replay scripts are deterministic runs that can be used for E2E testing.
- [Security & Trust](/agent-device/docs/security-trust.md): Security and trust guidance for agent-device local app automation, device permissions, screenshots, recordings, logs, network dumps, audio probes, traces, and reports.
- [Selectors](/agent-device/docs/selectors.md): Use find to locate elements by semantic attributes instead of raw refs. Tips: Use find ... wait <timeoutMs> to wait for UI to appear.Combine with scoped snapshots using snapshot -s "<label>" for speed.[Android] If a matched node is not hittable, agent-device will click/focus the nearest hittable ancestor.Use fill when you want find-plus-targeted text replacement in one step. Use click or press plus type when you need append semantics in the focused field.
- [Sessions](/agent-device/docs/sessions.md): Sessions keep device state and snapshots consistent across commands. The implicit default session is scoped to the caller's git worktree or current working directory. Independent agents in different worktrees do not attach to each other's default session. When a session is established, human output includes a Session state: <path> line and JSON output includes sessionStateDir; this is the per-session artifact directory that can be inspected or removed after the run. JSON output also includes runnerLogPath and requestLogPath when available. Session artifact directories contain per-run evidence for concurrent agents: requests/<request-id>.ndjson - daemon request diagnostics for this session.events.ndjson - session event timeline for requests and recorded actions; rotates to events.ndjson.1 past 5 MB (AGENT_DEVICE_EVENT_LOG_MAX_BYTES, whole bytes), with events.ndjson.window.json recording each retained generation's first absolute line index, line count, and first-line digest so events cursors stay absolute and are verified against the files on disk.runner.log - Apple runner and xcodebuild build/start output for this session.app.log - app/device logs when logs start or logs clear --restart is active. events.ndjson is privacy-shaped for automation timelines. It preserves command names, status, durations, bounded device/app inventory previews, lifecycle outcomes, artifact basenames, and structural action details such as scroll distance/direction, safe refs, and coordinates. User-entered text, clipboard contents, push/event payloads, selector values, free-form flags/messages/paths, and raw unknown command arguments are omitted or replaced with content-free placeholders. --no-record suppresses recorded action entries; request start/finish entries still record command, status, and timing. The top-level daemon log is for daemon lifecycle/startup issues. Use the session artifact directory first when debugging a specific run. Open an explicitly named session only when you intentionally want a shared/reusable handle: Shut down the simulator/emulator on close (Apple simulators and Android emulators, prevents resource leakage in CI/multi-tenant workloads): A never-booted iOS Simulator can take several minutes to finish its first boot. Give open (or prepare ios-runner) a startup budget that covers it; the session's device claim is held from the first open onward, so a competing workspace sees DEVICE_IN_USE throughout: Notes: open <app> within an existing session switches the active app and updates the session bundle id.open <url> in iOS sessions opens deep links.open <app> <url> in iOS sessions opens deep links.On iOS devices, http(s):// URLs open in Safari when no app is active. Custom scheme URLs require an active app in the session.On iOS, appstate is session-scoped and requires a matching active session on the target device.For remote connect --remote-config sessions, see Commands.Use --session <name> for intentional named-session sharing. Do not parallelize mutating commands against the same session; serialize stateful actions such as open, press, fill, type, scroll, back, alert, replay, batch, and close. For replay scripts and deterministic E2E guidance, see Replay & E2E.
- [Snapshots](/agent-device/docs/snapshots.md): Snapshots provide a structured view of the UI and generate current-screen refs. --actions constraints: iOS simulators only. Physical iOS devices, macOS, and Android targets reject the flag.It names the affordances an element merged away (iOS UIAccessibilityCustomAction, React Native accessibilityActions), so a card whose reply/options controls are not separate elements still lists them.The names are for planning and discovery, not invocation. There is no API to trigger one: reach the affordance through the element's detail screen, through the same control exposed as a labeled element elsewhere, or by coordinates from its rect.Each merged element costs one accessibility round trip, so the pass is opt-in and bounded. When it cannot read every candidate, the response says how many it read — an absent list on an unread element is not evidence that it has none.Mutually exclusive with --raw. Custom actions are only readable through the private-AX capture path, which the raw diagnostic strategy does not take, so the pair is rejected as INVALID_ARGS before any device work — on the CLI, the Node client, and MCP alike. Choose one or the other.