Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add steipete/agent-scripts --skill native-app-performance -a claude-code
Open on GitHub

What 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.xml with 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-code

2Manually: put the files in place

~/.claude/skills/native-app-performance/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/native-app-performance/

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

Similar skills

All skills for DevOps and infrastructure →

From the same set20

The whole set →
markdown-converter markdown-converter converts documents, spreadsheets, PDF, media, and structured data into Markdown via uvx without manual parser setup. CX Codex +1 346installs codex-first codex-first routes tasks between Claude and Codex workers. Claude handles specifications and judgment while Codex runs implementations and automated reviews. CX Codex +1 288installs browser-use browser-use — a skill to control your real Chrome profile with saved logins and extensions. Routes through the Codex plugin when available, then OpenClaw extension over mcporter, and falls back to direct DevTools attachment if needed. CX Codex +1 278installs github-deep-review github-deep-review — a skill for in-depth GitHub issue and PR review. Reads code, traces the root cause, proposes the best fix, and identifies what must be verified before merge. CX Codex +1 275installs instruments-profiling The instruments-profiling skill guides macOS and iOS profiling with Instruments and xctrace, from trace capture to stack export. Use it when a native app has a slow path. CX Codex +1 242installs ssh-doctor ssh-doctor troubleshoots macOS SSH failures, including pre-auth disconnections, stale sshd sessions, and Remote Login misconfigurations. CX Codex +1 239installs domain-dns-ops The domain-dns-ops skill guides domain, Cloudflare zone, and redirect work. Use it when setting up a domain and checking DNS or HTTPS behavior. CX Codex +1 192installs discord-clawd discord-clawd — a skill to send questions to a Discord-backed agent via OpenClaw relay. Not for archive search—use it to communicate directly with a live session. CX Codex +1 122installs

Project sponsors

Companies that keep this analytics open