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
| Tool | Description |
|---|---|
list-devices | List iOS simulators, Android emulators and devices, Chromium apps, Mac apps, Vega (Fire TV) devices, and HarmonyOS phones and emulators |
boot-device | Boot a simulator, emulator, Vega Virtual Device, or HarmonyOS emulator, spawn an Electron app, or start a Mac app |
launch-app | Open an app by bundle id (iOS) or package name (Android) |
restart-app | Terminate then relaunch an app |
reinstall-app | Install or reinstall an app, clearing app data and runtime permissions |
open-url | Open a URL or URL scheme on the device |
settings-permissions | Grant, deny, or reset a runtime permission without navigating the Settings UI |
rotate | Set the device orientation to portrait or either landscape |
fold | Fold or unfold a foldable iOS simulator or Android emulator to a posture or a hinge angle |
shake | Shake the device |
button | Press a hardware button: home, back, power, volume, app switch, action button |
tv-remote | Press a TV remote or D-pad button on Apple TV, Android TV, or Vega |
stop-simulator-server | Stop the transport session for one device and free its resources |
stop-all-simulator-servers | Stop every service a device owns: simulator servers, native devtools, TV daemons, native network capture |
stop-metro | Stop 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 repeatskind. It also does not include fields without a value orruntimeKind: "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
foldableorruntimeKind=tv. A simulator in another state, for exampleBooting, 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:
appPathdoes not exist, or it is not a.appdirectory (iOS), an.apkfile (Android), a.vpkgfile (Vega) or a.hapfile (HarmonyOS).bundleIddoes not match the bundle id in the.app, the package name in the.apkor 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.
foldreturns 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
closedoropen. - Unfolded, the UI is landscape.
rotatesets the orientation of the device, not of the UI.Portraitgives 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_OPENEDorOPENED) and the matchingposture. - 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
describeframes 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
| Tool | Description |
|---|---|
screenshot | Capture the device screen |
describe | Get the accessibility / DOM element tree for the current screen |
screenshot-diff | Compare two PNG screenshots and return a visual-diff summary |
await-screen-idle | Block until the screen has rendered content and stopped changing |
await-ui-element | Block 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.describeomits 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
| Tool | Description |
|---|---|
gesture-tap | Tap at normalized coordinates. Mac apps also take a right-click |
gesture-swipe | Smooth swipe or drag between two points |
gesture-scroll | Scroll a Chromium app (mouse wheel) or the scroll view under a point in a Mac app |
gesture-drag | Press, move, and release the mouse in a Chromium app or a Mac app |
gesture-pinch | Pinch to zoom around a center point |
gesture-rotate | Two-finger circular arc that rotates on-screen content |
gesture-custom | Send an arbitrary sequence of touch events for complex gestures |
keyboard | Type text or press special keys |
paste | Put text on the device clipboard and paste it (sim/emu), or insert it in a Mac app |
run-sequence | Execute several interaction steps in a single call |
screen-recording-start | Start recording the screen to an h264 mp4 |
screen-recording-stop | Stop 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
describechanged. - 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
| Tool | Description |
|---|---|
debugger-connect | Connect to the JS runtime CDP debugger |
debugger-status | Report connection status and diagnostics |
debugger-evaluate | Execute JavaScript in the app's runtime: Hermes on device, V8 on Chromium |
debugger-component-tree | List the React component names and testIDs on the current screen |
debugger-inspect-element | Inspect the React component hierarchy at a screen coordinate |
debugger-log-registry | Summarize console logs captured from the app |
debugger-reload-metro | Restart the Metro bundle without restarting the native process |
view-network-logs | Retrieve captured HTTP requests from the running app |
view-network-request-details | Get 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-screenreads the accessibility tree of the app, plus the views with an identifier that the tree does not contain. It does not takeskipClassesorskipClassPrefixes.native-full-hierarchy,native-find-viewsandnative-view-at-pointread 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-viewssearch byidentifierorlabeldoes not find SwiftUI controls.describeshows them. - When a search by
identifierorlabelfinds no view, its result has anotethat refers todescribe.
- SwiftUI puts the identifier and the label of a control on an accessibility element, not on a view. Thus a
native-network-logsreads the requests that the app sends throughNSURLSession. Withstop: true, it fails with the errorNATIVE_NETWORK_LOGS_STOP_UNSUPPORTED. The capture stops when the tool-server disconnects from the app.
The Mac apps section contains the details.
| Tool | Description |
|---|---|
native-full-hierarchy | Get the complete UIKit view tree |
native-find-views | Search views by class, accessibility id, label, tag, or nativeID |
native-view-at-point | Inspect the deepest visible view at a native window point, or with hitTest: true the view that would receive touch input |
native-network-logs | Read 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:
- Call
native-network-logswith the serial of the device and the package name of the app. The first call usually returnsarmed: false. - Call
native-network-logsagain untilarmedistrue. - Do the action that sends the request again.
- Call
native-network-logsagain to read the list of requests.
| Parameter | Effect on Android |
|---|---|
udid | The serial of the device |
bundleId | The package name of the app |
port | The 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. |
limit | The maximum number of requests in the list. Argent returns the most recent requests, oldest first. The default is 50. |
clear | Remove the current requests from the later lists. Their IDs stay valid. |
stop | Stop 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:
| State | Meaning |
|---|---|
| active | Argent captures the OkHttp requests of the app. If Argent captures only some requests, the header line gives the reason. |
| waiting | The app did not load OkHttp yet. The capture starts when the app loads it. |
| unavailable | The 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
CookieandUser-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:
| Tool | What it reports |
|---|---|
launch-app, restart-app | Argent 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-execute | A 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-start | The 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:
stoppedistruewhen 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 theadb reversetunnel of the app.stoppedisfalsewhen 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
| Tool | Description |
|---|---|
chromium-tabs | List, switch, open, and close tabs or BrowserWindows |
chromium-cookies | Read 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 parameter | Description |
|---|---|
macosAppPath | Path to the .app bundle. Argent launches the app in the background. |
macosAppArgs | Executable arguments. Defaults to no arguments. |
udid | Device ID instead of a path. Reuses the last app path, or the newest matching build found by Spotlight. |
force | Restart 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.
| Tool | macOS behavior |
|---|---|
list-devices | Lists running apps started by Argent, with platform: "macos" and kind: "app". |
launch-app | Starts the app if needed. Leaves a running app unchanged. |
restart-app | Quits the app and starts the same bundle again. Rebuild first to test code changes. |
open-url | Delivers the URL to the running app. Web URLs go to the app, not a browser. |
reinstall-app | Unsupported. Rebuild and use restart-app. |
stop-simulator-server, stop-all-simulator-servers | Disconnect 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
| Problem | Action |
|---|---|
| Code signing blocks launch | Follow Configure code signing. |
| The saved app path no longer exists | Call boot-device with the current macosAppPath. |
| The app does not connect during launch | Check the log in the error. Make sure startup does not block the app's main thread. |
| The app uses a launcher script | Point Argent at a bundle whose executable is the native app. |
| The app has no supported window | Open a standard window. Apps with only panels, borderless windows, or a menu bar icon are unsupported. |
| The launch result warns that reconnection is unavailable | After disconnecting, use restart-app. This can occur in sandboxed apps with long bundle identifiers. |
| The Argent library files are missing | Update 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:
| Option | When to use it |
|---|---|
Set ENABLE_HARDENED_RUNTIME = NO for Debug | Use 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 entitlements | Use this when your test build needs the hardened runtime. |
| Sign the Argent library with your app's team | Use this when your development-signed build must retain library validation. |
To sign the library with your team:
- Try to start the app. The launch error provides the
codesigncommand. - Run
security find-identity -v -p codesigningto find your team's Apple Development identity. - Substitute that identity into the provided command and run it yourself. Signing requires access to your keychain.
- 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:
-
In the app target, set
PRODUCT_BUNDLE_IDENTIFIERtocom.example.notes$(ARGENT_ID_SUFFIX). -
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 -
Give the agent the resulting
.apppath and bundle identifier, such ascom.example.notes.login. -
Use that identifier in the e2e test's
launchstep.
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.
| Tool | macOS behavior |
|---|---|
describe | Returns the app's accessibility tree. See fields and identifiers. |
await-ui-element, await-screen-idle | Wait for matching elements or a stable interface using the app tree. |
screenshot | Captures the app window and attached sheets, popovers, alerts, and menus. Other app windows are excluded. |
screenshot-diff | Captures at scale: 1.0. Save baselines at the same scale. No top band is masked. |
gesture-tap | Clicks. Use button: "right" for a context menu or clickCount: 2 for a double-click. |
gesture-drag | Drags with the left button. Equal start and end points produce a long press. |
gesture-scroll | Scrolls the content under the point, like a mouse wheel. durationMs has no effect. |
keyboard | Types Unicode text or sends keys and shortcuts, such as command+a or shift+tab. |
paste | Inserts text into the focused editable control. Leaves the clipboard unchanged and does not invoke app paste handlers. |
run-sequence | Runs tap, scroll, drag, keyboard, paste, and await steps. |
| Native view tools | Require the device's bundleId. Their x and y use points, rather than fractions of the window. |
native-network-logs | Starts 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.
| Field | Meaning |
|---|---|
| Role | AppKit accessibility role, such as AXButton, AXTextField, or AXScrollArea. Web elements use the same roles. |
| Identifier | A stable identifier supplied by your app. See the examples below. |
| Label | The control's label, associated text, or placeholder when no label exists. |
| Value | Current 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. |
password | A password field. Its value is omitted. |
checked | The state of a web checkbox or radio button. |
scrollHidden | The number of elements scrolled out of view. Scroll to bring them into the tree. |
Set identifiers in your app:
| App type | Identifier source |
|---|---|
| AppKit | The control's accessibility identifier |
| SwiftUI | .accessibilityIdentifier("save-button") |
| Web content | data-testid="save-button", or id when data-testid is absent |
| react-native-macos | testID="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"
}
choose and prepared save answers bypass overwrite confirmation. The result does not indicate whether the destination already existed. Check the destination before saving.
| Parameter | Description |
|---|---|
udid | Mac app device ID. |
action | list, choose, cancel, discard, or stub. |
path | For choose or a stub answer: absolute path or ~/ path. Open targets must exist; save destinations need an existing parent folder. |
paths | Multiple open targets, if the dialog allows multiple selection. Use path or paths, not both. |
panel | Panel number from list. Required when more than one panel is open. |
timeoutMs | Wait for a panel before choose, cancel, or discard. Default 5000; maximum 30000. |
stubMode | For stub: answer (default), cancel, or off. |
panelKind | For a prepared answer: open or save. Set this explicitly for repeatable tests. |
| Action | Result |
|---|---|
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.dataandpublic.itemaccept 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.
menu-bar
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..."]
}
| Parameter | Description |
|---|---|
udid | Mac app device ID. |
action | list or choose. |
path | One to nine titles from the top-level menu to the command. |
identifier | Command 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 requirescom.apple.security.get-task-allowon signed builds to avoid an administrator prompt that blocks recording. If you getNATIVE_PROFILER_APP_NOT_DEBUGGABLE, use a development-signed build. In a background session such as SSH, passtemplate_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, includingLeaksandAllocations, 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 setmalloc_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. Userestart-appto remove the overhead before measuring CPU or hangs. -
Stop and recover. Check
warningandexportDiagnosticsfor 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.
| Area | Limitation or workaround |
|---|---|
| Background windows | Hiding the app does not pause automation. The next action shows it again without activating it. |
| Multiple windows | Input and menu commands target the agent's current window. Panels beside that window may be inaccessible; panels over it can be controlled. |
| Menus | Context 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 menu | Unavailable while the app runs in the background. |
| Drag and drop | Cannot cross app boundaries or transfer file promises. |
| Gestures | Use gesture-drag and gesture-scroll. Hover, gesture-swipe, custom touch sequences, pinch, and rotate tools are unsupported. |
| Keyboard layout | Apps that inspect key codes receive US-layout codes regardless of your keyboard layout. |
| SwiftUI disclosure groups | Click the chevron. Clicking the group's center may do nothing. |
| SwiftUI focused commands | Commands using @FocusedValue can target the wrong window after a second window opens. Restart the app to recover. |
| Protected windows | Capture protection blocks screenshots, screenshot diffs, and e2e snapshots. Inspection and input still work. |
| Other tools | Hardware 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
| Tool | Description |
|---|---|
react-profiler-start | Start CPU profiling and React commit capture on the connected Hermes runtime |
react-profiler-stop | Stop profiling and collect the CPU profile and commit tree |
react-profiler-status | Check if a React profiler run records, was saved, was lost or taken over |
react-profiler-analyze | Analyze stored profiling data into a markdown performance report |
react-profiler-fiber-tree | Inspect the React fiber tree as JSON |
native-profiler-start | Start native profiling: Instruments on iOS and Mac apps, Perfetto on Android |
native-profiler-stop | Stop native profiling and export the trace |
native-profiler-analyze | Analyze an exported native trace into a markdown report |
profiler-combined-report | Cross-correlate React Profiler and native profiler data |
profiler-load | Restore a previously captured session from disk so query tools can use it |
profiler-commit-query | Query React commit data, or the render counts of each component |
profiler-cpu-query | Query Hermes CPU profile data with targeted modes |
profiler-stack-query | Query 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 timeline: 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,
Rendersshows two counts: the re-renders in the stored commits and the re-renders in all commits. An example is6 / 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.
- The app writes a marker line to the device log.
- Argent reads the logs of the connected Android devices and the booted iOS simulators.
- 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:
| Value | Meaning |
|---|---|
active | A run that this tool-server started records, or react-profiler-stop collects the run |
saved | No run records. saved_session names the files of the last run, or of a session from profiler-load |
lost | Argent did not save the last run of this tool-server. lost_run.cause gives the reason |
taken_over | Another session records, or another session replaced the run of this tool-server |
not_started | No run records, and this tool-server has no run on record for the device |
no_react_runtime | Argent 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 startsends a SIGHUP. argent server stopor 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-startreturnsalready_runningwithmine: true,staleandheartbeat_age_seconds. The value ofmineidentifies the tool-server, not the agent. The run can belong to another agent on the same tool-server. Callreact-profiler-stopto collect your run. Ifstaleistrueand you did not start the run, ask the user before you passforce: true. - A fresh run of another session:
react-profiler-startreturnsalready_runningwithmine: false. Ask the user before you passforce: true. - A stale run of another tool-server, a run without an owner record, or a lost run of this tool-server:
react-profiler-startstops the run and starts a new one. It does the same for any run when you passforce: true. The result hastook_overwith 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-statusreturnsactive.react-profiler-startreturnsalready_runningwithmine: true, also when you passforce: true.- A second
react-profiler-stopfails withREACT_PROFILER_STOP_IN_PROGRESS.
E2E
The old flow-* names, for example flow-execute, still call these tools. See Record and replay e2e tests.
| Tool | Description |
|---|---|
e2e-start-recording | Start recording a new e2e test, resetting .argent/e2e/<name>.yaml |
e2e-add-step | Execute a tool call and record it as a step in the open recording |
e2e-add-echo | Record an echo step that prints a message during replay |
e2e-add-script | Run a local JavaScript or TypeScript file and add it to the open recording |
e2e-finish-recording | Finish the recording and write the e2e test to disk |
e2e-execute | Run 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.
| Tool | Description |
|---|---|
propose_variant | Stage one design variant for one on-screen element |
await_user_selection | Block until you pick among the staged variants |
Workspace and maintenance
| Tool | Description |
|---|---|
update-argent | Apply a pending Argent update |
dismiss-update | Postpone 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.
| Tool | Description | Tool for the agent |
|---|---|---|
terminate-app | Stop an app without relaunching it | restart-app |
ui-tree | Get the raw accessibility tree as nested JSON, iOS simulator and Android | describe |
foreground-app | Get the app in front, iOS simulator and Android | None |
fill | Set the text of the focused text field | keyboard |
native-devtools-status | Check whether native devtools are connected and injection is prepared | Any other native-* tool |
native-describe-screen | Read the app's native accessibility screen description | describe |
native-user-interactable-view-at-point | Inspect the deepest view at a point that would receive touch input | native-view-at-point with hitTest: true |
chromium-storage | Read and write localStorage and sessionStorage of the active page | debugger-evaluate |
react-profiler-cpu-summary | Return the top Hermes CPU hotspots by self-time | profiler-cpu-query, mode top_functions |
react-profiler-component-source | Find a component's source file, line, and memoization status | react-profiler-analyze |
react-profiler-renders | Count mounted instances of each component in the live fiber tree | profiler-commit-query, mode render_counts |
e2e-read-prerequisite | Read the execution prerequisite of an e2e test without running it | e2e-execute without prerequisiteAcknowledged |
gather-workspace-data | Fetch a structured snapshot of the app project's workspace | None |
Some agent tools do not always give the same result as the hidden tool:
restart-appalways relaunches the app. No agent tool leaves an app stopped. When the app is not installed,restart-appfails andterminate-appsucceeds.describereturns 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.describedoes not give thehidden,covered,alertVisible,keyboardVisibleorforegroundAppfields.keyboardtypes at the cursor and keeps the text that the field holds.fillreplaces that text. With no focused field,keyboarddrops the text and succeeds, andfillfails withFILL_NO_FOCUSED_FIELD.fillreads the field back, except on a physical iPhone.keyboarddoes not.native-describe-screen,native-find-views,native-full-hierarchy,native-view-at-point,native-user-interactable-view-at-pointand, on iOS,native-network-logsreturn the samemessageasnative-devtools-statuswhen native devtools are not connected. Theirstatusnames the remedy, wherenative-devtools-statusgivesstate. 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.describeshows the disabled and selected states and the VoiceOver hint on an iOS simulator.describedoes not show the frames in points, the view class or some traits, such astoggleButton.native-describe-screenreturns them.chromium-storagewith no key returns every entry. Throughdebugger-evaluate, a barelocalStoragereturns{}, so useObject.fromEntries(Object.entries(localStorage)).profiler-cpu-querymeasures 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 ofreact-profiler-cpu-summary.react-profiler-cpu-summarylists anonymous functions as(anonymous).profiler-cpu-querycounts them as idle.react-profiler-analyzegives 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 exampleContent. The report marks a component that React DevTools records asMemo(...)with[React.memo]. It does not givehasUseCallbackorhasUseMemo.react-profiler-component-sourcefails whenproject_rootis not on the computer of the tool-server.react-profiler-analyzereturns the report with awarning. When no component in the report table is inproject_root, thewarningsays so. This can mean that all components in the table are library components, or thatproject_rootis wrong. Whenproject_rootholds no components,react-profiler-analyzeuses the project root that Metro reports, and thewarningsays so.react-profiler-rendersreads only the top 30 levels of the React fiber tree and counts the mounted components, not the re-renders. For render counts, useprofiler-commit-querywithmode: "render_counts"after a profiling session.e2e-executewithoutprerequisiteAcknowledgedreturns the execution prerequisite and runs no step only when the e2e test has a prerequisite. When the e2e test has no prerequisite,e2e-executeruns 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.