Skip to main content

Tools reference

Argent exposes its capabilities to the coding agent as MCP tools. You rarely call these by hand, but knowing what exists tells you what you can ask for.

Run argent tools to list them from the terminal, argent tools describe <name> for the full schema of one, and argent run <name> to invoke one directly.

Devices and apps​

ToolDescription
list-devicesList iOS simulators, Android emulators and devices, Chromium apps, Mac apps, Vega (Fire TV) devices, and HarmonyOS phones and emulators
boot-deviceBoot a simulator, emulator, Vega Virtual Device, or HarmonyOS emulator, spawn an Electron app, or start a Mac app
launch-appOpen an app by bundle id (iOS) or package name (Android)
restart-appTerminate then relaunch an app
reinstall-appInstall or reinstall an app, clearing app data and runtime permissions
open-urlOpen a URL or URL scheme on the device
settings-permissionsGrant, deny, or reset a runtime permission without navigating the Settings UI
rotateSet the device orientation to portrait or either landscape
foldFold or unfold a foldable iOS simulator or Android emulator to a posture or a hinge angle
shakeShake the device
buttonPress a hardware button: home, back, power, volume, app switch, action button
tv-remotePress a TV remote or D-pad button on Apple TV, Android TV, or Vega
stop-simulator-serverStop the transport session for one device and free its resources
stop-all-simulator-serversStop every service a device owns: simulator servers, native devtools, TV daemons, native network capture
stop-metroStop the Metro bundler listening on a given port

Through the MCP server, list-devices returns a shorter text than the SDK and argent run:

  • Each device is one line of compact JSON.
  • The text does not include isEmulator, which repeats kind. It also does not include fields without a value or runtimeKind: "mobile".
  • An iOS runtime is shortened, for example to iOS 27.0.
  • The iOS simulators that are shut down come after the JSON object, one line for each simulator. A line gives the platform, the udid, the name, the runtime, the state and the tags, for example foldable or runtimeKind=tv. A simulator in another state, for example Booting, stays in the JSON object.

The SDK and argent run return the full JSON object.

launch-app and restart-app accept launchArgs, a list of arguments that Argent passes to the app process at launch. For example, ["-FeatureFlag", "YES"] overrides a UserDefaults value. launchArgs works on Apple simulators, physical iPhones and Mac apps. Other targets ignore it. If the app already runs, launch-app terminates it first, so that the app gets the arguments. On a local iOS simulator, the tool fails if that termination does not finish within 15 seconds. On a remote simulator, launch-app and restart-app fail if the termination fails for a reason other than the app not running, and launch nothing. On a physical iPhone, the app sees -- before the arguments. UserDefaults overrides still apply. On a Mac app, launch-app applies launchArgs only when it starts the app. See Mac apps.

reinstall-app uninstalls the app first, so Argent checks the app at appPath before the uninstall. The tool fails and keeps the installed app when one of these checks fails:

  • appPath does not exist, or it is not a .app directory (iOS), an .apk file (Android), a .vpkg file (Vega) or a .hap file (HarmonyOS).
  • bundleId does not match the bundle id in the .app, the package name in the .apk or the bundle name in the .hap. On a remote simulator, Argent does not compare the bundle id.

On Android, Argent also checks the device after the uninstall. If the package is still on the device, the tool fails and does not install the .apk. These packages stay after the uninstall:

  • A system app. The app data stays on the device.
  • An app that is an active device admin. The app data stays on the device.
  • An updated system app. The uninstall removes only the update. If the update has a newer version than the system app, Android also removes the app data.

If Argent cannot check the device after the uninstall, the tool also fails and does not install the .apk. The app may already be uninstalled.

On a local iOS simulator, the tool fails and does not install the .app if the uninstall does not finish within 30 seconds.

On a local iOS simulator, boot-device, launch-app, restart-app, reinstall-app and open-url give error_kind: "timeout" when a simctl step does not finish within its time limit. The message names the step and the limit. On a remote simulator, launch-app and restart-app do the same for a sim-remote step that does not finish within 30 seconds.

On a local iOS simulator, boot-device fails if simctl list does not answer within 10 seconds, because Argent cannot read the state of the simulator. In that case, list-devices returns a hint that says that the list can be incomplete.

On Chromium, open-url fails when the URL does not load a page, start a download or run as a javascript: URL. Examples are a URL with no scheme, an unknown scheme, tel:, mailto:, a host that does not resolve, a response with no content and a navigation that a beforeunload handler on the current page cancels. An HTTP error status, for example 404, does not make the tool fail, also when Chromium shows its own error page for it. In headless Chrome, a 401 that asks for credentials makes the tool fail.

stop-metro returns stopped: true when it sends SIGTERM to every listening process it finds, or the process has already exited, and stopped: false when it finds none. The tool fails if it cannot read the port, if it finds a listener but not the process that owns it, or if it cannot signal a listener it found, for example with EPERM. On macOS, the tool detects a listener that belongs to another user only when it sees no other listener on the port, so that listener can still hold the port after stopped: true.

Argent drives a foldable iOS simulator, for example the iPhone Duo, and a foldable Android emulator, for example a Pixel Fold or a generic foldable AVD. list-devices marks a foldable device and a foldable AVD with foldable: true. fold moves the hinge to a posture (closed, half-open or open) or to an angle from 0 to 180 degrees.

  • Closed, the cover panel shows the UI. Half-open and open, the inner panel shows the UI. The panel that shows the UI is the active panel.
  • All tools use the active panel. This is also true after a fold made outside Argent.
  • The coordinates and the screenshot size change with the panel.
  • fold returns when the device accepts input again.

On an iOS simulator:

  • A video keeps the size of the panel where the recording started. Argent keeps the proportions of the other panel and adds black bars.
  • A fold between two angles that are not 0 or 180 can keep the current panel. To change panels, fold to closed or open.
  • Unfolded, the UI is landscape. rotate sets the orientation of the device, not of the UI. Portrait gives a landscape UI.
  • If Argent cannot find the active panel, it uses the cover panel. The tool result then has a warning.

