Debug

Skill: debug

On load: Read ../../.claude-plugin/plugin.json from this skill's base directory. Display debug v{version} before proceeding.

Debug React Native apps through Metro, console log streams, CDP evaluation, component tree inspection, and network monitoring.

IMPORTANT: Console streams, component trees, and network logs can be large.
Always dispatch a subagent for streaming and tree operations.

Dependencies

Step 0: Pre-Flight Check

Before any debug operation, run all three checks to understand what's available. Run once per session, not per command.

# 1. Metro running?
${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh status

# 2. Simulator booted?
xcrun simctl list devices booted

# 3. App connected to Metro? (only if Metro is up)
${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh targets

metro.sh targets returns a JSON array of debuggable CDP pages. Each entry has appId, title, and deviceName. An empty array [] means Metro is running but no app has connected to it.

Pre-Flight Decision Table

Never return empty results without diagnosing why. If a CDP operation returns nothing, re-run metro.sh targets to check whether the app disconnected mid-session.

Prerequisites

• Metro bundler must be running for CDP features (console via CDP, eval, tree, network)
• logs.sh works without Metro (OS-level log capture)
• Node 22+ required for cdp-bridge.js and hmr.sh (native WebSocket)
• Works with both vanilla React Native and Expo projects (Expo SDK 54+ tested)
• See ${CLAUDE_SKILL_DIR}/references/metro-endpoints.md for Metro HTTP API details

Scripts

All shared scripts live at ${CLAUDE_SKILL_DIR}/../_shared/scripts/. Run them with Bash.

Routing Table

Fallback Logic

Before any CDP operation (eval, tree, network, cdp-bridge.js console), verify the full chain from the Pre-Flight Decision Table. If pre-flight already ran this session, at minimum re-check metro.sh targets to confirm the app is still connected.

1. Metro not running:
   • Console logs requested → fall back to logs.sh (OS-level capture). Note the fallback to the user.
   • CDP required (eval, tree, network) → report: "Metro is not running. Start it with npx react-native start."
2. Metro running but targets empty:
   • Report: "Metro is running but no app is connected. Open your app in the simulator."
   • Do NOT attempt the CDP operation — it will return nothing.
3. CDP operation returns empty after passing pre-flight:
   • Re-run metro.sh targets. If targets disappeared, the app crashed or was closed.
   • Report what changed rather than returning bare empty results.

Workflows

1. Console Logs

When: "show console logs", "JS errors", "what's in the console"

Step 1: Run the Pre-Flight Check (or verify targets if pre-flight already ran this session).

Step 2a (Metro running):

Dispatch Agent:
  subagent_type: general-purpose
  model: haiku
  description: "debug: stream console logs via CDP"
  prompt: |
    1. Run: ${CLAUDE_SKILL_DIR}/../_shared/scripts/cdp-bridge.js console --timeout 10
       This streams console events as NDJSON to stdout.
    2. Parse the NDJSON output.
    3. Summarize:
       - Error count
       - Warning count
       - Notable log entries (first few errors/warnings with messages)
    4. Return a concise text summary.

Step 2b (Metro not running):

Dispatch Agent:
  subagent_type: general-purpose
  model: haiku
  description: "debug: stream console logs via OS capture"
  prompt: |
    1. Run: ${CLAUDE_SKILL_DIR}/../_shared/scripts/logs.sh ios --timeout 10
       This streams JS console logs as NDJSON to stdout.
    2. Parse the NDJSON output.
    3. Summarize:
       - Error count
       - Warning count
       - Notable log entries (first few errors/warnings with messages)
    4. Return a concise text summary.
    5. Note: These logs were captured via OS-level logging (Metro was not running).

2. Evaluate Expression

When: "evaluate", "run this JS", "check state"

Direct (no subagent — output is small):

1. Verify pre-flight passed (Metro up + targets present)
2. Run ${CLAUDE_SKILL_DIR}/../_shared/scripts/cdp-bridge.js eval "expression"
3. Return JSON result directly
4. If empty/error: re-check metro.sh targets before reporting

3. Component Tree

When: "React tree", "component tree", "find component"

Use --find when looking for a specific component (preferred — returns only matches). Use --depth N to limit output size for overview (depth 5 is a good starting point). Only use full tree (no flags) via subagent — output can be 10-100 KB.

Dispatch Agent:
  subagent_type: general-purpose
  model: haiku
  description: "debug: inspect React component tree"
  prompt: |
    1. Run: ${CLAUDE_SKILL_DIR}/../_shared/scripts/cdp-bridge.js tree [--find "ComponentName" if specified] [--depth 5 for overview]
       This outputs the React component tree as JSON.
    2. Parse the JSON tree.
    3. Summarize:
       - Component hierarchy (top-level structure)
       - For matches (if --find was used): component name, props, state
       - Notable patterns (deeply nested components, error boundaries)
    4. Return a concise text summary.

    LOOKING FOR: [insert component name or "full tree overview"]

4. Network Monitor

When: "network requests", "API calls", "what's being fetched"

Dispatch Agent:
  subagent_type: general-purpose
  model: haiku
  description: "debug: monitor network requests"
  prompt: |
    1. Run: ${CLAUDE_SKILL_DIR}/../_shared/scripts/cdp-bridge.js network --timeout 10
       This streams network events as NDJSON to stdout.
    2. Parse the NDJSON events.
    3. Summarize:
       - Total request count
       - URLs requested (grouped by domain if many)
       - Status codes
       - Notable failures (4xx, 5xx, timeouts)
    4. Return a concise text summary.

5. HMR Monitor

When: "HMR updates", "hot reload events", "module changes", "hot module replacement"

Dispatch Agent:
  subagent_type: general-purpose
  model: haiku
  description: "debug: monitor HMR update events"
  prompt: |
    1. Run: ${CLAUDE_SKILL_DIR}/../_shared/scripts/hmr.sh monitor --timeout 30
       This streams HMR events as NDJSON to stdout.
    2. Parse the NDJSON output.
    3. Summarize:
       - Total update count
       - Modules updated (list file paths)
       - Any errors reported
       - Timeline of update-start / update-done cycles
    4. Return a concise text summary.

Tips

• Port resolution for Metro: --port flag > RCT_METRO_PORT env var > default 8081
• Console logs via logs.sh capture OS-level output and work even without Metro
• cdp-bridge.js tree requires the app to be running in dev mode (non-dev builds strip the React DevTools hook)
• For the evaluate workflow, wrap expressions in JSON.stringify() for readable output of objects/arrays

Context Efficiency