rn-debugger
The debugger agent diagnoses crashes, blank screens, wrong data, frozen UI, and other broken behavior in a running React Native app. It gathers structured evidence from all available layers before applying minimal fixes.
Overview
Section titled “Overview”| Property | Value |
|---|---|
| Model | Opus |
| Color | Red |
| Skills | rn-device-control, rn-testing, rn-debugging |
| Tools | Bash, Read, Write, Edit, Glob, Grep, all MCP CDP/device tools |
When triggered
Section titled “When triggered”- “I see a RedBox error on the simulator”
- “the screen is blank after navigating to the profile tab”
- “the app froze and nothing responds to taps”
/debug-screencommand
Diagnostic Flow
Section titled “Diagnostic Flow”Step 0: Identify the App
Section titled “Step 0: Identify the App”Determines bundle ID, iOS binary name, and URI scheme from app.json or native config. These values replace all placeholder commands throughout the protocol.
Step 1: Take a Screenshot
Section titled “Step 1: Take a Screenshot”Captures the current screen state immediately before anything changes.
Step 2: Data Gathering
Section titled “Step 2: Data Gathering”Connects via cdp_status, then gathers evidence in parallel:
| Source | Tool |
|---|---|
| JS errors | cdp_error_log |
| Console errors | cdp_console_log(level="error") |
| Network requests | cdp_network_log |
| Current route | cdp_navigation_state |
| Component tree | cdp_component_tree(filter="<route>", depth=3) |
| Native UI tree | device_snapshot |
Step 3: Identify Error Type
Section titled “Step 3: Identify Error Type”Uses the error types matrix to classify the problem:
| Error Type | Where to Look |
|---|---|
| JS runtime error | cdp_error_log |
| Unhandled promise rejection | cdp_error_log |
| RedBox overlay | cdp_component_tree (APP_HAS_REDBOX) |
| console.error() | cdp_console_log(level="error") |
| Native crash (iOS) | collect_logs(sources=["native_ios"]) |
| Native crash (Android) | collect_logs(sources=["native_android"]) |
| Metro bundle error | curl localhost:8081/status |
| Network failure | cdp_network_log (status=0) |
If CDP shows no errors but the app is broken, the problem is native.
Step 4: Narrow Down Root Cause
Section titled “Step 4: Narrow Down Root Cause”Follows different investigation paths depending on the error type:
- RedBox: reads error log stack trace, locates the source line
- Blank screen: checks fiber roots, native logs, Metro status
- Wrong data: inspects store state, network responses, component props
- Wrong navigation: compares current route vs expected
- Frozen app: checks if debugger is paused, tests JS thread responsiveness
Step 5: Apply Fix
Section titled “Step 5: Apply Fix”Reads relevant source files, applies the minimal targeted fix. Fast Refresh applies automatically. Falls back to cdp_reload(full=true) if needed.
Step 6: Verify Recovery
Section titled “Step 6: Verify Recovery”Confirms the fix by checking cdp_status (no errors, no RedBox), taking a new screenshot, verifying cdp_error_log is clear, and re-running the failing action via Maestro.
Safety Constraints
Section titled “Safety Constraints”- Never changes git state
- Retry budget: after 3 failures of the same diagnostic step, stops and reports the blocker
- Always gathers evidence before fixing (Step 2 before reading source files)