Skip to content
Get packs

Native App Performance Profiling

Record, export and rank CPU hotspots in macOS apps from the command line using xctrace

Source Download skill
Repository
steipete/agent-scripts
Stars
7,433
Licence
MIT
Files
4 files

What it does

When installed, the agent can profile a native macOS app's CPU use from the terminal instead of opening Apple's Instruments app. It records a Time Profiler trace with xctrace, exports the sample data, maps memory addresses to function names using the app binary, and lists the functions that consume the most time so it can suggest where to optimise. It is a guide plus three helper scripts for this workflow.

Great for

  • macOS or iOS developers who want to find slow code paths in a native app
  • Engineers automating performance checks from scripts or CI on a Mac
  • Agents helping a developer interpret why a menu, refresh or other action feels slow

Skip it if

  • Web apps, Electron or other non-native code, since the tools only handle Apple binaries and xctrace traces (wrong tool for the stack)
  • Users without Xcode command line tools on macOS, because xcrun, xctrace, vmmap, otool and atos must be installed and the scripts will fail without them
  • Profiling production or other people's apps without permission, since recording attaches to running processes and captures what they are doing

Try asking

  • “Profile my running app with PID 4321 for 90 seconds and tell me the top hotspots”
  • “Record a Time Profiler trace of my local build at build/App.app and export the samples”
  • “Find the load address of my app with vmmap and rank the top 30 functions by sample count”
  • “Explain why the menu bar refresh is slow using the hotspot output from my trace”
Step-by-step guide: how to use Native App Performance ProfilingInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 4 original files, the MIT licence and an attribution note.

    native-app-performance.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip native-app-performance.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip native-app-performance.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Start the app yourself and use the attach mode when you want to profile a real running session; use launch mode with the exact binary path to avoid profiling the wrong build
  • Trigger the slow action during the recording window, and capture longer if the output has empty stacks
  • Review the scripts and the commands before letting the agent run them, since they execute local tools and write trace files to /tmp

What's inside

  • scripts/extract_time_samples.py
  • scripts/record_time_profiler.sh
  • scripts/top_hotspots.py
  • SKILL.md

Redistributed unmodified from steipete/agent-scripts under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.