# aldermon

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

## Usage

```sh
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
```

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.

```ini
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

```sh
make            # release build
make check      # fmt + clippy + tests
doas make install   # PREFIX=/usr/local by default
```

Installs `aldermon` + `aldermon-msr` (VID helper) to `$(PREFIX)/bin`, this
repo's `aldermon.conf` to `/etc/aldermon/aldermon.conf` (system default —
override per-user via `~/.config/aldermon/`), and the setup script to
`/usr/share/aldermon/`. `make install` also setcaps the helper (skipped for
staged `DESTDIR=` installs — `aldermon-setup.sh` applies it). `make
uninstall` reverses it (leaves the system conf dir if non-empty).

## Privileged setup — one-time (RAPL watts + VID)

```sh
doas /usr/share/aldermon/aldermon-setup.sh
doas usermod -aG adm $USER   # then re-login
```

1. RAPL: `energy_uj` is root-only, so the script installs a udev rule that
   chgrps it 0440 to group `adm` — watts then work unprivileged.
2. VID: opening `/dev/cpu/*/msr` passes two gates — the file-mode check
   (node is 0600; `CAP_SYS_RAWIO` does NOT override DAC) and `msr_open()`'s
   capability check. The script installs a udev rule making the nodes
   `0440 adm` and sets `cap_sys_rawio+ep` on `aldermon-msr`, a read-only
   helper that touches exactly one MSR; the app never holds the capability.

## Status

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