138 lines
6.0 KiB
Markdown
138 lines
6.0 KiB
Markdown
# 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 `fsync`s 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**, or **import a Windows crash dump (`.dmp`)** from a
|
|
Proton game and have it parsed and analysed. 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.
|
|
|
|
## Screenshots
|
|
|
|
| Dashboard | Inventory |
|
|
|---|---|
|
|
|  |  |
|
|
|
|
**Share** — a read-only or interactive terminal session over the relay, for remote help:
|
|
|
|
|
|
|
|
## Install
|
|
|
|
### Debian / Ubuntu — `.deb`
|
|
|
|
The simplest path: grab the latest **`rigdoctor_<version>_all.deb`** from the
|
|
[releases page](https://git.jesseyvanofferen.com/jessey/rigdoctor/releases) and install it —
|
|
apt pulls the GUI dependencies (PySide6, pyte) automatically:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
sudo curl https://git.jesseyvanofferen.com/api/packages/jessey/debian/repository.key -o /etc/apt/keyrings/gitea-jessey.asc
|
|
echo "deb [arch=all signed-by=/etc/apt/keyrings/gitea-jessey.asc] https://git.jesseyvanofferen.com/api/packages/jessey/debian stable main" | sudo tee /etc/apt/sources.list.d/gitea.list
|
|
sudo apt update
|
|
sudo apt install rigdoctor
|
|
```
|
|
|
|
Then `sudo apt upgrade` keeps it current.
|
|
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
rigdoctor-gui # desktop app (+ tray)
|
|
rigdoctor --help # everything from the terminal (works over SSH)
|
|
```
|
|
|
|
Handy CLI commands:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|