native-app-performance

---
name: native-app-performance
description: "Use when working with native app performance: xctrace, Time Profiler, traces, hotspots from steipete/agent-scripts."
source: https://github.com/steipete/agent-scripts/tree/main/skills/native-app-performance
generated: 2026-05-27T20:56:01.074Z
category: tool
audience: engineers
---

## When to use

- Using the native-app-performance skill's upstream workflow, guardrails, and local-tool assumptions.
- Auditing commands or operational steps before changing native app performance behavior.
- Needing a compact agent reference for native app performance: xctrace, Time Profiler, traces, hotspots.

## Key concepts

### Quick start (CLI)

1) Record Time Profiler (attach): 2) Record Time Profiler (launch): 3) Extract time samples: 4) Get load address for symbolication: 5) Symbolicate + rank hotspots:.

### 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/recordtimeprofiler.sh: record via attach or launch. scripts/extracttimesamples.py: export time-sample XML from a trace. scripts/tophotspots.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.

## API reference

```
npx skills add steipete/agent-scripts --skill native-app-performance
```

Install the native-app-performance skill from steipete/agent-scripts.

```
npx skills add steipete/agent-scripts --skill native-app-performance
```

```
xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --attach <pid>.
```

Command or snippet documented by the upstream native-app-performance skill.

```
# Start app yourself, then attach
xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --attach <pid>
```

```
xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --launch ...
```

Command or snippet documented by the upstream native-app-performance skill.

```
xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --launch -- /path/App.app/Contents/MacOS/App
```

```
scripts/extracttimesamples.py --trace /tmp/App.trace --output /tmp/time-sample.xml.
```

Command or snippet documented by the upstream native-app-performance skill.

```
scripts/extract_time_samples.py --trace /tmp/App.trace --output /tmp/time-sample.xml
```

```
vmmap <pid> | rg -m1 "TEXT" -n.
```

Command or snippet documented by the upstream native-app-performance skill.

```
# While app is running
vmmap <pid> | rg -m1 "__TEXT" -n
```

```
scripts/tophotspots.py --samples /tmp/time-sample.xml \.
```

Command or snippet documented by the upstream native-app-performance skill.

```
scripts/top_hotspots.py --samples /tmp/time-sample.xml \
  --binary /path/App.app/Contents/MacOS/App \
  --load-address 0x100000000 --top 30
```

## Gotchas

- Always confirm you’re profiling the correct binary (local build vs /Applications). Prefer direct binary path for --launch.

---
Generated by SkillMake from https://github.com/steipete/agent-scripts/tree/main/skills/native-app-performance on 2026-05-27T20:56:01.074Z.
Verify against source before relying on details.

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