Skip to content

Releases: ColorFlowStudios/CPU-Guardian

CPU-Guardian v1.0.0

16 Mar 20:03
@ColorFlowStudios ColorFlowStudios
v1.0.0
2d12337

Choose a tag to compare

View all tags
CPU-Guardian v1.0.0 Latest
Latest

CPU Guardian

Pro-Core CPU Thermal Management — Monitor temperatures, control frequencies, and protect your hardware automatically.

License: MIT
Python
Platform
Version

CPU Guardian is a lightweight Linux desktop application that continuously monitors per-core CPU temperatures and automatically adjusts CPU frequencies and governors to keep your system cool — with real-time visualizations, desktop notifications, and multiple tunable profiles.

Features

  • Real-time per-core monitoring — Live temperature and frequency readout for every logical core
  • Automatic thermal throttling — Three-stage frequency control (Full / Mid / Safe) triggered by configurable temperature thresholds
  • Emergency cooldown mode — Instantly throttles all cores and waits for temperatures to drop before restoring performance
  • HyperThreading-aware — Frequency and governor changes are applied to physical cores and all their HT siblings
  • Multiple sensor backends — Reads from lm-sensors, psutil, and /sys/class/thermal with automatic fallback
  • Governor management — Switches between performance, schedutil, ondemand, and powersave governors per core based on temperature
  • Built-in profiles — Gaming, Quiet, Powersave, and Custom presets with one-click switching
  • Statistics tracker — Session min/max/avg temperatures per core, plus overheat event counting
  • Desktop notifications — notify-send alerts on overheat and cooldown events
  • Audio alerts — System beep on emergency stop (PulseAudio → ALSA → X11 bell fallback)
  • 5 UI themes — Amber, Cyan, Matrix, Crimson, Arctic
  • Persistent configuration — Settings saved to ~/.config/cpu_guardian/settings.json

Requirements

