Argent

Block until the screen has rendered content and stopped changing, or a timeout elapses. Polls the same accessibility / DOM tree as `describe` every pollIntervalMs (default 200ms) until it has content and that content holds identical for minStableMs (default 250ms), or timeoutMs (default 3000ms) is reached. Returns { settled, waitedMs, polls } — settled=false means the screen never went still before the timeout. Use after a launch/navigation to wait for the UI to render before screenshotting or tapping.

Block until a UI element reaches an expected state or a timeout elapses, so you don't have to poll screenshot/describe yourself. Conditions: exists — the selector matches an element anywhere in the tree. visible — the selector matches an element with a non-zero on-screen frame. hidden — the selector matches nothing, or only a zero-area element (e.g. a spinner that disappeared). text — the first VISIBLE match in reading order (topmost, then leftmost; falling back to the first match overall if none is visible) contains expectedText (case-insensitive substring), or exactly matches it when textMatch is `equals`. A loose selector can match several elements; only that one is inspected, so if a different match is the one holding the text the wait still reports failure — narrow the selector to target it. The selector is { text?, identifier?, role? }; every provided field must match. text and role match as case-insensitive substrings of the element's label/value and role; identifier matches exactly (case-insensitive), also accepting the unqualified Android resource-id name ('submit' matches 'com.example.app:id/submit'). It polls the same accessibility / DOM tree as `describe` (iOS AXRuntime, Android uiautomator, Chromium CDP, Vega automation toolkit) every pollIntervalMs (default 400ms) until timeoutMs (default 5000ms). Returns { success: boolean, elapsed: number } — success=false means the condition never held before the timeout (a `note` then explains what was seen). Use this after a tap/navigation to wait for the next screen, or before tapping an element that appears asynchronously.

Start an iOS simulator, launch an Android emulator, start a Vega (Fire TV) Virtual Device, or spawn an Electron app and wait until it is ready to accept interactions. Pick the platform by which argument you pass: 'udid' for an iOS simulator from list-devices, 'avdName' for an Android AVD (a serial is assigned automatically), 'vvdImage' for a Vega VVD (the 'vvdImage' of a vega device from list-devices, e.g. 'tv'), or 'electronAppPath' for an Electron app (a CDP remote-debugging port is picked automatically, or pass 'electronPort' to fix one). Use at the start of a session once you have picked a target. Returns a tagged payload: { platform: 'ios', udid, booted } or { platform: 'android', serial, avdName, booted } or { platform: 'vega', serial, vvdImage, booted } or { platform: 'chromium', id, port, pid, booted } (an Electron app boots as a Chromium/CDP device). Android boots take 2–10 minutes depending on machine and cold/warm state; the tool transparently hot-boots from the AVD's default_boot snapshot when usable and falls back to cold boot otherwise. Vega starts the single SDK-managed VVD via the vega CLI (~10s) and returns once it reports running. If an Android/Electron boot stage fails, the tool terminates the device it spawned so the next retry starts clean.

Press a device hardware button (iOS simulator, Android emulator or device). iOS sends a Down then Up event automatically; Android injects a single `adb` key event. Supported buttons depend on the platform: home, back, power, volumeUp, volumeDown, appSwitch, actionButton — buttons not present on the target platform (e.g. 'back' on iOS, 'actionButton' on Android) are rejected with a clear error. Use when you need to trigger hardware button events. Returns { pressed: buttonName }. Fails if the device backend is not reachable — the simulator-server for iOS, or `adb` for Android (Android presses are injected with `adb shell input keyevent`).

Read and write cookies of a Chromium (CDP) app (via the Network domain, so HttpOnly cookies are included). - action="get" (url?): list cookies, optionally restricted to given URLs (defaults to the active page). - action="set" (name, value, + url OR domain, optional path/secure/httpOnly/sameSite/expires): create or update a cookie. - action="delete" (name, + url/domain/path): remove a matching cookie. - action="clear": remove ALL browser cookies. Use when seeding an authenticated session before a flow (set the session cookie, then navigate) or asserting cookie state after one. Returns { cookies, count } for get, or a small status object ({ set } / { deleted } / { cleared }) otherwise. Fails if the device is not a Chromium (CDP) device, or set is missing name/value. Chromium-only.

Read and write localStorage / sessionStorage of a Chromium (CDP) app's active page. - action="get": with `key`, returns that value; without `key`, returns all entries. - action="set" (key, value): write an entry. - action="remove" (key): delete an entry. - action="clear": empty the store. Set `store` to "local" or "session". Storage is per-origin, so it reflects the active tab's document. Use when seeding feature flags / auth tokens before a flow or asserting persisted app state after one. Returns { value } for a single key, { entries, count } for all, or a status object ({ set } / { removed } / { cleared }) otherwise. Fails if the device is not a Chromium (CDP) device, or set is missing key/value. Chromium-only.

