Argent Metro Debugger

1. Prerequisites

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.

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. Before the RN app can reach Metro, 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. 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.

2. Tool Overview

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.

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.

Connect & diagnostics

Reload & recovery

Inspection & console

---

3. Component Inspection

debugger-component-tree vs debugger-inspect-element

Both can point to source files, but inspect-element is purpose-built for source tracing. component-tree is for orientation and tap-target discovery.

includeSkipped guidance

Applies to both debugger-component-tree and debugger-inspect-element. Set to true only when debugging filter behavior — e.g., an expected component is missing from output, or you need to inspect a very specific branch of the tree (not just an overview).

Warning: Output can be very large. Always combine with maxNodes (component-tree) or maxItems (inspect-element) and increase it incrementally (e.g., start at 50, then grow). Do not use includeSkipped without a limit on large apps.

---

4. Golden Rules

1. `debugger-status` first when something fails — it runs discovery, connection, and returns diagnostics. 2. "No CDP targets" → get the app to connect to Metro — use restart-app on the device, then retry debugger-status. 3. Never assume one failure is permanent — follow recovery steps before asking the user. For starting Metro and full failure recovery, see argent-react-native-app-workflow and references/failure-scenarios.md.

---

5. Reading Console Logs (Log Registry)

Logs are written to a flat log file on disk. Use the log-registry → grep pattern instead of reading logs inline.

Workflow

1. Call `debugger-log-registry` — returns: file (log path), totalEntries, byLevel, clusters (top message groups with counts and source file info) 2. Search the file using Grep or Read with patterns from the response.

Large log files: If totalEntries exceeds 10 000, delegate the grep exploration to an Explore subagent — pass it the file path, the entry format, and the patterns you need.

Flat log format

One entry per line — fields (whitespace-separated, | delimiter before message)

Source attribution (file + line) is also available in clusters returned by debugger-log-registry.

Log files and messages can be large - Always scope your search, treat the file like a database, not a document.

When reading from the log file:

• Never Read the log file directly. Use grep or shell commands with limits using the above file format tips.
• Default to -m 50 unless you need more.
• Use tail -N recent entries.
• clusters[].message gives you the exact text which you may look for

If the file is too large Delegate to an Explore subagent with the file path, the format spec above, and the specific patterns you need.

---

Quick Reference

Failure Scenarios: Recovery Steps

When a debugger tool fails, use `debugger-status` first to diagnose. Then match the error or situation below and act as specified. Do not retry the same failing tool repeatedly without following the recovery steps.

Source Resolution for inspect-element

debugger-inspect-element tries to resolve each component in the hierarchy to its source file and line. It uses a fallback chain:

1. `_debugStack` (React fiber property) — a stack trace string from the bundled code. When available, the tool symbolicates it via Metro's /symbolicate endpoint to resolve to the original source file, then reads a code fragment from disk. Set resolveSourceMaps: false to skip symbolication and return raw bundled locations instead. 2. `_debugSource` (React fiber property) — contains { fileName, lineNumber, columnNumber } pointing directly to the original source file. No symbolication needed. The tool reads the code fragment from disk automatically. 3. Neither available — the tool returns the component hierarchy with source: null and code: null for all items. The hierarchy (component names) is still useful.

When Source Info Is Missing

If debugger-inspect-element returns all items with source: null, the React Native project's Babel configuration does not inject source information into JSX elements. This is common with the automatic JSX transform (used by Expo SDK 50+ and React Native 0.73+).

To enable source resolution, inform the user that they can add @babel/plugin-transform-react-jsx-source to their project's Babel config. For example, in babel.config.js:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ["babel-preset-expo"], // or 'module:@react-native/babel-preset'
    plugins: [
      "@babel/plugin-transform-react-jsx-source", // enables _debugSource on fibers
    ],
  };
};

After adding the plugin, restart Metro (npx react-native start --reset-cache or npx expo start --clear) and reload the app. The tool will then automatically pick up _debugSource and resolve components to their source files. No extra npm install needed — the plugin ships with babel-preset-expo and @babel/preset-env.