native-app-performance
Native macOS/iOS app performance profiling via xctrace/Time Profiler and CLI-only analysis of Instruments traces. Use when asked to profile, attach, record, or analyze Instruments .trace files, find hotspots, or optimize native app performance without opening Instruments UI.
When & Why to Use This Skill
This Claude skill enables automated, CLI-based performance profiling for native macOS and iOS applications. It streamlines the optimization process by leveraging xctrace to record, extract, and analyze Instruments traces, allowing developers to identify code hotspots and symbolicate stack traces efficiently without needing the Instruments GUI.
Use Cases
- 1. Automated Performance Analysis: Execute profiling sessions via the command line to integrate performance audits directly into developer workflows.
- 2. Bottleneck Identification: Quickly locate CPU-intensive functions and execution hotspots using symbolicated XML samples and ranking scripts.
- 3. Headless Environment Profiling: Analyze application performance on remote machines or CI environments where the graphical Instruments UI is unavailable.
- 4. Native App Optimization: Improve macOS/iOS application responsiveness by analyzing runtime load addresses and execution samples to reduce latency.
| name | native-app-performance |
|---|---|
| description | Native macOS/iOS app performance profiling via xctrace/Time Profiler and CLI-only analysis of Instruments traces. Use when asked to profile, attach, record, or analyze Instruments .trace files, find hotspots, or optimize native app performance without opening Instruments UI. |
Native App Performance (CLI-only)
Goal: record Time Profiler via xctrace, extract samples, symbolicate, and propose hotspots without opening Instruments.
Quick start (CLI)
- Record Time Profiler (attach):
# Start app yourself, then attach
xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --attach <pid>
- Record Time Profiler (launch):
xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --launch -- /path/App.app/Contents/MacOS/App
- Extract time samples:
scripts/extract_time_samples.py --trace /tmp/App.trace --output /tmp/time-sample.xml
- Get load address for symbolication:
# While app is running
vmmap <pid> | rg -m1 "__TEXT" -n
- Symbolicate + rank hotspots:
scripts/top_hotspots.py --samples /tmp/time-sample.xml \
--binary /path/App.app/Contents/MacOS/App \
--load-address 0x100000000 --top 30
Workflow notes
- Always confirm you’re profiling the correct binary (local build vs /Applications). Prefer direct binary path for
--launch. - Ensure you trigger the slow path during capture (menu open/close, refresh, etc.).
- If stacks are empty, capture longer or avoid idle sections.
xcrun xctrace help recordandxcrun xctrace help exportshow correct flags.
Included scripts
scripts/record_time_profiler.sh: record via attach or launch.scripts/extract_time_samples.py: export time-sample XML from a trace.scripts/top_hotspots.py: symbolicate and rank top app frames.
Gotchas
- ASLR means you must use the runtime
__TEXTload address fromvmmap. - If using a new build, update the
--binarypath; symbols must match the trace. - CLI-only flow: no need to open Instruments if stacks are symbolicated via
atos.