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.

⭐277stars🔀46forks📁View on GitHub🕐Updated Dec 31, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill enables professional-grade performance profiling for native macOS and iOS applications using a CLI-only workflow. It automates the use of Apple's xctrace and Time Profiler to record, extract, and analyze performance data, allowing developers to identify code hotspots and optimize application speed without ever opening the Instruments GUI. By streamlining symbolication and sample ranking, it transforms complex trace data into actionable optimization insights.

Use Cases

  • Automated Performance Analysis: Integrate performance recording into automated testing pipelines to detect speed regressions in native macOS/iOS apps.
  • Remote Environment Profiling: Conduct deep performance traces on remote build servers or headless environments where the Instruments graphical interface is unavailable.
  • Hotspot Identification: Automatically symbolicate stack traces and rank the most CPU-intensive functions to pinpoint specific code bottlenecks.
  • Efficient Debugging: Quickly attach to running processes or launch new binaries via CLI to capture precise timing data during specific user interactions or slow paths.
namenative-app-performance
descriptionNative 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)

  1. Record Time Profiler (attach):
# Start app yourself, then attach
xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --attach <pid>
  1. Record Time Profiler (launch):
xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --launch -- /path/App.app/Contents/MacOS/App
  1. Extract time samples:
scripts/extract_time_samples.py --trace /tmp/App.trace --output /tmp/time-sample.xml
  1. Get load address for symbolication:
# While app is running
vmmap <pid> | rg -m1 "__TEXT" -n
  1. 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 record and xcrun xctrace help export show 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 __TEXT load address from vmmap.
  • If using a new build, update the --binary path; symbols must match the trace.
  • CLI-only flow: no need to open Instruments if stacks are symbolicated via atos.