List and switch the tabs / windows of a Chromium (CDP) app (an Electron app's BrowserWindows or a Chromium browser's tabs), and open or close them. - action="list": enumerate page targets with stable ids (`t1`, `t2`, …), title, url, and which is active. - action="select" (tab=<tabId|label>): make that tab the active one. The active tab is what describe / gesture-tap / screenshot / debugger-evaluate / open-url all operate on, so switch before driving a different tab. - action="new" (url?, label?): open a new tab/page and activate it. - action="close" (tab?=<tabId|label>): close a tab (defaults to the active one); if the active tab is closed, another live tab becomes active. Use when an app exposes multiple windows or tabs and you need to inspect or drive one other than the current page, or to open/close a page during a flow. tabIds are stable for the session and never reused. Returns { tabs: [{ tabId, targetId, title, url, active, label? }] }. Fails if the device is not a Chromium (CDP) device, or the requested tabId/label no longer matches a live tab. Chromium-only.

Fetch the current screen of a running React Native app as a compact component text tree. Only shows on-screen components with unique positions — off-screen (scrolled) content, full-screen transparent wrappers, and implementation-detail components are pruned. Each visible component is listed with its name, text content, and normalized tap coordinates in [0,1] space (fractions of the screen, not pixels — same space as tap/swipe/gesture). This is the preferred element discovery tool for React Native apps. More information in argent-react-native-app-workflow skill. Workflow: 1. Call this tool to get the component tree. 2. Find the desired element by name, text, testID, or accessibilityLabel. 3. Use the (tap: x,y) coordinates directly with the tap tool. Call again after navigation or state changes since positions may shift. Set includeSkipped=true to see a summary of all filtered components. Use when you need tap coordinates for a React Native UI element. Returns a compact text tree with (tap: x,y) coords. Fails if Metro debugger is not connected.

Connect to a JS runtime CDP debugger. iOS / Android / Vega: connects to Metro's CDP endpoint on the given port. Chromium: re-uses the page CDP session opened by boot-device — port is ignored. Returns connection info including port, projectRoot (empty on Chromium and on legacy Metro, e.g. Vega), deviceName, appName, logicalDeviceId (absent on Vega), and isNewDebugger. If already connected, returns the existing connection. Use when starting a debug session or before calling other debugger-* tools. Fails if the runtime is unreachable (Metro down, or Chromium CDP terminated).

Execute arbitrary JavaScript in the app's JS runtime via CDP — Hermes on iOS / Android / Vega, V8 on Chromium. Returns the evaluation result as a JSON-serializable value, along with deviceName, appName, and logicalDeviceId for context. Use when you need to read app state, call app functions, or test logic at runtime. The result is serialized by value, so cyclic objects (many RN runtime values — fiber nodes, navigation refs, global — are cyclic) fail with a serialization error rather than returning silently. Fails if the expression throws or the runtime is not connected.

Inspect the React component hierarchy at a screen coordinate (x, y). Returns components from the tapped element upward through its parent hierarchy, each with its source file:line and a code fragment. The first items (lowest indices) are the most specific — the exact component under the tap point and its direct parents. Higher indices are broader context (page, navigator). Default shows 35 items which covers all app-specific code; use maxItems=70+ to also see the navigation/screen structure. Uses getInspectorDataForViewAtPoint + _debugStack + Metro /symbolicate. Set resolveSourceMaps to false to skip symbolication and get raw bundled locations instead. Set includeSkipped=true to see filtered items annotated with skip reasons. Use when you need the source file and line for a component at a tap coordinate. Fails if the app is not connected or the coordinate is outside the screen.

Get a summary of all console logs captured from the app's JS runtime. Returns the log file path, entry counts by level, and message clusters (grouped by similarity). Works against Hermes (iOS / Android / Vega) and V8 (Chromium). Use when investigating warnings, errors, or unexpected output — call this first for an overview, then read the returned file for details. Returns empty stats if no log data has been captured yet.

Restart the Metro JS bundle in the connected React Native app without restarting the native process. Use when you want to apply code changes or reset JS state. Returns { reloaded, port, method, deviceName, appName, logicalDeviceId } indicating which reload path was used and which device/app was targeted. Fails if Metro is not running on the given port.