On an Android emulator:

  • The result gives deviceState (CLOSED, HALF_OPENED or OPENED) and the matching posture.
  • Argent dismisses a lock screen that the fold to closed shows, if it has no PIN or password.
  • The result has a warning if the screen is off or the lock screen shows after the fold.
  • On a generic foldable profile, closed shows only the left part of the display, and describe frames do not match taps. Use a Pixel Fold profile to test the cover panel.
  • A physical device and an emulator without a hinge reject the call.

Argent supports physical iPhones; physical iPads are not supported yet. list-devices shows a physical device as an iOS entry with kind device. The state is connected only while the device is attached by USB cable; Argent controls physical devices over the cable and does not use Wi-Fi. The state is paired when the device is paired but not reachable now. Argent never selects a physical device automatically: name its udid. A paired device cannot be driven until it is connected by cable again. See Physical iOS devices for the requirements, the signing model, and the app-scoped interaction contract.

With the macos-apps flag on, list-devices shows each native Mac app that Argent started and that still runs, as a macos entry with kind app. See Mac apps.

Inspecting the screen​

ToolDescription
screenshotCapture the device screen
describeGet the accessibility / DOM element tree for the current screen
screenshot-diffCompare two PNG screenshots and return a visual-diff summary
await-screen-idleBlock until the screen has rendered content and stopped changing
await-ui-elementBlock until a UI element reaches an expected state, instead of polling in a loop

On an iOS simulator, a line of describe can show:

  • [disabled] for a control that is not enabled.
  • [selected] for a selected control.
  • hint="..." for an element that has a VoiceOver hint. describe omits a hint that is identical to the label. A physical iPhone does not report the VoiceOver hint.

On a physical iPhone, describe includes a web sign-in sheet or an in-app Safari view that covers the app. The system alert that asks to sign in with a website shows only after launch-app com.apple.springboard.

Interacting​

ToolDescription
gesture-tapTap at normalized coordinates. Mac apps also take a right-click
gesture-swipeSmooth swipe or drag between two points
gesture-scrollScroll a Chromium app (mouse wheel) or the scroll view under a point in a Mac app
gesture-dragPress, move, and release the mouse in a Chromium app or a Mac app
gesture-pinchPinch to zoom around a center point
gesture-rotateTwo-finger circular arc that rotates on-screen content
gesture-customSend an arbitrary sequence of touch events for complex gestures
keyboardType text or press special keys
pastePut text on the device clipboard and paste it (sim/emu), or insert it in a Mac app
run-sequenceExecute several interaction steps in a single call
screen-recording-startStart recording the screen to an h264 mp4
screen-recording-stopStop the recording and retrieve the video

gesture-tap, gesture-swipe, gesture-scroll, gesture-drag, and gesture-custom require position coordinates from 0 to 1, inclusive, not pixels. Argent rejects coordinates outside this range before sending input and names the invalid coordinate. This also applies to calls in run-sequence and e2e steps. The deltaX and deltaY scroll distances can be negative or greater than 1.

Through the MCP server, an interaction tool and await-ui-element return a screenshot and the element tree after the screen stops changing. These limits apply:

  • Argent waits at most 15 seconds for the screenshot and the element tree together. If a capture takes longer, the result does not include it.
  • Argent does not send a capture call again after a timeout.

Argent does not repeat an element tree that the agent already has. Each full element tree starts with a Tree id line. Argent compares the element tree with the last full element tree that the MCP server returned for the same device. That element tree comes from an earlier action or from a describe call. When the two are identical, the result contains a note in place of the element tree. The note gives the id of the full element tree and the tool that returned it. The screenshot is not affected.

The note does not show that the action had no effect. The element tree does not contain all state. For example, text that the agent types in a field can be absent from it.

All agents on one MCP connection share this comparison. An agent that does not have the element tree with the id in the note calls describe.

Argent sends the full element tree again in these cases:

  • The element tree or the hint of describe changed.
  • Argent sent the note 3 times in a row.
  • The last full element tree is more than 5 minutes old.
  • The client cancelled the call that returned the last full element tree.

A describe call always returns the full element tree, with its Tree id. With the disable-auto-describe flag, a describe result has no Tree id.

Call screenshot or describe to read the screen again.

JavaScript runtime debugging​

ToolDescription
debugger-connectConnect to the JS runtime CDP debugger
debugger-statusReport connection status and diagnostics
debugger-evaluateExecute JavaScript in the app's runtime: Hermes on device, V8 on Chromium
debugger-component-treeList the React component names and testIDs on the current screen
debugger-inspect-elementInspect the React component hierarchy at a screen coordinate
debugger-log-registrySummarize console logs captured from the app
debugger-reload-metroRestart the Metro bundle without restarting the native process
view-network-logsRetrieve captured HTTP requests from the running app
view-network-request-detailsGet full details of one request by its requestId

Native devtools​

On a Mac app, these tools read the app through the Argent library:

  • native-describe-screen reads the accessibility tree of the app, plus the views with an identifier that the tree does not contain. It does not take skipClasses or skipClassPrefixes.
  • native-full-hierarchy, native-find-views and native-view-at-point read the AppKit views of the app.
    • SwiftUI puts the identifier and the label of a control on an accessibility element, not on a view. Thus a native-find-views search by identifier or label does not find SwiftUI controls. describe shows them.
    • When a search by identifier or label finds no view, its result has a note that refers to describe.
  • native-network-logs reads the requests that the app sends through NSURLSession. With stop: true, it fails with the error NATIVE_NETWORK_LOGS_STOP_UNSUPPORTED. The capture stops when the tool-server disconnects from the app.

The Mac apps section contains the details.

ToolDescription
native-full-hierarchyGet the complete UIKit view tree
native-find-viewsSearch views by class, accessibility id, label, tag, or nativeID
native-view-at-pointInspect the deepest visible view at a native window point, or with hitTest: true the view that would receive touch input
native-network-logsRead native HTTP requests on iOS, Android and Mac apps, or stop native network capture on Android

Native network capture on Android​

On Android, native-network-logs reads the OkHttp traffic of a debuggable app. The device must run Android 8.0 or later. Argent captures all OkHttp requests only on Android 9 or later. On Android 8.0 and 8.1, Argent captures only the requests of the React Native networking client and of Fresco. In an app without React Native, Argent captures no requests, and the capture state is unavailable. The app must run as arm64-v8a or x86_64. Argent attaches an in-app agent to the running app.

