# Investigate Puffin

Investigate Puffin profiler recordings (.puffin files), find slow scopes, and compare...

- Repository: https://github.com/rerun-io/rerun (11675 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add rerun-io/rerun --skill investigate-puffin -g -a claude-code -y`
Codex: `npx skills add rerun-io/rerun --skill investigate-puffin -g -a codex -y`
Cursor: `npx skills add rerun-io/rerun --skill investigate-puffin -g -a cursor -y`
Gemini CLI: `npx skills add rerun-io/rerun --skill investigate-puffin -g -a gemini-cli -y`

## Description

Investigate Puffin profiler recordings (.puffin files), find slow scopes, and compare before/after traces using the `rerun dump-puffin` command and bundled analysis helpers.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Investigate puffin traces

Analyze a `.puffin` recording from an application instrumented with Puffin.
Use the recording path supplied by the user. Or use the `capture_profile_trace` message if using the rerun MCP.

## Setup

Requires the `rerun` CLI (Rerun 0.38 or later), Python 3.10 or later, and jq.
The Python helpers use only the standard library.
Set `PUFFIN_SKILL_DIR` to the absolute directory containing this `SKILL.md`.
In Claude Code, you can use `export PUFFIN_SKILL_DIR="${CLAUDE_SKILL_DIR}"`; in other agents, resolve the directory from the installed skill location.

Dump the trace to a file and check scope registration:

```bash
rerun dump-puffin <path> > /tmp/puffin.json
jq '.scopes | length' /tmp/puffin.json
```

If no (recent enough) `rerun` binary is on the path but you are in a Rerun checkout, run the sub-command from source instead:

```bash
cargo run --quiet -p rerun-cli --no-default-features -- dump-puffin <path> > /tmp/puffin.json
```

Always dump to a file.
`.puffin` traces can produce many MB of JSON, so query the saved JSON instead of reading it all into context.

If `.scopes | length` is **0**, names fall back to `scope#<id>` and source locations are missing.
Ask for a new capture that includes scope registration if names are needed for the investigation.
If another capture is not feasible, proceed with dynamic `data` labels and explain the limits.
Check the registration table after exporting: do not assume that every capture tool or version preserves it.

### How traces are captured

Use the application's Puffin capture or export support to save a `.puffin` file.
For applications serving profiling data through `puffin_http`, connect a compatible `puffin_viewer` and export the recording.
The dumper uses Puffin 0.20; captures from incompatible format versions may require a matching parser.

Rerun-specific examples:

The rest: https://github.com/rerun-io/rerun/blob/HEAD/skills/investigate-puffin/SKILL.md