Argent Metro Debugger
Debug a JS runtime via CDP using argent debugger tools. Primary path is React Native via Metro (iOS / Android / Vega); a subset of the tools (debugger-connect, debugger-status, debugger-evaluate, debugger-log-registry) also drive a Chromium (CDP) app's renderer (an Electron app, or any Chromium browser exposing CDP) through the same surface. Use when connecting to the runtime, inspecting React components, reading console logs, or evaluating JavaScript.
- Skill ID
- software-mansion/argent/argent-metro-debugger
- Publisher
- software-mansion
- Repository
- argent
- Installs
- 285
- Files
- 3
- Synced
- Sep 16, 2026
Open any RiverX project, open the Skills panel in the chat, and search for this identifier. The files are fetched from the source repository at install time.
software-mansion/argent/argent-metro-debuggerInstalls these files- SKILL.md
- references/failure-scenarios.md
- references/source-maps.md
What this skill tells the agent
1. Prerequisites
Physical iPhone: not supported; every debugger-* tool rejects kind: "device".
For React Native (iOS / Android): 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 — it returns status: "connected" or status: "not_connected" with a reason and guidance (it does not fail when the debugger is unreachable).
For Vega (Fire TV): requires a Debug `.vpkg` (a Release build never attaches) and Metro reachable from the device (vega device start-port-forwarding --port 8081 --forward false). Verify via debugger-status. debugger-component-tree, debugger-inspect-element, debugger-reload-metro and the react-profiler-* / profiler-* tools are unavailable there — see the argent-tv-interact skill.
For Chromium (CDP): requires a Chromium/CDP app already available — an Electron app booted via boot-device with electronAppPath, or any Chromium browser exposing a CDP port (auto-discovered by list-devices on 9222 / ARGENT_CHROMIUM_PORTS). The debugger re-uses the page CDP session — port is ignored, device_id is the chromium-cdp-<port> value from list-devices / boot-device. Only debugger-connect, debugger-status, debugger-evaluate, debugger-log-registry, view-network-logs, and view-network-request-details work on Chromium (the latter two read the browser's native CDP Network recording for the active tab instead of the Metro-injected fetch interceptor); debugger-component-tree, debugger-reload-metro, debugger-inspect-element, and the react-profiler-* / profiler-* tools are RN-only and reject Chromium at the capability gate with Tool 'X' is not supported on chromium app.
Android: reverse port for Metro
Android emulators and physical devices do not resolve the host's localhost by default and the RN app fails to reach Metro server. To prevent this issue, forward port 8081 (or whichever port Metro is on) from the device back to the host:
adb -s <serial> reverse tcp:8081 tcp:8081<serial> is the Android serial from list-devices. 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.
2. Tool Overview
All tools accept port (default 8081) AND device_id (the iOS Simulator UDID, Android serial, or Vega serial — a.k.a. logicalDeviceId, the CDP-reported id that matches the device). Vega's legacy inspector reports no logicalDeviceId, so there keep passing the serial.
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.
With two or more devices on one Metro, debugger-connect refuses a udid/serial and hands back the logicalDeviceId to re-target with. That id then keys the session — including for teardown. Pass it in `stop-all-simulator-servers`' `devices` alongside the device id, or the session survives your session end holding its CDP socket, console server and log file. The teardown reports what it could not reach in left_running; re-call with the id it names.
Connect & diagnostics
| Tool | Purpose |
|---|---|
debugger-connect | Connect to the JS runtime's CDP (Metro on iOS / Android / Vega; the page CDP session on Chromium). Returns port, projectRoot (empty on Chromium and on legacy Metro, e.g. Vega), deviceName, appName, logicalDeviceId (absent on Vega), isNewDebugger, connected. When a logicalDeviceId comes back, use it as the device_id for every subsequent debugger call. |
debugger-status | Like connect + loadedScripts, enabledDomains, sourceMapReady (no-op on Chromium). Never fails when the runtime is unreachable — returns { status: "connected", ... } or { status: "not_connected", reason, detail, guidance } (reasons: metro_not_running, no_app_connected, device_mismatch, cdp_unreachable, runtime_unresponsive, stale_connection, reconnecting). Use to diagnose. |
Reload & recovery
| Tool | Purpose |
|---|---|
debugger-reload-metro | Reload all connected apps (like pressing "r" in Metro terminal). Needs a CDP target. |
restart-app | Terminate and relaunch the app by device id and bundleId. Use when app lost Metro connection. |
Inspection & console
| Tool | Purpose |
|---|---|
debugger-component-tree | Full React fiber tree (names, depth, bounding rects, tap coordinates). |
debugger-inspect-element | Inspect at (x, y) using logical pixel coordinates (not normalized 0-1): component hierarchy with source file:line and code fragment. See references/source-maps.md. |
debugger-log-registry | Get log summary (counts, clusters, file path). Then use Grep on the flat log file for details. If it returns status: "not_connected", there is no file — follow its guidance instead of grepping. |
debugger-evaluate | Run a JS expression in the app runtime. |
3. Component Inspection
debugger-component-tree vs debugger-inspect-element
debugger-component-tree | debugger-inspect-element | |
|---|---|---|
| Best for | Layout overview; finding tap targets; user-defined component hierarchy | Identifying a visible element and tracing it to its source file |
| Use when | "What's on screen and where?" | "What component is this and where is it defined?" |