To capture a request:

  1. Call native-network-logs with the serial of the device and the package name of the app. The first call usually returns armed: false.
  2. Call native-network-logs again until armed is true.
  3. Do the action that sends the request again.
  4. Call native-network-logs again to read the list of requests.
ParameterEffect on Android
udidThe serial of the device
bundleIdThe package name of the app
portThe Metro port. Argent removes the traffic to this port on a local address from the list. The default is the Metro port of the device.
limitThe maximum number of requests in the list. Argent returns the most recent requests, oldest first. The default is 50.
clearRemove the current requests from the later lists. Their IDs stay valid.
stopStop native network capture for this app. The capture of a different app continues.

The result contains header, armed, capture, captureDetail, count, total and requests. The capture field and the header line show the state of the capture. The capture field is absent when armed is false. The captureDetail field contains the detail that the in-app agent sent with the state. The header line shows this detail too. These are the states:

StateMeaning
activeArgent captures the OkHttp requests of the app. If Argent captures only some requests, the header line gives the reason.
waitingThe app did not load OkHttp yet. The capture starts when the app loads it.
unavailableThe in-app agent cannot capture in this process, for example because R8 fully minified OkHttp. The header line gives the reason.

Each request has an ID with the format android-<4 hex digits>-<number>, for example android-3f9a-12. An ID is valid only in the tool-server that listed it. An ID is not valid after native-network-logs with stop: true or stop-all-simulator-servers stops the capture, or after the tool-server stops. Give the ID to view-network-request-details together with an id of the same device. This needs no debugger connection. The details contain these items:

  • The request headers that went on the wire, for example Cookie and User-Agent. When Argent knows only the headers that the app set, the details say so.
  • Each redirect with the request headers that went on the wire for it and the headers of its response, for example Location.
  • The final URL of the response.
  • The request body and the response body.

The details do not contain an initiator.

Only the in-app agent that Argent attached can report requests to Argent.

While native network capture is on for an app, these tools tell you:

ToolWhat it reports
launch-app, restart-appArgent attaches the in-app agent to the new process. The tool waits until the capture is ready, for at most 5 seconds. If the capture is not ready after this time, Argent reads the reason from the log of the device. This step can add 3 seconds when adb does not answer. The networkCapture field tells if Argent attached it. If Argent did not attach it, the field gives the reason.
e2e-executeA launch step uses restart-app. The report shows the networkCapture note as a warning on the first launch of the app, and again when the note changes. A new pid alone is not a change.
react-profiler-start, native-profiler-startThe result contains a warning that names the apps on the device with native network capture on.

A process of the app can also start in a different way, for example from a launcher tap, from a link or after a crash. The next call of native-network-logs attaches the in-app agent to this process.

Native network capture stays on until native-network-logs with stop: true stops it for the app, or stop-all-simulator-servers stops the services of the device. After that, call restart-app to start the app without the in-app agent. See Network inspection for the limits.

With stop: true, native-network-logs does not list requests. The result contains status, stopped and message:

  • stopped is true when native network capture was on for the app. Argent removes the session file and the files of the in-app agent from the data directory of the app. Argent also removes the adb reverse tunnel of the app.
  • stopped is false when native network capture was not on for the app. Argent does not start native network capture for the app.

The in-app agent stays in the current process of the app until this process ends. The message field tells you to call restart-app. After the stop, launch-app and restart-app do not attach the in-app agent. The next call of native-network-logs without stop starts native network capture again.

On iOS, stop: true fails with the error NATIVE_NETWORK_LOGS_STOP_UNSUPPORTED. The native devtools of iOS cannot stop network capture. On iOS, network capture stays on for the app until stop-all-simulator-servers stops the services of the device and the app restarts.

Chromium and Electron​

ToolDescription
chromium-tabsList, switch, open, and close tabs or BrowserWindows
chromium-cookiesRead and write cookies, including HttpOnly ones

Mac apps​

Use these tools for native AppKit, SwiftUI, and react-native-macos apps on macOS 14.4 or later. See Mac apps for setup and supported workflows.

The macos-apps feature flag is on by default. When disabled, Mac apps disappear from list-devices, and tools reject Mac app IDs. The file-panel and menu-bar tools are available only on a macOS host with the flag enabled.

Start and restart an app​

Call boot-device with the path to your built app:

{ "macosAppPath": "/Users/anna/Projects/Notes/build/Notes.app" }

Argent returns a device ID such as macos-app-com.example.notes. Pass that ID as udid to subsequent tools. Each bundle identifier represents one device.

boot-device parameterDescription
macosAppPathPath to the .app bundle. Argent launches the app in the background.
macosAppArgsExecutable arguments. Defaults to no arguments.
udidDevice ID instead of a path. Reuses the last app path, or the newest matching build found by Spotlight.
forceRestart the same build, including a copy started outside Argent. Never replaces a different build.

The result contains platform: "macos", id, bundleId, pid, appPath, sandboxed, logPath, args, and booted: true. A running app returns alreadyRunning: true without restarting. Check appPath to confirm which build runs and logPath for app output.

A note reports conditions that need attention, such as no open window or arguments that differ from the request. Launch tools wait up to 10 seconds for a window. Use force to apply changed arguments to an already running app.

ToolmacOS behavior
list-devicesLists running apps started by Argent, with platform: "macos" and kind: "app".
launch-appStarts the app if needed. Leaves a running app unchanged.
restart-appQuits the app and starts the same bundle again. Rebuild first to test code changes.
open-urlDelivers the URL to the running app. Web URLs go to the app, not a browser.
reinstall-appUnsupported. Rebuild and use restart-app.
stop-simulator-server, stop-all-simulator-serversDisconnect Argent. The app keeps running; network capture stops and its recorded requests are lost.

For launch-app and restart-app, bundleId must match the device. Both accept launchArgs and otherwise reuse the previous arguments. Their results include appPath and args.

open-url accepts http, https, and file URLs. Other schemes must appear in the app's CFBundleURLTypes.

The app starts with / as its working directory and basic login variables such as HOME, USER, PATH, and LANG. It does not inherit custom environment variables from the tool-server.

Handle running copies and save prompts​

Argent cannot attach to a copy launched outside Argent. Save your work and quit that copy, or use boot-device with force: true. A forced launch can lose unsaved changes.

