aldermon

btop-style TUI monitor for Alder Lake (i5-12600KF), built around real vCore voltage for overclock-safety work.

Usage

aldermon --tui          # TUI (default workhorse)
aldermon --vid          # VID spike tool (debug; needs MSR access, see below)
aldermon --log          # append CSV samples to ./aldermon-vid.log
aldermon                # one-shot sensor dump
aldermon --help         # options
aldermon --version      # aldermon x.y.z

The TUI always shows the delivered vCore (SIO in0), the CPU's requested SVID setpoint (IA32_PERF_STATUS), and the delta (delivered − requested; negative = VRM droop, positive = LLC overshoot). VID needs MSR access: run under root, or install once (below) — the setcap'd aldermon-msr helper holds CAP_SYS_RAWIO, the app itself stays unprivileged. Without access the panel shows VID n/a (no msr access).

--log appends one CSV row per poll to ./aldermon-vid.log (header + per-CPU VID / frequency / raw MSR columns). With --tui it logs live; with --vid it logs continuously until interrupted.

Short flags group: -lvt == --log --vid --tui.

The TUI needs a real terminal; piped/redirected stdout exits with a clear error instead of a panic.

Features: vCore hero panel (limit marker, 5-min peak, auto-scale), package power/temp, per-core frequency bars + temps, E/P-core sections, braille sub-pixel scrolling graphs, footer max frequency.

Config

aldermon.conf is read from the working directory, then ~/.config/aldermon/aldermon.conf, then /etc/aldermon/aldermon.conf (first file found wins; no merging). Simple KEY = VALUE lines; # comments; unknown keys are ignored. All values optional — built-in defaults target an ASRock Z690M ITX/ax (nct6798). Numeric keys are range-checked; an out-of-range value falls back to the default.

vcore_limit   = 1.403   # safety limit shown as marker on the vCore bar
temp_warn     = 80.0
temp_crit     = 95.0

# Per-graph y scales (also editable in the settings pane, F2)
vcore_min     = 0.0
vcore_bar_max = 1.50
clock_min     = 0          # kHz
clock_bar_max = 4500000
power_min     = 0.0
power_bar_max = 200.0
temp_min      = 0
temp_max      = 100

poll_ms         = 250      # sample/tick period (50..10000)
graph_secs      = 300      # history kept, sizes peaks + auto-scale
graph_scale_fixed = false  # true = pin to the scales above
graphs          = true
layout          = auto     # auto | single | dual

Install

One command, from this directory:

./aldermon-install.sh   # recon -> printed plan -> confirm -> ONE doas/sudo
                        # prompt -> install only what's needed -> verify

Stages: [1/4] binary+helper — version-gated (installs if missing or older, skips if current); [2/4] /etc config — only if missing (your system-conf edits survive; per-user ~/.config/aldermon/ never touched); [3/4] watts — powercap udev rule + chmod helper (group adm); [4/4] VID is OPTIONAL: after the root prompt the installer asks whether to add the msr udev rule + helper capability. Declining leaves vCore/temps/ freqs untouched (already unprivileged) — the panel just keeps showing VID n/a (no msr access).

Modes: --check status report, changes nothing; --setup privileged parts only (for staged/package installs); --clean/-c force-reinstall binary, helper, permissions and STOCK config; --vid/--no-vid pre-answer stage 4; --yes/-y accept the plan without prompting; --uninstall removes the binaries, capability, udev rules and RUN helper and restores the device nodes' stock permissions (keeps your /etc config); --purge also deletes the config. On uninstall it asks whether to drop your user from group adm (--del-adm/--keep-adm pre-answer).

Low-level: make check, doas make install (honors PREFIX/DESTDIR; keeps an existing system conf; setcaps when unstaged — run aldermon-install.sh --setup after staged installs), make uninstall reverses (leaves the system conf dir if non-empty).

Why the privileges look like this (RAPL watts + VID)

• RAPL energy_uj is 0400 root-only; powercap has NO devnode, so udev's RUN+= helper chgrp/chmods it to 0440 adm.
• /dev/cpu/*/msr (VID) passes TWO gates on open: the DAC file-mode check first (nodes are 0600 — CAP_SYS_RAWIO is not CAP_DAC_OVERRIDE, so setcap alone gets EACCES), then msr_open()'s capable(CAP_SYS_RAWIO) (so chmod alone gets EPERM). The installer opens both: udev MODE/GROUP 0440 adm for the nodes, cap_sys_rawio+ep on the read-only aldermon-msr helper only — the app never holds the capability.
• Once per user: the installer adds you to group adm if missing; activate it with a re-login (or newgrp adm for the current shell). Uninstall asks whether to remove you from adm (adm also grants log access).

Status

Working: TUI, config (+ system /etc default), RAPL power. Remaining notes live in the local-only .LLM_Memory/ (gitignored).