rigdoctor/README.md

RigDoctor

A modular diagnostics, monitoring, and health-check toolkit for Linux gamers.

Status: 🟢 Phase 1 (MVP) in progress. Foundational decisions are settled and the sensor core (M1) works — snapshot / monitor read NVIDIA GPU, CPU, memory, and NVMe live. Crash logger (M3) and health report (M4) are next. See docs/ROADMAP.md.

Why this exists

Linux gaming hardware faults are hard to diagnose: GPUs falling off the PCIe bus, the screen suddenly going black mid-game, silent thermal/VRAM throttling, power transients, driver/library mismatches, Proton quirks, and CPU governor / power-profile misconfiguration. The data needed to diagnose them is scattered across nvidia-smi, /sys/class/hwmon, journalctl, SMART, and more — and the most useful readings (the ones right before a hard freeze) are usually lost because nothing flushed them to disk.

RigDoctor pulls all of that into one modular tool: live monitoring, crash-safe logging, a one-shot health report, and an interactive installer that only sets up the modules a given user actually needs for their hardware.

Seed use cases: an RTX 3070 that intermittently "falls off the bus" under heavy GPU load (Path of Exile on Linux, Escape from Tarkov on Windows), and a monitor going black mid-game. See docs/SPEC.md §1.

How you run it

Three front-ends over one shared engine — pick what fits:

• CLI / headless — full functionality from the terminal, works over SSH.
• Desktop GUI — graphical dashboard, log browser, and health-report viewer.
• Tray applet — a small applet in the top menu bar with quick actions (e.g. start recording) and at-a-glance status.

The GUI and tray are optional modules; a headless install loses no diagnostic capability.

Key decisions (settled)

Topic	Decision
Name	RigDoctor
Language / stack	Python 3 + Qt (PySide6) — core/CLI/daemon stdlib-only; Qt only for GUI/tray
Primary distro	Ubuntu (Debian via apt); others best-effort later
Primary GPU	NVIDIA first; AMD, then Intel later
MVP	Sensor core + crash logger + health report (NVIDIA-only, CLI-first)
Distribution	.deb + interactive module installer
Scope of action	Read-only + suggestions (no auto-apply yet)
Stress tests	Out of scope

Full rationale and the still-open questions are in docs/DECISIONS.md.

Repo layout

Path	Purpose
docs/SPEC.md	Product specification — vision, requirements, modules (the main planning doc)
docs/ARCHITECTURE.md	Technical design — core engine, front-ends, daemon, installer
docs/MODULES.md	Catalog of modules with scope, dependencies, status
docs/ROADMAP.md	Phased milestones
docs/DECISIONS.md	Decision log + remaining open questions
src/rigdoctor/	Source code — core/ engine + sources, cli.py, render.py
installer/	Installer / .deb packaging (empty until Phase 4)
tests/	Tests (stdlib unittest)

Run it (dev)

Stdlib-only, no install needed (target is Python ≥ 3.11; tested on 3.14):

PYTHONPATH=src python3 -m rigdoctor snapshot     # one-shot sensor read
PYTHONPATH=src python3 -m rigdoctor snapshot --json
PYTHONPATH=src python3 -m rigdoctor monitor -n 1 # live view (Ctrl-C to quit)
PYTHONPATH=src python3 -m rigdoctor sources       # list detected sensor sources
PYTHONPATH=src python3 -m unittest discover -s tests

Or pip install -e . to get a rigdoctor command on your PATH.

Start here

1. Read docs/SPEC.md for what we're building.
2. Read docs/ROADMAP.md for the build order (Phase 1 = the MVP).
3. Read docs/DECISIONS.md for the settled decisions (D1–D15).