VeloQ CLI
The VeloQ CLI hands agents Nsight Systems, Nsight Compute and PyTorch profile data as versioned JSON, with analysis skills.
- 131 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The `curl` install script runs in the shell and writes to `~/.local/bin` and `~/.agents/skills/`.
- Reads profile files and creates cache and figures in a `<report>.veloq/` folder next to the report.
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/lucifer1004/veloq/main/scripts/install.sh | bashLinux and macOS. Puts the binary in `~/.local/bin` and skills in `~/.agents/skills/`. The `--no-skills` and `--no-binary` flags split the install.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The `curl` install script runs in the shell and writes to `~/.local/bin` and `~/.agents/skills/`.
- Reads profile files and creates cache and figures in a `<report>.veloq/` folder next to the report.
This is third-party code. Review the repository files before installing.
What it does
VeloQ reads exported GPU profiles and answers one question per command. It has three sources: Nsight Systems (timeline), Nsight Compute (kernel reports) and experimental PyTorch/Kineto in Chrome trace format. The list has 17 verbs for NSys, 11 for NCU and 10 for PyTorch, plus the root verbs `info`, `sources`, `clean`, `recipes`, `agent` and `self-update`. Output goes into one v1 JSON envelope with a stable per-row key, with CSV and table projections where useful. The agent does not have to read long text dumps from `nsys` and `ncu`: it gets shaped rows with truncation signals. The binary ships with the skills `nsys-profile-analysis`, `ncu-profile-analysis` and `pytorch-profile-analysis`.
Who it is for. CUDA kernel developers and ML engineers who hand GPU profile analysis to a Claude Code or Codex agent.
Good fit when
- You need the longest kernels in an Nsight Systems trace grouped by NVTX path.
- Two runs must be compared: each row has a stable key, so outputs line up.
- The agent needs per-launch metrics from an Nsight Compute report, including disassembly and warp stall reasons.
- A PyTorch profile was captured as a Chrome trace and you look for collectives and correlations.
Not a fit when
- You want to explore a timeline interactively: the Nsight GUI is for that.
- You have no profiles: VeloQ reads finished exports and does not replace `nsys` or `ncu`.
- Your `nsys` is older than 2024.6: it needs the `parquetdir` export type.
Example request
Show the ten longest kernels in trace.nsys-rep and group them by NVTX path.Limitations
VeloQ reads exports of `nsys` and `ncu` and does not replace them, so the NVIDIA profilers themselves are needed. For NSys traces the minimum `nsys` version is 2024.6. The PyTorch/Kineto source is marked experimental. The one-line install works on Linux x86_64 and aarch64 and on macOS x86_64 and arm64, while on Windows you use `cargo binstall veloq` or the ready exe from releases. Skills install instructions only, and data extraction still needs the `veloq` binary on PATH. The `veloq agent install` command connects the Codex and Claude plugins.
How to disable. `veloq agent uninstall claude` or `veloq agent uninstall codex` removes the plugin. The binary sits in `~/.local/bin` and skills in `~/.agents/skills/`, and both can be deleted. Cache and figures live next to the report in `<report>.veloq/`, and `veloq clean` clears them.
FAQ
How do I install VeloQ for Claude Code?
Run the install script from the README: it puts the `veloq` binary in `~/.local/bin` and the analysis skills in `~/.agents/skills/`. `veloq agent install claude` connects the Claude plugin.
Which profiles does VeloQ read?
Nsight Systems reports, Nsight Compute reports and, experimentally, PyTorch/Kineto traces in Chrome trace format. NSys needs `nsys` 2024.6 or newer, because data comes through `nsys export -t parquetdir`.
Why use VeloQ over raw nsys output in the agent context?
Output is condensed into rows with truncation signals in one versioned JSON envelope, so fewer tokens are spent. Rows have a stable key, and captures can be compared with each other.
Does VeloQ work on Windows?
Yes. Install the binary with `cargo binstall veloq` or take `veloq-x86_64-windows.exe` from the releases page. The README install script targets Linux and macOS.
What output format does VeloQ use?
JSON by default in one v1 envelope: lists live in `data.rows[]`, and errors use the same shape with a non-zero exit code. Many commands also accept `--format csv` and `--format table`.
Discussion
No questions or reviews yet.
Related
CLI toolsClaude Code skill reading Nsight Compute reports on Blackwell: from a CUDA kernel profile to a diagnosis and an optimization plan.
Local profiling MCP server: an agent runs profilers and benchmarks and gets bounded evidence about hotspots
Reads local logs of Claude Code, Codex, Cursor and other agents and shows token spend, time and failures in a TUI
A TUI that shows what Claude Code, Codex, Gemini CLI and opencode do in a project: the open file, last-commit diff, live commands
DevLens analyzes a repo once and serves agents ranked files, call flow and change impact over MCP, no file-by-file reading
Black-box auditor runs a released CLI, catches side writes to disk and gives agents a command index with a readiness score.
README in short
The README describes a family of CLIs for GPU profiles: the verbs for each of the three sources, the JSON envelope format and a comparison with the Nsight GUI and hand-rolled SQLite scripts. It continues with install options, a quick start with examples and NCU verb tables with output formats.