Argent refuses to replace a different build with the same bundle identifier, even with force. Quit that build or use distinct bundle identifiers.

Restarts, e2e launch steps, and native-profiler-start with malloc_stack_logging: true stop if the app asks whether to save changes. Answer the prompt before retrying or restarting the tool-server. Use file-panel for a new document's Delete or Don't Save prompt.

An unresponsive app can be force-quit after five seconds. Check the result's note for possible loss of unsaved changes.

Resolve launch and connection failures​

ProblemAction
Code signing blocks launchFollow Configure code signing.
The saved app path no longer existsCall boot-device with the current macosAppPath.
The app does not connect during launchCheck the log in the error. Make sure startup does not block the app's main thread.
The app uses a launcher scriptPoint Argent at a bundle whose executable is the native app.
The app has no supported windowOpen a standard window. Apps with only panels, borderless windows, or a menu bar icon are unsupported.
The launch result warns that reconnection is unavailableAfter disconnecting, use restart-app. This can occur in sandboxed apps with long bundle identifiers.
The Argent library files are missingUpdate Argent and retry.

If the app does not connect within 20 seconds, Argent stops it and includes recent app output in the error.

Configure code signing​

Argent loads a library into the app at launch. Code signing must permit that library. Use a Debug build; the standard Xcode macOS App and react-native-macos templates work without changes.

For a Debug build with the hardened runtime, choose one option:

OptionWhen to use it
Set ENABLE_HARDENED_RUNTIME = NO for DebugUse this when your test build does not require the hardened runtime. Keep Release settings unchanged.
Add com.apple.security.cs.disable-library-validation to the Debug entitlementsUse this when your test build needs the hardened runtime.
Sign the Argent library with your app's teamUse this when your development-signed build must retain library validation.

To sign the library with your team:

  1. Try to start the app. The launch error provides the codesign command.
  2. Run security find-identity -v -p codesigning to find your team's Apple Development identity.
  3. Substitute that identity into the provided command and run it yourself. Signing requires access to your keychain.
  4. Start the app again. Repeat signing if an Argent update changes the library.

Ad hoc signed builds have no signing team and cannot use the team-signing option.

A separate code-signing flag, --options library, blocks Argent even when the app disables library validation through an entitlement. Remove that flag from the test build's signing options, such as OTHER_CODE_SIGN_FLAGS.

Exported builds with the hardened runtime need com.apple.security.cs.allow-dyld-environment-variables. They also need com.apple.security.cs.disable-library-validation or an Argent library signed by the app's team. A Release configuration signed for development can work without the first entitlement because development signing permits debugging.

Keep these signing changes out of distributed builds. Use a development build for testing. Argent is tested with apps you build; other apps may have incomplete inspection or input support even when their signatures permit launch.

Run builds from separate worktrees​

Give each build a unique bundle identifier to run worktrees in parallel:

  1. In the app target, set PRODUCT_BUNDLE_IDENTIFIER to com.example.notes$(ARGENT_ID_SUFFIX).

  2. Build each worktree with a different suffix and output directory. For a scheme named Notes:

    xcodebuild -scheme Notes -configuration Debug \
    -derivedDataPath ./build ARGENT_ID_SUFFIX=.login build
  3. Give the agent the resulting .app path and bundle identifier, such as com.example.notes.login.

  4. Use that identifier in the e2e test's launch step.

Builds without ARGENT_ID_SUFFIX keep the original identifier. Set the suffix on the command line, not PRODUCT_BUNDLE_IDENTIFIER itself: a global override also changes CocoaPods bundle identifiers.

If you copy and re-sign an existing bundle instead, preserve its entitlements. Removing entitlements can disable the App Sandbox. Ad hoc signed copies cannot retain team-dependent features such as iCloud, keychain sharing, or app groups.

Inspection and input​

Coordinates use the app window, including its title bar, with the origin at the top left. Sheets, popovers, alerts, and menus can extend that area. Use the frames returned by describe for input coordinates.

ToolmacOS behavior
describeReturns the app's accessibility tree. See fields and identifiers.
await-ui-element, await-screen-idleWait for matching elements or a stable interface using the app tree.
screenshotCaptures the app window and attached sheets, popovers, alerts, and menus. Other app windows are excluded.
screenshot-diffCaptures at scale: 1.0. Save baselines at the same scale. No top band is masked.
gesture-tapClicks. Use button: "right" for a context menu or clickCount: 2 for a double-click.
gesture-dragDrags with the left button. Equal start and end points produce a long press.
gesture-scrollScrolls the content under the point, like a mouse wheel. durationMs has no effect.
keyboardTypes Unicode text or sends keys and shortcuts, such as command+a or shift+tab.
pasteInserts text into the focused editable control. Leaves the clipboard unchanged and does not invoke app paste handlers.
run-sequenceRuns tap, scroll, drag, keyboard, paste, and await steps.
Native view toolsRequire the device's bundleId. Their x and y use points, rather than fractions of the window.
native-network-logsStarts capturing URLSession requests on the first call. Startup requests can be missed. Each app restart begins a new record.

Screenshots and scrolling​

Use scale: 1.0 for one pixel per point. By default, screenshots downscale windows larger than 768 points on the longest side, to at least 0.6 pixels per point. The minimum explicit scale is 0.1. Mac apps ignore ARGENT_SCREENSHOT_SCALE and rotation.

Scrolling targets the nearest scrollable content under the point. Web content scrolls first; an enclosing native scroll view can take over at the page boundary. The call fails if no eligible content can scroll.

scrolled: true does not prove movement. Compare the tree before and after scrolling to detect the end of a list.

Text checks​

A text check on a field reads its entered text, not its placeholder. A container check includes descendant text but skips subtrees with their own identifiers. Web elements and non-accessibility views expose the text they display.

When several elements match, text checks prefer an open menu or combo box list, then the uppermost alert, sheet, or popover, then the window. A matching paragraph takes precedence over the text area that contains it.

describe on a Mac app​

describe returns a nested tree under AXApplication. Use the reported roles and identifiers to locate controls.

FieldMeaning
RoleAppKit accessibility role, such as AXButton, AXTextField, or AXScrollArea. Web elements use the same roles.
IdentifierA stable identifier supplied by your app. See the examples below.
LabelThe control's label, associated text, or placeholder when no label exists.
ValueCurrent text or state. Date pickers use ISO 8601 in the Mac's time zone; token fields use comma-separated tokens.
[clickable]A control that responds to clicks.
passwordA password field. Its value is omitted.
checkedThe state of a web checkbox or radio button.
scrollHiddenThe number of elements scrolled out of view. Scroll to bring them into the tree.

Set identifiers in your app:

App typeIdentifier source
AppKitThe control's accessibility identifier
SwiftUI.accessibilityIdentifier("save-button")
Web contentdata-testid="save-button", or id when data-testid is absent
react-native-macostestID="save-button", including on plain View and Text elements

Argent omits identifiers generated by AppKit or SwiftUI, such as ListRow. A view with an identifier can appear even if it is not an accessibility element.

The tree excludes hidden, scrolled-out, or out-of-bounds elements. Native controls covered by sheets, popovers, or other app windows can also be excluded. The menu bar is separate: use menu-bar.

Web inspection includes open shadow roots and same-origin iframes. Closed shadow roots and cross-origin iframes are unavailable. A JavaScript alert, confirmation, or prompt replaces the page content in the tree until dismissed.

Read the result's hint when elements are missing. A minimized window produces an empty tree. Reads can also be incomplete because of unresponsive elements or size limits: 3000 elements and 40 levels of depth. While the Mac is locked, inspection can miss context menus, and hidden checks cannot pass reliably. Unlock the Mac and retry.

file-panel​

Use file-panel to answer open and save dialogs by path. The system file list is unavailable to describe and gesture-tap.

After opening a save dialog, choose a destination:

{
"udid": "macos-app-com.example.notes",
"action": "choose",
"path": "~/Desktop/report.pdf"
}
Existing files can be overwritten

choose and prepared save answers bypass overwrite confirmation. The result does not indicate whether the destination already existed. Check the destination before saving.

ParameterDescription
udidMac app device ID.
actionlist, choose, cancel, discard, or stub.
pathFor choose or a stub answer: absolute path or ~/ path. Open targets must exist; save destinations need an existing parent folder.
pathsMultiple open targets, if the dialog allows multiple selection. Use path or paths, not both.
panelPanel number from list. Required when more than one panel is open.
timeoutMsWait for a panel before choose, cancel, or discard. Default 5000; maximum 30000.
stubModeFor stub: answer (default), cancel, or off.
panelKindFor a prepared answer: open or save. Set this explicitly for repeatable tests.
ActionResult
list{ panels } with each panel's number, kind, title, folder, and options.
choose{ chosen, panel, kind, paths }. Closes the dialog and delivers the paths to the app.
cancel{ cancelled, panel }.
discard{ discarded, panel }. Closes a new document without saving. Requires a Delete or Don't Save button.
stub{ armed, mode, panelKind }. Prepares an answer for the next matching dialog, without showing it.

Set visible app-specific controls, such as a format selector, before choose. Controls hidden behind the system's Show Options button are unavailable.

Prepare an answer before a dialog opens​

Use stub before an action that opens a dialog. A prepared answer waits for a matching panelKind; other dialogs open normally. For example, a prepared open answer does not dismiss an intervening save dialog.

Without panelKind, existing paths imply open; a single new path implies save. A prepared cancel applies to the next dialog of either kind. Use stubMode: "off" to remove a prepared answer. Disconnecting Argent also removes it.

If a dialog rejects a prepared answer, it opens normally. Call list and read stubRefused for the reason.

File types and sandbox access​

  • A save dialog accepts one file path. An open dialog accepts multiple paths only when configured for multiple selection.
  • The path must match the dialog's file or folder selection mode. A document package counts as a file.
  • Save extensions must match an allowed format unless the app allows other file types. Formats public.data and public.item accept any extension.
  • With multiple save formats, the extension selects the format on macOS 15 and later. On macOS 14, the dialog keeps its initially selected format.
  • Open paths are not checked against the dialog's allowed file types.
  • Sandboxed apps receive access only to the selected paths. A save answer grants access to the file, not its entire folder.

Use menu-bar for commands outside the app window. The app stays in the background, and the pointer does not move.

Read the available commands with action: "list", then choose one by its current titles:

{
"udid": "macos-app-com.example.notes",
"action": "choose",
"path": ["File", "Export..."]
}
ParameterDescription
udidMac app device ID.
actionlist or choose.
pathOne to nine titles from the top-level menu to the command.
identifierCommand identifier from list. Use path or identifier, not both.

list returns { menuBar, items }: an indented menu tree and item count. Disabled and checked items are marked. choose returns { chosen } with the selected path, plus identifier when used.

Title matching ignores case and treats ... and … as equivalent. Use the title currently shown, such as Undo Delete Task. Window-menu identifiers distinguish windows with the same title but change when a window reopens.

If a command is disabled, focus the relevant control or dismiss the current alert. If a pop-up or context menu is open, press Escape before choosing a menu-bar command. Missing items, ambiguous identifiers, and submenu titles produce errors with available choices.

The menu list stops at 2000 items or eight submenu levels. Check truncated and hint if the result is incomplete.

Profiling a Mac app​

Pass the Mac app's device_id to native-profiler-start, native-profiler-stop, native-profiler-analyze, and profiler-stack-query. Use profiler-load with mode: "load_native" to reopen a saved native session. See Profiling for shared behavior.

  • Start. Launch the app through Argent first and omit app_process. The bundled Instruments template captures CPU samples, UI hangs, and memory leaks. In a desktop session, Argent requires com.apple.security.get-task-allow on signed builds to avoid an administrator prompt that blocks recording. If you get NATIVE_PROFILER_APP_NOT_DEBUGGABLE, use a development-signed build. In a background session such as SSH, pass template_path: "Time Profiler" to profile CPU and hangs on a signed build without that entitlement.

  • WebKit and leak checks. With malloc stack logging off, Argent refuses the bundled template if it detects a WebKit heap (NATIVE_PROFILER_APP_HAS_WEBKIT_HEAP) or the check fails (NATIVE_PROFILER_APP_HEAP_CHECK_FAILED). The check applies only to the bundled template. With logging off, any template that uses the Allocations instrument, including Leaks and Allocations, can freeze an affected app until you force-quit it.

    To record CPU and hangs without restarting or checking for leaks, use template_path: "Time Profiler". To record leaks, keep the bundled template and set malloc_stack_logging: true.

  • Trace older allocations. The bundled template can capture allocation stacks for objects allocated during recording. To trace allocations from launch, set malloc_stack_logging: true. This restarts the app and clears its current state. If start reports that it restarted the app, malloc stack logging stays active even if Instruments fails to attach. Use restart-app to remove the overhead before measuring CPU or hangs.

  • Stop and recover. Check warning and exportDiagnostics for an incomplete trace or skipped exports. If Instruments failed to attach or exited during startup, confirm the app is running and start a new recording. If the app ended or Instruments stalled during stop, repeat the scenario when you need a complete trace.

Interpret pauses and leak results​

During capture, Argent can wait up to 25 seconds before sending an action to a suspended app. If an action times out with MACOS_APP_RPC_TIMEOUT, check the app with describe before retrying. An action that was already sent may have taken effect.

When suspension timing is available, the report keeps the duration Instruments recorded and shows how much of the hang overlapped a pause. The overlap can extend a hang when the app has work to finish. A wait for something like a timer or I/O can continue through the pause. Repeat the same actions with template_path: "Time Profiler" to measure hangs without leak checks.

A short recording may end before a leak check finishes. Follow the report's warning and allow time for a leak check. With Time Profiler, the report says that memory leaks were not checked.

React profiler on react-native-macos​

Start a supported Debug build through Argent. Pass the Mac app's ID from list-devices as device_id, even on a shared Metro. The profiler connects directly to Metro. The debugger-* tools are unavailable for Mac apps.

Use the same device_id and Metro port for the React profiler and query tools. The default port is 8081. To reopen a saved React profile, use profiler-load with mode: "load_react". To compare React commits with native hangs, record both profiles during the same interaction. Analyze both profiles before calling profiler-combined-report.

If Metro lists other runtimes but cannot find the Mac app, tools that need the runtime return DEBUGGER_TARGET_DEVICE_MISMATCH and list the available targets. If Metro lists no runtimes, they return DEBUGGER_METRO_NO_TARGETS. In either case, react-profiler-status returns session_status: "no_react_runtime" with the reason in note. Check that the app is running, wait for it to load its JavaScript, and verify the Metro port before retrying.

For react-profiler-analyze, pass platform: "macos" if the recording lacks platform information. The report prefers .macos.* source files, then .native.* files, then files without a platform suffix. If the recording lacks architecture information, the tool checks macos/Podfile.

Additional limitations​

See Mac app limits for unsupported app types and features.

AreaLimitation or workaround
Background windowsHiding the app does not pause automation. The next action shows it again without activating it.
Multiple windowsInput and menu commands target the agent's current window. Panels beside that window may be inaccessible; panels over it can be controlled.
MenusContext and pop-up menus can bring the window forward temporarily. Only one menu can stay open on the Mac; another click can close it.
Title-bar document menuUnavailable while the app runs in the background.
Drag and dropCannot cross app boundaries or transfer file promises.
GesturesUse gesture-drag and gesture-scroll. Hover, gesture-swipe, custom touch sequences, pinch, and rotate tools are unsupported.
Keyboard layoutApps that inspect key codes receive US-layout codes regardless of your keyboard layout.
SwiftUI disclosure groupsClick the chevron. Clicking the group's center may do nothing.
SwiftUI focused commandsCommands using @FocusedValue can target the wrong window after a second window opens. Restart the app to recover.
Protected windowsCapture protection blocks screenshots, screenshot diffs, and e2e snapshots. Inspection and input still work.
Other toolsHardware buttons, device rotation, shake, fold, TV remote, permission settings, screen recording, JavaScript debugger tools, and Chromium tools are unsupported. Use native-network-logs for traffic; view-network-logs, view-network-request-details, and native-devtools-status are unavailable.

Profiling​

ToolDescription
react-profiler-startStart CPU profiling and React commit capture on the connected Hermes runtime
react-profiler-stopStop profiling and collect the CPU profile and commit tree
react-profiler-statusCheck if a React profiler run records, was saved, was lost or taken over
react-profiler-analyzeAnalyze stored profiling data into a markdown performance report
react-profiler-fiber-treeInspect the React fiber tree as JSON
native-profiler-startStart native profiling: Instruments on iOS and Mac apps, Perfetto on Android
native-profiler-stopStop native profiling and export the trace
native-profiler-analyzeAnalyze an exported native trace into a markdown report
profiler-combined-reportCross-correlate React Profiler and native profiler data
profiler-loadRestore a previously captured session from disk so query tools can use it
profiler-commit-queryQuery React commit data, or the render counts of each component
profiler-cpu-queryQuery Hermes CPU profile data with targeted modes
profiler-stack-queryQuery native trace data for iterative native investigation

Argent caps Instruments recordings at 10 minutes on iOS simulators and Mac apps. Call native-profiler-stop to recover the available trace after the cap or an unexpected exit.

While stop is saving and exporting on the same target, a second stop joins the first. Start and analyze wait for it to finish. Retry profiler-load or profiler-combined-report after stop completes if the tool reports that the capture is still in progress.

Instruments reports exclude CPU time attributed to Argent and Instruments from app hotspots. Percentages still use all sampled CPU time with call stacks. Hang reports label suspect functions from either tool. If the report says the main thread likely waited, treat those functions as context for the wait.

In the top_functions and time_window modes, profiler-cpu-query gives the self time of each call-tree node as a share of the sampled time. A function that runs on several call paths has one row for each path, and top_n counts rows. With react_only, profiler-cpu-query lists only the functions with a PascalCase name, which is the name format of a React component.

react-profiler-stop stores the data of each component only for the hot commits and the commits next to them. A commit is hot when it takes 16 ms or more. react-profiler-stop also stores the render count and the render time of each component over all commits. profiler-commit-query with mode: "render_counts" returns these counts. A session that an older version of Argent stored does not have them.

