Sessions

    Sessions keep device state and snapshots consistent across commands.

    agent-device open Settings --platform ios
agent-device session list
agent-device open Contacts          # change app in this workspace's default session
agent-device close

    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:

    agent-device open Contacts --platform ios --session my-session
agent-device snapshot -i
agent-device close --session my-session

    Shut down the simulator/emulator on close (Apple simulators and Android emulators, prevents resource leakage in CI/multi-tenant workloads):

    agent-device close --shutdown

    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.

    Need React or React Native expertise you can count on?

    Let's talk