Metal GPU Trace

metal-gpu-trace

Measure how a Wine or macOS program uses the GPU on an Apple silicon Mac, from the command line or through an AI coding agent: GPU time per frame, frame pacing, FPS and memory, recorded with Instruments' Metal System Trace; whether a translation layer (DXMT, Mullion, MoltenVK) splits the work into too many short encoders; Metal .gputrace captures read without Xcode; and Apple's published facts on each GPU family to read the numbers against. Python 3.9+ standard library, zsh, and Xcode (for xctrace). MIT license. Español.

Recording

PERF_OUT=~/perf-runs zsh perf_record.sh game-d3d12 30 /path/to/wine ~/.wine /path/to/game game.exe

PERF_OUT=~/perf-runs zsh perf_record.sh app-metal 30 native - /path/to/app ./app

Arguments: label, seconds, a Wine directory holding bin/wine (or native), the Wine prefix, the working directory, the program and its arguments. Without PERF_OUT, runs go to ./perf-runs. Reading the trace afterwards takes about a minute on an M1 Pro (87 s for a 10 s recording); through the MCP server the whole call times out after 10 s per recorded second plus 120 s, and an overrun recording leaves no files behind. One recording runs at a time; keep other GPU work off the Mac while it records.

Under Wine, give it 30 s: Wine's start-up takes part of the recording. A recording with under 100 frames is too short to compare.

Disk use

Each recording keeps a JSON summary and three CSVs, about 2 MB for 10 s (most of it the Metal memory samples). The .trace (tens to hundreds of MB) is deleted unless KEEP_TRACE=1. KEEP_RUNS=N keeps only the newest N recordings. PERF_MEMORY=0 skips the Metal memory table, the slowest to read: the summary then has no metal_memory_mib and there is no memory CSV (41 % faster to summarize a 626 MB trace). The MCP tools perf_record and perf_baseline_record offer the same as memory=false.

MCP server

Install

The server runs with uvx from PyPI, with nothing to clone (brew install uv installs it). Recording also needs Xcode installed (xcrun xctrace version prints a version).

uvx metal-gpu-trace

This is the command each client below runs. Desktop apps do not see Homebrew's PATH: give them the full path that which uvx prints (/opt/homebrew/bin/uvx on Apple silicon). uvx keeps the version it first downloaded; run the command once with --refresh after uvx to get the latest. uvx metal-gpu-trace@0.4.0 pins a version.

The server reads these environment variables:

Claude Code

claude mcp add --scope user metal-trace -e METAL_TRACE_OUT=$HOME/perf-runs -e METAL_TRACE_WINE=/path/to/wine \

-- uvx metal-gpu-trace claude mcp list

claude mcp list shows metal-trace as connected. --scope user makes it available in every project; leave it out to add it to the current project only.

Windows

On Windows the server records native programs (perf_record_windows.py); no Wine and no Metal. METAL_TRACE_WINE is not needed: perf_record and perf_attach use native. METAL_TRACE_READ is separated by ;.

Frames come from Intel's PresentMon console application (MIT): one row per Present() of the process, with MsBetweenPresents and the GPU time MsGPUTime. Download PresentMon- -x64.exe from its releases, check its SHA-256 against the one GitHub shows, and call the presentmon_install tool, or put it in %LOCALAPPDATA%\metal-gpu-trace or on PATH, or point PRESENTMON_EXE at it. The user must be an administrator or in the "Performance Log Users" group. Without PresentMon the summary falls back to DWM composition intervals (gpu.source is dwm-composition): they cover the whole desktop, miss games in exclusive full screen, and carry no GPU time. With neither a frame log, PresentMon nor DWM samples, a recording fails; it never invents frames.

What cannot be measured is null, not zero: the 1% low needs 100 frames and the 0.1% low 1000; stutter rate and jitter need two frames; thermal_throttling_detected needs GPU times; a drawstress log holds one mean per line, so its summary (gpu.frame_times) has no frame-level percentiles, stutter or jitter. DWM keeps only intervals between consecutive composed frames and drops a jump of several frames. perf_diagnose calls a large working set with uneven frame times MEMORY_PRESSURE_SUSPECTED: a suspicion, since memory bandwidth is not measured.

winget install --id=astral-sh.uv -e

claude mcp add --scope user metal-trace -e METAL_TRACE_OUT=%USERPROFILE%\perf-runs -- uvx metal-gpu-trace claude mcp list

To run from a clone instead of PyPI (needs Python 3.9 or newer):

claude mcp add --scope user metal-trace -e METAL_TRACE_OUT=%USERPROFILE%\perf-runs -- python C:\path\to\metal-gpu-trace\metal_trace_mcp.py

In JSON clients use "command": "uvx" (or the full path where uvx prints) and Windows paths with doubled backslashes. Claude Desktop reads %APPDATA%\Claude\claude_desktop_config.json. Run the Windows tests with python -m pytest test_perf_record_windows.py.

Claude Desktop, Cursor and other JSON clients

These apps do not expand ~ or $HOME: write absolute paths.

{

"mcpServers": { "metal-trace": { "command": "/opt/homebrew/bin/uvx", "args": ["metal-gpu-trace"], "env": { "METAL_TRACE_OUT": "/absolute/path/to/perf-runs", "METAL_TRACE_WINE": "/absolute/path/to/wine" } } } }

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.metal-trace]

command = "/opt/homebrew/bin/uvx" args = ["metal-gpu-trace"] env = { METAL_TRACE_OUT = "/absolute/path/to/perf-runs", METAL_TRACE_WINE = "/absolute/path/to/wine" }

Tools

| perf_panel | Writes .panel.html: a page with GPU time per frame and its hitches, the numbers, Metal memory and, for two runs, A against B. It has no server and loads nothing from the network; the viewer hides or reorders widgets and exports the layout as JSON. With --http, `/panel#token=...&runs=a,b