The report of react-profiler-analyze contains these items:

  • The React render time line: total render time, session length, share of the session, largest share in one second, and number of commits. These values are approximate. React DevTools gives only the largest rendered subtree of each commit as the commit duration. Argent uses the sum of the component render times of a commit when that sum is larger. The values do not include effects or native work. A development build is slower than a production build.
  • "No commit reached 16ms" when no commit takes 16 ms or more. The report does not say that the session is good or bad.
  • A warning when no commit is hot but a commit takes 16 ms or more. Argent can name no component of this commit, so Argent does not store it.
  • A "Most Frequent Re-renders" table. A report with no hot commit contains the table only when a component meets the conditions below. A report with hot commits contains the table only when a component in it is not in the Top Components table. The table lists up to 5 app components, sorted by render time per second. Other components that meet the conditions are named in one line. In a report with hot commits, that line leaves out components already in the Top Components table. A component must re-render in 10 or more commits and use 1 ms or more of render time per second. A row shows what re-rendered. It does not show a problem. React Native components, list internals, animation wrappers, providers and development components are not in the table. When Argent cannot index the source in project_root, the table can also contain library components, and the text above the table says so.
  • In the Top Components table, Renders shows two counts: the re-renders in the stored commits and the re-renders in all commits. An example is 6 / 50.

When a session has no hot commits, the other modes of profiler-commit-query return a message that tells the agent to use render_counts.

While a profiler that react-profiler-start or native-profiler-start started records on a device, interaction tools on that device return no automatic screenshot or element tree. The tool-server sets profiling: true on the tool-call response, and the MCP server returns a note in place of the capture. An explicit describe call returns its tree and no note. Call screenshot or describe to see the screen. Through the MCP server, an interaction tool still waits until the screen stops changing before it returns, so a screenshot or describe called next shows the screen after the interaction. The skip ends when the profiler stops, when the 10-minute recording cap ends the capture, when the app reloads its JavaScript during a React profile, or when the profiler session ends. On an Android emulator or device, Argent also sets the simulator-server of the device to on-demand screenshots while a profiler records. On an emulator, a screenshot then takes one frame in about 100 ms. On a physical device, a screenshot takes about 150 ms to 200 ms. It starts the screen capture for a short time. Interaction tools do not start the screen capture. When the last profiler on the device stops, Argent sets the simulator-server back to the default mode. An older simulator-server ignores the setting and keeps the default mode.

On a shared Metro, react-profiler-start may ask for Metro's logicalDeviceId to select an iOS or Android target. Interaction tools still take the device ID. Argent matches a recording that uses a logicalDeviceId to a device in three steps.

  1. The app writes a marker line to the device log.
  2. Argent reads the logs of the connected Android devices and the booted iOS simulators.
  3. The device whose log contains the marker is the device of the React profile.

When Argent finds no device, interaction tools on the device keep the automatic screenshot and element tree. react-profiler-start then returns a note. Argent cannot read the log of a physical iPhone or of a device from a provider.

For a Mac app, use the Mac app ID even when several devices share Metro.

One React profiler run at a time can record in an app. react-profiler-status returns one of these session_status values:

ValueMeaning
activeA run that this tool-server started records, or react-profiler-stop collects the run
savedNo run records. saved_session names the files of the last run, or of a session from profiler-load
lostArgent did not save the last run of this tool-server. lost_run.cause gives the reason
taken_overAnother session records, or another session replaced the run of this tool-server
not_startedNo run records, and this tool-server has no run on record for the device
no_react_runtimeArgent cannot read the React runtime of the app

The lost_run.cause values are js_reload, cdp_disconnected, session_torn_down, taken_over, stop_failed and ended_in_app. After ended_in_app, the data stays in the app. Call react-profiler-stop to collect the data. A react-profiler-start discards the data.

The tool-server keeps this record in memory only. The shutdown of the tool-server ends the run in the app first. react-profiler-status then returns not_started. The idle shutdown, SIGTERM, an update and an uncaught exception start this shutdown. The tool-server waits a short time for the app to answer. If the app does not answer, or if the shutdown does not run, the run continues in the app. The new tool-server then shows the run as taken_over.

Examples of an exit without the shutdown:

  • A kill -9, or a native abort such as an out-of-memory kill.
  • A SIGHUP. Closing the terminal of a foreground argent server start sends a SIGHUP.
  • argent server stop or an update on Windows. On Windows, SIGTERM ends the process immediately.

A run is stale when its heartbeat is older than 5 minutes, also while you use the app during a long recording. react-profiler-status, react-profiler-renders and react-profiler-fiber-tree refresh the heartbeat of a run that their tool-server records. They do not refresh the heartbeat of a session that replaced this run.

For an active run, react-profiler-status returns stale and heartbeat_age_seconds. It reads these values before it refreshes the heartbeat. Only the first call after the heartbeat goes stale returns stale: true.

react-profiler-start handles a run that records:

  • A run that this tool-server records: react-profiler-start returns already_running with mine: true, stale and heartbeat_age_seconds. The value of mine identifies the tool-server, not the agent. The run can belong to another agent on the same tool-server. Call react-profiler-stop to collect your run. If stale is true and you did not start the run, ask the user before you pass force: true.
  • A fresh run of another session: react-profiler-start returns already_running with mine: false. Ask the user before you pass force: true.
  • A stale run of another tool-server, a run without an owner record, or a lost run of this tool-server: react-profiler-start stops the run and starts a new one. It does the same for any run when you pass force: true. The result has took_over with the replaced session and the reason.

When another session replaced the run, react-profiler-stop fails with REACT_PROFILER_SESSION_TAKEN_OVER, also after that session stopped. It does not stop the other recording. If profiling stopped outside Argent and no session replaced the run, react-profiler-stop collects the data of the run.

On React Native 0.84 and older, Metro allows one debugger for each app. Any connection from a second tool-server, also a read-only react-profiler-status, disconnects the first tool-server. This happens before the second agent can ask the user. Argent records the run of the first tool-server as cdp_disconnected, and its react-profiler-stop fails with REACT_PROFILER_NO_ACTIVE_SESSION, not REACT_PROFILER_SESSION_TAKEN_OVER. On 0.85 and newer, Metro disconnects the earlier debugger only for a page without the supportsMultipleDebuggers capability.

While react-profiler-stop collects a run, wait for its result:

  • react-profiler-status returns active.
  • react-profiler-start returns already_running with mine: true, also when you pass force: true.
  • A second react-profiler-stop fails with REACT_PROFILER_STOP_IN_PROGRESS.

E2E​

The old flow-* names, for example flow-execute, still call these tools. See Record and replay e2e tests.

