@swmansion/argent 0.6.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/README.md +4 -3
  2. package/agents/argent-environment-inspector.md +4 -2
  3. package/agents/references/quality-control-checklist.md +1 -1
  4. package/bin/ax-service +0 -0
  5. package/dist/cli-cmds.mjs +1 -1
  6. package/dist/mcp-server.mjs +1 -1
  7. package/dist/tool-server.cjs +2218 -1095
  8. package/dylibs/libArgentInjectionBootstrap.dylib +0 -0
  9. package/dylibs/libKeyboardPatch.dylib +0 -0
  10. package/dylibs/libNativeDevtoolsIos.dylib +0 -0
  11. package/package.json +2 -2
  12. package/rules/argent.md +25 -21
  13. package/skills/argent-android-emulator-setup/SKILL.md +29 -0
  14. package/skills/argent-create-flow/SKILL.md +1 -1
  15. package/skills/{argent-simulator-interact → argent-device-interact}/SKILL.md +56 -34
  16. package/skills/{argent-simulator-setup → argent-ios-simulator-setup}/SKILL.md +3 -3
  17. package/skills/argent-metro-debugger/SKILL.md +12 -2
  18. package/skills/{argent-ios-profiler → argent-native-profiler}/SKILL.md +29 -26
  19. package/skills/argent-react-native-app-workflow/SKILL.md +29 -22
  20. package/skills/argent-react-native-optimization/SKILL.md +2 -2
  21. package/skills/argent-react-native-profiler/SKILL.md +9 -9
  22. package/skills/argent-react-native-profiler/references/diagnostic-tools.md +3 -3
  23. package/skills/argent-test-ui-flow/SKILL.md +26 -14
  24. /package/skills/{argent-simulator-interact → argent-device-interact}/references/gesture-examples.md +0 -0
package/dylibs/libKeyboardPatch.dylib CHANGED
Binary file
package/dylibs/libNativeDevtoolsIos.dylib CHANGED
Binary file
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@swmansion/argent",
3
- "version": "0.6.1",
4
- "description": "MCP server for iOS Simulator control",
3
+ "version": "0.7.0",
4
+ "description": "MCP server for iOS Simulator and Android Emulator control",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
package/rules/argent.md CHANGED
@@ -1,39 +1,39 @@
1
1
  ---
2
- description: Argent iOS Simulator Agent — always-on guidance for methodology and tools for working with, interacting, testing and profiling mobile app work
2
+ description: Argent iOS Simulator and Android Emulator Agent — always-on guidance for methodology and tools for working with, interacting, testing and profiling mobile app work
3
3
  alwaysApply: true
4
4
  ---
5
5
 
6
6
  <description>
7
- Argent MCP tools are available in this project for iOS simulator control. Argent MCP tools are the preferred form of interaction with the application.
7
+ Argent MCP tools are available in this project for iOS simulator and Android emulator control. Argent MCP tools are the preferred form of interaction with the application.
8
8
  Running MCP server and managing the Argent toolkit utilises `argent` command - if asked use `argent --help` for reference.
9
9
  To check current version of MCP server run `argent --version` command.
10
10
 
11
11
  Use cases:
12
12
 
13
- - User mentions iOS simulator, device, or app interaction
14
- - The app user is working with is a mobile application which can be run in the simulator
13
+ - User mentions iOS simulator, Android emulator, device, or app interaction
14
+ - The app user is working with is a mobile application which can be run in a simulator/emulator
15
15
  - Any tapping, swiping, typing, screenshotting, or inspecting a running app
16
- - Running, debugging, or testing a React Native app
17
- - Profiling performance or diagnosing re-renders in a React Native app
16
+ - Running, debugging, or testing a React Native app (iOS or Android)
17
+ - Profiling performance or diagnosing re-renders in a React Native app (iOS or Android)
18
18
  </description>
19
19
 
20
20
  <tapping_rule>
21
21
  <important>**Never** derive tap coordinates from a screenshot</important>
22
22
  Before **every** tap, you MUST call a discovery tool and extract coordinates from the result. This is not optional. Preferred tools are, in order:
23
23
 
24
- - `describe` - native app-level components and safely targetable foreground apps.
25
- - `native-describe-screen` - accessibility screen description via injected native devtools
24
+ - `describe` - native app-level components and safely targetable foreground apps (iOS and Android).
25
+ - `native-describe-screen` - accessibility screen description via injected native devtools (iOS only)
26
26
  - `debugger-component-tree` - react-native specific components
27
27
 
28
- `native-user-interactable-view-at-point` / `native-view-at-point` are follow-up diagnostics once you already have a candidate point.
28
+ `native-user-interactable-view-at-point` / `native-view-at-point` are follow-up diagnostics once you already have a candidate point (iOS only).
29
29
 
30
30
  Whenever something changed YOU MUST first call `describe`, or another appropriate discovery tool so you do not hallucinate element positions. Do not guess coordinates if you can use discovery tool. Do not tap if you have not called a discovery tool in the current step. Screenshots alone are never sufficient for coordinates.
31
31
 
32
32
  If a **tap fails twice** at the same coordinates, **stop retrying**. Re-run the discovery tool.
33
33
 
34
- If `describe` fails, **read the exact error before reacting**, follow the recovery guidance in `argent-simulator-interact` to choose the correct next action.
34
+ If `describe` fails, **read the exact error before reacting**, follow the recovery guidance in `argent-device-interact` to choose the correct next action.
35
35
 
36
- Before starting to interact with the app, read the `argent-simulator-interact` skill first.
36
+ Before starting to interact with the app, read the `argent-device-interact` skill first.
37
37
  </tapping_rule>
38
38
 
39
39
  <skill_reading_rule>
@@ -42,13 +42,13 @@ Before starting to interact with the app, read the `argent-simulator-interact` s
42
42
 
