Stats
Actions
Tags
From game-porting-skills
Captures Metal GPU traces (.gputrace) from running or launched processes using the gpucapture CLI tool, with no source code changes required.
How this skill is triggered — by the user, by Claude, or both
Slash command
/game-porting-skills:using-gpucaptureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
`gpucapture` is a CLI tool for capturing Metal GPU traces from running processes or launched executables. It requires no source code changes — attach to a process by PID, choose what to capture (frames, command buffers, custom scopes), and produce a `.gputrace` file for analysis.
gpucapture is a CLI tool for capturing Metal GPU traces from running processes or launched executables. It requires no source code changes — attach to a process by PID, choose what to capture (frames, command buffers, custom scopes), and produce a .gputrace file for analysis.
which gpucapture
gpucapture ships with macOS 27 and later. If not found, the user is on an older macOS version — suggest alternatives based on their situation:
MTLCaptureManager: Capturing a Metal workload programmaticallyIf the user explicitly asks for programmatic capture or Xcode capture, honor their request — point them to the relevant Apple docs URL above and answer from your own knowledge. Do not override their choice with gpucapture.
If gpucapture is available and the user has not specified a method, proceed with the steps below.
The man page is the authoritative reference for all subcommands, flags, boundary types, and environment variables. Read it before using gpucapture:
man gpucapture | col -b
The man page documents all subcommands (list, boundary, start, stop), flags, and boundary types. Two things to keep in mind that are easy to miss:
MTL_CAPTURE_ENABLED=1. There is no way to enable capture on an already-running process that was launched without it. If the user says the app is "already running," they likely need to relaunch it.MTLCAPTURE_WAIT_FOR_SIGNAL=1 pauses the process at MTLDevice creation until gpucapture start attaches. Both env vars should be set at launch.After capturing, verify the .gputrace file was created and report the file path and size to the user.
npx claudepluginhub apple/game-porting-toolkit --plugin game-porting-skillsOpens and inspects Metal GPU .gputrace files using the gpudebug CLI. Covers draw calls, render encoders, pipeline state, resource bindings, textures, buffers, and shader source.
Analyzes Meta Quest and Horizon OS VR performance using Perfetto traces — frame timing, CPU/GPU bottlenecks, render pass analysis. Use when profiling frame drops, jank, or thermal issues on Quest devices.
Interprets WebGPU Inspector frame captures including GPU object graphs, command lists, render/compute passes, buffers, textures, shaders, and validation errors. Useful when analyzing captured .json files from WebGPU Inspector MCP tools or DevTools.