Argent Metro DebuggerSAFE

An agentic toolkit to control, debug, and profile iOS and Android apps. Made by Software Mansion.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: argent-metro-debugger
description: 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.
---

## 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` / `XMLHttpRequest` 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:

```bash
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 the URNs it could not reach in `left_running`; re-call with the id after each URN's `<namespace>:<port>:` prefix. On an iOS simulator, also pass the simulator's `udid` to `debugger-component-tree`, so that its tap coordinates are correct when the UI is landscape.

### 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                                                                                       |
| ----------------------- | --------------

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Argent Metro Debugger](https://modelsatlas.com/skills/software-mansion/argent-metro-debugger/badge.svg)](https://modelsatlas.com/skills/software-mansion/argent-metro-debugger/)

Not your listing, or something out of date? Claim or update your listing.