Instruments Analyzer

Instruments Analyzer

A tool that gives AI agents programmatic access to Apple Instruments trace data. Instruments is normally a GUI-only tool — this tool bridges the gap by exporting `.trace` files into DuckDB, where they can be queried with SQL.

What it does

Given an Instruments `.trace` file, this tool will:

1. Export the trace to DuckDB + Parquet (via export_to_duckdb.py)
2. Explore the exported tables — CPU profiling, hitches, hangs, signposts, Core Animation, SwiftUI updates, RunLoop activity, and more
3. Prepare derived views for frame-level analysis (via prepare_analysis.py)
4. Analyze performance data using SQL queries with full schema knowledge

Install

Requires macOS with Xcode, [uv](https://github.com/astral-sh/uv), and [DuckDB](https://duckdb.org):

brew install duckdb
curl -LsSf https://astral.sh/uv/install.sh | sh

As an agent skill

# Claude Code
claude install-skill jlreyes/instruments-analyzer

# Any agent (via skills.sh)
npx skills add jlreyes/instruments-analyzer

Manual

Clone and copy the skill files into your project's `.claude/skills/` directory:

git clone https://github.com/jlreyes/instruments-analyzer.git
cp -r instruments-analyzer/. your-project/.claude/skills/instruments-analyzer/

Standalone (for use with any AI agent or CLI)

git clone https://github.com/jlreyes/instruments-analyzer.git
cd instruments-analyzer

Usage

1. Record a trace

xcrun xctrace record --template 'SwiftUI' --time-limit 20s \
  --output ./traces/recording.trace \
  --attach YourApp --no-prompt

Or use the included `PerfDebugging.tracetemplate` in Instruments.

2. Export to DuckDB

./scripts/export_to_duckdb.py traces/recording.trace traces/recording/analysis.duckdb

3. Analyze with your tool of choice

# Use with Claude Code
# Analyze the performance trace in traces/recording/analysis.duckdb.

# Or query directly with DuckDB
duc