43
43
  <general_rules>
44
44
 
45
- - All simulator interactions go through argent MCP tools — never use `xcrun simctl`,
45
+ - All simulator/emulator interactions go through argent MCP tools — never use `xcrun simctl`,
46
46
  raw `curl` to simulator ports, or the simulator-server binary directly.
47
47
  - Before calling any gesture tool for the first time, use ToolSearch to load its schema.
48
48
  - Interaction tools (`gesture-tap`, `gesture-swipe`, `gesture-pinch`, `gesture-rotate`, `gesture-custom`, `launch-app`, etc.) return a screenshot automatically.
49
49
  Call `screenshot` separately only for a baseline before any action or after a delay.
50
50
  - Always open apps with `launch-app` or `open-url` — never tap home screen icons.
51
- - Always use `run-sequence` when performing multiple sequential simulator actions where you don't need to observe the screen between steps. More in `argent-simulator-interact` skill.
51
+ - Always use `run-sequence` when performing multiple sequential simulator actions where you don't need to observe the screen between steps. More in `argent-device-interact` skill.
52
52
  - When the session ends or the user says they are done: call `stop-all-simulator-servers`.
53
53
  If the user started Metro separately, ask whether to call `stop-metro` (specify the port if not 8081).
54
54
  - If tools provided by mcp-server are not sufficient and action can be done using `xcrun` or other commands, use the command. Examples: changing simulator options, performing simulator action such as lock, shake, etc.
@@ -69,17 +69,21 @@ When `is_react_native` is true: load `argent-react-native-app-workflow` skill. U
69
69
  Load the matching skill before starting work and executing tools from argent-mcp — skills contain the full step-by-step
70
70
  procedure and edge-case handling for each workflow.
71
71
 
72
- SIMULATOR SETUP
73
- Skill: `argent-simulator-setup`
74
- When: Beginning a task that involves the simulator, no simulator booted yet, need UDID or simulator-server.
72
+ iOS SIMULATOR SETUP
73
+ Skill: `argent-ios-simulator-setup`
74
+ When: Beginning a task that involves the iOS simulator, no simulator booted yet, need UDID or simulator-server.
75
+
76
+ ANDROID EMULATOR SETUP
77
+ Skill: `argent-android-emulator-setup`
78
+ When: Beginning a task that involves the Android emulator, no emulator running yet, need an adb serial, or about to install an APK.
75
79
 
76
80
  TAPPING, SWIPING, TYPING, GESTURES, SCREENSHOTS, SCROLLING
77
- Skill: `argent-simulator-interact`
81
+ Skill: `argent-device-interact`
78
82
  When: Performing touch interactions, typing, pressing hardware buttons, launching/restarting apps, opening URLs, rotating device, or taking standalone screenshots.
79
83
 
80
84
  RUNNING / BUILDING / DEBUGGING REACT NATIVE APP
81
85
  Skill: `argent-react-native-app-workflow`
82
- When: Project is react-native, starting Metro or running iOS app, build failures, pod issues, lost Metro connection, reading logs, reloading JS bundle, reinstalling app.
86
+ When: Project is react-native, starting Metro or running the iOS or Android app, build failures, pod issues, lost Metro connection, reading logs, reloading JS bundle, reinstalling app.
83
87
 
84
88
  JS EVALUATION, METRO CONNECTION, REACT NATIVE
85
89
  Skill: `argent-metro-debugger`
@@ -89,9 +93,9 @@ REACT APP & COMPONENT PROFILING
89
93
  Use skill: `argent-react-native-profiler`
90
94
  When: To measure performance of specific components, to find app-wide bottlenecks. Investigating re-renders or CPU hotspots, producing ranked performance reports.
91
95
 
92
- NATIVE iOS PROFILING
93
- Use skill: `argent-ios-profiler`
94
- When: Profiling native iOS performance (CPU hotspots, UI hangs, memory leaks via Instruments). Useful as a reference for iOS-specific investigation when running dual profiling via `argent-react-native-profiler`.
96
+ NATIVE PROFILING
97
+ Use skill: `argent-native-profiler`
98
+ When: Profiling native performance (CPU hotspots, UI hangs, memory leaks). iOS only today; Android on the roadmap. Useful as a reference for platform-specific investigation when running dual profiling via `argent-react-native-profiler`.
95
99
 
96
100
  PERFORMANCE OPTIMIZATION
97
101
  Use skill: `argent-react-native-optimization`
