Argent Native Profiler
Record and analyze native iOS traces for CPU hotspots, UI hangs, and memory leaks when React Native or native mobile perf regresses beyond JS profiling.
Overview
Argent Native Profiler is an agent skill most often used in Ship (also Operate) that profiles native iOS CPU, UI hangs, and memory leaks using xctrace-backed traces and structured stack queries.
Install
npx skills add https://github.com/software-mansion/argent --skill argent-native-profilerWhat is this skill?
- Five-tool workflow: native-profiler-start/stop, native-profiler-analyze, profiler-stack-query, profiler-load
- iOS xctrace on booted simulator or device; Android explicitly rejected until Perfetto/simpleperf lands
- Structured bottleneck payload from analyze plus drill-down modes: hang_stacks, function_callers, thread breakdown, leak
- Documented investigation patterns linking hang detection → stack query → native source reads
- Reload prior sessions from disk via profiler-load for regression comparisons
- 5 named profiler tools in the documented workflow
- iOS-only backend today with Android on the roadmap
Adoption & trust: 1.9k installs on skills.sh; 1.2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your mobile app stutters or leaks memory but JS profilers cannot explain main-thread hangs or native hotspots.
Who is it for?
Solo or tiny teams on iOS/React Native with Xcode installed who need Instruments-grade traces inside an agent-driven workflow.
Skip if: Android-only debugging today, web frontend performance, or beginners without simulators/devices and Xcode command-line tools.
When should I use this skill?
When diagnosing native-level performance issues—CPU hotspots, UI hangs, or memory leaks—on iOS with xctrace available.
What do I get? / Deliverables
You capture an iOS trace, export analyzable data, and drill hang stacks and leak details to prioritize native fixes before the next release.
- Exported timestamped trace XML
- Structured bottleneck analysis payload
- Stack and leak drill-down reports from profiler-stack-query
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Native trace capture is the canonical ship/perf shelf—used when validating release builds and chasing frame drops before users feel jank. xctrace-backed profiling targets performance subphase work: hangs, CPU, and leaks rather than feature coding or store listing tasks.
Where it fits
Record a trace on a release build before store submission when scroll jank appears on a physical iPhone.
Re-open profiler-load sessions after a user report of escalating memory to see if the same leak signature returned.
Confirm a suspected native module call chain after optimizing React render paths failed to fix hangs.
How it compares
Native Instruments trace workflow—not a substitute for lightweight JS React DevTools profiling or cloud-only crash dashboards.
Common Questions / FAQ
Who is argent-native-profiler for?
Mobile developers, often on React Native stacks, who hit native-level performance or memory issues and already use Xcode tooling.
When should I use argent-native-profiler?
During ship perf passes on release candidates, when reproducing UI hangs on device, and in operate when investigating leak regressions after a production build.
Is argent-native-profiler safe to install?
Profiling implies shell and device access; review the Security Audits panel on this Prism page and audit what the skill package can execute locally.
SKILL.md
READMESKILL.md - Argent Native Profiler
## 1. Tools - `native-profiler-start` — start profiling on a booted device. iOS: xctrace recording for CPU, hangs, and leaks. - `native-profiler-stop` — stop the profiler and export trace data to timestamped XML files. - `native-profiler-analyze` — parse exported trace data and return a structured bottleneck payload. - `profiler-stack-query` — drill into parsed data: hang stacks, function callers, thread breakdown, leak details. - `profiler-load` — list and reload previous trace sessions from disk for re-investigation. --- ## 2. Platform Support - **iOS**: Fully supported. Backend: Xcode Instruments via `xctrace` on a booted simulator or connected device. Requires Xcode command-line tools on PATH. - **Android**: Not yet implemented. An Android backend (Perfetto or simpleperf via `adb`) is planned; today `native-profiler-start` rejects Android serials with a clear "iOS-only for now" error. --- ## 3. Investigation Patterns After `native-profiler-analyze` surfaces findings, use `profiler-stack-query` to drill into root causes: - **Hang detected** → `profiler-stack-query` mode=`hang_stacks` for full native call chains → mode=`function_callers` for the suspected function → read native source. - **CPU hotspot** → `profiler-stack-query` mode=`thread_breakdown` for per-thread distribution → mode=`function_callers` for the dominant function. - **Memory leak** → `profiler-stack-query` mode=`leak_stacks` filtered by `object_type` for responsible frames and libraries. After presenting findings, ask the user whether to investigate further, implement fixes, or stop. After applying fixes, always re-profile the same scenario and compare with `profiler-load`. Report honestly whether the target metric improved, regressed, or stayed flat. If the fix showed no net benefit or introduced regressions elsewhere, say so and reconsider. **Tip:** For reproducible before/after comparisons, record the interaction sequence as a flow using the `argent-create-flow` skill before the first profiling run. Replay with `flow-execute` on subsequent runs to eliminate interaction variance. > **Note:** The `argent-react-native-profiler` instructs to start native profiling automatically alongside React profiling. This skill's workflow and investigation patterns apply in both cases. --- ## 4. Workflow **Complete all steps in order — do not break mid-flow.** ### Step 0: Ensure the target app is running The `native-profiler-start` tool **auto-detects** the running app on the device. You do not need to derive `app_process` manually — just make sure the app is launched. 1. If the app is already running on the device, skip to Step 1 (do not pass `app_process`). 2. If the app is not running, use `launch-app` with the correct bundle ID first. 3. Only pass `app_process` explicitly if the tool reports multiple running user apps and you need to disambiguate. > **Note**: If multiple build flavors are installed (dev, staging, prod), the tool will detect whichever one is currently running. If both are running, it will ask you to specify. ### Step 1: Start recording Call `native-profiler-start` with `device_id` (iOS UDID; Android not yet supported). The tool auto-detects the running app and saves the trace to `/tmp/argent-profiler-cwd/` with a timestamped filename. Let the user interact with the app or drive interaction via simulator tools (see `argent-device-interact` skill). ### Step 2: Stop and export Call `native-profiler-stop` with `device_id`. On iOS this sends SIGINT to xctrace, waits for trace packaging, and exports CPU, hangs, and leaks data to XML. Check `exportDiagnostics` in the response for any export warnings. ### Step 3: Analyze Call `native-profiler-analyze` with `device_id`. Returns a m