Requirement Notes
Linux Only supported OS
Python 3.9+ 3.10–3.12 recommended
tkinter GUI toolkit (usually python3-tk)
psutil >= 5.9 Temperature and frequency reading
lm-sensors Optional but recommended for accurate readings
sudo access Required to write to /sys/devices/system/cpu/*/cpufreq/

Installation

Using the prebuilt ZIP

If you downloaded the ZIP:

unzip cpu_guardian_gui.zip
cd cpu_guardian
./install.sh

Everything else (dependencies, launcher, sudoers) is handled automatically by the installer.

Automatic (recommended)

git clone https://github.com/ColorFlowStudios/CPU-Guardian.git
cd cpu-guardian
chmod +x install.sh
./install.sh

The installer will:

  1. Detect your distribution (Debian/Ubuntu, Fedora/RHEL, Arch)
  2. Install missing dependencies (tkinter, psutil, lm-sensors)
  3. Copy files to /opt/cpu-guardian
  4. Create a launcher at /usr/local/bin/cpu-guardian
  5. Register a desktop entry (application menu integration)
  6. Optionally install a passwordless sudoers rule for frequency control

Manual (pip)

pip install psutil
python -m cpu_guardian

Uninstall

./uninstall.sh

Usage

From the terminal:

cpu-guardian

From the application menu:
Search for CPU Guardian in your desktop environment's application launcher.

Configuration

Settings are stored at ~/.config/cpu_guardian/settings.json and are loaded automatically on startup. All values can be edited through the GUI's Settings dialog.

Key settings

Setting Default Description
check_interval 5 Polling interval in seconds
pause_temp 90.0 °C Emergency throttle threshold
safe_temp 85.0 °C Switch to safe frequency
mid_temp 75.0 °C Switch to mid frequency
cooldown_temp 55.0 °C Resume normal operation after cooldown
full_turbo_khz auto-detected Max frequency in normal operation
mid_turbo_khz 2,700,000 Max frequency at mid temperature
safe_turbo_khz 1,000,000 Max frequency in safe/hot mode
gov_cool performance Governor when core is cool
gov_mid schedutil Governor at mid temperature
gov_hot powersave Governor when core is hot
theme amber UI color theme
use_sudo true Use sudo for sysfs writes

Temperature / frequency ladder

Temp < mid_temp     →  full_turbo_khz  +  gov_cool
Temp < safe_temp    →  mid_turbo_khz   +  gov_mid
Temp < pause_temp   →  safe_turbo_khz  +  gov_hot
Temp ≥ pause_temp   →  EMERGENCY COOLDOWN (all cores throttled)

Profiles

CPU Guardian ships with three built-in profiles alongside a fully customizable Custom mode.

Profile Description Pause temp Freq range
Gaming Maximum performance, throttle only in emergency 95 °C 70–100% of CPU max
Quiet Low temperatures, moderate speed 80 °C 1.2–2.4 GHz
Powersave Minimum power consumption 75 °C 0.8–1.6 GHz
Custom User-defined via GUI configurable configurable

Architecture

cpu_guardian/
├── __main__.py          Entry point
├── config.py            Configuration dataclass + JSON persistence
├── monitor.py           Background monitoring thread (MonitorThread)
├── sensors.py           Hardware abstraction: temperatures + frequency r/w
├── stats.py             Per-core session statistics tracker
├── notifications.py     Desktop notifications (notify-send) + beep
├── cpuinfo.py           Static CPU info reader
├── support.py           Support utilities
└── gui/
    ├── app.py           Main application window
    ├── theme.py         5 color themes + font/spacing constants
    ├── widgets.py       TempBar, TempGraph, LogView, BigTempDisplay
    ├── profile_editor.py  Profile editor dialog
    ├── stats_panel.py   Statistics panel
    ├── cpuinfo_panel.py CPU info panel
    ├── info_panel.py    Info panel
    ├── dialogs.py       Settings + About dialogs
    └── support_dialog.py  Support dialog

The MonitorThread runs as a daemon thread, polls sensors at check_interval seconds, applies frequency and governor changes via sysfs, and fires callbacks to the GUI using MonitorEvent objects.

Sensor Backends

CPU Guardian reads temperatures using three backends in priority order:

  1. lm-sensors (sensors -j) — most accurate, requires package installation
  2. psutil — cross-platform, supports coretemp, k10temp, zenpower, cpu_thermal
  3. sysfs (/sys/class/thermal/thermal_zone*) — ARM/embedded fallback

Frequencies are read from /sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq with a psutil fallback.

Sudo & Permissions

CPU Guardian writes to /sys/devices/system/cpu/*/cpufreq/scaling_max_freq and .../scaling_governor to control frequencies. This requires root access.

The installer can add a targeted passwordless sudoers rule:

username ALL=(ALL) NOPASSWD: /usr/bin/tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_max_freq
username ALL=(ALL) NOPASSWD: /usr/bin/tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

If the rule is not installed, CPU Guardian will still monitor temperatures but frequency control will be disabled unless run with sudo.

Development

# Clone and install dev dependencies
git clone https://github.com/ColorFlowStudios/CPU-Guardian.git
cd cpu-guardian
pip install -e ".[dev]"

# Run tests
pytest tests/

# Lint
ruff check .

# Type-check
mypy cpu_guardian/

Screenshots — Themes

Here are some examples of the available GUI themes:

Amber Cyan Matrix
Amber Theme Cyan Theme Matrix Theme
Crimson Arctic
Crimson Theme Arctic Theme

Benchmarks

CPU Guardian reduces peak temperatures and stabilizes CPU frequencies.
Benchmarks were performed using XMRig, which fully loads the CPU (100% utilization).
While the initial hashrate without CPU Guardian may appear higher, thermal throttling quickly reduces performance.
With CPU Guardian, initial hashrate may start slightly lower, but thermal throttling is prevented, resulting in higher average...

Read more
Assets 3
Loading