package/skills/argent-android-emulator-setup/SKILL.md ADDED
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: argent-android-emulator-setup
3
+ description: Set up and connect to an Android emulator using argent MCP tools. Use when starting a new session on Android, booting an emulator, getting a device serial, or before any UI interaction task.
4
+ ---
5
+
6
+ ## 1. Prerequisites
7
+
8
+ - **Android SDK Platform Tools** on PATH — provides `adb`.
9
+ - **Android Emulator** on PATH — needed to boot AVDs. If you will only use an already-running emulator or a physical device, adb alone is sufficient.
10
+ - An AVD created via Android Studio or `avdmanager create avd`.
11
+
12
+ Verify with `adb version` and `emulator -list-avds`.
13
+
14
+ ## 2. Setup
15
+
16
+ 1. **Find a ready device** — call `list-devices`. Filter for entries with `platform: "android"`. Ready devices (`state: "device"`) come first. Pick the first `serial` (e.g. `emulator-5554`) unless the user specified one.
17
+ 2. **Boot if needed** — if nothing Android is ready, call `boot-device` with `avdName: <name>` from the same call's `avds` list. The tool transparently picks hot vs cold boot: it probes the AVD's `default_boot` snapshot, restores it under a tight deadline when usable, and falls back to a full cold boot otherwise. Hot path is typically ~30s; cold path takes 2–10 min. On any stage failure the tool kills the emulator process it started so your next call starts from a clean state.
18
+ 3. **Metro (for React Native)** — once a device is up, run `adb -s <serial> reverse tcp:8081 tcp:8081` so the device can reach Metro on your host. Repeat if the device restarts. See the `argent-metro-debugger` skill.
19
+
20
+ ## 3. Using the device
21
+
22
+ Pass the Android serial as `udid` to the unified interaction tools — `gesture-tap`, `gesture-swipe`, `describe`, `screenshot`, `launch-app`, `keyboard`, etc. Dispatch is automatic based on the id shape. See `argent-device-interact` for platform-neutral interaction tooling and the Android-specific gotchas section at the bottom of that skill.
23
+
24
+ ## 4. Notes
25
+
26
+ - Serials are the adb device id. iOS UDIDs and Android serials are not interchangeable, but you do NOT need to tell the tools which platform — dispatch is automatic.
27
+ - `describe` on Android returns a shallower tree than iOS (no accessibility-service equivalent), but covers most tap-target discovery.
28
+ - `reinstall-app` on Android always installs with `-g` so first-launch runtime permissions are pre-granted.
29
+ - To kill the emulator when you're done, run `adb -s <serial> emu kill` from a shell.
package/skills/argent-create-flow/SKILL.md CHANGED
@@ -129,7 +129,7 @@ steps:
129
129
 
130
130
  You do not need the user to ask for a flow. Record one proactively when you recognize any of these patterns:
131
131
 
132
- - **About to re-profile**: You completed a profiling session and are about to apply a fix and re-profile. Record the interaction steps now so the re-profile replays them identically (see `argent-react-native-profiler` and `argent-ios-profiler` skills).
132
+ - **About to re-profile**: You completed a profiling session and are about to apply a fix and re-profile. Record the interaction steps now so the re-profile replays them identically (see `argent-react-native-profiler` and `argent-native-profiler` skills).
133
133
  - **Repeating steps**: You have already performed a multi-step interaction sequence once and the task requires doing it again (comparison, retry, re-test).
134
134
  - **Complex path discovered**: You worked through a non-trivial sequence of taps/swipes/navigation to reach a desired app state. Capture it before it is lost.
135
135
  - **User says "again" / "one more time"**: Any request to redo what you just did is a signal to record first, then replay.
package/skills/{argent-simulator-interact → argent-device-interact}/SKILL.md RENAMED
@@ -1,13 +1,19 @@
1
1
  ---
2
- name: argent-simulator-interact
3
- description: Interact with an iOS simulator using argent MCP tools. Use when tapping UI elements, perfroming gestures, scrolling, typing text, pressing hardware buttons, launching apps, opening URLs, taking screenshots.
2
+ name: argent-device-interact
3
+ description: Interact with an iOS simulator or Android emulator using argent MCP tools. Use when tapping UI elements, performing gestures, scrolling, typing text, pressing hardware buttons, launching apps, opening URLs, taking screenshots.
4
4
  ---
5
5
 
6
+ ## Unified tool surface
7
+
8
+ All interaction tools below accept a `udid` parameter and auto-dispatch iOS vs Android based on its shape (UUID → iOS simulator, anything else → Android adb serial). You use the same tool names on both platforms.
9
+
10
+ For platform-specific caveats (Metro `adb reverse`, locked-screen describe errors, etc.), see § 9 Platform-specific notes at the bottom.
11
+
6
12
  ## 1. Before You Start
7
13
 
8
14
  If you delegate simulator tasks to sub-agents, make sure they have MCP permissions.
9
15
 
10
- Use `list-simulators` to find available simulators. **Pick the first result** if specific not specified by user — booted iPhones are listed first. If none are booted, use `boot-simulator` first.
16
+ Use `list-devices` to get a target id. Results are tagged with `platform` (`ios` or `android`); booted/ready devices come first. Pick the first entry that matches the platform you need — if none are ready, call `boot-device` with `udid` (iOS) or `avdName` (Android). See `argent-ios-simulator-setup` / `argent-android-emulator-setup` for full setup flow.
11
17
 
12
18
  **Load tool schemas before first use.** Gesture tools (`gesture-tap`, `gesture-swipe`, `gesture-pinch`, `gesture-rotate`, `gesture-custom`) may be deferred — their parameter schemas are not loaded until fetched. Always use ToolSearch to load the schemas of all gesture tools you plan to use **before** calling any of them. If you skip this step, parameters may be coerced to strings instead of numbers, causing validation errors.
13
19
 
@@ -16,7 +22,7 @@ Use `list-simulators` to find available simulators. **Pick the first result** if
16
22
  1. **Always refer to tapping_rule** from your argent.md rule before tapping.
17
23
  2. Before performing interactions, consider whether they can be **dispatched sequentially** - more on that in `run-sequence`.
18
24
  3. **Use `gesture-swipe` for lists/scrolling**, not `gesture-custom`, unless you need non-linear movement. Consider whether you need multiple swipes, if yes - use `run-sequence`.
19
- 4. **Tap a text field before typing** — try `paste` first, fall back to `keyboard`.
25
+ 4. **Tap a text field before typing** — on iOS try `paste` first then fall back to `keyboard`; on Android use `keyboard` directly (`paste` is iOS-only).
20
26
  5. **Coordinates are normalized** — always 0.0–1.0, not pixels.
21
27
  6. **For native iOS app navigation, prefer `describe` first.** It works on any screen without app restart. Do not navigate from screenshots on regular in-app screens unless `describe` failed to expose a reliable target. Use `native-describe-screen` only when you need app-scoped UIKit properties.
22
28
 
