native-app-performance — Claude Code skill: profile macOS and iOS apps
A skill that profiles native macOS and iOS apps with xctrace and Time Profiler. Instruments traces get analyzed from the terminal, no Instruments UI needed.
npx skills add harperreed/dotfiles --skill native-app-performance -a claude-codeWhat native-app-performance does
The skill walks the agent through the whole path: capture a Time Profiler run, pull the samples out, symbolicate them, then rank the hottest frames. You can attach to a process that is already running with --attach <pid>, or start the binary yourself with --launch. From there scripts/extract_time_samples.py exports the trace to time-sample XML, and scripts/top_hotspots.py turns those samples into a ranked list of app frames.
Three scripts ship with it: scripts/record_time_profiler.sh handles recording, scripts/extract_time_samples.py does the export, scripts/top_hotspots.py symbolicates and ranks. It is macOS-only, since it leans on xcrun xctrace, vmmap and atos. You need either a running process or a binary path, plus the __TEXT load address from vmmap.
ASLR moves things around on every launch, so the load address has to come from vmmap while the app is alive, not from an earlier session. Rebuild the app and the --binary path needs updating too, because symbols have to match the trace you are reading. Empty stacks usually mean the capture was short or landed on idle time; raise --time-limit and trigger the slow path while recording. Confirm you are profiling the build you think you are — a local one, not the copy sitting in /Applications.
What it helps with
- find hotspots in a native app without opening Instruments
- record a Time Profiler session against a running PID
- analyze an existing
.tracefile from the command line - symbolicate samples and match them to the right binary
- check that the local build is being profiled, not the
/Applicationscopy
Example prompts for the agent
- Record a 90-second Time Profiler run against the running process and save the trace to
/tmp/App.trace - Extract the samples from
/tmp/App.traceand show me the top 30 hotspots - Symbolicate the samples using
/path/App.app/Contents/MacOS/Appand the load address fromvmmap
How to install native-app-performance
1Skills CLI (Vercel)
npx skills add harperreed/dotfiles --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 harperreed/dotfiles --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 harperreed/dotfiles --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 harperreed/dotfiles native-app-performance2Manually: put the files in place
.github/skills/native-app-performance/SKILL.md1Skills CLI (Vercel)
npx skills add harperreed/dotfiles --skill native-app-performance -a gemini-cli2Platform CLI
gemini skills install https://github.com/harperreed/dotfiles --path .claude/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 harperreed/dotfiles --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 harperreed/dotfiles --skill native-app-performance -a claude-code. The skill lands in ~/.claude/skills/native-app-performance/SKILL.md.
What does native-app-performance do?
It records Time Profiler through xctrace, exports the samples, symbolicates them and ranks the top app frames. Instruments never has to be opened.
Why do my samples come back unsymbolicated?
The __TEXT load address is probably stale. ASLR changes it each run, so pull it from vmmap while the app is running and refresh the --binary path after a rebuild.
