Instruments Profiler

A Claude Code Skill that fully automates Xcode Instruments profiling for iOS/macOS apps — from recording to analysis to actionable recommendations.

What It Does

This skill automates the entire Instruments profiling workflow:

Device Selection — Automatically detects simulators and connected devices
Release Build — Builds optimized Release configuration (Debug builds give inaccurate measurements)
Profiling — Runs xctrace record with SwiftUI or App Launch templates
Symbolication — Resolves your app's symbols using dSYM for readable stack traces
Analysis — Parses trace data and generates detailed Markdown reports
Recommendations — Identifies hot frames, hangs, hitches, and suggests fixes

Why This Matters

Xcode Instruments is powerful but painful:

Complex GUI with steep learning curve
Manual template selection and configuration
Raw trace data requires expertise to interpret
No automatic actionable insights

This skill eliminates all of that. Just say "profile this app" and get a complete performance report with specific optimization recommendations.

Installation

Quick Install (3 steps)

hljs language-bash

# 1. Clone to your Skills directory
git clone https://github.com/kyoya1123/instruments-profiler.git ~/.claude/skills/instruments-profiler

# 2. Restart Claude Code

Usage

Basic Commands

Just tell Claude what you want to measure:

hljs language-bash

/instruments-profiler

hljs language-csharp

Profile this app with Instruments

hljs language-bash

Measure the app launch time

hljs

Run Instruments profiling

Profiling Modes

Mode	Template	Best For
SwiftUI	SwiftUI + Time Profiler + Hangs + Hitches	View updates, CPU usage, UI responsiveness
App Launch	App Launch	Startup time, library loading, initialization
Time Profiler	Time Profiler	General CPU profiling
Leaks	Leaks	Memory leak detection
Allocations	Allocations	Memory allocation analysis
Animation Hitches	Animation Hitches	Frame drop detection, scroll performance
Energy Log	Energy Log	Battery consumption analysis (physical device only)

Requirements

Claude Code
iOS Simulator or connected iOS device (physical device recommended for stable operation)

How It Works

hljs language-sql

Device Selection → Release Build → Profiling → Symbolication → Analysis → Report

Device Selection — Detects simulators and connected devices, asks you to choose
Release Build — Builds optimized Release configuration (Debug builds give inaccurate measurements)
Profiling — Runs xctrace record with your selected template
Symbolication — Resolves symbols using dSYM for readable stack traces
Analysis — Parses trace data and generates a detailed Markdown report
Report — Identifies hot frames, hangs, hitches, and suggests specific fixes

Troubleshooting

Problem	Cause	Solution
Permission denied	Developer tools not authorized	System Settings → Privacy → Developer Tools
Device not found	Invalid device name/UDID	Run `xctrace list devices`
Empty trace	Recording too short	Interact with the app during profiling
Symbols show as "unknown"	Missing dSYM	Ensure Release build includes dSYM
Cannot find process	Process search failed	Use `--launch` instead of `--attach`

Contributing

Issues and pull requests welcome! Please file issues in both English or Japanese.

License

MIT License - see LICENSE

instruments-profiler

Instruments Profiler

What It Does

Why This Matters

Installation

Quick Install (3 steps)

Usage

Basic Commands

Profiling Modes

Requirements

How It Works

Troubleshooting

Contributing

License

Similar Packages

Tags

Original Author

Publisher