hotkernel 0.1.0__tar.gz

hotkernel-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+.venv/
+venvs/
+dist/
+build/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+results/profiles/*.nsys-rep
+results/profiles/*.ncu-rep
+results/profiles/*.sqlite
+*.cubin
+*.gif.tmp
+.DS_Store
+Thumbs.db
+docs/plan-*.md

hotkernel-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Xinhua Gu
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

hotkernel-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: hotkernel
+Version: 0.1.0
+Summary: Find the hot kernel, cool it down: an Nsight/SASS MCP server with a verify-and-record contract and a kernel-speedrun loop for coding agents.
+Project-URL: Homepage, https://github.com/xinhuagu/hotkernel
+Project-URL: Issues, https://github.com/xinhuagu/hotkernel/issues
+Author: Xinhua Gu
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: claude-code,codex,cuda,gpu,kernel,mcp,nsight,profiling,triton
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# hotkernel
+
+**Find the hot kernel, cool it down.**
+
+An MCP server that gives your coding agent hands on Nsight and SASS, a verify-and-record contract it cannot fudge, and a kernel-speedrun loop it runs on its own on the GPU on your desk.
+
+[![PyPI](https://img.shields.io/pypi/v/hotkernel)](https://pypi.org/project/hotkernel/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/xinhuagu/hotkernel/blob/main/LICENSE)
+![MCP](https://img.shields.io/badge/MCP-Claude%20Code%20·%20Codex%20·%20any%20MCP%20client-black)
+
+English | [中文](https://github.com/xinhuagu/hotkernel/blob/main/README_zh.md)
+
+</div>
+
+Ask Claude to "make this kernel faster" today and it guesses: it cannot see the Nsight report, does not know which kernel eats 60% of the step, has never read the SASS the compiler produced, and cannot benchmark its own rewrite on your card. hotkernel is the missing pair of hands. Nine tools wrap `nsys`, `ncu`, `cuobjdump`, `torch.profiler` and a strict verify-and-record contract; one skill turns them into a loop: profile, pick the hot kernel, read its SASS, check it against the roofline, rewrite it in Triton, verify against the baseline, record the verdict, keep or revert, repeat.
+
+**Three targets, three autonomous agent runs, one RTX 5090: rmsnorm 3.2× faster than eager PyTorch, softmax 1.2× faster than `torch.softmax`, gemv level with cuBLAS. Every kernel the agent kept runs at 95–105% of the card's measured streaming bandwidth.**¹
+
+> ¹ Each range comes from three independent `verify()` calls of the agent's final kernel against the baseline, n=7 interleaved runs each, on one RTX 5090 at 575 W under WSL2. Speedups are relative to the baseline scripts in `examples/`: eager PyTorch for rmsnorm, `torch.softmax` for softmax, `torch.mv` (cuBLAS) for gemv. "Measured streaming bandwidth" is device memcpy on the same card under the same timer, 1501 GB/s (84% of the 1792 GB/s spec), see [the calibration](https://github.com/xinhuagu/hotkernel/blob/main/docs/platform-matrix.md). Raw logs for every number are in [`results/`](https://github.com/xinhuagu/hotkernel/tree/main/results).
+
+## Install
+
+```bash
+claude mcp add -e HOTKERNEL_PYTHON=$HOME/venvs/mytorch/bin/python hotkernel -- uvx hotkernel   # Claude Code
+codex mcp add --env HOTKERNEL_PYTHON=$HOME/venvs/mytorch/bin/python hotkernel -- uvx hotkernel # Codex
+```
+
+Any other MCP client: `{"command": "uvx", "args": ["hotkernel"], "env": {"HOTKERNEL_PYTHON": "..."}}`. `HOTKERNEL_PYTHON` is the interpreter that has your PyTorch and Triton; the server itself stays torch-free.
+
+The loop is a skill: copy [`skills/kernel-speedrun/`](https://github.com/xinhuagu/hotkernel/tree/main/skills/kernel-speedrun) into your agent's skills directory (Claude Code: `~/.claude/skills/`).
+
+## Before / after
+
+All rows: RTX 5090 @ 575 W, bf16, timing protocol 3, three independent `verify()` runs of n=7 each.
+
+| Target | Baseline | Baseline mean | Agent's kernel mean | Speedup | Share of measured bandwidth | Agent time | What the agent wrote |
+|---|---|---|---|---|---|---|---|
+| rmsnorm 4096×8192 | eager PyTorch (5 kernels) | 0.287–0.300 ms | 0.088–0.095 ms | **3.17–3.32×** | 95–101% | 10 min, 7 experiments (a second 3-minute run found the same kernel) | one Triton program per row, row in registers, one read and one write |
+| softmax 4096×8192 | `torch.softmax` | 0.107–0.111 ms | 0.090–0.093 ms | **1.17–1.21×** | 96–99% | 6 min, 4 experiments | one program per row, max, exp and sum in registers, 8 warps |
+| gemv 8192×8192 | `torch.mv` (cuBLAS) | 0.088–0.091 ms | 0.085–0.088 ms | **1.03–1.05×**, 2 of 3 runs significant: level with cuBLAS | 101–105%² | 7 min, 3 experiments | autotuned row-block GEMV, 2 rows × 1024 columns per program |
+
+> ² gemv is almost all reads; the copy ceiling is half reads and half writes, so a read-only kernel can sit slightly above it.
+
+Every row on [LEADERBOARD.md](https://github.com/xinhuagu/hotkernel/blob/main/LEADERBOARD.md) was written by `record()`, including the runs that did not win and a deliberately wrong candidate that `verify()` rejected as `incorrect`. Each agent run's full transcript is in `results/<target>/agent-run-*/`.
+
+## What the agent gets
+
+| Tool | What it does | Needs |
+|---|---|---|
+| `gpu_info` | card, driver, memory, power limit, compute capability | `nvidia-smi` |
+| `roofline` | ridge point for this card; memory- or compute-bound verdict and attainable time for a kernel given flops and bytes, against the spec sheet or the measured bandwidth | nothing |
+| `torch_trace` | top CUDA kernels of a script by device time, via `torch.profiler` | your torch |
+| `profile` | run a command under Nsight Systems or Nsight Compute, parsed | `nsys` / `ncu` |
+| `top_kernels` | the n heaviest kernels from a saved report, with ncu throughput and occupancy | nothing |
+| `disasm` | PTX or SASS of a cubin, or of the latest Triton-cache kernel by name | `cuobjdump` |
+| `bench` | run a script n times, collect its `{"ms": …, "ok": …}` line, return mean/std/min | your torch |
+| `verify` | run baseline and candidate interleaved, n times each; speedup and a verdict: `faster`, `slower`, `inconclusive`, `incorrect` (any `ok=false`, no speedup reported), `invalid` (shape, dtype, seed or timing protocol changed) | your torch |
+| `record` | write the verify result to `results/<target>/`, regenerate the leaderboard from the logs, and say whether the change beats the run's best so far | nothing |
+
+`torch_trace`, `bench`, `verify` and `record` work on any machine with PyTorch. Nsight is optional and only makes the picture sharper.
+
+## The loop
+
+The skill in [`skills/kernel-speedrun/SKILL.md`](https://github.com/xinhuagu/hotkernel/blob/main/skills/kernel-speedrun/SKILL.md) is the whole method:
+
+1. `bench` the baseline. That is the number to beat.
+2. `torch_trace` or `profile` to find the kernel that actually dominates.
+3. `roofline` with the kernel's flops and bytes: memory-bound kernels want fusion, compute-bound kernels want tensor cores and bigger tiles.
+4. `disasm` the Triton kernel after its first compile: register spills, uncoalesced loads, long dependency chains are all visible in SASS.
+5. One hypothesis, one change, then `verify(candidate, baseline, n=7)`. It returns `faster` only when the gap beats `2 * sqrt(std_b²/n + std_c²/n)` and every candidate run passed the correctness check.
+6. `record()` the result, win or lose. It writes the log and the leaderboard; the agent never edits the board. Keep the change only if `record()` says it beats the run's best so far, otherwise revert.
+7. Stop after three changes in a row that do not beat the best, or when the kernel is within 10% of the measured bandwidth floor.
+
+It is [autoresearch](https://github.com/karpathy/autoresearch) with kernel wall-clock as the metric instead of training loss.
+
+## Measured, not claimed
+
+LLMs writing CUDA kernels have a credibility problem: the AI CUDA Engineer claimed 10 to 100× in 2025 and was found to be bypassing its own correctness checks, and KernelBench exists because "the kernel compiles" and "the kernel is correct and faster" are different things. hotkernel's answer is structural:
+
+- **The contract lives in the baseline.** Shape, dtype, seed, reference, tolerances and the timer are in the baseline file the agent cannot edit; the candidate only supplies a function. `verify` returns `invalid` if anything in the contract differs.
+- **The timer was wrong twice and fixed in the open.** Version 1 reused one input and let the 96 MB L2 pose as DRAM. Version 2 flushed L2 by zeroing a buffer and charged every call ~45 µs of someone else's write-backs; the softmax agent noticed that Nsight and `verify` disagreed by 2×. Version 3 rotates buffers larger than twice the L2 and was calibrated against five streaming kernels, which all land at 79–84% of the spec sheet, matching ncu's hardware counters. Old rows are kept and marked as not counted.
+- **Wrong is loud.** `verify` reports no speedup for a run whose `ok` is false, every row carries n and std, and the baseline is in the repo so anyone can rerun it.
+
+## Platforms
+
+- **NVIDIA GPU required.** Reference card: RTX 5090 (sm_120). The roofline table covers 5090, 4090, 3090 and H100, each with its source; add yours in `src/hotkernel/gpus.py`.
+- **WSL2 is the reference platform.** All nine tools are verified on an RTX 5090 under WSL2 Ubuntu 24.04, driver 617.42: `nsys` 2026.1.3 and `ncu` 2026.2.1 extracted into user space from NVIDIA's apt repo (no sudo), `cuobjdump` and `nvdisasm` straight from the Triton wheel (no CUDA toolkit needed). `ncu` needs the GPU performance-counter permission once (NVIDIA Control Panel, Developer settings). Versions, commands and raw outputs: [`docs/platform-matrix.md`](https://github.com/xinhuagu/hotkernel/blob/main/docs/platform-matrix.md).
+- **Native Windows:** the server runs (pure Python). If your torch lives in WSL2, start the server through `wsl.exe`; the platform matrix has the exact `claude mcp add` line.
+- **Triton on RTX 50 series:** FlashAttention 2/3/4 do not run on sm_120, which is exactly why hand-tuned Triton kernels matter on these cards.
+
+## License
+
+Apache-2.0.

hotkernel-0.1.0/README.md

@@ -0,0 +1,95 @@
+<div align="center">
+
+# hotkernel
+
+**Find the hot kernel, cool it down.**
+
+An MCP server that gives your coding agent hands on Nsight and SASS, a verify-and-record contract it cannot fudge, and a kernel-speedrun loop it runs on its own on the GPU on your desk.
+
+[![PyPI](https://img.shields.io/pypi/v/hotkernel)](https://pypi.org/project/hotkernel/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/xinhuagu/hotkernel/blob/main/LICENSE)
+![MCP](https://img.shields.io/badge/MCP-Claude%20Code%20·%20Codex%20·%20any%20MCP%20client-black)
+
+English | [中文](https://github.com/xinhuagu/hotkernel/blob/main/README_zh.md)
+
+</div>
+
+Ask Claude to "make this kernel faster" today and it guesses: it cannot see the Nsight report, does not know which kernel eats 60% of the step, has never read the SASS the compiler produced, and cannot benchmark its own rewrite on your card. hotkernel is the missing pair of hands. Nine tools wrap `nsys`, `ncu`, `cuobjdump`, `torch.profiler` and a strict verify-and-record contract; one skill turns them into a loop: profile, pick the hot kernel, read its SASS, check it against the roofline, rewrite it in Triton, verify against the baseline, record the verdict, keep or revert, repeat.
+
+**Three targets, three autonomous agent runs, one RTX 5090: rmsnorm 3.2× faster than eager PyTorch, softmax 1.2× faster than `torch.softmax`, gemv level with cuBLAS. Every kernel the agent kept runs at 95–105% of the card's measured streaming bandwidth.**¹
+
+> ¹ Each range comes from three independent `verify()` calls of the agent's final kernel against the baseline, n=7 interleaved runs each, on one RTX 5090 at 575 W under WSL2. Speedups are relative to the baseline scripts in `examples/`: eager PyTorch for rmsnorm, `torch.softmax` for softmax, `torch.mv` (cuBLAS) for gemv. "Measured streaming bandwidth" is device memcpy on the same card under the same timer, 1501 GB/s (84% of the 1792 GB/s spec), see [the calibration](https://github.com/xinhuagu/hotkernel/blob/main/docs/platform-matrix.md). Raw logs for every number are in [`results/`](https://github.com/xinhuagu/hotkernel/tree/main/results).
+
+## Install
+
+```bash
+claude mcp add -e HOTKERNEL_PYTHON=$HOME/venvs/mytorch/bin/python hotkernel -- uvx hotkernel   # Claude Code
+codex mcp add --env HOTKERNEL_PYTHON=$HOME/venvs/mytorch/bin/python hotkernel -- uvx hotkernel # Codex
+```
+
+Any other MCP client: `{"command": "uvx", "args": ["hotkernel"], "env": {"HOTKERNEL_PYTHON": "..."}}`. `HOTKERNEL_PYTHON` is the interpreter that has your PyTorch and Triton; the server itself stays torch-free.
+
+The loop is a skill: copy [`skills/kernel-speedrun/`](https://github.com/xinhuagu/hotkernel/tree/main/skills/kernel-speedrun) into your agent's skills directory (Claude Code: `~/.claude/skills/`).
+
+## Before / after
+
+All rows: RTX 5090 @ 575 W, bf16, timing protocol 3, three independent `verify()` runs of n=7 each.
+
+| Target | Baseline | Baseline mean | Agent's kernel mean | Speedup | Share of measured bandwidth | Agent time | What the agent wrote |
+|---|---|---|---|---|---|---|---|
+| rmsnorm 4096×8192 | eager PyTorch (5 kernels) | 0.287–0.300 ms | 0.088–0.095 ms | **3.17–3.32×** | 95–101% | 10 min, 7 experiments (a second 3-minute run found the same kernel) | one Triton program per row, row in registers, one read and one write |
+| softmax 4096×8192 | `torch.softmax` | 0.107–0.111 ms | 0.090–0.093 ms | **1.17–1.21×** | 96–99% | 6 min, 4 experiments | one program per row, max, exp and sum in registers, 8 warps |
+| gemv 8192×8192 | `torch.mv` (cuBLAS) | 0.088–0.091 ms | 0.085–0.088 ms | **1.03–1.05×**, 2 of 3 runs significant: level with cuBLAS | 101–105%² | 7 min, 3 experiments | autotuned row-block GEMV, 2 rows × 1024 columns per program |
+
+> ² gemv is almost all reads; the copy ceiling is half reads and half writes, so a read-only kernel can sit slightly above it.
+
+Every row on [LEADERBOARD.md](https://github.com/xinhuagu/hotkernel/blob/main/LEADERBOARD.md) was written by `record()`, including the runs that did not win and a deliberately wrong candidate that `verify()` rejected as `incorrect`. Each agent run's full transcript is in `results/<target>/agent-run-*/`.
+
+## What the agent gets
+
+| Tool | What it does | Needs |
+|---|---|---|
+| `gpu_info` | card, driver, memory, power limit, compute capability | `nvidia-smi` |
+| `roofline` | ridge point for this card; memory- or compute-bound verdict and attainable time for a kernel given flops and bytes, against the spec sheet or the measured bandwidth | nothing |
+| `torch_trace` | top CUDA kernels of a script by device time, via `torch.profiler` | your torch |
+| `profile` | run a command under Nsight Systems or Nsight Compute, parsed | `nsys` / `ncu` |
+| `top_kernels` | the n heaviest kernels from a saved report, with ncu throughput and occupancy | nothing |
+| `disasm` | PTX or SASS of a cubin, or of the latest Triton-cache kernel by name | `cuobjdump` |
+| `bench` | run a script n times, collect its `{"ms": …, "ok": …}` line, return mean/std/min | your torch |
+| `verify` | run baseline and candidate interleaved, n times each; speedup and a verdict: `faster`, `slower`, `inconclusive`, `incorrect` (any `ok=false`, no speedup reported), `invalid` (shape, dtype, seed or timing protocol changed) | your torch |
+| `record` | write the verify result to `results/<target>/`, regenerate the leaderboard from the logs, and say whether the change beats the run's best so far | nothing |
+
+`torch_trace`, `bench`, `verify` and `record` work on any machine with PyTorch. Nsight is optional and only makes the picture sharper.
+
+## The loop
+
+The skill in [`skills/kernel-speedrun/SKILL.md`](https://github.com/xinhuagu/hotkernel/blob/main/skills/kernel-speedrun/SKILL.md) is the whole method:
+
+1. `bench` the baseline. That is the number to beat.
+2. `torch_trace` or `profile` to find the kernel that actually dominates.
+3. `roofline` with the kernel's flops and bytes: memory-bound kernels want fusion, compute-bound kernels want tensor cores and bigger tiles.
+4. `disasm` the Triton kernel after its first compile: register spills, uncoalesced loads, long dependency chains are all visible in SASS.
+5. One hypothesis, one change, then `verify(candidate, baseline, n=7)`. It returns `faster` only when the gap beats `2 * sqrt(std_b²/n + std_c²/n)` and every candidate run passed the correctness check.
+6. `record()` the result, win or lose. It writes the log and the leaderboard; the agent never edits the board. Keep the change only if `record()` says it beats the run's best so far, otherwise revert.
+7. Stop after three changes in a row that do not beat the best, or when the kernel is within 10% of the measured bandwidth floor.
+
+It is [autoresearch](https://github.com/karpathy/autoresearch) with kernel wall-clock as the metric instead of training loss.
+
+## Measured, not claimed
+
+LLMs writing CUDA kernels have a credibility problem: the AI CUDA Engineer claimed 10 to 100× in 2025 and was found to be bypassing its own correctness checks, and KernelBench exists because "the kernel compiles" and "the kernel is correct and faster" are different things. hotkernel's answer is structural:
+
+- **The contract lives in the baseline.** Shape, dtype, seed, reference, tolerances and the timer are in the baseline file the agent cannot edit; the candidate only supplies a function. `verify` returns `invalid` if anything in the contract differs.
+- **The timer was wrong twice and fixed in the open.** Version 1 reused one input and let the 96 MB L2 pose as DRAM. Version 2 flushed L2 by zeroing a buffer and charged every call ~45 µs of someone else's write-backs; the softmax agent noticed that Nsight and `verify` disagreed by 2×. Version 3 rotates buffers larger than twice the L2 and was calibrated against five streaming kernels, which all land at 79–84% of the spec sheet, matching ncu's hardware counters. Old rows are kept and marked as not counted.
+- **Wrong is loud.** `verify` reports no speedup for a run whose `ok` is false, every row carries n and std, and the baseline is in the repo so anyone can rerun it.
+
+## Platforms
+
+- **NVIDIA GPU required.** Reference card: RTX 5090 (sm_120). The roofline table covers 5090, 4090, 3090 and H100, each with its source; add yours in `src/hotkernel/gpus.py`.
+- **WSL2 is the reference platform.** All nine tools are verified on an RTX 5090 under WSL2 Ubuntu 24.04, driver 617.42: `nsys` 2026.1.3 and `ncu` 2026.2.1 extracted into user space from NVIDIA's apt repo (no sudo), `cuobjdump` and `nvdisasm` straight from the Triton wheel (no CUDA toolkit needed). `ncu` needs the GPU performance-counter permission once (NVIDIA Control Panel, Developer settings). Versions, commands and raw outputs: [`docs/platform-matrix.md`](https://github.com/xinhuagu/hotkernel/blob/main/docs/platform-matrix.md).
+- **Native Windows:** the server runs (pure Python). If your torch lives in WSL2, start the server through `wsl.exe`; the platform matrix has the exact `claude mcp add` line.
+- **Triton on RTX 50 series:** FlashAttention 2/3/4 do not run on sm_120, which is exactly why hand-tuned Triton kernels matter on these cards.
+
+## License
+
+Apache-2.0.

hotkernel-0.1.0/README_zh.md

@@ -0,0 +1,95 @@
+<div align="center">
+
+# hotkernel
+
+**找到最耗时的 kernel，把它变快。**
+
+一个 MCP server：让你的编程 agent 能读 Nsight 和 SASS，给它一套它没法作弊的"验证并记录"协议，再配一个它能在你桌上那张显卡上自己跑的 kernel 速通循环。
+
+[![PyPI](https://img.shields.io/pypi/v/hotkernel)](https://pypi.org/project/hotkernel/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/xinhuagu/hotkernel/blob/main/LICENSE)
+![MCP](https://img.shields.io/badge/MCP-Claude%20Code%20·%20Codex%20·%20any%20MCP%20client-black)
+
+[English](https://github.com/xinhuagu/hotkernel/blob/main/README.md) | 中文
+
+</div>
+
+今天你让 Claude"把这个 kernel 跑快点"，它只能靠猜：它看不到 Nsight 的报告，不知道哪个 kernel 吃掉了一步的 60%，没读过编译器生成的 SASS，也没法在你的卡上测自己改的版本。hotkernel 就是它缺的那双手。九个工具包住 `nsys`、`ncu`、`cuobjdump`、`torch.profiler` 和一套严格的验证与记录协议；一个 skill 把它们串成循环：剖析、选最耗时的 kernel、读它的 SASS、对照 roofline、用 Triton 重写、对着基线验证、记录裁决、保留或回滚、再来。
+
+**三个目标，三次 agent 自主运行，一张 RTX 5090：rmsnorm 比 PyTorch 朴素实现快 3.2 倍，softmax 比 `torch.softmax` 快 1.2 倍，gemv 与 cuBLAS 持平。agent 保留下来的每个 kernel 都跑到了这张卡实测流式带宽的 95% 到 105%。**¹
+
+> ¹ 每个区间来自对 agent 最终 kernel 的三次独立 `verify()`，每次与基线交替各跑 7 次，一张 RTX 5090，575 W，WSL2。加速比只相对 `examples/` 里的基线脚本：rmsnorm 是 PyTorch 朴素实现，softmax 是 `torch.softmax`，gemv 是 `torch.mv`（cuBLAS）。"实测流式带宽"是同一张卡、同一计时器下的显存拷贝速度，1501 GB/s（规格 1792 GB/s 的 84%），见[标定](https://github.com/xinhuagu/hotkernel/blob/main/docs/platform-matrix.md)。每个数字的原始日志都在 [`results/`](https://github.com/xinhuagu/hotkernel/tree/main/results)。
+
+## 安装
+
+```bash
+claude mcp add -e HOTKERNEL_PYTHON=$HOME/venvs/mytorch/bin/python hotkernel -- uvx hotkernel   # Claude Code
+codex mcp add --env HOTKERNEL_PYTHON=$HOME/venvs/mytorch/bin/python hotkernel -- uvx hotkernel # Codex
+```
+
+其他 MCP 客户端：`{"command": "uvx", "args": ["hotkernel"], "env": {"HOTKERNEL_PYTHON": "..."}}`。`HOTKERNEL_PYTHON` 指向装了你 PyTorch 和 Triton 的解释器；server 本身不依赖 torch。
+
+循环是一个 skill：把 [`skills/kernel-speedrun/`](https://github.com/xinhuagu/hotkernel/tree/main/skills/kernel-speedrun) 复制到你 agent 的 skills 目录（Claude Code 是 `~/.claude/skills/`）。
+
+## 改前 / 改后
+
+所有行：RTX 5090 @ 575 W，bf16，计时协议 3，三次独立 `verify()`，每次 n=7。
+
+| 目标 | 基线 | 基线均值 | agent 的 kernel 均值 | 加速比 | 占实测带宽 | agent 用时 | agent 写了什么 |
+|---|---|---|---|---|---|---|---|
+| rmsnorm 4096×8192 | PyTorch 朴素实现（5 个 kernel） | 0.287–0.300 ms | 0.088–0.095 ms | **3.17–3.32 倍** | 95–101% | 10 分钟 7 次实验（另一次 3 分钟的运行找到了同一个 kernel） | 每行一个 Triton 程序，整行放寄存器，一读一写 |
+| softmax 4096×8192 | `torch.softmax` | 0.107–0.111 ms | 0.090–0.093 ms | **1.17–1.21 倍** | 96–99% | 6 分钟 4 次实验 | 每行一个程序，max、exp、sum 都在寄存器里，8 个 warp |
+| gemv 8192×8192 | `torch.mv`（cuBLAS） | 0.088–0.091 ms | 0.085–0.088 ms | **1.03–1.05 倍**，三次中两次显著：与 cuBLAS 持平 | 101–105%² | 7 分钟 3 次实验 | 自动调参的分行块 GEMV，每个程序 2 行 × 1024 列 |
+
+> ² gemv 几乎全是读；拷贝上限是一半读一半写，所以纯读的 kernel 可以略高于它。
+
+[LEADERBOARD.md](https://github.com/xinhuagu/hotkernel/blob/main/LEADERBOARD.md) 上的每一行都由 `record()` 写入，包括没赢的运行，以及一个被 `verify()` 判为 `incorrect` 的故意写错的候选。每次 agent 运行的完整对话记录在 `results/<目标>/agent-run-*/`。
+
+## agent 拿到的工具
+
+| 工具 | 做什么 | 依赖 |
+|---|---|---|
+| `gpu_info` | 显卡、驱动、显存、功耗墙、计算能力 | `nvidia-smi` |
+| `roofline` | 这张卡的拐点；给定 flops 和 bytes，判断带宽瓶颈还是算力瓶颈并给出可达时间，可对照规格或实测带宽 | 无 |
+| `torch_trace` | 用 `torch.profiler` 列出脚本里按设备时间排序的 CUDA kernel | 你的 torch |
+| `profile` | 在 Nsight Systems 或 Nsight Compute 下跑命令，返回解析后的报告 | `nsys` / `ncu` |
+| `top_kernels` | 从已保存的报告里取最重的 n 个 kernel，附 ncu 吞吐和占用率 | 无 |
+| `disasm` | 给 cubin 或 Triton 缓存里最新的同名 kernel 出 PTX 或 SASS | `cuobjdump` |
+| `bench` | 把脚本跑 n 次，收集它打印的 `{"ms": …, "ok": …}`，返回均值、标准差、最小值 | 你的 torch |
+| `verify` | 基线和候选交替各跑 n 次；给出加速比和裁决：`faster`、`slower`、`inconclusive`、`incorrect`（任一次 `ok=false`，不报加速比）、`invalid`（shape、dtype、种子或计时协议被改） | 你的 torch |
+| `record` | 把 verify 结果写到 `results/<目标>/`，从日志重新生成排行榜，并告诉 agent 这次改动是否超过本轮最好成绩 | 无 |
+
+`torch_trace`、`bench`、`verify`、`record` 在任何装了 PyTorch 的机器上都能用。Nsight 是可选的，只是让图更清楚。
+
+## 循环
+
+[`skills/kernel-speedrun/SKILL.md`](https://github.com/xinhuagu/hotkernel/blob/main/skills/kernel-speedrun/SKILL.md) 就是全部方法：
+
+1. `bench` 基线，这是要打败的数字。
+2. `torch_trace` 或 `profile` 找到真正占大头的 kernel。
+3. 用 kernel 的 flops 和 bytes 调 `roofline`：带宽瓶颈的要融合，算力瓶颈的要上 tensor core、加大分块。
+4. Triton kernel 第一次编译后 `disasm`：寄存器溢出、访存不合并、长依赖链在 SASS 里都看得见。
+5. 一个假设、一处改动，然后 `verify(candidate, baseline, n=7)`。只有差距超过 `2 * sqrt(std_b²/n + std_c²/n)` 且候选每次都通过正确性检查，才返回 `faster`。
+6. 无论输赢都 `record()`。它写日志和排行榜，agent 从不改排行榜。只有 `record()` 说这次超过了本轮最好成绩才保留，否则回滚。
+7. 连续三次改动都没超过最好成绩，或 kernel 已在实测带宽地板的 10% 以内，就停。
+
+它就是把 [autoresearch](https://github.com/karpathy/autoresearch) 的指标从训练 loss 换成 kernel 墙钟时间。
+
+## 实测，不是宣称
+
+让 LLM 写 CUDA kernel 这件事有信誉问题：2025 年 AI CUDA Engineer 宣称 10 到 100 倍，后来被发现绕过了自己的正确性检查；KernelBench 之所以存在，就是因为"编译通过"和"又对又快"是两回事。hotkernel 的回答是结构性的：
+
+- **协议写在基线里。** shape、dtype、种子、参考实现、容差和计时器都在 agent 不能改的基线文件里，候选只提供一个函数。协议里任何一项不一致，`verify` 就返回 `invalid`。
+- **计时器错过两次，都是公开改正的。** 第一版复用同一个输入，让 96 MB 的 L2 冒充了显存带宽。第二版用清零缓冲区的方式清 L2，结果每次调用多算了约 45 微秒别人的写回；是 softmax 的 agent 发现 Nsight 和 `verify` 差了一倍。第三版轮换总量超过 L2 两倍的缓冲区，并用五个流式 kernel 标定，它们都落在规格带宽的 79% 到 84%，与 ncu 硬件计数器一致。旧数据保留，标注为不计入。
+- **错了会很响。** `ok` 为假的运行 `verify` 不报加速比，每一行都带 n 和标准差，基线就在仓库里，谁都能重跑。
+
+## 平台
+
+- **需要 NVIDIA 显卡。** 参考卡 RTX 5090（sm_120）。roofline 表覆盖 5090、4090、3090 和 H100，每行附来源；在 `src/hotkernel/gpus.py` 里加你的卡。
+- **WSL2 是参考平台。** 九个工具全部在 RTX 5090、WSL2 Ubuntu 24.04、驱动 617.42 上验证过：`nsys` 2026.1.3 和 `ncu` 2026.2.1 从 NVIDIA 的 apt 源解包到用户目录（不需要 sudo），`cuobjdump` 和 `nvdisasm` 直接来自 Triton 的 wheel（不需要装 CUDA toolkit）。`ncu` 需要一次性开放 GPU 性能计数器权限（NVIDIA 控制面板，开发者设置）。版本、命令和原始输出见 [`docs/platform-matrix.md`](https://github.com/xinhuagu/hotkernel/blob/main/docs/platform-matrix.md)。
+- **原生 Windows：** server 能跑（纯 Python）。如果你的 torch 在 WSL2 里，通过 `wsl.exe` 启动 server；平台矩阵里有完整的 `claude mcp add` 命令。
+- **RTX 50 系上的 Triton：** FlashAttention 2/3/4 在 sm_120 上都跑不了，这正是手调 Triton kernel 在这些卡上重要的原因。
+
+## 许可证
+
+Apache-2.0。

hotkernel-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "hotkernel"
+version = "0.1.0"
+description = "Find the hot kernel, cool it down: an Nsight/SASS MCP server with a verify-and-record contract and a kernel-speedrun loop for coding agents."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [{ name = "Xinhua Gu" }]
+keywords = ["mcp", "cuda", "triton", "nsight", "gpu", "profiling", "kernel", "claude-code", "codex"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: GPU :: NVIDIA CUDA",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Debuggers",
+]
+dependencies = [
+  "mcp>=1.2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+hotkernel = "hotkernel.server:main"
+
+[project.urls]
+Homepage = "https://github.com/xinhuagu/hotkernel"
+Issues = "https://github.com/xinhuagu/hotkernel/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hotkernel"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/hotkernel", "skills", "README.md", "README_zh.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"