Get JS runtime debugger connection status and diagnostic info. Use when you need to verify connectivity before using other debugger tools. Returns port, projectRoot (empty on Chromium and on legacy Metro, e.g. Vega), deviceName, appName, logicalDeviceId (absent on Vega), isNewDebugger (false on the legacy inspector), connected flag, loadedScripts count, and sourceMapReady (always true — waits for pending source maps before returning; no-op on Chromium). Fails if the runtime is unreachable.

Get the accessibility / DOM element tree for the current screen. On iOS, uses the AXRuntime accessibility service to inspect whatever is currently visible — including system dialogs, permission prompts, and any foreground app content. On Android, runs `uiautomator dump`. On Chromium, walks the renderer's DOM via Chrome DevTools Protocol — every visible element with its ARIA role, accessible name, and bounding rect (normalized to 0–1). On Vega (Fire TV), reads the on-device automation toolkit (`getPageSource`); each element carries `[focused]`/`[selected]` so you can see where the D-pad cursor is, then move it with the `tv-remote` tool (Vega is remote-driven, not touch). If describe returns an empty tree on Vega, relaunch the foreground app (the toolkit attaches at launch) and try again. When a system dialog is visible, describe returns the dialog's interactive elements (buttons, text) with tap coordinates. When no dialog is present, it returns the foreground app's accessible elements. Returns `{ description, source }` where `description` is a text rendering of the UI tree — one line per element with its role, label/value/id, interactivity flags, and frame. Frame coordinates are normalized [0,1] fractions of the screen / window width/height (not pixels) — the same space as gesture-tap / gesture-swipe / gesture-pinch. To tap an element use the centre of its frame: `tap_x = frame.x + frame.width / 2`, `tap_y = frame.y + frame.height / 2`. The same formula appears in the response header so it can be applied to a line in isolation. For app-scoped inspection with full UIKit properties (accessibilityIdentifier, viewClassName), use native-describe-screen with an explicit bundleId instead (iOS only). For React Native apps, debugger-component-tree returns React component names with tap coordinates. On a TV target (Apple TV / Android TV — a `list-devices` entry with runtimeKind 'tv') this returns the focus-driven view instead: the currently FOCUSED element and the list o…

Clear the Argent update notification for the given number of hours. Use when the user asks to postpone or silence update reminders. Returns { message } confirming the suppression duration. Fails if the hours value is negative or the suppression state cannot be persisted.

Record an echo step in the active flow. Echo steps print a message when the flow is replayed — useful as labels between tool calls. Use when you want to annotate a recorded flow with a human-readable label or checkpoint message. Returns { message, flowFile }. Fails if no active flow recording is in progress.

Execute a tool call and record it as a step in the active flow. Use when recording a flow with flow-start-recording and you want to run and capture each action. A coordinate `gesture-tap` is recorded as a portable `tap: { selector }` step when the tapped element has stable text/identifier (otherwise coordinates are kept with a warning); a `restart-app` is recorded as a `launch` step (record one FIRST to make the flow a self-contained e2e flow). Returns { message, toolResult, flowFile } on success. If it fails an error is returned and nothing is recorded. If a step was recorded by mistake, edit the .yaml file directly to remove it.

Run a saved flow from the .argent/flows/ directory, or an explicit boundary-managed flow_path. Steps run in order: `launch` starts an app from scratch (terminate + relaunch) and waits until it is ready; `tool` calls dispatch through the registry; `tap`/`long-press`/`type` resolve a selector to an element and act on it (`tap: { on, times: 2 }` double-taps; `long-press: { on, duration }` presses and holds; `tap`/`long-press` alternatively take a raw normalized point — bare `{ x, y }` or `on: { x, y }`; any selector may scope its matches geometrically, the CSS combinators read off frames: `within: <selector>` (descendant — inside that container's frame), `after: <selector>` (CSS `~` — following it in reading order), `next: <selector>` (CSS `+` — the nearest such follower, which unlike CSS reaches past a non-matching neighbour rather than failing), plus `any: true` (CSS `*` — legal only WITH a scope and never beside text/id/role). Scopes nest to disambiguate — `within: { id: card, within: { id: list } }` reads "inside card inside list", each container's frame inside the next); `scroll-to` scrolls (momentum-free) until a target is visible; `pinch` zooms (`pinch: { on?, scale }` — scale > 1 in, < 1 out; screen center when `on` is omitted); `rotate` is the two-finger rotation gesture (`rotate: { on?, by }` — degrees, + clockwise, within ±3000°; screen center when `on` is omitted; distinct from the `rotate` tool, which changes device orientation); `await` waits for a UI condition; `wait` pauses for a fixed number of milliseconds; `assert` checks one now; `snapshot` diffs a screenshot — or, with `cropOn: <selector>`, one element's cropped region — against a stored baseline (a missing baseline fails the step — set updateBaselines to adopt the current screen; a cropped element whose size drifted fails on dimensions); `echo` annotates; `run` executes another flow inline — a YAML path resolved against the directory of the flow file that references it (co-located runs only). A `…

Finish recording the active flow. Returns a summary of all recorded steps and the final YAML content. Use when you have added all desired steps and want to finalize the flow file. Fails if no active flow recording is in progress. You can still edit the .yaml file directly afterwards to remove or reorder steps.

Read the execution prerequisite of a flow without running it — a saved flow from the .argent/flows/ directory, or an explicit boundary-managed flow_path. Returns the prerequisite description so you can verify the required state is met before calling flow-execute. Use when you need to check what app/simulator state is required before executing a flow; pass the same flow source (name or flow_path) you will pass to flow-execute, so the prerequisite you read is the contract of the flow that will actually run. Fails if the flow file does not exist.

Start recording a new flow. Creates a .yaml file in the .argent/flows/ directory. Use when you want to capture a reusable sequence of device interactions for later replay. Returns { message, flowFile, savedTo } and optionally { previousFlow } if a prior recording was abandoned. Fails if the .argent/flows/ directory cannot be created or the flow file cannot be written. After starting, use flow-add-step to append tool calls — each step is executed LIVE so you can verify it works before it gets recorded. For a self-contained e2e flow, record a restart-app of the app under test as the FIRST step (captured as the flow's `launch` step); for a reusable fragment, skip that and pass executionPrerequisite instead. Use flow-add-echo to add labels. Call flow-finish-recording when done. If a recorded step turns out to be wrong, you can edit the .yaml file directly to remove or reorder steps.

Fetch a structured snapshot of a mobile app project's workspace. Returns package.json contents, metro/babel config text, app.json, eas.json, tsconfig, platform directory presence (ios/, android/), presence of android/gradlew (android_has_gradle), iOS .xcworkspace name and Podfile presence, lockfile type, .env file keys (no values), installed CLI tool versions, scripts/ directory listing, husky hooks, CI config type, Makefile targets, lint-staged config, and a list of detected config files. DO NOT RUN THIS TOOL IF YOU ARE THE MAIN AGENT AND THIS TASK CAN BE DELEGATED TO A SUBAGENT. If you are a subagent tasked with exploring the project environment, run this as the first step. The snapshot provides the raw data needed to determine the project type (React Native, Expo, Flutter, native iOS/Android, or other), build commands, startup scripts, platform support, package manager, and QA tooling. Follow up with Read/Glob/Grep for deeper exploration of anything the snapshot surfaces. Use when you need to inspect project configuration without manually reading multiple files. Returns partial data if workspacePath does not exist or is not readable; missing items are represented as null or empty collections. Fails if the workspacePath is not an absolute path or the directory cannot be accessed.

Send a sequence of touch events for complex gestures. Use for: long press, drag-and-drop, custom scroll, pinch (second touch point). For simple taps use the gesture-tap tool. For straight-line scrolling use the gesture-swipe tool. For pinch gestures use gesture-pinch. For rotation gestures use gesture-rotate. All x/y values are normalized 0.0–1.0 (screen fractions, not pixels). delayMs controls the delay before each event (default 16ms ≈ 60fps). Set interpolate to auto-generate smooth intermediate Move events between your keyframes. Returns { events: number } with the total count of events dispatched. Fails if the target device is not booted or an event type is invalid. Example long-press at center: [{"type":"Down","x":0.5,"y":0.5},{"type":"Up","x":0.5,"y":0.5,"delayMs":800}] Example smooth scroll down: [{"type":"Down","x":0.5,"y":0.7}, {"type":"Move","x":0.5,"y":0.6},{"type":"Move","x":0.5,"y":0.5},{"type":"Move","x":0.5,"y":0.4}, {"type":"Up","x":0.5,"y":0.3}] Example pinch-to-zoom (with interpolate:10 for smoothness): events: [{"type":"Down","x":0.4,"y":0.5,"x2":0.6,"y2":0.5}, {"type":"Up","x":0.2,"y":0.5,"x2":0.8,"y2":0.5}] interpolate: 10

Press the left mouse button at a start point, move to an end point, and release — a desktop mouse drag in a Chromium app. All positions are normalized 0.0–1.0 (fractions of the window, not pixels), same coordinate space as gesture-tap and describe. Interpolates mouse-move events at ~60fps over durationMs for a natural drag. Use for slider thumbs, drag-and-drop, text selection, or draggable UI elements. Dragging never scrolls content on desktop — use gesture-scroll for lists/pages. Chromium only — on iOS/Android use gesture-swipe. Returns { dragged: true, timestampMs }. Fails if the Chromium CDP session is not reachable for the given device.

Execute a pinch-to-zoom gesture by moving two fingers toward or away from a center point to change the scale of on-screen content. All positions and distances are normalized 0.0–1.0 (fractions of screen width/height, not pixels)—same coordinate space as gesture-tap and gesture-swipe. startDistance > endDistance = pinch in (zoom out). startDistance < endDistance = pinch out (zoom in). Typical values: startDistance 0.2, endDistance 0.6 for a zoom-in pinch at screen center. Auto-generates interpolated frames at ~60fps. The angle parameter controls the axis (0 = horizontal, 90 = vertical). Optional endCenterX/endCenterY drift the centroid linearly over the gesture (omitted = fixed center). Use when you need to zoom in or out on a map, image, or zoomable view. Returns { pinched: true, timestampMs }. Fails if the simulator-server / emulator backend is not reachable for the given device.

Send a two-finger circular arc gesture to rotate on-screen content by a specified angle. Two fingers are placed opposite each other at a fixed radius from the center, then swept from startAngle to endAngle degrees. All positions and radii are normalized 0.0–1.0 (fractions of screen width/height, not pixels)—same coordinate space as gesture-tap and gesture-swipe. endAngle > startAngle = clockwise rotation. Typical values: radius 0.15, startAngle 0, endAngle 90 for a 90° clockwise turn. A single radius applies to both axes, so on a non-square screen it traces a physical ellipse (finger separation varies through the turn); pass radiusX+radiusY (fractions of width/height with radiusX·width = radiusY·height) for a physically circular orbit instead. Auto-generates interpolated frames at ~60fps. Unlike gesture-pinch which moves fingers linearly to zoom, this orbits fingers in an arc to change orientation. Use when you need to rotate a map, image picker, or any rotateable UI element. Returns { rotated: true, timestampMs }. Fails if the simulator-server / emulator backend is not reachable for the given device.

Scroll content in a Chromium app by dispatching mouse-wheel events at a point. Anchor x/y are normalized 0.0–1.0 (fractions of the window, not pixels), same coordinate space as gesture-tap and describe. Deltas are fractions of the window too: deltaY 0.5 scrolls down half a window; negative scrolls back up. Use when content is below/above the fold (describe shows off-screen elements with zero height) or a list needs scrolling. Chromium only — on iOS/Android use gesture-swipe. Returns { scrolled: true, timestampMs }. Fails if the Chromium CDP session is not reachable for the given device.

Execute a smooth swipe / drag touch gesture between two points on the device (iOS simulator or Android emulator). All from/to positions are normalized 0.0–1.0 (fractions of screen width/height, not pixels), same as gesture-tap. Generates interpolated Move events for a natural feel (~60fps). Swipe up (fromY > toY) to scroll content down. Use when you need to scroll a list, dismiss a modal, drag an element, or navigate between pages. Not supported on Chromium — use gesture-scroll there instead. Pass settle:true for a momentum-free swipe that lands exactly where the finger lifts (no fling), when you need a deterministic scroll distance. Returns { swiped: true, timestampMs }. Fails if the simulator-server / emulator backend is not reachable for the given device.

Press the device screen (iOS simulator, Android emulator, or Chromium app) at normalized coordinates: x and y are fractions of screen width and height in 0.0–1.0 (not pixels). Sends a Down event followed by an Up event at the same point. For Chromium, this dispatches a CDP mouse-press/release on the renderer. Set clickCount: 2 for a double-tap / double-click — the taps are dispatched as one gesture with proper click counting, which two separate tap calls cannot guarantee. Use when you need to tap a button, link, or any tappable element on the screen. Returns { tapped: true, timestampMs }. Fails if the simulator-server / emulator backend / Chromium CDP is not reachable for the given device. Before tapping, determine the correct coordinates by using discovery tools — pick by platform: iOS / Android use `describe`, `native-describe-screen`, or `debugger-component-tree`; Chromium uses `describe` (the DOM walker), since the native and RN-specific discovery tools don't apply. More information in `argent-device-interact` skill

Type text or press special keys on the device (iOS simulator, Android emulator or device, Chromium app, Vega Virtual Device, or Apple TV / Android TV) using keyboard events. Use when you need to enter text or trigger a named key such as enter, escape, or arrow keys. On Vega and Apple TV / Android TV, prefer the remote tools for D-pad navigation; use keyboard to type into a focused text field (e.g. a search or login box). Returns { typed: string, keys: number }. Fails if an unsupported key name is provided or the device's input backend is not reachable. - text: types a string (supports uppercase, digits, common punctuation). To type a credential, use `{{secret:<NAME>}}` — resolved server-side from the `ARGENT_SECRET_<NAME>` env var or an argent secrets file (`.argent/secrets.env` in the project, `~/.argent/secrets.env`, or an `ARGENT_SECRET_`-prefixed key in the project's `.env`/`.env.local`), so the plaintext never enters agent context; the result echoes the placeholder, not the value, and the after-typing auto-screenshot is skipped. - key: presses a single named key (enter, escape, backspace, tab, arrow-up/down/left/right, f1–f12) — NOT supported on TV targets; move focus with `tv-remote` instead. On a TV target (runtimeKind 'tv') only `text` applies — focus a text field first (with `tv-remote`), then type into it (injected HID keyboard on Apple TV, `adb input text` on Android TV). Provide text, key, or both — when both are given, the text is typed first and the key is pressed after it (text + key:"enter" types and submits).

Open an app by its bundle id (iOS) or package name (Android), or confirm the running renderer (Chromium). Use when starting any app — prefer this over tapping home-screen / launcher icons. Also prepares the native-devtools injection before the app starts (the iOS slice on iOS, the tvOS slice on Apple TV); on tvOS, interaction is focus-driven — use the tv-* tools rather than coordinate taps. Returns { launched, bundleId }. Fails if the app is not installed on the target device (iOS / Android). For Chromium, the app is already running behind a CDP port; this call simply refreshes the cached viewport and acknowledges the bundleId tag. To change the visible route, use `open-url`. On Vega (Fire TV), pass the interactive component app id from manifest.toml (e.g. com.example.app.main) as bundleId. Common iOS bundle ids: com.apple.MobileSMS, com.apple.mobilesafari, com.apple.Preferences, com.apple.Maps, com.apple.camera, com.apple.Photos, com.apple.mobilemail, com.apple.mobilenotes, com.apple.MobileAddressBook Common Android packages: com.android.settings, com.android.chrome, com.google.android.apps.maps, com.google.android.gm, com.android.vending, com.google.android.dialer, com.google.android.apps.messaging

List iOS simulators, Android emulators, connected physical Android devices, running Chromium apps, and Vega (Fire TV) devices in one place. Use at the start of a session to pick a target id ('udid' for iOS entries, 'serial' for Android/Vega entries, 'id' for Chromium) to pass to interaction tools, and to see which targets are already running. Returns { devices, avds } where each device carries a 'platform' discriminator ('ios', 'android', 'chromium', or 'vega'); 'avds' lists Android AVDs bootable via boot-device. A Vega VVD is listed under 'devices' whether running or stopped (state 'running'/'stopped'); start a stopped one with boot-device using its 'vvdImage'. Android entries also carry a 'kind' ('emulator' for a local AVD, 'device' for a physical phone connected over USB / wireless adb) — physical phones are detected from `adb devices` (any serial that is not an `emulator-*` one) and are driven through the same interaction tools as emulators; they do not need boot-device (just connect the phone with USB debugging authorised). TV targets are tagged with runtimeKind 'tv' (Apple TV simulators on iOS, Android TV / leanback devices on Android) — these are focus-driven, not touch-driven: use `describe` to read focus, `tv-remote` for remote presses (up/down/left/right/select/back/menu/home), and `keyboard` to type, rather than the coordinate/gesture tools. iOS simulators from an additional CoreSimulator device set (the 'ios.additionalDeviceSets' configuration — e.g. devices created by Radon IDE) are listed alongside default-set ones, tagged with their owning 'deviceSet' path; they are driven through the same tools by udid, but run headless (no Simulator.app window attaches to them). Chromium apps are discovered by probing CDP debugging ports (default 9222; extend via the ARGENT_CHROMIUM_PORTS=<comma-separated-ports> env var). They must already be running with --remote-debugging-port=<port> — use boot-device with electronAppPath to launch one. Booted/ready devices are l…

Read the running app's native accessibility screen description via injected native devtools. Returns a flat list of accessibility leaf elements with: - raw native point-space frame and tapPoint - normalizedFrame and normalizedTapPoint relative to the app's main screen bounds - top-level screenFrame metadata - traits and optional labels/identifiers This is a low-level native inspection tool. The normalized fields are intended to help with backend migration work, but the public describe contract is still separate. Useful for evaluating or debugging the lower-level native data that powers the public describe tool. If status is restart_required: call restart-app then retry.

Check whether native devtools are connected to a specific app and whether the next launch is prepared for injection. Use when you need to verify native devtools readiness before calling native-full-hierarchy, native-describe-screen, or native-network-logs. Returns { envSetup, appRunning, connected, requiresRestart, nextLaunchWillBeInjected, injectable }: - envSetup: DYLD_INSERT_LIBRARIES is configured in the simulator's launchd environment - appRunning: the target bundle currently has a running UIKit process on the simulator - connected: the dylib is active in the current running process for this bundleId - requiresRestart: the app is already running but its current process does not have native devtools injected (always false for a non-injectable app) - nextLaunchWillBeInjected: if you launch this bundle now, native devtools env setup is already in place (always false for a non-injectable app) - injectable: whether native devtools can ever be injected into this app. Apple system apps (bundle ids under com.apple.) are platform binaries with library validation, so the dylib can never load into them. Call this before using app-scoped native hierarchy tools or native-network-logs. If injectable is false: this is a TERMINAL state — the app can never be injected. Do NOT restart/retry. Use the standard `describe` tool (its accessibility path reads the screen without injection) or `screenshot` (then interact by coordinate). Do not fall back to the native-devtools feature tools (native-describe-screen, native-find-views, native-full-hierarchy, native-network-logs, native-view-at-point, native-user-interactable-view-at-point) — they run the same injection precheck and fail with the same non-injectable error. If appRunning is false and nextLaunchWillBeInjected is true: use launch-app normally. If requiresRestart is true: call restart-app, then proceed with the native feature. Returns { status: "init_failed", message, attempts } instead when the simulator's native-devtools e…

Search for specific UIViews in the running app by class name, accessibility identifier, label, tag, or React Native nativeID. Use when you need to locate a specific view by its properties without dumping the entire hierarchy. Returns { status: "ok", matches } with matching views including their frames, properties, optional ancestors, and optional children. Much more targeted than native-full-hierarchy. At least one of className, identifier, label, tag, or nativeID must be provided. Fails if native devtools are not connected, the app is not running, or status is restart_required (call restart-app then retry).

Get the complete UIKit view tree for the running app. WARNING: Output can be extremely large (100KB–500KB+) for complex apps, especially those built with SwiftUI. Prefer native-find-views for targeted queries. Use skipClasses / skipClassPrefixes to prune SwiftUI internal subtrees and reduce output size. Use the fields param to request only the properties you need. Use when you need deep layout debugging, finding views with no accessibility labels, or verifying view structure not exposed through the accessibility tree. Returns { status: "ok", windows } with the full view hierarchy, or { status: "restart_required" } if the dylib is not injected. Fails if native devtools are not connected or the app is not running.

Retrieve network requests captured at the native NSURLProtocol level. Unlike the JS-level network inspector (view-network-logs), this captures ALL network traffic from the app including native modules, Swift/Objective-C networking, and background transfers that bypass JS fetch. Use when you need to inspect native-level HTTP traffic that is invisible to JS fetch interception. Returns { status, count, events } where each event contains URL, method, status code, headers, and timing. Returns { status: "restart_required" } if the dylib is not injected - if this happens, call "restart-app" then retry. Fails if native devtools are not connected or the app is not running.

Analyze exported native trace data and return an LLM-optimized markdown report. iOS: parses CPU time profile, UI hangs, and memory leaks from the exported XML files. Android: queries the Perfetto .pftrace via the in-process Perfetto trace-processor engine for CPU hotspots, UI hangs with jank reason + main-thread state breakdown, GC annotation, and an RSS-growth weak signal. Returns a structured markdown report with severity indicators, tables, and actionable suggestions. After presenting the report, ask the user whether to investigate further (drill-down with profiler-stack-query for hang stacks, CPU context, leak details) or implement fixes and re-profile. Call native-profiler-stop first to export the trace data. Use when you need to interpret a completed native profiling recording. Fails if native-profiler-stop has not been called first to export trace data.

Start native profiling on a booted device. iOS: Instruments via xctrace (CPU, hangs, memory). Android: Perfetto (CPU, jank, RSS-growth weak signal). Auto-detects the running app process unless app_process is explicitly provided. After starting, let the user interact with the app, then call native-profiler-stop. Use when you want to capture native CPU, hang, and memory data for a running app. Returns { status, pid, traceFile } confirming the recording has started. Fails if no app is running on the device, or the profiler cannot attach to the process.

Stop native profiling and export trace data. iOS: sends SIGINT to xctrace, waits for packaging, then exports CPU, hangs, and leaks XML. Android: sends SIGTERM to the perfetto daemon, polls /proc/<pid>, then `adb pull`s the .pftrace. Call native-profiler-start first. Use when the user has finished the interaction to profile and you need to export the trace. Returns { traceFile, exportedFiles, exportDiagnostics? }; traceFile is the raw trace bundle and exportedFiles the exports, all downloadable artifacts materialized to local paths. Fails if no active native-profiler-start session exists for the given device_id.

Inspect the deepest UIView at a raw native window point that would actually receive touch input. Unlike native-view-at-point, this respects userInteractionEnabled and is closer to UIKit hit-testing semantics. IMPORTANT: x and y are raw iOS window coordinates in points, NOT normalized [0,1] simulator tap coordinates. If status is restart_required: call restart-app then retry.

Inspect the deepest visible UIView at a raw native window point. Unlike native-user-interactable-view-at-point, this ignores userInteractionEnabled, so it answers "what is visually here?" rather than "what would receive the touch?". IMPORTANT: x and y are raw iOS window coordinates in points, NOT normalized [0,1] simulator tap coordinates. If status is restart_required: call restart-app then retry.

Open a URL or URL scheme on the device. Use to navigate to a web page or deep-link into an app. On Chromium, this navigates the primary renderer to the given URL. Cross-platform schemes: https://, tel:, mailto:. iOS also: messages://, settings://, maps://. Android also: geo:, plus any app-specific deep link. Deep-linking caveat: an https:// link opens the native app only when an installed app is verified for the link's domain (iOS Universal Links / Android App Links) — otherwise it opens in the browser, and on iOS simulators it may open in Safari even when the owning app is installed. To reliably open an installed app, use its custom scheme (scheme://path) or launch-app with its bundle id. Returns { opened, url, note? }. note carries the deep-linking caveat when a web URL was opened on a native device. Fails if no app is registered to handle the URI (iOS/Android) or the renderer rejects the navigation (Chromium).

Generate a cross-correlated report combining React Profiler and native profiler data. Maps native hangs to React commits using wall-clock time alignment. Requires both react-profiler-analyze and native-profiler-analyze to have been called first. Call this tool when both profilers were run in parallel on the same session. Returns a markdown report correlating hangs with React commits, memory leaks, and investigation hints. Fails if either react-profiler-analyze or native-profiler-analyze has not been called first.

Query React commit data for iterative investigation of render performance. Requires react-profiler-stop to have been called first. Modes: - by_component: All commits where a specific component rendered, with causes and durations. - by_time_range: What happened in a specific time window. - by_index: Full detail dump of a single commit (all components, props changed, parent cascade). - cascade_tree: Parent-child cascade tree for a commit showing who triggered whom. Use when drilling into specific components or time windows after react-profiler-analyze. Returns a markdown table or tree of commit data matching the requested mode. Fails if react-profiler-stop has not been called or no commit data is stored.

Query Hermes CPU profile data with targeted modes for iterative investigation. Requires react-profiler-stop (and ideally react-profiler-analyze) to have been called first. Modes: - top_functions: Global CPU hotspots ranked by self-time. Optional time_window_ms to filter. - time_window: CPU breakdown for a specific time range (e.g. during a slow commit or hang). - call_tree: For a given function_name, show its callees and optionally callers. - component_cpu: For a given component_name, aggregate CPU activity across all its commits. Use when investigating JS CPU hotspots or correlating CPU cost with specific components. Returns a markdown table of CPU hotspots, call tree, or per-component CPU breakdown. Fails if no CPU profile is stored — run react-profiler-stop first.

Fetch and restore a previously captured profiling session from disk into memory so query tools can operate on it. This is the disk-restore counterpart to react-profiler-stop/native-profiler-stop, which write data, and to the query tools (profiler-cpu-query, profiler-commit-query, profiler-stack-query), which read it. Use when you need to revisit past session data without capturing a new recording. Modes: - list: Show all available profiling sessions in the project's debug directory. - load_react: Load a React profiler session (CPU profile + commit tree) into memory. Requires session_id. - load_native: Re-parse native profiler XML files into memory. Requires session_id and device_id. For Android .pftrace restores, pass app_process for older sessions that do not have a metadata sidecar. Returns a summary of the loaded session or a session list for the list mode. Fails if the session_id is not found or required XML files are missing from disk.

Query native profiler trace data for iterative investigation of native performance. Requires native-profiler-stop → native-profiler-analyze to have been called first. Modes: - hang_stacks: Full CPU context during a specific hang (by hang_index). - function_callers: Who calls a specific native function and what it calls. - thread_breakdown: CPU time split by thread, optionally filtered. - leak_stacks: Memory leak details (iOS only), optionally filtered by object_type. Use when drilling into native hang stacks, thread CPU breakdown, or memory leaks after native-profiler-analyze. Returns a markdown report with native call stacks, thread weights, or leak details for the selected mode. Fails if native-profiler-analyze has not been run or no parsed trace data is in memory.