# shanselman/gputaskman architecture

> Architecture diagram of the GitHub repository shanselman/gputaskman, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shanselman/gputaskman
- Repository: https://github.com/shanselman/gputaskman

## Overview

gputaskman is a cross-platform terminal monitor for GPU devices and per-process workloads. The user launches the CLI, which gathers device and process counters, enriches process rows with runtime/model and LLM-buffer evidence, then presents a live TUI or script-friendly report; recording and comparison are additional output paths. Backend and platform details are mapped from the README and source index. Several subsystem links rely on indexed imports or README statements rather than sampled call sites, so uncertain connections are omitted.

Main entry points: [`src/gputaskman/collector.py`](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/collector.py) (Snapshot collector), [`src/gputaskman/cli.py`](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/cli.py) (CLI), [`src/gputaskman/llm.py`](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/llm.py) (LLM analysis), [`src/gputaskman/app.py`](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/app.py) (Live TUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and presentation"]
  node_cli["CLI<br/>[cli.py]"]
  node_tui["Live TUI<br/>[app.py]"]
end

subgraph group_sampling["GPU sampling"]
  node_collector["Snapshot collector<br/>[collector.py]"]
  node_recovery["Device recovery<br/>[recovery.py]"]
end

subgraph group_inspection["Process and model insight"]
  node_procinfo["Process inspection<br/>[procinfo.py]"]
  node_llm["LLM analysis<br/>[llm.py]"]
  node_gguf["GGUF estimates<br/>[gguf.py]"]
end

subgraph group_platform["Platform measurements"]
  node_adapters["Adapter discovery<br/>[dxgi.py]"]
  node_windows["Windows counters<br/>[pdh.py]"]
  node_nvml["NVIDIA telemetry<br/>[nvml.py]"]
  node_drm["Linux DRM backend<br/>[drm.py]"]
  node_linux["Linux integration<br/>[linux.py]"]
  node_macos["Apple GPU backend<br/>[macos.py]"]
  node_wsl["WSL host counters<br/>[wslhost.py]"]
  node_amd["AMD telemetry<br/>[adl.py]"]
  node_amdsmi["AMD SMI<br/>[amdsmi.py]"]
  node_host["Host sampler<br/>[host.py]"]
end

subgraph group_output["Reports and history"]
  node_report["Text and JSON<br/>[report.py]"]
  node_record["Snapshot recording<br/>[record.py]"]
  node_diff["Snapshot comparison<br/>[diff.py]"]
end

node_user(("User"))
node_localruntimes["Local LLM servers"]

node_user -->|"runs"| node_cli
node_cli -->|"launches"| node_tui
node_cli -->|"samples"| node_collector
node_cli -->|"formats output"| node_report
node_cli -->|"records snapshots"| node_record
node_cli -->|"compares snapshots"| node_diff
node_tui -->|"refreshes snapshot"| node_collector
node_tui -->|"samples system stats"| node_host
node_collector -->|"enumerates GPUs"| node_adapters
node_collector -->|"reads counters"| node_windows
node_collector -->|"samples NVIDIA"| node_nvml
node_collector -->|"samples Linux DRM"| node_drm
node_collector -->|"uses Linux backend"| node_linux
node_collector -->|"uses Apple backend"| node_macos
node_collector -->|"reads host data"| node_wsl
node_collector -->|"samples AMD"| node_amd
node_collector -->|"samples AMD"| node_amdsmi
node_collector -->|"inspects processes"| node_procinfo
node_collector -->|"analyzes workloads"| node_llm
node_llm -->|"estimates buffers"| node_gguf
node_procinfo -->|"reads model metadata"| node_gguf
node_llm -.->|"queries APIs"| node_localruntimes
node_record -->|"captures snapshots"| node_collector
node_record -->|"serializes data"| node_report
node_diff -->|"compares workload details"| node_llm
node_recovery -->|"reinitializes sampling"| node_collector
node_recovery -->|"refreshes device access"| node_nvml

click node_cli "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/cli.py"
click node_tui "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/app.py"
click node_collector "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/collector.py"
click node_adapters "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/dxgi.py"
click node_windows "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/pdh.py"
click node_nvml "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/nvml.py"
click node_drm "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/drm.py"
click node_linux "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/linux.py"
click node_macos "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/macos.py"
click node_wsl "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/wslhost.py"
click node_amd "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/adl.py"
click node_amdsmi "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/amdsmi.py"
click node_procinfo "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/procinfo.py"
click node_llm "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/llm.py"
click node_gguf "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/gguf.py"
click node_host "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/host.py"
click node_report "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/report.py"
click node_record "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/record.py"
click node_diff "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/diff.py"
click node_recovery "https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/recovery.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_tui,node_user toneBlue
class node_collector,node_recovery toneAmber
class node_procinfo,node_llm,node_gguf,node_localruntimes toneMint
class node_adapters,node_windows,node_nvml,node_drm,node_linux,node_macos,node_wsl,node_amd,node_amdsmi,node_host toneRose
class node_report,node_record,node_diff toneIndigo
```

## Components

### Entry and presentation

- [CLI](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/cli.py): `src/gputaskman/cli.py`
- [Live TUI](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/app.py): `src/gputaskman/app.py`

### GPU sampling

- [Snapshot collector](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/collector.py): `src/gputaskman/collector.py`
- [Device recovery](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/recovery.py): `src/gputaskman/recovery.py`

### Process and model insight

- [Process inspection](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/procinfo.py): `src/gputaskman/procinfo.py`
- [LLM analysis](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/llm.py): `src/gputaskman/llm.py`
- [GGUF estimates](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/gguf.py): `src/gputaskman/gguf.py`

### Platform measurements

- [Adapter discovery](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/dxgi.py): `src/gputaskman/dxgi.py`
- [Windows counters](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/pdh.py): `src/gputaskman/pdh.py`
- [NVIDIA telemetry](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/nvml.py): `src/gputaskman/nvml.py`
- [Linux DRM backend](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/drm.py): `src/gputaskman/drm.py`
- [Linux integration](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/linux.py): `src/gputaskman/linux.py`
- [Apple GPU backend](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/macos.py): `src/gputaskman/macos.py`
- [WSL host counters](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/wslhost.py): `src/gputaskman/wslhost.py`
- [AMD telemetry](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/adl.py): `src/gputaskman/adl.py`
- [AMD SMI](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/amdsmi.py): `src/gputaskman/amdsmi.py`
- [Host sampler](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/host.py): `src/gputaskman/host.py`

### Reports and history

- [Text and JSON](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/report.py): `src/gputaskman/report.py`
- [Snapshot recording](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/record.py): `src/gputaskman/record.py`
- [Snapshot comparison](https://github.com/shanselman/gputaskman/blob/main/src/gputaskman/diff.py): `src/gputaskman/diff.py`

### Other components

- **User**
- **Local LLM servers**

## Connections

- User → CLI: runs (evidence: `README.md`)
- CLI → Live TUI: launches (evidence: `src/gputaskman/cli.py`)
- CLI → Snapshot collector: samples (evidence: `src/gputaskman/cli.py`)
- CLI → Text and JSON: formats output (evidence: `src/gputaskman/cli.py`)
- CLI → Snapshot recording: records snapshots (evidence: `src/gputaskman/cli.py`)
- CLI → Snapshot comparison: compares snapshots (evidence: `src/gputaskman/cli.py`)
- Live TUI → Snapshot collector: refreshes snapshot (evidence: `src/gputaskman/app.py`)
- Live TUI → Host sampler: samples system stats (evidence: `src/gputaskman/app.py`)
- Snapshot collector → Adapter discovery: enumerates GPUs (evidence: `src/gputaskman/collector.py`)
- Snapshot collector → Windows counters: reads counters (evidence: `src/gputaskman/collector.py`)
- Snapshot collector → NVIDIA telemetry: samples NVIDIA (evidence: `src/gputaskman/collector.py`)
- Snapshot collector → Linux DRM backend: samples Linux DRM (evidence: `src/gputaskman/collector.py`)
- Snapshot collector → Linux integration: uses Linux backend (evidence: `src/gputaskman/collector.py`)
- Snapshot collector → Apple GPU backend: uses Apple backend (evidence: `src/gputaskman/collector.py`)
- Snapshot collector → WSL host counters: reads host data (evidence: `src/gputaskman/collector.py`)
- Snapshot collector → AMD telemetry: samples AMD (evidence: `src/gputaskman/collector.py`)
- Snapshot collector → AMD SMI: samples AMD (evidence: `src/gputaskman/collector.py`)
- Snapshot collector → Process inspection: inspects processes (evidence: `src/gputaskman/collector.py`)
- Snapshot collector → LLM analysis: analyzes workloads (evidence: `src/gputaskman/collector.py`)
- LLM analysis → GGUF estimates: estimates buffers (evidence: `src/gputaskman/llm.py`)
- Process inspection → GGUF estimates: reads model metadata (evidence: `src/gputaskman/procinfo.py`)
- LLM analysis → Local LLM servers: queries APIs (evidence: `src/gputaskman/llm.py`)
- Snapshot recording → Snapshot collector: captures snapshots (evidence: `src/gputaskman/record.py`)
- Snapshot recording → Text and JSON: serializes data (evidence: `src/gputaskman/record.py`)
- Snapshot comparison → LLM analysis: compares workload details (evidence: `src/gputaskman/diff.py`)
- Device recovery → Snapshot collector: reinitializes sampling (evidence: `src/gputaskman/recovery.py`)
- Device recovery → NVIDIA telemetry: refreshes device access (evidence: `src/gputaskman/recovery.py`)