Cómo usar
- Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
- Consulta las herramientas, credenciales y entornos necesarios en el documento original.
- Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/software-mansion/argent --skill argent-native-profilerAntes de empezar
- La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
- Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.
1. Tools and platforms
native-profiler-start→native-profiler-stop→native-profiler-analyze: record, export, and report.profiler-stack-query: drill into the analyzed data (hang stacks, function callers, thread breakdown, leaks).profiler-load: reload an earlier session from disk.
iOS (Instruments via xctrace): simulator only; a physical iPhone is not supported. Needs full Xcode (xcrun xctrace version). Reports CPU hotspots, UI hangs and memory leaks.
Android (Perfetto): emulator or physical device. Reports CPU hotspots and UI hangs (with jank reasons and the main thread's blocking function), plus an RSS-growth signal for memory pressure: treat it as a hint to confirm, not a confirmed leak. The app must be debuggable or declare <profileable android:shell="true"/> in its manifest, or no perf_sample callstacks are captured.
For Mac apps (platform: "macos"), use Instruments with full Xcode. If start returns NATIVE_PROFILER_APP_NOT_DEBUGGABLE, use a development-signed build. In a background session such as SSH, template_path: "Time Profiler" also works for CPU and hangs on a signed build without the debugging entitlement. Do not sign files or add entitlements.
If native-profiler-start returns NATIVE_PROFILER_APP_HAS_WEBKIT_HEAP or NATIVE_PROFILER_APP_HEAP_CHECK_FAILED on a Mac app, choose the retry based on what you need to measure.
- For CPU and hangs, use
template_path: "Time Profiler"to keep the app running in its current state. - For leaks, use the bundled template with
malloc_stack_logging: true, even for allocations made during the recording. Save any state you need before retrying because this restarts the app.
While logging is off, avoid Leaks, Allocations, and other templates that use the Allocations instrument on these apps. They can freeze the app.
argent-react-native-profiler starts native profiling alongside React profiling by default; this skill's workflow and investigation patterns apply in both cases.
2. Workflow
Complete all steps in order; do not break mid-flow.
- Start. Launch the app through Argent if needed, then call
native-profiler-start. On iOS and Android, useapp_processif auto-detection is ambiguous or selects the wrong app. On a Mac, the device ID identifies the app. Then let the user interact, or followargent-device-interacton mobile andargent-macos-app-interacton Mac. During recording, usescreenshotordescribewhen needed because interaction tools omit the automatic screenshot and tree. Actions still wait for the screen to settle. On Android emulators, screenshots capture one frame in about 100 ms. On physical Android devices, they briefly wake screen capture and take about 150–200 ms, so use them sparingly. - Stop. Keep the app running through
native-profiler-stop. For Instruments, readwarningandexportDiagnosticsbefore interpreting the report. If the app ended, Instruments stalled, or exports were skipped, repeat the recording when you need the missing data. - Analyze.
native-profiler-analyze. Findings are 🔴 RED (act on it) or 🟡 YELLOW (worth investigating, may be acceptable). - Present and ask. Summarize the key findings, then ask the user whether to investigate further, implement fixes, or stop. Do not move on silently.
- Drill down with
profiler-stack-query(patterns below). - Fix and re-profile the same scenario; compare with the earlier session via
profiler-load(list, thenload_nativewith itssession_idand thedevice_id). Report honestly whether the target metric improved, regressed, or stayed flat; if there is no net benefit or something else regressed, say so and reconsider. For reproducible before/after runs, record the interaction as an e2e test (argent-create-e2eskill) before the first run and replay it withe2e-execute.
Investigation patterns
- Hang → mode
hang_stacksfor the native call chain →function_callersfor the suspected function → read the native source. If a Mac hang overlaps a leak-check pause, repeat the scenario withtemplate_path: "Time Profiler"to measure the hang without leak checks. - CPU hotspot →
thread_breakdownfor the per-thread split →function_callersfor the dominant function. - Memory leak (iOS simulator or Mac app). Keep recording about 25 seconds after the suspected leak so Instruments has time to finish a check. If the report warns that the capture was too short, repeat the recording before drawing conclusions about leaks. Use
leak_stackswithobject_typeto find allocation stacks. For missing stacks such as<Call stack limit reached>, save any needed app state and usemalloc_stack_logging: trueon a separate leak pass. On Mac, reserve it for allocations that predate recording and userestart-appto clear the overhead before measuring CPU or hangs.
3. Caveats
- Simulator and emulator timings reflect the host machine, not device hardware. Compare runs against each other rather than trusting absolute numbers; a physical Android device gives real-hardware numbers.
- Profiler overhead: if
JSLexer,JSONEmitteror Hermes internals dominate the JS thread, that is instrumentation cost, not app work. Discount those entries. - Run-to-run variance: treat only consistent, directional changes (across 2+ runs, or a >15% delta) as signal.
- Live data: if the app fetches live API data, different responses change the workload independently of code changes. Note when data-dependent screens vary.