@@ -42,35 +48,35 @@ Common schemes: `messages://`, `settings://`, `maps://?q=<query>`, `tel://<numbe
42
48
 
43
49
  ## 4. Choosing the Right Tool
44
50
 
45
- | Action | Tool | Notes |
46
- | ---------------- | ---------------- | --------------------------------------------------------- |
47
- | Multiple actions | `run-sequence` | Batch steps in one call (no intermediate screenshots) |
48
- | Open an app | `launch-app` | **Always — never tap home-screen icons** |
49
- | Restart an app | `restart-app` | Terminate and relaunch by bundle ID |
50
- | Open URL/scheme | `open-url` | Web pages, deep links, URL schemes |
51
- | Single tap | `gesture-tap` | Buttons, links, checkboxes |
52
- | Scroll/swipe | `gesture-swipe` | Straight-line scroll or swipe |
53
- | Long press | `gesture-custom` | Context menus, drag start |
54
- | Drag & drop | `gesture-custom` | Complex drag interactions |
55
- | Pinch/zoom | `gesture-pinch` | Two-finger pinch with auto-interpolation |
56
- | Rotation | `gesture-rotate` | Two-finger rotation with auto-interpolation |
57
- | Custom gesture | `gesture-custom` | Arbitrary touch sequences, optional interpolation |
58
- | Hardware key | `button` | Home, back, power, volume, appSwitch, actionButton |
59
- | Type text (fast) | `paste` | Form fields — uses clipboard |
60
- | Type text | `keyboard` | Fallback when paste fails; supports Enter, Escape, arrows |
61
- | Rotate device | `rotate` | Orientation changes |
51
+ | Action | Tool | Notes |
52
+ | ---------------- | ---------------- | ---------------------------------------------------------------------- |
53
+ | Multiple actions | `run-sequence` | Batch steps in one call (no intermediate screenshots) |
54
+ | Open an app | `launch-app` | **Always — never tap home-screen icons** |
55
+ | Restart an app | `restart-app` | Terminate and relaunch by bundle ID |
56
+ | Open URL/scheme | `open-url` | Web pages, deep links, URL schemes |
57
+ | Single tap | `gesture-tap` | Buttons, links, checkboxes |
58
+ | Scroll/swipe | `gesture-swipe` | Straight-line scroll or swipe |
59
+ | Long press | `gesture-custom` | Context menus, drag start |
60
+ | Drag & drop | `gesture-custom` | Complex drag interactions |
61
+ | Pinch/zoom | `gesture-pinch` | Two-finger pinch with auto-interpolation |
62
+ | Rotation | `gesture-rotate` | Two-finger rotation with auto-interpolation |
63
+ | Custom gesture | `gesture-custom` | Arbitrary touch sequences, optional interpolation |
64
+ | Hardware key | `button` | Home, back, power, volume, appSwitch, actionButton |
65
+ | Type text (fast) | `paste` | iOS only. Form fields — uses clipboard |
66
+ | Type text | `keyboard` | iOS+Android. Fallback when paste fails; supports Enter, Escape, arrows |
67
+ | Rotate device | `rotate` | Orientation changes |
62
68
 
63
69
  ## 5. Finding Tap Targets
64
70
 
65
71
  IMPORTANT. When moved to a different screen after an action or do not know the coordinates of component, **always** perform proper discovery first.
66
72
 
67
- | App type | Discovery tool | What it returns |
68
- | --------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
69
- | Target app discovery | `describe` | Accessibility element tree for the current simulator screen with normalized frame coordinates. Works on any app, system dialogs, and Home screen — no app restart or `bundleId` required |
70
- | React Native | `debugger-component-tree` | React component tree with names, text, testID, and (tap: x,y) |
71
- | App-scoped native | `native-describe-screen` | Low-level app-scoped accessibility elements with normalized and raw coordinates; requires `bundleId` |
72
- | Permission / system modal overlay | `describe` | `describe` detects system dialogs automatically and returns dialog buttons with tap coordinates. Fall back to `screenshot` only if `describe` does not expose the controls |
73
- | Final visual fallback | `screenshot` | Use only when discovery tools cannot inspect the current UI reliably. Do not derive routine in-app navigation targets from screenshots |
73
+ | App type | Discovery tool | What it returns |
74
+ | --------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
+ | Target app discovery | `describe` | Accessibility element tree for the current device screen (iOS AX-service or Android uiautomator) with normalized frame coordinates. Works on any app, system dialogs, and Home screen — no app restart or `bundleId` required |
76
+ | React Native | `debugger-component-tree` | React component tree with names, text, testID, and (tap: x,y) |
77
+ | App-scoped native | `native-describe-screen` | Low-level app-scoped accessibility elements with normalized and raw coordinates; requires `bundleId` |
78
+ | Permission / system modal overlay | `describe` | `describe` detects system dialogs automatically and returns dialog buttons with tap coordinates. Fall back to `screenshot` only if `describe` does not expose the controls |
79
+ | Final visual fallback | `screenshot` | Use only when discovery tools cannot inspect the current UI reliably. Do not derive routine in-app navigation targets from screenshots |
74
80
 
75
81
  Point follow-up native diagnostics after you already have a candidate point:
76
82
 
@@ -147,13 +153,13 @@ For long-press, drag-and-drop, and other complex sequences, see `references/gest
147
153
 
148
154
  Values: `home`, `back`, `power`, `volumeUp`, `volumeDown`, `appSwitch`, `actionButton`
149
155
 
150
- ### paste — Type text into focused field
156
+ ### paste — Type text into focused field (iOS only)
151
157
 
152
158
  ```json
153
159
  { "udid": "<UDID>", "text": "Hello, world!" }
154
160
  ```
155
161
 
156
- Tap the field first, then paste. Fall back to `keyboard` if it doesn't work.
162
+ Tap the field first, then paste. Fall back to `keyboard` if it doesn't work. On Android the call is rejected by the capability gate ("Tool 'paste' is not supported on android") — use `keyboard` directly.
157
163
 
