Skip to main content
skill CX Codex

instruments-profiling — Claude Code skill: 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.

MIT 242 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 instruments-profiling -a claude-code
Open on GitHub

What instruments-profiling does

The skill covers Time Profiler runs started with xcrun xctrace and attachments to an existing process. It explains how to pass a binary or app bundle, set a capture duration, save a .trace file, and select an iOS device. It also helps the agent choose the intended app instance.

Trace inspection uses xcrun xctrace export, the trace table of contents, and an XPath expression for time-profile data. The exported XML can then be aggregated in Python or Rust. The workflow includes opening the trace in Instruments and narrowing the Call Tree to relevant frames.

A wrong bundle can invalidate the result because LaunchServices may resolve an installed app instead of the local build. Use a direct binary path or attach to a known PID, then verify the process path. iOS stack analysis also needs debug symbols, and xctrace may require Developer Tools permission for Terminal or Xcode.

What it helps with

  • capture a Time Profiler trace for a macOS app
  • attach to a running process by PID
  • target the local build instead of an installed bundle
  • export time-profile samples from a .trace file
  • inspect hot frames in the Call Tree

Example prompts for the agent

  • Profile the local app with Time Profiler and save the result to /tmp/App.trace.
  • Attach to PID <pid>, verify the process path, and investigate the slow operation.
  • Export time-profile data from /tmp/App.trace to /tmp/time-profile.xml for a Python script.

How to install instruments-profiling

1Skills CLI (Vercel)

npx skills add steipete/agent-scripts --skill instruments-profiling -a claude-code

2Manually: put the files in place

~/.claude/skills/instruments-profiling/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/instruments-profiling/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about instruments-profiling

How do I install instruments-profiling in Claude Code?

Run npx skills add steipete/agent-scripts --skill instruments-profiling -a claude-code, then check ~/.claude/skills/instruments-profiling/SKILL.md.

What does instruments-profiling do?

It guides performance and stack profiling for native macOS and iOS apps with Instruments and xctrace, including trace capture and stack export.

Why can Instruments profile the wrong app?

LaunchServices can resolve an installed app instead of the local build. Target the binary directly or attach to a known PID, then verify the process path.

Source text

SKILL.md · MIT
---
name: instruments-profiling
description: "Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports."
metadata:
  short-description: Instruments profiling for macOS/iOS apps
---

# Instruments Profiling (macOS/iOS)

Use this skill when the user wants performance profiling or stack analysis for native apps.
Focus: Time Profiler, `xctrace` CLI, and picking the correct binary/app instance.

## Quick Start (CLI)

- List templates: `xcrun xctrace list templates`
- Record Time Profiler (launch):
  - `xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --launch -- /path/To/App.app`
- Record Time Profiler (attach):
  - Launch app yourself, get PID, then:
  - `xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --attach <pid>`
- Open trace in Instruments:
  - `open -a Instruments /tmp/App.trace`

Note: `xcrun xctrace --help` is not a valid subcommand. Use `xcrun xctrace help record`.

## Picking the Correct Binary (Critical)

**Gotcha: Instruments may profile the wrong app** (e.g., one in `/Applications`) if LaunchServices resolves a different bundle.
Use these rules:

- Prefer direct binary path for deterministic launch:
  - `xcrun xctrace record ... --launch -- /path/App.app/Contents/MacOS/App`
- If launching `.app`, ensure it’s the intended bundle:
  - `open -n /path/App.app`
  - Verify with `ps -p <pid> -o comm= -o command=`
- If both `/Applications/App.app` and a local build exist, explicitly target the local build path.
- After launch, confirm the process path before trusting the trace.

## Command Arguments (xctrace)

- `--template 'Time Profiler'`: template name from `xctrace list templates`.
- `--launch -- <cmd>`: everything after `--` is the target command (binary or app bundle).
- `--attach <pid|name>`: attach to running process.
- `--output <path>`: `.trace` output. If omitted, file saved in CWD.
- `--time-limit 60s|5m`: set capture duration.
- `--device <name|UDID>`: required for iOS device runs.
- `--target-stdout -`: stream launched process stdout to terminal (useful for CLI tools).

## Exporting Stacks (CLI)

- Inspect trace tables:
  - `xcrun xctrace export --input /tmp/App.trace --toc`
- Export raw time-profile samples:
  - `xcrun xctrace export --input /tmp/App.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="time-profile"]' --output /tmp/time-profile.xml`
- Post-process in a script (Python/Rust) to aggregate stacks.

## Instruments UI Workflow

- Template: Time Profiler
- Use “Record” and capture the slow path (startup vs steady-state)
- Call Tree tips:
  - Hide System Libraries
  - Invert Call Tree
  - Separate by Thread
  - Focus on hot frames and call counts

## Gotchas & Fixes

- **Wrong app profiled**: LaunchServices resolves installed app instead of local build.
  - Fix: use direct binary path or `--attach` with known PID.
- **No samples / empty trace**: App exits quickly or never hits work.
  - Fix: longer capture, trigger workload during recording.
- **Privacy prompts**: `xctrace` may need Developer Tools permission.
  - Fix: System Settings → Privacy & Security → Developer Tools → allow Terminal/Xcode.
- **Large XML exports**: `time-profile` exports are huge.
  - Fix: filter with XPath and aggregate offline; don’t print to terminal.

## iOS Specific Notes

- Device: use `xcrun xctrace list devices` and `--device <UDID>`.
- Launch via Xcode if needed; attach with `xctrace --attach`.
- Ensure debug symbols for meaningful stacks.

## Verification Checklist

- Confirm trace process path matches target build.
- Confirm stacks show expected app frames.
- Capture covers the slow operation (startup/refresh). 
- Export stacks for automated diffing if optimizing.

© steipete · MIT · steipete/agent-scripts

Similar skills

All skills for Mobile →

From the same set20

The whole set →
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 native-app-performance 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. CX Codex +1 251installs 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 openclaw-relay openclaw-relay is a Claude Code skill that routes prompts and messages to OpenClaw sessions via local acpx or SSH, resolving targets from named aliases in config/session_aliases.json. CX Codex +1 120installs

Project sponsors

Companies that keep this analytics open