Stats
Actions
Tags
From game-porting-skills
Opens and inspects Metal GPU .gputrace files using the gpudebug CLI. Covers draw calls, render encoders, pipeline state, resource bindings, textures, buffers, and shader source.
How this skill is triggered — by the user, by Claude, or both
Slash command
/game-porting-skills:using-gpudebugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
`gpudebug` is a CLI debugger for Metal GPU traces. It opens a `.gputrace` file and provides commands for navigating the captured API call hierarchy, inspecting resources and pipeline state, fetching textures and buffers to disk, and browsing shader source code.
gpudebug is a CLI debugger for Metal GPU traces. It opens a .gputrace file and provides commands for navigating the captured API call hierarchy, inspecting resources and pipeline state, fetching textures and buffers to disk, and browsing shader source code.
which gpudebug
gpudebug ships with macOS 27 and later. If not found, tell the user it is not available and suggest opening the .gputrace in Xcode's Metal Debugger instead: Analyzing your Metal workload
If the user explicitly asks to inspect the trace in Xcode, honor their request — point them to the Apple docs URL above and answer from your own knowledge. Do not override their choice with gpudebug.
The man page is the authoritative reference for all commands, options, the trace hierarchy, and node naming conventions. Read it before using gpudebug:
man gpudebug | col -b
The man page covers: CLI flags, the trace tree structure, node naming (prefixes and indexing), all REPL commands (list, go, info, fetch, find, next/prev, status), scripting examples, and tips.
Always drive gpudebug non-interactively — never start an interactive REPL. Use -q to suppress the startup banner. The man page documents the full scripting model, command syntax, and examples.
A background replayer connects to the GPU on startup. Browse commands (list, go, info, find) work immediately, but fetch requires the replayer to be ready. Structure scripts so browse operations come first — by the time you need to fetch, the replayer has usually initialized. If the replayer failed (e.g., trace captured on a different GPU architecture), static browsing still works but fetch is unavailable.
npx claudepluginhub apple/game-porting-toolkit --plugin game-porting-skillsCaptures Metal GPU traces (.gputrace) from running or launched processes using the gpucapture CLI tool, with no source code changes required.
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.
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.