mcpField
N
native-app-performance

native-app-performance

github.com/steipeteDevelopment7.4k243 installsUpdated 1w ago
Repository

About native-app-performance

native-app-performance is a CLI-only skill for recording and analyzing native app Time Profiler traces. It helps developers extract samples, symbolicate stacks, and rank app hotspots without opening Instruments.

Key features

  1. 01Record Time Profiler traces by attach or launch
  2. 02Extract time samples from traces
  3. 03Symbolicate stacks using binary and load address
  4. 04Rank the most active app frames

Use cases

  1. 01Find hotspots in a native app
  2. 02Profile a specific slow operation
  3. 03Analyze traces without opening Instruments

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/steipete/agent-scripts --skill native-app-performance

After installing, type/native-app-performancein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

scripts/
extract_time_samples.py
record_time_profiler.sh
top_hotspots.py

Details

From the project README

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.

Comments

Markdown supported