# vram-viz

Real-time GPU memory analyzer with a cyberpunk dashboard. See exactly where your VRAM went — per-process dedicated and shared GPU memory, mapped to running processes with live auto-refresh.

**Works on Windows** (uses GPU performance counters for accurate per-process VRAM — nvidia-smi reports N/A for this on WDDM drivers, but vram-viz gets the real numbers).

## Install

```bash
pip install vram-viz
```

Or run from source:

```bash
git clone https://github.com/olegp/vram-viz.git
cd vram-viz
pip install -e .
```

## Usage

### Web Dashboard (default)

```bash
vram-viz                  # opens at http://localhost:5111
vram-viz --port 8080      # custom port
```

Features:
- Animated geometric mesh background
- Real-time GPU utilization sparkline chart
- VRAM treemap — proportional blocks showing which processes own what memory
- Per-process table with sortable columns and terminate buttons
- Auto-refresh every 3 seconds
- Subtle glitch title + scanning line effect

### CLI Mode

```bash
vram-viz --cli              # one-shot terminal table
vram-viz --cli --top 10     # top 10 processes only
vram-viz --cli --watch 2    # refresh every 2s
```

### JSON Output

```bash
vram-viz --json             # pipe-friendly JSON dump
```

## How It Works

| Layer | Source | What it provides |
|-------|--------|------------------|
| GPU stats | NVML (`nvidia-ml-py`) | Total/used/free VRAM, temperature, utilization %, power draw |
| Per-process VRAM | Windows GPU Performance Counters | Dedicated + shared GPU memory per PID (the only reliable source on WDDM) |
| Process names | `psutil` | Resolves PIDs to process names, executables, command lines |

## Requirements

- Windows 10+ (GPU performance counters are a Windows feature)
- NVIDIA GPU with drivers installed
- Python 3.9+

## License

MIT