158
164
  ### keyboard — Type text or press special keys
159
165
 
@@ -196,10 +202,11 @@ Screenshots are downscaled by default (30% of original resolution) to reduce con
196
202
 
197
203
  ### Troubleshooting
198
204
 
199
- | Problem | Solution |
200
- | -------------------- | ------------------------------------------------------------- |
201
- | Screenshot times out | Restart the simulator-server via `stop-simulator-server` tool |
202
- | No booted simulator | Run `boot-simulator` first. |
205
+ | Problem | Solution |
206
+ | ----------------------- | ------------------------------------------------------------- |
207
+ | Screenshot times out | Restart the simulator-server via `stop-simulator-server` tool |
208
+ | No booted iOS simulator | Call `boot-device` with the iOS `udid` |
209
+ | No ready Android device | Call `boot-device` with `avdName` |
203
210
 
204
211
  ---
205
212
 
@@ -270,3 +277,18 @@ Tap a known button, then scroll down:
270
277
  ```
271
278
 
272
279
  Stops on the first error and returns partial results.
280
+
281
+ ---
282
+
283
+ ## 9. Platform-specific notes
284
+
285
+ ### Android
286
+
287
+ - **Metro reachability**: run `adb reverse tcp:8081 tcp:8081` on the device before the RN app starts, or Metro won't be reachable from the device. See `argent-metro-debugger` for the full workflow. Re-run if the device restarts.
288
+ - **First-launch permission prompts**: `reinstall-app` on Android always installs with `-g` so runtime permissions are pre-granted on first launch — no flag to pass.
289
+ - **Locked screen / secure surfaces**: `describe` throws a clear error if it can't capture (keyguard, DRM, Play Integrity). Unlock the device or fall back to `screenshot`.
290
+ - **APK vs .app in `reinstall-app`**: pass `.apk` absolute path on Android; `.app` directory on iOS.
291
+
292
+ ### iOS
293
+
294
+ _(no iOS-only gotchas collected here yet — add them as they come up)_
package/skills/{argent-simulator-setup → argent-ios-simulator-setup}/SKILL.md RENAMED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: argent-simulator-setup
2
+ name: argent-ios-simulator-setup
3
3
  description: Set up and connect to an iOS simulator using argent MCP tools. Use when starting a new session, booting a simulator, getting a simulator UDID, or before any simulator interaction task.
4
4
  ---
5
5
 
@@ -8,8 +8,8 @@ description: Set up and connect to an iOS simulator using argent MCP tools. Use
8
8
  If you delegate simulator tasks to sub-agents, make sure they have MCP permissions.
9
9
 
10
10
  1. **Find a booted simulator**
11
- Use `list-simulators`. Pick the first result — booted iPhones are listed first.
12
- If none are booted, use `boot-simulator` with the desired UDID.
11
+ Use `list-devices`. Filter for entries with `platform: "ios"` — booted iPhones are listed first.
12
+ If none are booted, call `boot-device` with `udid: <chosen UDID>`.
13
13
 
14
14
  2. **Verify connection**
15
15
  All interaction tools (`gesture-tap`, `gesture-swipe`, `gesture-custom`, etc.) auto-start the server if not already running.
package/skills/argent-metro-debugger/SKILL.md CHANGED
@@ -7,11 +7,21 @@ description: Debug a React Native app via Metro CDP using argent debugger tools.
7
7
 
8
8
  The debugger requires **Metro dev server running** (default `localhost:8081`) and **a React Native app connected to Metro** (at least one CDP target). Verify via `debugger-status`.
9
9
 
10
+ ### Android: reverse port for Metro
11
+
12
+ Android emulators and physical devices do not resolve the host's `localhost` by default. Before the RN app can reach Metro, forward port 8081 (or whichever port Metro is on) from the device back to the host:
13
+
14
+ ```bash
15
+ adb -s <serial> reverse tcp:8081 tcp:8081
16
+ ```
17
+
18
+ `<serial>` is the Android `serial` from `list-devices`. Once reversed, the app on the device connects to Metro just like an iOS simulator does, and all `debugger-*` / `network-*` / `react-profiler-*` tools work unchanged. If the device restarts or adb drops, re-run the command. A failing Metro connection on Android almost always means `adb reverse` has not been done or has been lost.
19
+
10
20
  ## 2. Tool Overview
11
21
 
12
- All tools accept `port` (default 8081) AND `device_id` (the iOS Simulator UDID, a.k.a. `logicalDeviceId`). Always make sure you target the correct app on the correct device.
22
+ All tools accept `port` (default 8081) AND `device_id` (the iOS Simulator UDID or Android serial, a.k.a. `logicalDeviceId` — the CDP-reported id that matches the device). Always make sure you target the correct app on the correct device.
13
23
 
14
- One Metro port can serve multiple connected devices (e.g. two simulators on `localhost:8081`). `device_id` pins every debugger/network/profiler call to a specific device so sessions do not collide.
24
+ One Metro port can serve multiple connected devices (e.g. two simulators on `localhost:8081`, or an iOS simulator alongside an Android emulator with `adb reverse` set up). `device_id` pins every debugger/network/profiler call to a specific device so sessions do not collide.
15
25
 
16
26
  ### Connect & diagnostics
17
27
 
package/skills/{argent-ios-profiler → argent-native-profiler}/SKILL.md RENAMED
@@ -1,23 +1,28 @@
1
1
  ---
2
- name: argent-ios-profiler
3
- description: Native iOS profiling for CPU hotspots, UI hangs, and memory leaks via xctrace. Use when diagnosing native-level performance issues on iOS simulators or devices.
2
+ name: argent-native-profiler
3
+ description: Native profiling for CPU hotspots, UI hangs, and memory leaks. Currently iOS-only (xctrace-backed); Android support (Perfetto/simpleperf) is on the roadmap. Use when diagnosing native-level performance issues.
4
4
  ---
5
5
 
6
- ## 1. Tool Overview
6
+ ## 1. Tools
7
7
 
8
- | Tool | Purpose |
9
- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
10
- | `ios-profiler-start` | Start xctrace recording on a booted simulator or device. Captures CPU, hangs, and leaks. Optional: `app_process`, `template_path`. |
11
- | `ios-profiler-stop` | Stop xctrace, export trace data to XML files (timestamped, persist on disk). |
12
- | `ios-profiler-analyze` | Parse exported XML and return structured bottleneck payload (CPU hotspots, UI hangs, leaks). |
13
- | `profiler-stack-query` | Drill into parsed data: hang stacks, function callers, thread breakdown, leak details. |
14
- | `profiler-load` | List and reload previous trace sessions from disk for re-investigation. |
8
+ - `native-profiler-start` — start profiling on a booted device. iOS: xctrace recording for CPU, hangs, and leaks.
9
+ - `native-profiler-stop` — stop the profiler and export trace data to timestamped XML files.
10
+ - `native-profiler-analyze` — parse exported trace data and return a structured bottleneck payload.
11
+ - `profiler-stack-query` — drill into parsed data: hang stacks, function callers, thread breakdown, leak details.
12
+ - `profiler-load` — list and reload previous trace sessions from disk for re-investigation.
15
13
 
16
14
  ---
17
15
 
18
- ## 2. Investigation Patterns
16
+ ## 2. Platform Support
19
17
 
20
- After `ios-profiler-analyze` surfaces findings, use `profiler-stack-query` to drill into root causes:
18
+ - **iOS**: Fully supported. Backend: Xcode Instruments via `xctrace` on a booted simulator or connected device. Requires Xcode command-line tools on PATH.
19
+ - **Android**: Not yet implemented. An Android backend (Perfetto or simpleperf via `adb`) is planned; today `native-profiler-start` rejects Android serials with a clear "iOS-only for now" error.
20
+
21
+ ---
22
+
23
+ ## 3. Investigation Patterns
24
+
25
+ After `native-profiler-analyze` surfaces findings, use `profiler-stack-query` to drill into root causes:
21
26
 
22
27
  - **Hang detected** → `profiler-stack-query` mode=`hang_stacks` for full native call chains → mode=`function_callers` for the suspected function → read native source.
23
28
  - **CPU hotspot** → `profiler-stack-query` mode=`thread_breakdown` for per-thread distribution → mode=`function_callers` for the dominant function.
@@ -27,20 +32,20 @@ After presenting findings, ask the user whether to investigate further, implemen
27
32
 
28
33
  **Tip:** For reproducible before/after comparisons, record the interaction sequence as a flow using the `argent-create-flow` skill before the first profiling run. Replay with `flow-execute` on subsequent runs to eliminate interaction variance.
29
34
 
30
- > **Note:** The `argent-react-native-profiler` instructs to start iOS profiling automatically alongside React profiling. This skill's workflow and investigation patterns apply in both cases.
35
+ > **Note:** The `argent-react-native-profiler` instructs to start native profiling automatically alongside React profiling. This skill's workflow and investigation patterns apply in both cases.
31
36
 
32
37
  ---
33
38
 
34
- ## 3. Workflow
39
+ ## 4. Workflow
35
40
 
36
41
  **Complete all steps in order — do not break mid-flow.**
37
42
 
38
43
  ### Step 0: Ensure the target app is running
39
44
 
40
- The `ios-profiler-start` tool **auto-detects** the running app on the simulator.
45
+ The `native-profiler-start` tool **auto-detects** the running app on the device.
41
46
  You do not need to derive `app_process` manually — just make sure the app is launched.
42
47
 
43
- 1. If the app is already running on the simulator, skip to Step 1 (do not pass `app_process`).
48
+ 1. If the app is already running on the device, skip to Step 1 (do not pass `app_process`).
44
49
  2. If the app is not running, use `launch-app` with the correct bundle ID first.
45
50
  3. Only pass `app_process` explicitly if the tool reports multiple running user apps and you need to disambiguate.
46
51
 
@@ -48,16 +53,16 @@ You do not need to derive `app_process` manually — just make sure the app is l
48
53
 
49
54
  ### Step 1: Start recording
50
55
 
51
- Call `ios-profiler-start` with `device_id` (simulator UDID). The tool auto-detects the running app and saves the trace to `/tmp/argent-profiler-cwd/` with a timestamped filename.
52
- Let the user interact with the app or drive interaction via simulator tools (see `argent-simulator-interact` skill).
56
+ Call `native-profiler-start` with `device_id` (iOS UDID; Android not yet supported). The tool auto-detects the running app and saves the trace to `/tmp/argent-profiler-cwd/` with a timestamped filename.
57
+ Let the user interact with the app or drive interaction via simulator tools (see `argent-device-interact` skill).
53
58
 
54
59
  ### Step 2: Stop and export
55
60
 
56
- Call `ios-profiler-stop` with `device_id`. This sends SIGINT to xctrace, waits for trace packaging, and exports CPU, hangs, and leaks data to XML. Check `exportDiagnostics` in the response for any export warnings.
61
+ Call `native-profiler-stop` with `device_id`. On iOS this sends SIGINT to xctrace, waits for trace packaging, and exports CPU, hangs, and leaks data to XML. Check `exportDiagnostics` in the response for any export warnings.
57
62
 
58
63
  ### Step 3: Analyze
59
64
 
60
- Call `ios-profiler-analyze` with `device_id`. Returns a markdown report with bottlenecks categorized as CPU hotspots, UI hangs, or memory leaks, sorted by severity.
65
+ Call `native-profiler-analyze` with `device_id`. Returns a markdown report with bottlenecks categorized as CPU hotspots, UI hangs, or memory leaks, sorted by severity.
61
66
 
62
67
  ### Step 4: Present findings and ask about next steps
63
68
 
@@ -72,12 +77,12 @@ Use `profiler-stack-query` to investigate specific findings. See §3 Investigati
72
77
  To revisit a previous trace:
73
78
 
74
79
  1. Call `profiler-load` mode=`list` to see available sessions.
75
- 2. Call `profiler-load` mode=`load_instruments` session_id=`<timestamp>` device_id=`<UDID>` to re-parse the XML files.
80
+ 2. Call `profiler-load` mode=`load_native` session_id=`<timestamp>` device_id=`<UDID>` to re-parse the XML files.
76
81
  3. Use `profiler-stack-query` to investigate the reloaded data.
77
82
 
78
83
  ---
79
84
 
80
- ## 4. Understanding Results
85
+ ## 5. Understanding Results
81
86
 
82
87
  Bottlenecks are categorized by severity:
83
88
 
@@ -92,12 +97,10 @@ Each bottleneck type indicates a different class of problem:
92
97
 
93
98
  ---
94
99
 
95
- ## 5. Important Caveats
100
+ ## 6. Important Caveats
96
101
 
97
102
  - **Simulator vs device**: Simulator profiling reflects host Mac performance, not real device hardware. Use device profiling for accurate CPU timings and memory behavior.
98
- - **xctrace availability**: Requires Xcode command-line tools installed. Verify with `xcrun xctrace version`.
103
+ - **xctrace availability (iOS)**: Requires Xcode command-line tools installed. Verify with `xcrun xctrace version`.
99
104
  - **Profiler overhead**: xctrace instrumentation adds CPU load. If `JSLexer`, `JSONEmitter`, or Hermes runtime internals dominate the JS thread in CPU hotspot results, those reflect profiler overhead — not app work. Discount those entries when evaluating findings.
100
105
  - **Run-to-run variance**: Small fluctuations in CPU percentages between runs are normal. Treat only consistent directional changes (across 2+ runs or >15% delta) as actionable signal.
101
106
  - **Live data variability**: If the app fetches live API data, different responses between runs change rendering workload independently of code changes. Note when data-dependent screens show variance.
102
-
103
- ---
package/skills/argent-react-native-app-workflow/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: argent-react-native-app-workflow
3
- description: Step-by-step workflows for developing or debugging React Native apps with iOS simulator. Use when starting the app, debugging Metro, fixing builds, diagnosing runtime errors, or running tests.
3
+ description: Step-by-step workflows for developing or debugging React Native apps on iOS simulator or Android emulator. Use when starting the app, debugging Metro, fixing builds, diagnosing runtime errors, or running tests.
4
4
  ---
5
5
 
6
6
  ## 1. Starting the React Native App
@@ -39,23 +39,27 @@ Do NOT default to `npx react-native start` or `npx react-native run-ios` without
39
39
 
40
40
  1. **Projects with flavors or custom configs**: Use project-specific start script if present (e.g. `npm run start:local`), and start Metro **before** running the app.
41
41
 
42
- ### 1.3 Run the iOS App
42
+ ### 1.3 Run the App
43
43
 
44
44
  In a **separate** terminal (Metro keeps running in the first):
45
45
 
46
- **Use the project's custom build/run script if one exists** (e.g. `npm run ios`, `yarn ios:debug`). Only fall back to the default if no custom scripts are defined:
46
+ **Use the project's custom build/run script if one exists** (e.g. `npm run ios`, `npm run android`, `yarn ios:debug`). Only fall back to the default if no custom scripts are defined:
47
47
 
48
48
  ```bash
