A GPU task manager for Windows, Linux, and WSL: per-process VRAM, GPU activity, and LLM model/KV-cache insights (Windows AMD and NVIDIA).
Python
Add system RAM and CPU panel and per-process RAM/CPU% columns
Michael Erickson6e8bf810ea11
diff --git a/README.md b/README.mdindex 844aee8..2e7cb3c 100644--- a/README.md+++ b/README.md@@ -656,6 +656,7 @@ Identification is designed to stay cheap. Measured on one Windows machine:| macOS: `ioreg` device stats + Metal clients | ~10 ms | Every refresh || macOS: memory-map scan (`proc_pidinfo` region walk) | ~4 ms per process | Same policy as the memory-map scan above || macOS: `footprint` GPU memory | ~70 ms per process, background thread | Busy and new processes every ~2 s, idle ones every 30 s (54 runs in 40 s with 27 GPU processes, M4 Mac mini) |+| System RAM/CPU panel (fork): Windows `NtQuerySystemInformation` process list + psutil totals | ~6 ms for ~480 processes (Windows 11, i9-13900K) | Every refresh; `--no-system` turns it off. psutil per-process `memory_info`/`cpu_times` took ~1 s per pass here, so it is only the non-Windows fallback |With two llama-servers running, a steady refresh costs roughly 15-30 ms of CPU (about 340 ms beforeprocess details were cached).diff --git a/src/gputaskman/app.py b/src/gputaskman/app.pyindex c8e68e3..b40450c 100644--- a/src/gputaskman/app.py+++ b/src/gputaskman/app.py@@ -17,6 +17,7 @@ from textual.screen import ModalScreenfrom textual.widgets import DataTable, Footer, Markdown, Select, Staticfrom textual.worker import get_current_worker+from .host import HostSample, HostSamplerfrom .collector import BACKEND, Collector, ProcRow, Snapshot, enumerate_adapters, ordered_adaptersfrom .llm import gbfrom .nvml import NvDevice, format_metric@@ -174,6 +175,7 @@ class GpuTaskManager(App):CSS = """Screen { layout: vertical; }#dashboard { height: auto; max-height: 50%; }+ #system { height: auto; border: round $success; padding: 0 1; }#device { height: auto; border: round $accent; padding: 0 1; }#history { height: auto; border: round $secondary; padding: 0 1; }#chart-controls { height: 1; }@@ -196,6 +198,7 @@ class GpuTaskManager(App):Binding("question_mark", "help", "Explain"),]SORTS = [("VRAM", lambda r: -(r.gpu.shown_vram or 0)), ("GPU%", lambda r: -r.gpu.gpu_pct),+ ("RAM", lambda r: -(r.ram or 0)), ("CPU%", lambda r: -(r.cpu or 0)),("spill", lambda r: -r.gpu.shared), ("paged", lambda r: -r.gpu.paged_out),("name", lambda r: r.name.lower())]CHART_COLORS = {@@ -210,8 +213,13 @@ class GpuTaskManager(App):}CHARTS = tuple(CHART_COLORS)- def __init__(self, gpu_index: int | None = None, interval: float = 1.0, host: bool = True) -> None:+ def __init__(self, gpu_index: int | None = None, interval: float = 1.0, host: bool = True,+ system: bool = True) -> None:super().__init__()+ self.system = system+ self.host_sample: HostSample | None = None+ self.hist_cpu: deque = deque(maxlen=60)+ self.hist_ram: deque = deque(maxlen=60)self.gpu_index = gpu_indexself.interval = intervalself.host = host@@ -248,6 +256,8 @@ class GpuTaskManager(App):def compose(self) -> ComposeResult:with VerticalScroll(id="dashboard"):+ if self.system:+ yield Static("Sampling RAM and CPU...", id="system")yield Static("Sampling GPU counters...", id="device")with Vertical(id="history"):with Horizontal(id="chart-controls"):@@ -266,7 +276,10 @@ class GpuTaskManager(App):def on_mount(self) -> None:t = self.query_one("#procs", DataTable)- for col in ("PID", "Process", "Kind", "Runtime", "VRAM", "Spill", "Paged", "GPU%", "3D", "Copy", "Video", "What's inside"):+ cols = ["PID", "Process", "Kind", "Runtime", "VRAM", "Spill", "Paged", "GPU%", "3D", "Copy", "Video"]+ if self.system:+ cols += ["RAM", "CPU%"]+ for col in (*cols, "What's inside"):t.add_column(col, key=col)t.focus()self.poll()@@ -285,12 +298,14 @@ class GpuTaskManager(App):collector.host_status = "off (multi-GPU WSL host matching is not validated; use --gpu N)"stack.callback(collector.close)collectors.append(collector)+ hs = HostSampler() if self.system else Noneworker.cancelled_event.wait(0.5)while not worker.is_cancelled:if not self.paused:snapshots = [collector.sample() for collector in collectors]+ host = hs.sample() if hs else Noneif not worker.is_cancelled:- self.call_from_thread(self.apply_all, snapshots)+ self.call_from_thread(self.apply_all, snapshots, host)worker.cancelled_event.wait(self.interval)# ------------------------------------------------------------------ rendering@@ -298,10 +313,18 @@ class GpuTaskManager(App):def apply(self, snap: Snapshot) -> None:self.apply_all([snap])- def apply_all(self, snapshots: list[Snapshot]) -> None:+ def apply_all(self, snapshots: list[Snapshot], host: HostSample | None = None) -> None:if not self.is_running:return # A worker may finish sampling after shutdown has removed the widgets.self.snapshots = snapshots+ if host is not None:+ self.host_sample = host+ self.hist_cpu.append(host.cpu_pct)+ self.hist_ram.append(100 * host.ram_used / host.ram_total if host.ram_total else None)+ for snap in snapshots:+ for row in snap.procs: # Windows (W:) / outside (H:) rows have no local pid: RAM/CPU stay unknown+ hp = self.host_sample.proc(row.pid) if self.host_sample and not row.host else None+ row.ram, row.cpu = (hp.rss, hp.cpu_pct) if hp else (None, None)multi = len(snapshots) > 1table = self.query_one("#procs", DataTable)if multi and "GPU" not in table.columns:@@ -370,12 +393,49 @@ class GpuTaskManager(App):if len(self.snapshots) > 1:devices.append(Text(f"GPU {index}", style="bold"))devices.append(self.render_device(snap))+ if self.system and self.host_sample:+ self.query_one("#system", Static).update(self.render_system(self.host_sample))device = self.query_one("#device", Static)device.border_title = "Slim monitoring" if self.monitoring else "Full diagnostics"device.update(Group(*devices) if len(self.snapshots) > 1 else devices[0])self.render_charts()+ def render_system(self, h: HostSample) -> Group:+ """System RAM + CPU (fork addition). All values are OS-reported via psutil / NtQuerySystemInformation."""+ width = max(min(self.size.width - 50, 80), 16)+ ram_pct = 100 * h.ram_used / h.ram_total if h.ram_total else 0+ ram = Text("RAM ")+ ram.append_text(stacked_bar([(h.ram_used, "dodger_blue2")], h.ram_total, width))+ ram.append(f" {gb(h.ram_used)} / {gb(h.ram_total)}", style="bold")+ ram.append(f" {ram_pct:.0f}% free {gb(h.ram_available)}", style="grey62")+ if h.swap_total:+ ram.append(f" pagefile {gb(h.swap_used)}/{gb(h.swap_total)}",+ style="yellow" if h.swap_used > h.swap_total / 4 else "grey62")+ cpu = Text("CPU ")+ cpu.append_text(stacked_bar([(h.cpu_pct, "green3")], 100, width))+ cpu.append(f" {h.cpu_pct:4.0f}%", style="bold")+ cpu.append(f" {h.logical} threads" + (f"/{h.physical} cores" if h.physical else "")+ + (f" {h.cpu_mhz:.0f} MHz" if h.cpu_mhz else ""), style="grey62")+ cores = Text(" ")+ for v in h.per_core:+ cores.append(SPARK[min(int(v / 100 * (len(SPARK) - 1) + 0.5), len(SPARK) - 1)],+ style="red" if v >= 90 else "yellow" if v >= 60 else "green3")+ cores.append(" per-thread", style="grey50")+ hist = Text(" ")+ hist.append(spark(self.hist_cpu, 30), style="green3")+ hist.append(" CPU 60s ", style="grey50")+ hist.append(spark(self.hist_ram, 30), style="dodger_blue2")+ hist.append(" RAM 60s", style="grey50")+ lines = [ram, cpu, cores, hist]+ if not self.monitoring:+ top = Text(" top RAM: ", style="grey62")+ top.append(" ".join(f"{p.name} {gb(p.rss)}" for p in h.top("rss", 5)))+ top.append("\n top CPU: ", style="grey62")+ top.append(" ".join(f"{p.name} {p.cpu_pct:.0f}%" for p in h.top("cpu_pct", 5) if p.cpu_pct >= 0.5) or "idle")+ lines.append(top)+ return Group(*lines)+def render_device(self, s: Snapshot) -> Group:nv = s.nvname = s.adapter.name if s.adapter else (nv.name if nv else "GPU")@@ -600,6 +660,10 @@ class GpuTaskManager(App):pct(e.get("3d", 0) + e.get("compute", 0) if split else None),pct(e.get("copy", 0) if split else None),pct(e.get("decode", 0) + e.get("encode", 0) + e.get("video", 0) if split else None),+ *([Text(gb(r.ram) if r.ram is not None else "n/a", justify="right",+ style="" if r.ram is not None else "grey62"),+ pct(r.cpu) if r.cpu is not None or r.host else Text("…", justify="right", style="grey62")]+ if self.system else []),Text(r.inside, style="magenta" if r.llm else "grey62", overflow="ellipsis", no_wrap=True),*([Text("?" if s.backend == "wsl" and not r.host else str(r.gpu_index))]if len(self.snapshots) > 1 else []),diff --git a/src/gputaskman/cli.py b/src/gputaskman/cli.pyindex 8ef2cea..7b801a3 100644--- a/src/gputaskman/cli.py+++ b/src/gputaskman/cli.py@@ -38,6 +38,7 @@ def main() -> None:ap.add_argument("--list-gpus", action="store_true", help="list selectable GPU adapters and exit")ap.add_argument("--no-host", action="store_true",help="WSL: don't read Windows host GPU counters through interop (WSL VM total, Windows apps)")+ ap.add_argument("--no-system", action="store_true", help="hide the system RAM/CPU panel and columns")ap.add_argument("-i", "--interval", type=float, default=1.0, help="refresh seconds (default 1)")args = ap.parse_args()if args.gpu is not None and args.gpu < 0:@@ -65,6 +66,7 @@ def main() -> None:if args.once or args.json:from .collector import Collector+ from .host import HostSamplerfrom .report import dumptry:@@ -76,12 +78,15 @@ def main() -> None:c.host.wait(15.0) # WSL: the first Windows counter sample takes several secondsif hasattr(c.counters, "warm_up"):c.counters.warm_up(15.0) # macOS: per-process GPU memory comes from a background footprint pass+ hs = None if args.no_system else HostSampler()+ if hs:+ hs.sample() # CPU% is a rate too; this primes ittime.sleep(1.0) # engine utilization is a rate; needs two samples- print(dump(c.sample(), args.json))+ print(dump(c.sample(), args.json, hs.sample() if hs else None))finally:c.close()returnfrom .app import GpuTaskManager- GpuTaskManager(gpu_index=args.gpu, interval=args.interval, host=not args.no_host).run()+ GpuTaskManager(gpu_index=args.gpu, interval=args.interval, host=not args.no_host, system=not args.no_system).run()diff --git a/src/gputaskman/collector.py b/src/gputaskman/collector.pyindex 9d3cd63..f8f07c0 100644--- a/src/gputaskman/collector.py+++ b/src/gputaskman/collector.py@@ -52,6 +52,8 @@ class ProcRow:host: bool = False # pid is from another PID namespace, never a local one (see origin)origin: str = "" # with host: "windows" (a Windows process seen from WSL) | "outside" (outside this container)gpu_index: int | None = None+ ram: int | None = None # system RAM (working set) from host.py; None = unknown, not zero+ cpu: float | None = None # % of the whole machine from host.py; None until the second sample@propertydef key(self) -> str:diff --git a/src/gputaskman/host.py b/src/gputaskman/host.pynew file mode 100644index 0000000..ffeaff8--- /dev/null+++ b/src/gputaskman/host.py@@ -0,0 +1,202 @@+"""System RAM and CPU, alongside the GPU view.++Every number here is reported by the OS through psutil (measured, not inferred). Unknown stays None:+a process we may not inspect has ``rss=None`` / ``cpu_pct=None``, never 0. Fork addition, not upstream.+"""++from __future__ import annotations++import struct+import sys+import time+from dataclasses import dataclass, field++import psutil+++@dataclass+class HostProc:+ pid: int+ name: str+ rss: int | None # resident / working set bytes+ private: int | None # Windows private bytes (commit charged to the process); None elsewhere+ cpu_pct: float | None # share of the WHOLE machine (0-100), like Task Manager; None on the first sample+++@dataclass+class HostSample:+ cpu_pct: float # whole machine, 0-100+ per_core: list[float]+ cpu_mhz: float | None+ logical: int+ physical: int | None+ ram_total: int+ ram_used: int # total - available (what Task Manager calls "In use", approximately)+ ram_available: int+ swap_total: int+ swap_used: int+ procs: list[HostProc] = field(default_factory=list)+ denied: int = 0 # processes whose memory we were not allowed to read+ cost_ms: float = 0.0++ def proc(self, pid: int | None) -> HostProc | None:+ return self._by_pid.get(pid) if pid is not None else None++ def __post_init__(self) -> None:+ self._by_pid = {p.pid: p for p in self.procs}++ def top(self, key: str, n: int = 5) -> list[HostProc]:+ return sorted((p for p in self.procs if getattr(p, key) is not None), key=lambda p: -getattr(p, key))[:n]+++class HostSampler:+ """Keeps psutil.Process objects between samples: per-process CPU% is a rate and needs the previous reading."""++ def __init__(self) -> None:+ self._procs: dict[int, psutil.Process] = {}+ self._rated: set[int] = set() # pids with a previous CPU reading+ self._logical = psutil.cpu_count() or 1+ self._physical = psutil.cpu_count(logical=False)+ self._last_cpu: dict[int, int] = {}+ self._last_wall = 0.0+ psutil.cpu_percent(percpu=True) # prime the system-wide rate++ def sample(self) -> HostSample:+ t0 = time.perf_counter()+ per_core = psutil.cpu_percent(percpu=True)+ vm, sw = psutil.virtual_memory(), psutil.swap_memory()+ try:+ freq = psutil.cpu_freq()+ mhz = freq.current if freq and freq.current else None+ except (OSError, NotImplementedError): # unavailable on some platforms/containers+ mhz = None+ if _nt_query is not None:+ procs, denied = self._sample_nt(), 0+ return self._finish(t0, per_core, mhz, vm, sw, procs, denied)+ procs, denied, seen = [], 0, set()+ for p in psutil.process_iter():+ pid = p.pid+ seen.add(pid)+ p = self._procs.setdefault(pid, p)+ try:+ with p.oneshot():+ name = p.name()+ mi = p.memory_info()+ cpu = p.cpu_percent(None)+ except psutil.NoSuchProcess:+ continue+ except psutil.AccessDenied:+ denied += 1+ procs.append(HostProc(pid, _safe_name(p), None, None, None))+ continue+ first = pid not in self._rated+ self._rated.add(pid)+ procs.append(HostProc(pid, name, mi.rss, getattr(mi, "private", None),+ None if first else cpu / self._logical))+ for gone in self._procs.keys() - seen:+ del self._procs[gone]+ self._rated &= seen+ return self._finish(t0, per_core, mhz, vm, sw, procs, denied)++ def _sample_nt(self) -> list[HostProc]:+ now = time.perf_counter()+ rows = _nt_query()+ wall = now - self._last_wall if self._last_wall else None+ procs = []+ for pid, (name, ws, private, cpu100ns) in rows.items():+ prev = self._last_cpu.get(pid)+ cpu = None+ if wall and prev is not None and pid != 0: # pid 0 = System Idle Process: its "CPU" is idle time+ cpu = max(0.0, (cpu100ns - prev) / 1e7 / wall / self._logical * 100)+ procs.append(HostProc(pid, name, ws, private, cpu))+ self._last_cpu = {pid: r[3] for pid, r in rows.items()}+ self._last_wall = now+ return [p for p in procs if p.pid != 0]++ def _finish(self, t0, per_core, mhz, vm, sw, procs, denied) -> HostSample:+ return HostSample(+ cpu_pct=sum(per_core) / len(per_core) if per_core else 0.0, per_core=per_core, cpu_mhz=mhz,+ logical=self._logical, physical=self._physical,+ ram_total=vm.total, ram_used=vm.total - vm.available, ram_available=vm.available,+ swap_total=sw.total, swap_used=sw.used, procs=procs, denied=denied,+ cost_ms=(time.perf_counter() - t0) * 1000)+++# Windows: one NtQuerySystemInformation(SystemProcessInformation) call returns every process's working set,+# private bytes and CPU time. psutil opens each process instead: measured 2026-11-08 on a 483-process+# Windows 11 box, memory_info ~1.1 s and cpu_times ~1.0 s per pass, versus a few ms here. Same numbers:+# WorkingSetSize = psutil rss, PagefileUsage = psutil private. No process handle needed, so no AccessDenied.+_nt_query = None+if sys.platform == "win32" and struct.calcsize("P") == 8:+ import ctypes++ _ntdll = ctypes.WinDLL("ntdll")+ _ntdll.NtQuerySystemInformation.restype = ctypes.c_long++ def _nt_query_impl() -> dict[int, tuple[str, int, int, int]]:+ size = 1 << 20+ while True:+ buf = ctypes.create_string_buffer(size)+ need = ctypes.c_ulong()+ status = _ntdll.NtQuerySystemInformation(5, buf, size, ctypes.byref(need)) # SystemProcessInformation+ if status == -1073741820: # STATUS_INFO_LENGTH_MISMATCH: processes appeared; grow and retry+ size = max(size * 2, need.value + (64 << 10))+ continue+ if status < 0:+ raise OSError(f"NtQuerySystemInformation failed: 0x{status & 0xffffffff:08x}")+ break+ raw, base, out, off = buf.raw, ctypes.addressof(buf), {}, 0+ while True:+ nxt = struct.unpack_from("<I", raw, off)[0]+ user, kernel = struct.unpack_from("<qq", raw, off + 40)+ name_len, name_ptr = struct.unpack_from("<H6xQ", raw, off + 56)+ pid = struct.unpack_from("<Q", raw, off + 80)[0]+ ws, = struct.unpack_from("<Q", raw, off + 144)+ private, = struct.unpack_from("<Q", raw, off + 184)+ if name_ptr:+ name = raw[name_ptr - base:name_ptr - base + name_len].decode("utf-16-le", "replace")+ else:+ name = "System Idle Process" if pid == 0 else "?"+ out[pid] = (name, ws, private, user + kernel)+ if not nxt:+ return out+ off += nxt++ _nt_query = _nt_query_impl+++def _safe_name(p: psutil.Process) -> str:+ try:+ return p.name()+ except psutil.Error:+ return "?"+++def to_dict(h: HostSample) -> dict:+ return {+ "source": "psutil (OS-reported)",+ "cpu": {"pct": round(h.cpu_pct, 1), "per_core": h.per_core, "mhz": h.cpu_mhz,+ "logical": h.logical, "physical": h.physical},+ "ram": {"total": h.ram_total, "used": h.ram_used, "available": h.ram_available,+ "swap_total": h.swap_total, "swap_used": h.swap_used},+ "top_ram": [vars(p) for p in h.top("rss", 10)],+ "top_cpu": [vars(p) for p in h.top("cpu_pct", 10)],+ "denied": h.denied,+ "cost_ms": round(h.cost_ms, 1),+ }+++def to_text(h: HostSample) -> str:+ from .llm import gb++ lines = [f"CPU {h.cpu_pct:.0f}% {h.logical} threads" + (f" / {h.physical} cores" if h.physical else "")+ + (f" {h.cpu_mhz:.0f} MHz" if h.cpu_mhz else ""),+ f"RAM {gb(h.ram_used)} / {gb(h.ram_total)} available {gb(h.ram_available)}"+ f" swap/pagefile {gb(h.swap_used)} / {gb(h.swap_total)}",+ "", f"{'PID':>7} {'PROCESS':<28} {'RAM':>9} {'PRIVATE':>9} {'CPU%':>5}"]+ for p in h.top("rss", 10):+ lines.append(f"{p.pid:>7} {p.name[:28]:<28} {gb(p.rss):>9} {gb(p.private) if p.private is not None else 'n/a':>9} "+ f"{f'{p.cpu_pct:.0f}' if p.cpu_pct is not None else 'n/a':>5}")+ if h.denied:+ lines.append(f"({h.denied} processes not readable without admin)")+ return "\n".join(lines)diff --git a/src/gputaskman/report.py b/src/gputaskman/report.pyindex f0f0062..08cc2ff 100644--- a/src/gputaskman/report.py+++ b/src/gputaskman/report.py@@ -250,5 +250,13 @@ def to_text(s: Snapshot, limit: int = 30) -> str:return "\n".join(out)-def dump(s: Snapshot, as_json: bool) -> str:- return json.dumps(to_dict(s), indent=2, default=str) if as_json else to_text(s)+def dump(s: Snapshot, as_json: bool, host=None) -> str:+ """host: an optional host.HostSample (system RAM/CPU), added as a "host" section."""+ from . import host as hostmod++ if as_json:+ d = to_dict(s)+ if host is not None:+ d["host"] = hostmod.to_dict(host)+ return json.dumps(d, indent=2, default=str)+ return to_text(s) + ("\n\n" + hostmod.to_text(host) if host is not None else "")diff --git a/tests/test_host.py b/tests/test_host.pynew file mode 100644index 0000000..a18053e--- /dev/null+++ b/tests/test_host.py@@ -0,0 +1,40 @@+import os+import sys+import unittest++import psutil++from gputaskman import host+++class HostTests(unittest.TestCase):+ def test_unknown_is_not_zero(self):+ h = host.HostSample(cpu_pct=5, per_core=[5], cpu_mhz=None, logical=1, physical=1, ram_total=100,+ ram_used=40, ram_available=60, swap_total=0, swap_used=0,+ procs=[host.HostProc(1, "a", None, None, None), host.HostProc(2, "b", 10, 5, 0.0)])+ self.assertEqual([p.pid for p in h.top("rss")], [2]) # the unreadable process is not ranked as 0+ self.assertIsNone(h.proc(1).rss)+ self.assertIsNone(host.to_dict(h)["cpu"]["mhz"])++ @unittest.skipUnless(sys.platform == "win32", "NtQuerySystemInformation is Windows-only")+ def test_nt_query_matches_psutil(self):+ me = psutil.Process(os.getpid())+ name, ws, private, cpu = host._nt_query()[os.getpid()]+ mi = me.memory_info()+ self.assertEqual(name.lower(), me.name().lower())+ self.assertLess(abs(private - mi.private), 8 << 20)+ self.assertLess(abs(ws - mi.rss), 16 << 20)+ self.assertGreater(cpu, 0)++ def test_sampler_rates_cpu_after_second_sample(self):+ s = host.HostSampler()+ first = s.sample()+ self.assertTrue(all(p.cpu_pct is None for p in first.procs)) # a rate needs two readings+ second = s.sample()+ self.assertTrue(any(p.cpu_pct is not None for p in second.procs))+ self.assertTrue(0 <= second.cpu_pct <= 100)+ self.assertGreater(second.ram_total, second.ram_used > 0)+++if __name__ == "__main__":+ unittest.main()