How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/software-mansion/argent --skill argent-macos-app-interactBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
argent-device-interact still applies for everything not listed here (run-sequence, await-ui-element, secrets).
Contract
- Needs the
macos-appsflag, which is on by default. When a tool says it is off, tell the user to run the command it names. Do not change the flag yourself. - One app is one device.
list-devicesshows only apps argent started that still run, also those of other sessions: never pick one unless the user named that app or this session started it. - Start an app with
boot-device {macosAppPath: "<abs path>.app"}, never withopenor Xcode. Uselaunch-apponly for an app argent already started: with no recorded path it takes whichever copy Spotlight finds. - Build the
.appwithout starting it:xcodebuild ... build, then take the bundle fromBUILT_PRODUCTS_DIR(xcodebuild -showBuildSettings). Xcode Run andreact-native run-macosstart a copy without the argent library:boot-devicethen fails withalready running ... without the argent library. Retry withforce: true, but ask the user first when they may have work open in that copy. - Never pass
forcewhen the error names another build path; report it. - After a code change: rebuild, then
restart-app. - A start result with a
notethat the app showed no window: taps and screenshots need one. Tell the user, and read the log file it names. - On a hardened-runtime refusal, report it to the user. Do not sign files or change code signing.
- Never activate the app or drive it with
osascript,openor other system tools. - At the end:
stop-all-simulator-servers {devices: ["macos-app-<bundle id>"]}closes argent's connection; the app keeps running.
Per-tool notes
- Swipe or drag:
gesture-drag. Long press:gesture-dragwith the same start and end point. Scroll:gesture-scroll. - Zoom or rotate:
gesture-pinchandgesture-rotatefail; use the app's own controls or shortcuts. - After a right-click (
gesture-tapwithbutton: "right"), the returned tree lists the menu items; a plaingesture-tapon one chooses it (the menu can stay in the tree for a moment while it closes).keyboardescapecloses the menu;enterchooses nothing after a right-click, so tap the item. - No hover: a tooltip is out of reach.
open-url: the URL goes to the running app. A custom scheme must be one the app declares;httpandhttpsgo to the app, not the browser; afile:URL opens that document in the app.- A SwiftUI
DisclosureGroupopens only at its chevron, near the left end of its frame: a tap at the centre passes and does nothing. Tap along the left end in steps of about 0.008 until itsvaluechanges. menu-barfor any menu command. An item listed[disabled]cannot be chosen right now: an edit command (Copy, Select All) needs the text field clicked first; while an alert is open only its own commands work, so answer the alert first. When a menu of the app is open,choosefails: sendkeyboard {key: "escape"}, then choose again.- Open and save panels: never click in the file list, which
describecannot read. Usefile-panel, also for the Delete or Don't Save prompt of an edited new document.
Tree
- Identifiers: AppKit accessibility identifier, SwiftUI
.accessibilityIdentifier(), webdata-testid(elseid), React NativetestID(also on a plainVieworText). - Hint
The Mac is lockedorfallback walk: clicks and typing still work, elements can be missing (an open context menu among them), and ahiddencheck cannot pass. Ask the user to unlock when a target is missing. - An action that fails or has no effect: a minimized window takes no input. Restore it by choosing it in the Window menu with
menu-bar; without such an item, ask the user.
Profiling
Use argent-native-profiler for native profiling or argent-react-native-profiler to capture React performance on a react-native-macos app. Instruments can pause the app during leak checks, delaying actions and inspection. After MACOS_APP_RPC_TIMEOUT, use describe before retrying because the action may already have taken effect.
E2E tests
Read references/e2e.md before recording or writing a test for a Mac app.
react-native-macos
Start Metro before launching a react-native-macos Debug build with boot-device. See argent-react-native-app-workflow for Metro setup. Use describe to inspect the screen. The JavaScript debugger tools are unavailable for Mac apps.