nsight-graphics-analyzer
English | 简体中文
Nsight Graphics Analyzer is a Windows-only skill and CLI wrapper for NVIDIA
Nsight Graphics 2026.1+. It helps Claude Code, Codex, or a human at the
terminal capture GPU frames, export Nsight GPU Trace data, and inspect the
result through small JSON files instead of multi-hundred-MB TSV artifacts.
The Python code uses only the standard library. No pip install is required.
Requirements
| Requirement | Notes |
|---|
| Windows 10/11 | Required. The wrapper uses Windows process and path APIs. |
| NVIDIA Nsight Graphics 2026.1+ | Install separately from NVIDIA Developer. |
| Python 3.10+ | Standard library only. |
| NVIDIA GPU and supported driver | Required for Nsight capture and replay workflows. |
Run the environment check first:
python skills\nsight-graphics-analyzer\scripts\nsight.py doctor
If ngfx_install is null, install Nsight Graphics before trying to capture.
Quick Start
Capture a short GPU Trace and generate the three compact JSON artifacts:
python skills\nsight-graphics-analyzer\scripts\nsight.py gputrace-capture `
--exe "C:\Path\To\YourApp.exe" --wd "C:\Path\To" `
--start-after-ms 5000 --max-duration-ms 1000 `
--architecture Ada --metric-set-name "Throughput Metrics" `
--time-every-action `
--out "C:\Path\To\Captures\sample.ngfx-gputrace"
The wrapper writes these files next to the trace:
| Artifact | Purpose |
|---|
*.gputrace.summary.json | Frame budget, hardware context, dominant subsystem, metric catalog, warnings. |
*.gputrace.stages.json | Top-level NVTX / D3DPERF stages with headline metrics. |
*.gputrace.actions.json | Slowest leaf markers. |
Start with summary.json, then drill into the slowest stage:
python skills\nsight-graphics-analyzer\scripts\nsight.py gputrace-stages `
"C:\Path\To\Captures\<session>\sample.ngfx-gputrace" `
--parent "<stage-name-regex>" --top 10
The raw exported GPUTRACE_REGIMES.xls can be 300+ MB. Do not open it in an
agent context. Use the drill commands instead.
Installation
The installable skill lives at:
skills/nsight-graphics-analyzer/
The repository root holds project docs, tests, CI, and plugin manifests.
Codex
Use the Codex plugin marketplace flow. This repository
contains the plugin manifest at .codex-plugin/plugin.json and the marketplace
metadata at .agents/plugins/marketplace.json, so Codex can discover the skill
directly from GitHub:
codex plugin marketplace add FrostyLeaves/nsight-graphics-analyzer
codex
Inside Codex, open /plugins, choose the nsight-graphics-analyzer
marketplace, and install Nsight Graphics Analyzer. Restart the session if
your Codex build does not load newly installed plugins immediately.
For local development against a clone, add the checkout as a local marketplace:
git clone https://github.com/FrostyLeaves/nsight-graphics-analyzer
codex plugin marketplace add .\nsight-graphics-analyzer
codex
Then install the plugin from /plugins.
If you only need the raw skill fallback, copy it into the global Codex skills
directory:
git clone https://github.com/FrostyLeaves/nsight-graphics-analyzer
New-Item -ItemType Directory -Force -Path $HOME\.codex\skills | Out-Null
Copy-Item -Recurse -Force `
.\nsight-graphics-analyzer\skills\nsight-graphics-analyzer `
$HOME\.codex\skills\
Use a symlink instead of copying only when you want Codex to read your live
working tree:
New-Item -ItemType SymbolicLink `
-Path $HOME\.codex\skills\nsight-graphics-analyzer `
-Target .\nsight-graphics-analyzer\skills\nsight-graphics-analyzer
Claude Code
This repository ships .claude-plugin/marketplace.json, so Claude Code can
install it as a single-plugin marketplace. From the Claude Code prompt:
/plugin marketplace add FrostyLeaves/nsight-graphics-analyzer
/plugin install nsight-graphics-analyzer@nsight-graphics-analyzer
/reload-plugins
/reload-plugins lets the current session pick up the new plugin without a
restart. Once loaded, Claude Code activates the skill automatically when the
conversation mentions Nsight, GPU trace, frame capture, or other trigger
phrases declared in SKILL.md. You can also invoke it explicitly with
/nsight-graphics-analyzer:nsight-graphics-analyzer.
For local development against a clone, point the marketplace at the working
copy instead of GitHub:
