jlreyes

Instruments Analyzer — Data skill for Claude Code

Data community

A Python tool that gives AI agents programmatic access to Apple Instruments trace data by exporting .trace files to DuckDB for SQL analysis.

How to install Instruments Analyzer

This entry records only its repository, not the path inside it, so there is no exact command to give. Open jlreyes/instruments-analyzer and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Instruments Analyzer does

A Python tool that gives AI agents programmatic access to Apple Instruments trace data by exporting .trace files to DuckDB for SQL analysis.

Alternatives in Data

HTML Video — Programmatic video for coding agents — HTML to video on your laptop 4.5k ★
n8n Code JavaScript — JavaScript in n8n Code nodes with data access patterns 3.6k ★
Portaljs Architect — Recommend a data-portal architecture (storage, compute, catalog, access, hosting, metadata) from your needs, t 2.3k ★

README

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:

Export the trace to DuckDB + Parquet (via export_to_duckdb.py)
Explore the exported tables — CPU profiling, hitches, hangs, signposts, Core Animation, SwiftUI updates, RunLoop activity, and more
Prepare derived views for frame-level analysis (via prepare_analysis.py)
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