native-app-performance — Claude Code skill: profile iOS and macOS apps
CLI skill for analyzing native app performance via xctrace and Time Profiler. Records execution traces, extracts samples, symbolicates stack frames, and identifies bottlenecks without opening Instruments.
MIT 251 installs ★ 7,554 updated 2026-10-20
npx skills add steipete/agent-scripts --skill native-app-performance -a claude-codeWhat native-app-performance does
Records Time Profiler traces through xctrace record—either by attaching to a running process or launching the app fresh. Extracts time samples to XML, retrieves the __TEXT load address via vmmap, then symbolicates and ranks the hottest frames in your app.
Three scripts ship with it: record_time_profiler.sh to capture, extract_time_samples.py to export trace data, and top_hotspots.py to symbolicate and rank. Key requirement: ASLR means you must pass the actual __TEXT address from vmmap, and the binary in --binary must match the profiled build (symbols won't line up otherwise).
Everything runs in the terminal. No need to launch Instruments once stacks are symbolicated via atos. Make sure your recording captures the slow path—menu interactions, refresh, lag—not idle stretches.
What it helps with
- capture a Time Profiler trace for iOS or macOS without opening Instruments
- extract hotspots and bottlenecks from an xctrace file
- symbolicate stack frames and rank them by CPU time
- attach to a running process and profile it on the fly
Example prompts for the agent
- Attach to PID 1234 and record 90 seconds of Time Profiler to
/tmp/App.trace - Launch
/path/App.app/Contents/MacOS/App, profile for 60 seconds, then extract the hotspots - Symbolicate
/tmp/time-sample.xmlwith load address 0x100000000 and show the top 30 frames
How to install native-app-performance
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill native-app-performance -a claude-code2Manually: put the files in place
~/.claude/skills/native-app-performance/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/native-app-performance/
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill native-app-performance -a codex2Manually: put the files in place
.agents/skills/native-app-performance/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill native-app-performance -a cursor2Manually: put the files in place
.cursor/skills/native-app-performance/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install steipete/agent-scripts skills/native-app-performance2Manually: put the files in place
.github/skills/native-app-performance/SKILL.md1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill native-app-performance -a gemini-cli2Platform CLI
gemini skills install https://github.com/steipete/agent-scripts --path skills/native-app-performanceManually: put the files in place
.devin/skills/native-app-performance/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill native-app-performance -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about native-app-performance
How do I install native-app-performance in Claude Code?
Run npx skills add steipete/agent-scripts --skill native-app-performance -a claude-code, then open ~/.claude/skills/native-app-performance/SKILL.md.
What does native-app-performance do?
It records Time Profiler traces via xctrace, extracts time samples, symbolicates stack frames, and reveals performance bottlenecks—all from the command line without Instruments.
Why are stacks empty or symbols not resolving?
Check three things: the binary in --binary must match the profiled build, the __TEXT address from vmmap must be fresh (capture it while the app is running), and your trace must capture the slow path (UI interactions, data fetches), not idle time.
Source text
SKILL.md · MIT
--- name: native-app-performance description: "Native app performance: xctrace, Time Profiler, traces, hotspots." --- # 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): ```bash # Start app yourself, then attach xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --attach <pid> ``` 2) Record Time Profiler (launch): ```bash xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --launch -- /path/App.app/Contents/MacOS/App ``` 3) Extract time samples: ```bash scripts/extract_time_samples.py --trace /tmp/App.trace --output /tmp/time-sample.xml ``` 4) Get load address for symbolication: ```bash # While app is running vmmap <pid> | rg -m1 "__TEXT" -n ``` 5) Symbolicate + rank hotspots: ```bash 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`.
© steipete · MIT · steipete/agent-scripts