1. Prerequisites
The debugger requires
Metro dev server running (default
) and
a React Native app connected to Metro (at least one CDP target). Verify via
.
Android: reverse port for Metro
Android emulators and physical devices do not resolve the host's
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:
bash
adb -s <serial> reverse tcp:8081 tcp:8081
is the Android
from
. Once reversed, the app on the device connects to Metro just like an iOS simulator does, and all
/
/
tools work unchanged. If the device restarts or adb drops, re-run the command. A failing Metro connection on Android almost always means
has not been done or has been lost.
2. Tool Overview
All tools accept
(default 8081) AND
(the iOS Simulator UDID or Android serial, a.k.a.
— 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
, or an iOS simulator alongside an Android emulator with
set up).
pins every debugger/network/profiler call to a specific device so sessions do not collide.
Connect & diagnostics
| Tool | Purpose |
|---|
| Connect to Metro CDP. Returns port, projectRoot, deviceName, appName, , isNewDebugger, connected. The returned is the for every subsequent debugger/network/profiler call. |
| Like connect + loadedScripts, enabledDomains, sourceMapReady. Use to diagnose. |
Reload & recovery
| Tool | Purpose |
|---|
| Reload all connected apps (like pressing "r" in Metro terminal). Needs a CDP target. |
| Terminate and relaunch the app by device id and bundleId. Use when app lost Metro connection. |
Inspection & console
| Tool | Purpose |
|---|
| Full React fiber tree (names, depth, bounding rects, tap coordinates). |
| 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
|
| Get log summary (counts, clusters, file path). Then use / on the flat log file for details. |
| Run a JS expression in the app runtime. |
3. Component Inspection
vs
| | |
|---|
| 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?" |
Both can point to source files, but
is purpose-built for source tracing.
is for orientation and tap-target discovery.
guidance
Applies to both
and
. Set to
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
(component-tree) or
(inspect-element) and increase it incrementally (e.g., start at 50, then grow). Do not use
without a limit on large apps.
4. Golden Rules
- first when something fails — it runs discovery, connection, and returns diagnostics.
- "No CDP targets" → get the app to connect to Metro — use on the device, then retry .
- 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
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
- Call — returns: (log path), , , (top message groups with counts and source file info)
- Search the file using or with patterns from the response.
Large log files: If
exceeds 10 000, delegate the grep exploration to an
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)
| Field | Example | Notes |
|---|
| | Unique grep anchor |
| | ISO 8601 |
| , , | Uppercase, padded to 5 chars |
| or | Relative path from source map; if unavailable |
| | Full message; embedded newlines replaced with space |
Source attribution (file + line) is also available in
returned by
.
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 the log file directly. Use or shell commands with limits using the above file format tips.
- Default to unless you need more.
- Use recent entries.
- gives you the exact text which you may look for
If the file is too large Delegate to an
subagent with the file path, the format spec above, and the specific patterns you need.
Quick Reference
| Action | Tool |
|---|
| Diagnose / check connection | |
| Connect to Metro CDP | |
| Reload JS (already connected) | |
| Relaunch app on device | |
| Inspect component at point | |
| Full component tree | |
| Console log overview | (summary + log file path for /) |
| Evaluate JS | |