🩺 Linux Doctor

Linux diagnostics that explain the problem — and remember what changed.

Linux Doctor runs safe, read-only checks and surfaces only the issues that actually matter. Each finding comes with a clear explanation and a copy-paste fix. It remembers your last run, so every report tells you what's new, what got fixed, and what stayed the same.

Its own code never modifies your system. Drop-in checks (~/.config/linux-doctor/checks/) and the Pro add-on are code that you install and run with your own privileges — see docs/configuration.md.

• 🎯 One clear next step — every report leads with ▶ START HERE, the single most useful action, not a wall of graphs
• 🧠 Memory built in — health score (0–100), trend sparkline, and a plain-language NEW/FIXED diff on every run
• 🔒 Read-only by construction — it never changes your system; fixes are suggestions you run yourself (the optional --fix shows a dry run first, and running it takes a second opt-in)
• 🖥️ CLI + desktop app — terminal report, web dashboard, and a Tauri desktop app (AppImage / deb / rpm) sharing the exact same checks
• 📦 Runs anywhere — npx, npm, AUR, RPM spec, .deb, AppImage; works gracefully on immutable distros (Silverblue, Bazzite)

Why Linux Doctor?

Linux already has the data — journalctl, systemctl --failed, df, free, smartctl — but not the answer. It hands you raw output and leaves you to find the line that matters. Linux Doctor reads the same sources and returns the conclusion: what is wrong, why it matters, and the one command to fix it.

It is deliberately a doctor, not a monitor. It does not stream metrics, manage processes, or sit in the background waiting to page you. It answers "what's wrong right now?" in seconds, remembers the previous answer, and tells you what changed. That is a different job from a monitoring stack:

Run it when something feels off, before filing a bug report, or daily from a systemd timer — and get one clear next step instead of a wall of graphs. Use it alongside your monitoring stack, not instead of it.

Download the app (recommended)

Desktop app — no install, no package manager:

• Latest release — grab linux-doctor-<version>-x86_64.AppImage

chmod +x linux-doctor-*-x86_64.AppImage
./linux-doctor-*-x86_64.AppImage

Also attached to each release: .deb (Debian/Ubuntu), .rpm (Fedora/RHEL/openSUSE) and the CLI tarball. AppImage runs on most distributions (glibc-based); on immutable systems (Fedora Silverblue, Bazzite) it works out of the box. Nothing needs to be installed — the desktop packages embed their own Node.js 22 runtime (<resources>/runtime/node), so the app's checks run even on a machine with no Node on PATH. LINUX_DOCTOR_NODE=/path/to/node still overrides it.

Installed size: the bundled runtime adds roughly 130 MB to the package.

WEBKIT_DISABLE_DMABUF_RENDERER=1 ./linux-doctor-*-x86_64.AppImage
# still blank? also try:
LIBGL_ALWAYS_SOFTWARE=1 WEBKIT_DISABLE_COMPOSITING_MODE=1 ./linux-doctor-*-x86_64.AppImage

Install & first run (CLI)

Needs Node.js ≥ 20.

npx github:zShaD0w7x/linux-doctor     # no install, straight from GitHub
# or:
npm install -g linux-doctor && linux-doctor

Prefer a native CLI package?

• Arch / AUR: makepkg -si from the PKGBUILD (AUR package linux-doctor)
• Fedora / RHEL / Bazzite / openSUSE: add the OBS repository and sudo dnf install linux-doctor, or build with the linux-doctor.spec
• Debian / Ubuntu: .deb from Latest release
• Any glibc distro: AppImage or npx github:zShaD0w7x/linux-doctor

STATUS   0 high, 2 medium, 19 info · health 74/100
TREND    ▄▅▅▆▆▇  last 6 run(s) · 61 → 74 ▲

▶ START HERE   #1 System is low on usable memory
               Close apps you are not using, then re-run this check.

Your system is low on usable memory: 9.4 GB of 15 GB is in use and 2.2 GB is
being pushed to swap. This is the most common cause of a sluggish desktop.
How to fix: close unused browser tabs, then re-run this check.

Since last run: 2 new · 1 fixed · 19 unchanged

The report leads with a ▶ START HERE line (the single most useful action) and a TREND sparkline, and every run is diffed against the previous one. Read-only by default: --fix prints a dry-run plan of commands sourced only from a small built-in safe-fix catalog — running it needs a second opt-in (--fix --yes), and [manual] items always stay yours to run.

What it checks

Every finding carries a stable identity: a code (check/reason), a severity decided against the severity rubric, human detail, evidence from the system, and a suggested fix. Codes are the join key for history diffing (NEW/FIXED) and for --ignore-code, so they never change silently.

Checks that don't apply to your machine — battery on a desktop, reboot on immutable systems — are skipped automatically and reported honestly in a Skipped section instead of producing misleading findings.

Health score & history

Every run is saved to ~/.local/share/linux-doctor/history.json (override with LINUX_DOCTOR_HISTORY). From that history you get a health score (0–100) with an auditable breakdown (100 − Σpenalties), a TREND sparkline of your last runs, and a plain-language diff per run — new, fixed, unchanged. Findings that share a root cause are collapsed before scoring, so one problem never counts twice. History is a bonus, never a dependency: --no-history disables it, and if it cannot be written the report still works.

Documentation

Roadmap

• GUI with a one-click report — shipped: a Tauri desktop app
• Report history and change detection — shipped: health score, NEW/FIXED diff
• More checks: Bluetooth, Wayland, backup, hardware errors, LUKS — shipped
• Auto-generated, distro-specific fix instructions
• Signed packages on AUR/COPR and AppStream metadata in every package (Flatpak is not a fit — see packaging/README.md)
• Maintenance: single maintainer, AI-assisted. Roadmap lives in CHANGELOG [Unreleased] and in GitHub issues — security fixes within days, contributions welcome.

Transparency

Development is AI-assisted, and every decision is the author's. Accountability is by artifacts: 600+ automated tests (golden snapshots, shell-safety, output-parity), CI on Fedora + Node 20/22/24, read-only by construction with a pinned safe-fix catalog. Judge it by those artifacts.

Editions

This repository is the Free edition — the whole product for everyday users, GPL-3.0-or-later, forever. Optional paid tiers for power users and companies are strictly additive and described in COMMERCIAL-LICENSE.md.

Licensing & brand

Dual-licensed.

• GPL-3.0-or-later — free for individuals and open-source projects. You may copy, modify and redistribute it, but any derivative work you distribute must stay open-source under the same terms.
• Commercial license — for companies that need to use Linux Doctor inside proprietary products.

What that means in practice:

• Copying the Free edition is allowed — that is the point of the GPL. Forks are welcome as long as they keep the license and the notices.
• It is still not a free-for-all: a distributed derivative must stay GPL, and shipping the code inside a closed product requires the commercial license. That obligation is enforceable copyright, not a polite request.
• The paid tiers' code is not here. Pro/Business/Enterprise live in private repositories; this edition is, and stays, the whole product for everyday users.
• The name and logo are not covered by the code license. If you fork, ship it under your own name — see docs/trademark.md.

Every source file carries an SPDX-License-Identifier: GPL-3.0-or-later header. By contributing, you agree your contributions are offered under both licenses (see CONTRIBUTING.md).