Argent React Native Profiler

This skill is complementary to argent-react-native-optimization, not a replacement for it.

Physical iPhone: not supported; react-profiler-* reject kind: "device". Profile on a simulator.

2. Tool Overview

React Profiler (Hermes / React commits)

Drill-Down Query Tools (call after analyze)

For native profiling (CPU hotspots, UI hangs, memory leaks), see the argent-native-profiler skill.

---

3. Agent Behavior Guidelines

Follow these rules throughout the profiling workflow:

• Start react-profiler-start and native-profiler-start in parallel (two tool calls in one message). Both need device_id; use the same UDID for both so their data can be correlated later. This gives best coverage.
• If the user only wants native profiling, use the argent-native-profiler skill workflow. Only skip native-profiler-start if the user has already explicitly said they don't want native profiling in this session

After analysis: ask about next steps

After presenting the analysis report, always ask the user what they want to do next. Present these options:

1. Investigate further — drill down into specific findings using query tools (CPU call trees, commit cascades, hang stacks, etc.) to identify root causes with confidence before making changes.
2. Implement fixes — apply changes based on the current findings, then re-profile to measure whether the metric changed (improved, regressed, or stayed flat).
3. Done for now — accept the report as-is.

Do NOT silently move on after the report. The report is the starting point, not the end — query tools exist specifically to let you dig deeper into anything the report flags.

During investigation: use query tools proactively

When drilling down, chain query tool calls based on what you find:

• A hot commit -> profiler-commit-query mode=by_index to see all components -> profiler-cpu-query mode=component_cpu for the slowest one -> profiler-cpu-query mode=call_tree for the hot function -> read the source file -> propose a fix.
• A memory leak -> profiler-stack-query mode=leak_stacks to identify the responsible module -> read the native source if actionable.
• A native hang -> profiler-stack-query mode=hang_stacks to get the native call chain -> correlate with React commit timing.

After fixes: always re-profile

When you apply a fix, always re-profile the same scenario afterward. Compare before/after metrics (commit durations, CPU time, render counts) and report honestly: did the target metric improve, stay flat, or regress? Did any other metric get worse? If you need to reference the original data, use profiler-load to reload the pre-fix session. If the fix showed no improvement or introduced a regression, say so explicitly and reconsider the approach.

Use flows for reproducible profiling

When profiling requires a specific interaction sequence (scroll a list, navigate screens, trigger an animation), record the interaction as a flow using the argent-create-flow skill before the first profiling run. Then replay the same flow for every subsequent run. This eliminates interaction variance as a confounder and makes before/after comparisons meaningful. Especially important when:

• You are about to re-profile after applying a fix (Step 8).
• The user asks you to compare multiple profiling sessions.
• The interaction path is more than 2-3 steps long.

---

4. Standard Profiling Workflow

Complete all steps in order — do not break mid-flow.

Step 1: Start profiling

Mind the react-native and ios-native profiler selection mentioned above when starting the session and start the tools. Save startedAtEpochMs from the response — you will need it for annotation offsets. Every subsequent profiler/query call in this session must use the same device_id. Before beginning, define lightweight success criteria with the user: which metric matters most (e.g., totalRenderMs, specific commit duration, render count for a component) and what threshold would be meaningful. This anchors later evaluation. On success:

• if user asked you to perform the profiling, determine how to profile yourself using tools described in argent-device-interact skill.
• if the user stated they wish to perform the interaction themselves — suggest what interaction to perform (e.g. "scroll the list", "switch tabs") and wait for their reply. If you received information about existing profiling session being owned by another agent:
• if session is marked as "stale", you may overtake it without prompting the user for allowance
• if session is NOT "stale" - before taking action and terminating the other session, stop and ask user what you should do, explaining the situation.

Annotate every interaction

After each gesture-tap or gesture-swipe call, record an annotation using the returned timestampMs. Compute offsetMs = timestampMs - startedAtEpochMs. Do this for every interaction — including back-navigation swipes, not just the primary action. Pass all collected annotations to react-profiler-analyze in Step 3.

Step 2: Stop and collect

Call react-profiler-stop and native-profiler-stop in parallel. Only skip native-profiler-stop if you did not start it in Step 1. Note duration_ms and fiber_renders_captured. If fiber_renders_captured: 0, warn the user — React commit data may be missing.

Step 3: Analyze

Call react-profiler-analyze with port, device_id, project_root, platform, and rn_version. The report includes metadata such as reactCompilerEnabled, strictModeEnabled, and buildMode — check these in the returned markdown report.

If you performed interactions using gesture-tap/gesture-swipe, pass annotations to mark when each action occurred. Each annotation's offsetMs must be computed as tapTimestampMs - startedAtEpochMs, where tapTimestampMs is the timestampMs returned by the gesture-tap/gesture-swipe tool and startedAtEpochMs was returned by react-profiler-start. Do not use Date.now() for this calculation — only server-side timestamps from the tool return values.

If dual profiling, also call native-profiler-analyze, then you must call profiler-combined-report for the cross-correlated view — do not skip this step when both profilers ran; the combined report surfaces correlations that individual reports miss.

The analyze report includes CPU hotspots per commit — showing exactly which JS functions ran during each slow React commit. Raw data is saved to disk automatically for later reload.