Graphsignal skill
A GPU profiler for AI agents: the agent runs vLLM or SGLang under graphsignal-run, reads the metrics and tunes flags for speed
- 276 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- The agent installs packages, starts model servers on GPUs and injects CUPTI or ROCm into the workload process
- The unauthenticated `/signals` endpoint shows process command lines and resources; if exposed beyond `127.0.0.1` the whole network can see them
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/graphsignalDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent installs packages, starts model servers on GPUs and injects CUPTI or ROCm into the workload process
- The unauthenticated `/signals` endpoint shows process command lines and resources; if exposed beyond `127.0.0.1` the whole network can see them
This is third-party code. Review the repository files before installing.
What it does
Graphsignal is a GPU profiler designed to be operated by an agent. It runs as a separate process next to an inference engine (vLLM, SGLang, TensorRT-LLM, PyTorch or any GPU application) and serves every measurement through a local JSON API. The agent launches a workload, benchmarks it, reads the data, changes flags or code and measures again. The skill is self-contained: you put `SKILL.md` into the skills directory and the agent installs the profiler itself, runs the workload under it and reads the result. The request sounds like optimize the latency of this vLLM server. Manual installation is `uv tool install 'graphsignal[cu12]'` or `pip install 'graphsignal[cu12]'`, with the cu13 extra for CUDA 13. You wrap the workload with a command such as `graphsignal-run vllm serve <model> --port 8001`. The profiler collects CUDA kernel and graph timing through CUPTI or ROCm, memory transfers and synchronization, NVML and AMD SMI telemetry (utilization, memory, power, temperature, clocks, NVLink and PCIe, XID and ECC errors), process metrics, engine metrics from Prometheus and console errors. The `/signals` endpoint on `127.0.0.1:18259` serves JSON, `/metrics` serves the same statistics in Prometheus format and `graphsignal-top` shows a live terminal view. For precise code markup there is a C++ header, `probe.h`.
Who it is for. Inference and MLOps engineers who run models on their own GPUs and want an agent to handle the profile-and-tune loop.
Good fit when
- A vLLM or SGLang server answers slower than expected and you need to see which kernels and synchronizations take the time
- You want to hand the agent the job of tuning launch flags and measuring each change right away
- You need to push GPU and engine metrics to Prometheus and Grafana with a leaderboard of the heaviest kernels
- The engine crashes and the cause hides in the console: you want errors and tracebacks in one JSON
- You need to time one piece of code or a kernel through `probe.h` instrumentation
Not a fit when
- The machine has no NVIDIA or AMD GPU: the profiler gathers CUPTI, NVML, ROCm and AMD SMI data
- You want a profiler with a graphical UI for manual analysis: the main channel here is JSON and the terminal
- You are profiling on Windows or macOS: the cu12 and cu13 extras work on Linux only
- You need detailed per-kernel tracing on AMD in production: that mode slows the workload noticeably
Example request
Use graphsignal to optimize latency per token for this vLLM server and show which kernels took the most time before and after the changesLimitations
- The `cu12` and `cu13` extras for GPU profiling work on Linux only. NVIDIA needs CUDA 12 or 13 and AMD needs ROCm.
- The `--cuda-graph-trace node` mode and `--rocm-kernel-trace all` tracing are meant for investigation and add noticeable overhead, so they do not stay in production.
- Binding `--listen-host 0.0.0.0` exposes the unauthenticated endpoint to the whole network, so restrict access with network rules.
- Once per run the profiler asks `api.graphsignal.com` about a new version; turn it off with `GRAPHSIGNAL_DISABLE_VERSION_CHECK=1`.
How to disable. Start the workload without the `graphsignal-run` wrapper and the profiler stops working. Remove the skill by deleting `~/.claude/skills/graphsignal`. `uv tool uninstall graphsignal` or `pip uninstall graphsignal` removes the package. The `GRAPHSIGNAL_API_KEY` variable turns on uploading data to the server; do not set it unless needed.
FAQ
How do I install the Graphsignal skill in Claude Code?
Run `mkdir -p ~/.claude/skills/graphsignal`, then download SKILL.md with `curl -fsSL https://raw.githubusercontent.com/graphsignal/graphsignal/main/SKILL.md -o ~/.claude/skills/graphsignal/SKILL.md`. For other agents it is enough to point at that file.
How do I start profiling?
Wrap your usual launch command: `graphsignal-run vllm serve <model> --port 8001`. It works with any command, for example `graphsignal-run python my_app.py`. Then read `http://127.0.0.1:18259/signals`.
Which engines are supported?
Engine metrics come from Prometheus for vLLM, SGLang and TensorRT-LLM. The CUPTI or ROCm GPU profile works with any GPU application, such as PyTorch.
Does data leave the machine?
Not unless `GRAPHSIGNAL_API_KEY` is set. The profiler listens on `127.0.0.1` and does not record prompts or completions. The network is touched only by the request to `api.graphsignal.com` about a new version, which a variable turns off.
How do I see metrics in Grafana?
The same listener serves Prometheus format at `http://127.0.0.1:18259/metrics`. For a leaderboard of the heaviest kernels use the query `topk(20, rate(cuda_kernels_nanoseconds_total[1m]))`.
Discussion
No questions or reviews yet.
Related
SkillsThe official Vast.ai skill: an agent searches GPU offers, rents instances and manages them through vastai.
The official Grafana skill set: PromQL, Loki, Tempo, Alloy, k6, dashboards and alerting for Claude Code, Cursor and Codex
13 NVIDIA skills for an agent on a Jetson device: diagnostics, memory, LLM serving, packages and video and inference benchmarks
Runpod Plugins: GPU cloud for agents
Runpod Official Plugins
The Runpod plugin with 16 skills and an MCP server: an agent starts pods, deploys endpoints and audits GPU spend
Glyd’s CLI runs language models on NVIDIA GPUs with compressed weights and cache to reduce the memory needed for inference.
A skill with a local index of 27,700 Microsoft Graph endpoints: endpoint search, permissions and API calls from the command line
README in short
The README presents the profiler as an agent tool, lists what it collects and starts with installation through the skill, then manual installation with uv and pip and the `graphsignal-run` flags. After that come the optimization loop through `/signals`, the Prometheus format, the live view, measurement modes with their overhead, probes and a section on security and privacy.
README badge
Original SKILL.md
---
name: graphsignal
description: >-
Profile AI inference workloads (vLLM, SGLang, TensorRT-LLM, PyTorch, any GPU
application) with the Graphsignal profiler and read the results from its
local /signals JSON endpoint. Use when the user wants GPU profiling,
kernel/CUDA-graph timing, engine metrics, or error monitoring for a workload,
asks about `graphsignal-run`, or wants an AI agent to inspect a running
workload's performance.
---
# Graphsignal Profiler
Graphsignal is a GPU profiler built to be operated by an AI agent: install it, launch the workload under it, benchmark it, read the signals, change flags or code, measure again.
It observes a workload from a **sidecar process**: `graphsignal-run` launches the workload unmodified — no code changes, no imports — injects the CUPTI/ROCm activity library into it, and starts a watcher process that collects everything and serves it as one JSON document at `http://127.0.0.1:18259/signals`. Collected out of the box: GPU kernel/graph/transfer/sync timing (CUDA and ROCm), NVML device telemetry, process and host metrics, the engine's own Prometheus metrics (vLLM, SGLang, TensorRT-LLM), and errors extracted from console output. No profiling data is uploaded anywhere unless `GRAPHSIGNAL_API_KEY` is set.
## Install
Install as a uv tool, isolated from the workload environment:
```bash
UV_TOOL_BIN_DIR=/usr/local/bin uv tool install 'graphsignal[cu12]' # CUDA 12.x
# or
UV_TOOL_BIN_DIR=/usr/local/bin uv tool install 'graphsignal[cu13]' # CUDA 13.x
```
`UV_TOOL_BIN_DIR=/usr/local/bin` puts `graphsignal-run` on `PATH` for every shell, including non-interactive scripts and containers. `pip install 'graphsignal[cu12]'` works too. The `cu12`/`cu13` extras are Linux-only, needed for GPU profiling; on AMD install without an extra (`uv tool install graphsignal`) — GPU profiling goes through AMD's `rocprofiler-sdk`, which ships with ROCm 7+.
Root is not required. Verify the install with `graphsignal-run --version`, and readiness after a launch with `curl -s http://127.0.0.1:18259/health` → `{"status": "ok"}`.
## Run
Wrap the workload's launch command:
```bash
graphsignal-run vllm serve Qwen/Qwen2.5-1.5B-Instruct --port 8000
graphsignal-run sglang serve --model-path <model> --port 8000
graphsignal-run trtllm-serve <model> --port 8000
graphsignal-run python my_app.py
```
Leading flags (before the command):
- `--metrics-port PORT` — where to scrape the engine's Prometheus metrics (default: derived from the engine's `--port`).