ToolDescription
e2e-start-recordingStart recording a new e2e test, resetting .argent/e2e/<name>.yaml
e2e-add-stepExecute a tool call and record it as a step in the open recording
e2e-add-echoRecord an echo step that prints a message during replay
e2e-add-scriptRun a local JavaScript or TypeScript file and add it to the open recording
e2e-finish-recordingFinish the recording and write the e2e test to disk
e2e-executeRun a saved e2e test

Design variants​

Staged through Argent Lens so you can compare proposals against the running app. These tools require the argent-lens flag and macOS. The flag is off by default, so argent tools omits them until you enable it.

ToolDescription
propose_variantStage one design variant for one on-screen element
await_user_selectionBlock until you pick among the staged variants

Workspace and maintenance​

ToolDescription
update-argentApply a pending Argent update
dismiss-updatePostpone the update reminder for a number of hours

SDK-only tools​

Argent hides these tools from MCP, so the agent does not see them. Call them with the Argent SDK, argent run <name>, or a tool: step in an e2e test. The SDK exports the UiTree, ForegroundApp and FillResult result types.

ToolDescriptionTool for the agent
terminate-appStop an app without relaunching itrestart-app
ui-treeGet the raw accessibility tree as nested JSON, iOS simulator and Androiddescribe
foreground-appGet the app in front, iOS simulator and AndroidNone
fillSet the text of the focused text fieldkeyboard
native-devtools-statusCheck whether native devtools are connected and injection is preparedAny other native-* tool
native-describe-screenRead the app's native accessibility screen descriptiondescribe
native-user-interactable-view-at-pointInspect the deepest view at a point that would receive touch inputnative-view-at-point with hitTest: true
chromium-storageRead and write localStorage and sessionStorage of the active pagedebugger-evaluate
react-profiler-cpu-summaryReturn the top Hermes CPU hotspots by self-timeprofiler-cpu-query, mode top_functions
react-profiler-component-sourceFind a component's source file, line, and memoization statusreact-profiler-analyze
react-profiler-rendersCount mounted instances of each component in the live fiber treeprofiler-commit-query, mode render_counts
e2e-read-prerequisiteRead the execution prerequisite of an e2e test without running ite2e-execute without prerequisiteAcknowledged
gather-workspace-dataFetch a structured snapshot of the app project's workspaceNone

Some agent tools do not always give the same result as the hidden tool:

  • restart-app always relaunches the app. No agent tool leaves an app stopped. When the app is not installed, restart-app fails and terminate-app succeeds.
  • describe returns pruned text with one line for each element, not the raw tree. On an iOS simulator, the text does not show which element contains which. describe does not give the hidden, covered, alertVisible, keyboardVisible or foregroundApp fields.
  • keyboard types at the cursor and keeps the text that the field holds. fill replaces that text. With no focused field, keyboard drops the text and succeeds, and fill fails with FILL_NO_FOCUSED_FIELD. fill reads the field back, except on a physical iPhone. keyboard does not.
  • native-describe-screen, native-find-views, native-full-hierarchy, native-view-at-point, native-user-interactable-view-at-point and, on iOS, native-network-logs return the same message as native-devtools-status when native devtools are not connected. Their status names the remedy, where native-devtools-status gives state. They fail instead for an Apple system app and for an app that a device provider did not lend. native-profiler-* do not use native devtools.
  • describe shows the disabled and selected states and the VoiceOver hint on an iOS simulator. describe does not show the frames in points, the view class or some traits, such as toggleButton. native-describe-screen returns them.
  • chromium-storage with no key returns every entry. Through debugger-evaluate, a bare localStorage returns {}, so use Object.fromEntries(Object.entries(localStorage)).
  • profiler-cpu-query measures each CPU sample with its own interval and does not list idle time as a function. Thus its times can be different from the times of react-profiler-cpu-summary. react-profiler-cpu-summary lists anonymous functions as (anonymous). profiler-cpu-query counts them as idle.
  • react-profiler-analyze gives the file and the line of the components in its table that it finds in the project. A library component has no file, and a component that is only in a commit cascade has no file. The report shows the source of the five components with the highest total render time. It can show fewer than five, because it needs the file of each component. For other components, the agent searches the source files. When several files define a name, the report selects one file for the platform of the recording and names up to three other files. The report can select the wrong file for a name that many components share, for example Content. The report marks a component that React DevTools records as Memo(...) with [React.memo]. It does not give hasUseCallback or hasUseMemo.
  • react-profiler-component-source fails when project_root is not on the computer of the tool-server. react-profiler-analyze returns the report with a warning. When no component in the report table is in project_root, the warning says so. This can mean that all components in the table are library components, or that project_root is wrong. When project_root holds no components, react-profiler-analyze uses the project root that Metro reports, and the warning says so.
  • react-profiler-renders reads only the top 30 levels of the React fiber tree and counts the mounted components, not the re-renders. For render counts, use profiler-commit-query with mode: "render_counts" after a profiling session.
  • e2e-execute without prerequisiteAcknowledged returns the execution prerequisite and runs no step only when the e2e test has a prerequisite. When the e2e test has no prerequisite, e2e-execute runs the e2e test.

terminate-app works on iOS and tvOS simulators, Android emulators and devices, and Vega Virtual Devices. On an iOS simulator it succeeds with terminated: false when the app is not running or not installed. Android and Vega always report terminated: true. Physical iPhones and Mac apps are not supported yet.

In ui-tree, fields a platform cannot report yet are listed in unsupportedFields. A node is hidden when no part of it is on screen inside its ancestors. On iOS, while a system alert shows, roots holds the system app first and the app it covers second. On Android, roots holds one root per window, topmost first. A system dialog, such as a runtime permission prompt or a crash dialog, sets alertVisible, and every node of the app it covers is covered. When Android hides the app's window under the dialog, foregroundApp is unset. foreground-app returns the same foregroundApp and alertVisible without reading the tree, plus the app's name on iOS.

Footnotes​

Argent marks the tools that only read state with the MCP readOnlyHint annotation. Examples are screenshot, describe, debugger-component-tree, list-devices and the profiler query tools. In plan mode, Claude Code runs these tools without a permission prompt. Tools that change the device, the app or files, and debugger-evaluate, do not have the annotation.