RigDoctor

Hardware monitoring & crash diagnostics for Linux gamers. Live sensors, crash-safe logging, plain-language health reports, per-game diagnostics, and optional AI explanations — in a desktop app, a tray applet, or the terminal. Ubuntu/Debian + NVIDIA first.

Linux gaming faults are hard to pin down — GPUs falling off the PCIe bus, black screens mid-game, silent thermal/VRAM throttling, driver/Proton mismatches. The useful data is scattered across nvidia-smi, /sys, journalctl, and SMART, and the readings right before a freeze are usually lost. RigDoctor pulls it together and keeps the evidence.

Features

• Live monitoring — a dark desktop dashboard (history graphs + per-subsystem cards), a tray applet with at-a-glance status, and a terminal view (rigdoctor monitor).
• Crash-safe recording — background logger that fsyncs every sample, so the state right before a hard freeze survives. Manual, always-on, or auto-start when a game launches.
• Health report — scans journalctl/SMART/driver for likely causes (Xid, OOM, disk errors, throttling…) and explains them with suggested fixes.
• Per-game diagnostics — pick a game, capture while you play, get a focused report; hard crashes are detected and analysed on next launch.
• Gaming tune-ups — flags risky settings (CPU governor, PCIe ASPM, persistence mode…) with one-click, reversible fixes.
• Proactive alerts — desktop notifications on overheating and critical kernel events (GPU-lost, Xid, out-of-memory, disk I/O).
• AI explanations (optional, opt-in) — explain a diagnostic in plain language with a local model (Ollama) or Claude. Never automatic; only when you press the button.
• Shareable reports — zip a diagnostic (logs, inventory, AI transcript) to hand to someone, or share a live terminal session for remote help.
• Self-updating — apt upgrade, or the in-app updater.

Install

Debian / Ubuntu — .deb

The simplest path: grab the latest rigdoctor_<version>_all.deb from the releases page and install it — apt pulls the GUI dependencies (PySide6, pyte) automatically:

sudo apt install ./rigdoctor_*_all.deb        # CLI only: add --no-install-recommends

Or add the apt repository for apt install + automatic updates. The registry is public and GPG-signed — no token needed; just add the signing key and a deb822 source:

# signing key → dearmored into the keyring
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://git.jesseyvanofferen.com/api/packages/jessey/debian/repository.key \
  | sudo gpg --dearmor -o /etc/apt/keyrings/gitea-jessey.gpg

# the source (modern deb822 format, GPG-verified, all-arch)
sudo tee /etc/apt/sources.list.d/rigdoctor.sources >/dev/null <<'EOF'
Types: deb
URIs: https://git.jesseyvanofferen.com/api/packages/jessey/debian
Suites: stable
Components: main
Architectures: all
Signed-By: /etc/apt/keyrings/gitea-jessey.gpg
EOF

sudo apt update && sudo apt install rigdoctor

Then sudo apt upgrade keeps it current.

Any distro — self-extracting .run (no root)

Download rigdoctor-<version>-installer.run from the releases page and run it. It installs into a private virtualenv under ~/.local (no root), adds the launchers + desktop entry, and opens the first-run setup wizard:

sh rigdoctor-*-installer.run

Updating & removing

• .deb: sudo apt upgrade (or reinstall a newer .deb).
• .run / user-local: the in-app Update button, or rigdoctor update.
• Remove: sudo apt remove rigdoctor, or rigdoctor uninstall for the user-local install.

Using it

Launch RigDoctor from your app menu, or:

rigdoctor-gui          # desktop app (+ tray)
rigdoctor --help       # everything from the terminal (works over SSH)

Handy CLI commands:

rigdoctor snapshot              # one-shot reading of every sensor
rigdoctor monitor              # live terminal dashboard
rigdoctor report               # health report (logs / SMART / driver)
rigdoctor diagnose start|finish # capture while gaming, then analyse
rigdoctor gameenv              # flag risky gaming settings + fixes
rigdoctor inventory            # hardware/OS inventory
rigdoctor ai explain           # AI explanation of the current findings (opt-in)
rigdoctor bundle               # zip the latest diagnostic into a shareable report

Requirements

• Linux — Ubuntu/Debian first-class (the .deb); the .run works on any distro with Python ≥ 3.11.
• GPU — NVIDIA fully supported (via nvidia-smi); AMD/Intel sensors are best-effort.
• CLI/daemon need only Python 3 (stdlib). The GUI/tray add PySide6 (python3-pyside6).
• Optional tools unlock more: smartmontools, lm-sensors, gamemode, mangohud. The setup wizard offers to install them.

Privacy

Everything stays on your machine — no telemetry, no phone-home. The AI assistant is off by default and runs only when you explicitly trigger it; with Ollama nothing leaves the machine, and the Claude option asks before sending. Reports are local files; they leave only if you share the zip.

Development

RigDoctor's core is stdlib-only Python; the GUI/tray use PySide6.

git clone https://git.jesseyvanofferen.com/jessey/rigdoctor && cd rigdoctor
pip install -e ".[gui]"                    # core + GUI; omit [gui] for CLI-only
python -m unittest discover -s tests       # run the test suite
PYTHONPATH=src python3 -m rigdoctor snapshot   # run without installing

Design docs live in docs/ — SPEC.md (vision/requirements), ARCHITECTURE.md, MODULES.md (module catalog), ROADMAP.md, and DECISIONS.md (the decision log). Contributions: branch off main, keep tests green (CI runs them on PRs), and bump the version

• CHANGELOG.md for shipped changes.