software-mansion/argent

argent-react-native-app-workflow

Step-by-step workflows for developing or debugging React Native apps on iOS simulator or Android emulator.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/software-mansion/argent --skill argent-react-native-app-workflow

Before 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.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Physical iPhone (kind: "device"): Metro debugging and profiling tools reject it. Use a simulator.

react-native-macos app: start Metro (§1.2), then follow argent-macos-app-interact instead of run-macos.

1. Starting the React Native App

1.1 Read the project's configuration first

Before running commands, read the project's build and run setup: every package.json script (custom scripts such as start:local, start:dev, ios, build:ios or flavors take priority over the defaults) and metro.config.js (a non-default port or watchFolders). Do NOT default to npx react-native … or npx expo … without checking. Before the first build, install dependencies if node_modules or ios/Pods is missing.

If the project structure is convoluted, ask the user before proceeding.

Once you know how the project starts Metro, builds and runs the app, and what environment setup it needs, reuse that for the rest of the session instead of rediscovering it.

1.2 Start Metro

  1. If Metro is already running on the project's port, do not start another (§2).
  2. Start it in the background with the project's start script (e.g. npm run start:local, yarn start:dev). With none: npx expo start in an Expo project, npx react-native start otherwise.
  3. Verify with debugger-status: status: "connected" or reason: "no_app_connected" both mean Metro is up (the app just hasn't attached yet); reason: "metro_not_running" means Metro is not reachable.

1.3 Run the App

Start the app only once Metro is ready, from the project root. Use the project's build/run script if one exists (e.g. npm run ios, npm run android, yarn ios:debug); fall back to the defaults below only if there is none.

Pass the target device explicitly, taken from list-devices: use the platform the user named, and do not pick a cabled physical phone just because it is listed. If the device isn't booted yet, boot it with boot-device (see argent-ios-simulator-setup / argent-android-emulator-setup).

bash
npx expo run:ios --device <UDID>                     # Expo
npx expo run:android --device <avdName from list-devices>
npx react-native run-ios --udid <UDID>               # bare RN (needs @react-native-community/cli)
npx react-native run-android --deviceId=<adb-serial>

2. Metro Already on the Port?

The default port is 8081 unless the project configures another. Check it with lsof -i :<port>. If something is listening, debugger-status tells you whether it is Metro: status: "connected" or reason: "no_app_connected" means it is. reason: "metro_not_running" while lsof shows a listener means the port is held by something that is not Metro; the result's detail shows what answered (... (got: ...)). In that case ask the user whether you may kill the process.

To stop a Metro process, use the stop-metro tool.


3. Build, Reload, Reinstall

SituationAction
JS/React only changeddebugger-reload-metro, or restart-app. No rebuild.
Native code, pods or project config changedRebuild with the project's run command (Metro can stay running).
App needs reinstalling from a .app / .apkreinstall-app.

When a build fails (e.g. xcodebuild exit code 65), try the simplest fix first: clean the build folder and retry, then clear caches and reinstall dependencies and pods.

After 2-3 failed build or run attempts, STOP and ask the user for guidance. The user may know about required env vars, Xcode version requirements, custom build configurations, monorepo-specific setup, or required external services. If the correct build approach is not obvious, ask the user early rather than guessing.


4. Runtime Problems in the App

Problem typeWhere to look
JavaScript errors / logsdebugger-log-registry for a summary and the log file path, then Grep the file
React component hierarchydebugger-component-tree, or debugger-inspect-element at logical pixel coordinates (not normalized 0-1)
App statedebugger-evaluate to run JavaScript in the app's runtime
Native crashes / native stackiOS: ~/Library/Logs/DiagnosticReports/. Android: adb -s <serial> logcat -d, with -b crash for crashes only

If list-devices returns a hint about the adb server, prefix the adb command above as the hint shows.

For connection failures, component inspection and searching the console log file, use the argent-metro-debugger skill.

Do not open the React Native DevMenu by default; use the argent tools instead.


5. Testing the App

Ask the user before running tests: which suite (unit, E2E, or both), whether to use existing CI commands, and whether they want you to run existing tests, write new ones, or explore test cases yourself. Find the test commands in package.json and the test config (Jest, Detox, …).

For interactive UI testing with screenshot verification after each action, use the argent-test-ui-flow skill. For visible UI changes, follow the argent-screenshot-diff skill when stable before/after screenshots add meaningful pixel-visible evidence.

from this repository

More skills

All skills
software-mansion
Community

argent-android-emulator-setup

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.

1h installs
6
GitHub stars
3.2K
Updated
Nov 19
software-mansion
Community

argent-create-e2e

Create, record, edit, replay, or repair reusable Argent e2e test YAML files. Use when the user asks to record, replay, or run an e2e test or a repeatable device path, set up profiling or an A/B comparison, or invoke the authoring engine behind argent-qa-e2e. Also use before repeating three or more interactions. For one-off UI checks, acceptance-driven regression tests, or screen video, use argent-test-ui-flow, argent-qa-e2e, or argent-screen-recording respectively.

1h installs
6
GitHub stars
3.2K
Updated
Nov 19
software-mansion
Community

argent-device-interact

Interact with an iOS simulator or iPhone, Android emulator or phone, or Chromium (CDP) app using argent MCP tools. Use when tapping UI elements, performing gestures, scrolling/swiping, typing text, pressing hardware buttons, launching apps, opening URLs, taking screenshots, waiting for an element to appear or disappear, or checking visible app state after interactions. Not for TV targets.

1h installs
6
GitHub stars
3.2K
Updated
Nov 19
software-mansion
Community

argent-ios-device-interact

Drive a physical iPhone through argent. Use when a physical iPhone is involved (a list-devices iOS entry with kind "device") and ONLY then; never for a simulator. For cable, trust, or signing problems read argent-ios-device-setup.

1h installs
6
GitHub stars
3.2K
Updated
Nov 19