49
- npx react-native run-ios
49
+ npx react-native run-ios # iOS
50
+ npx react-native run-android # Android
50
51
  ```
51
52
 
52
- Optional: specify device or simulator, e.g. `npx react-native run-ios --simulator="iPhone 16"`.
53
+ Optional: specify the target device, e.g. `npx react-native run-ios --simulator="iPhone 16"` or `npx react-native run-android --deviceId=<serial>`.
54
+
55
+ **Android only**: after install, run `adb -s <serial> reverse tcp:8081 tcp:8081` so the emulator/device can reach Metro on your host. Repeat if the device restarts or adb drops.
53
56
 
54
57
  **Agent checklist:**
55
58
 
56
59
  - [ ] Metro is already running and shows "ready"
57
60
  - [ ] Command run from project root
58
- - [ ] If simulator not booted: use the `boot-simulator` tool with proper UDID. Refer to the `argent-simulator-setup` skill.
61
+ - [ ] If the device isn't booted: use `boot-device` with the iOS `udid` or Android `avdName`. Refer to the `argent-ios-simulator-setup` / `argent-android-emulator-setup` skill.
62
+ - [ ] Android: `adb -s <serial> reverse tcp:8081 tcp:8081` done.
59
63
 
60
64
  ---
61
65
 
@@ -131,20 +135,21 @@ Once you discover the correct build/run workflow for a project, **save it to pro
131
135
  | App needs reinstalling from .app path | Use `reinstall-app` tool with UDID, bundle ID, and .app path. |
132
136
  | Persistent native build errors | Full clean + reinstall (step 2 above). |
133
137
 
134
- ### 3.5 iOS Simulator Control
138
+ ### 3.5 Device Control
135
139
 
136
- | Action | Tool / Command |
137
- | -------------------------- | -------------------------------------------------- |
138
- | List devices | `list-simulators` tool |
139
- | Boot a simulator | `boot-simulator` tool (pass UDID) |
140
- | Launch an app | `launch-app` tool (pass UDID + bundle ID) |
141
- | Restart an app | `restart-app` tool (pass UDID + bundle ID) |
142
- | Open a URL / deep link | `open-url` tool (pass UDID + URL) |
143
- | Rotate simulator | `rotate` tool |
144
- | Stop simulator server | `stop-simulator-server` tool (for a specific UDID) |
145
- | Stop all simulator servers | `stop-all-simulator-servers` tool |
140
+ | Action | Tool / Command |
141
+ | -------------------------- | ---------------------------------------------------------------------- |
142
+ | List devices | `list-devices` tool (iOS + Android) |
143
+ | Boot an iOS simulator | `boot-device` tool with `udid` |
144
+ | Boot an Android emulator | `boot-device` tool with `avdName` |
145
+ | Launch an app | `launch-app` tool (pass device id + bundle id / package name) |
146
+ | Restart an app | `restart-app` tool (pass device id + bundle id / package name) |
147
+ | Open a URL / deep link | `open-url` tool (pass device id + URL) |
148
+ | Rotate device | `rotate` tool |
149
+ | Stop simulator server | `stop-simulator-server` tool (iOS UDID or Android serial — one device) |
150
+ | Stop all simulator servers | `stop-all-simulator-servers` tool (iOS + Android) |
146
151
 
147
- For full simulator setup workflow, refer to the `argent-simulator-setup` skill.
152
+ For full simulator setup workflow, refer to the `argent-ios-simulator-setup` skill.
148
153
 
149
154
  ---
150
155
 
@@ -210,8 +215,9 @@ If the user's intent is ambiguous (run existing tests, write new tests, or find
210
215
  | Start Metro | `npx react-native start` |
211
216
  | Start Metro (reset cache) | `npx react-native start --reset-cache` |
212
217
  | Run iOS app | `npx react-native run-ios` |
213
- | List simulators | `list-simulators` tool |
214
- | Boot simulator | `boot-simulator` tool |
218
+ | Run Android app | `npx react-native run-android` |
219
+ | List devices | `list-devices` tool (iOS + Android) |
220
+ | Boot a device | `boot-device` tool (pass `udid` for iOS or `avdName` for Android) |
215
221
  | Take screenshot | `screenshot` tool |
216
222
  | Describe screen (a11y tree) | `describe` tool for normal app screens and in-app modals; use `screenshot` only when permission/system overlays are not exposed reliably |
217
223
  | Read JS console logs | `debugger-log-registry` tool |
@@ -220,6 +226,7 @@ If the user's intent is ambiguous (run existing tests, write new tests, or find
220
226
  | Inspect React component tree | `debugger-component-tree` tool |
221
227
  | Run JS in app | `debugger-evaluate` tool |
222
228
  | iOS native logs | `npx react-native log-ios` |
229
+ | Android native logs | `npx react-native log-android` or `adb -s <serial> logcat` |
223
230
  | Clean + reinstall (nuclear) | See §3.1 step 3 |
224
231
 
225
232
  ---
@@ -228,8 +235,8 @@ If the user's intent is ambiguous (run existing tests, write new tests, or find
228
235
 
229
236
  | Skill | When to use |
230
237
  | ------------------------------ | ------------------------------------------------------------------------------- |
231
- | `argent-simulator-setup` | Initial simulator boot and connection setup |
232
- | `argent-simulator-interact` | Tapping, swiping, typing, hardware buttons, gestures on the simulator |
238
+ | `argent-ios-simulator-setup` | Initial simulator boot and connection setup |
239
+ | `argent-device-interact` | Tapping, swiping, typing, hardware buttons, gestures on the simulator/emulator |
233
240
  | `argent-metro-debugger` | Full Metro CDP debugging: component inspection, console logs, JS evaluation |
234
241
  | `argent-react-native-profiler` | Profiling performance, finding re-render issues, CPU hotspots |
235
242
  | `argent-test-ui-flow` | Interactive UI testing with automatic screenshot verification after each action |
package/skills/argent-react-native-optimization/SKILL.md CHANGED
@@ -45,13 +45,13 @@ See [references/semantic-checklist.md](references/semantic-checklist.md) for ful
45
45
 
46
46
  1. Load `argent-react-native-profiler` skill, start dual profiling
47
47
  2. Exercise key user flows (navigate screens the user specified, or all major flows)
48
- 3. Analyze with `react-profiler-analyze` + `ios-profiler-analyze` + `profiler-combined-report`
48
+ 3. Analyze with `react-profiler-analyze` + `native-profiler-analyze` + `profiler-combined-report`
49
49
  4. Cross-reference profiling results with Phase 1–2 findings
50
50
  5. Fix highest-impact issues. Re-profile after architectural changes; batch mechanical fixes. If a recorded flow breaks after a fix (e.g., UI layout changed), follow `argent-create-flow` skill to repair the flow rather than silently discarding it.
51
51
 
52
52
  ### Phase 4: Verify no regressions
53
53
 
54
- Navigate every screen and UI flow within scope, confirm each renders without errors. If no scope was specified, verify the entire app — cover all reachable screens via `argent-simulator-interact`. Use `debugger-log-registry` to check for runtime errors and take screenshots to check for red/yellow error screens. Check for regressions introduced by fixes (e.g., fewer re-renders but higher CPU, or new jank in a different screen). Main agent only.
54
+ Navigate every screen and UI flow within scope, confirm each renders without errors. If no scope was specified, verify the entire app — cover all reachable screens via `argent-device-interact`. Use `debugger-log-registry` to check for runtime errors and take screenshots to check for red/yellow error screens. Check for regressions introduced by fixes (e.g., fewer re-renders but higher CPU, or new jank in a different screen). Main agent only.
55
55
 
56
56
  ## App-wide optimization
57
57