Skip to content

About

Read-only system vitals panel for the Omarchy bar (WIP)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

omarchy-system

A system panel for the Omarchy bar: temperatures, fans, CPU, memory, disk space, network throughput and power, behind a single bar glyph tinted green, amber or red. Everything it shows is read-only. The one thing it changes is the fan profile, from a row of buttons under the fan readings.

Status: early. The collector and the panel are verified on three laptops: a dual-screen ASUS laptop with two fans, a fanless laptop, and a single-fan laptop whose fan is owned by a vendor driver. The fanless, few-sensor and labelled-per-core paths all have real hardware behind them, and each of the two machines added after the first has changed the code (see Design notes). The optional Max fan profile has been tested on real hardware on the dual-screen ASUS laptop and on a desktop with an AMD Radeon RX 7900 XT.

Installing

omarchy plugin add https://github.com/brightwalker25/omarchy-system.git
omarchy plugin enable brightwalker25.system --section right

The plugin is added to ~/.config/omarchy/plugins/brightwalker25.system. The collector ships inside it and is found relative to the panel, so there is no symlink or PATH step.

Requirements:

  • Python 3, which the collector and the fan profile script run on.
  • For Quiet, Balanced and Boost, power-profiles-daemon, which Omarchy installs, and firmware that publishes a platform profile, as many laptops from ASUS, Lenovo, HP, Dell and others do.
  • For Max, the optional installer described below. On a machine without a platform profile, such as most desktops, Max is the only choice the row offers, so without it the row stays hidden.

Nothing is installed outside the plugin folder unless you choose to add the Max fan profile, described below.

To update:

omarchy plugin update brightwalker25.system

If you have installed Max, run its installer again after updating, as described under Keeping Max up to date.

Using the panel

Click the bar glyph to open the panel and click it again to close it. A middle click runs the collector at once instead of waiting for the next poll.

The glyph's colour summarises the panel:

Colour Meaning
Red A sensor at 90% or more of its critical limit, a filesystem at or past diskAlarmPercent, under 5% of memory available, or a battery at 15% or less and not charging
Amber A sensor at 80% of its limit, a filesystem within five points of diskAlarmPercent, under 10% of memory available, a battery at 25% or less and not charging, or a collector that could not be read
Green None of the above

While the panel is open the collector runs every refreshIntervalMs. While it is closed it runs once a minute, only to keep the glyph's colour current.

Settings

These appear in the widget's settings in Omarchy:

Setting Default Range What it does
refreshIntervalMs 2000 500 to 10000 How often the collector runs while the panel is open
perCoreCutoff 8 0 to 64 Above this thread count the per-core bars become a compact strip
maxSensorRows 4 3 to 40 Temperature rows before the rest are summarised in one line
maxFilesystemRows 4 1 to 20 Filesystem rows, root first and then the fullest, before the rest are summarised
diskAlarmPercent 90 50 to 99 How full a filesystem has to be before its bar takes the urgent colour

One further setting is read but not offered in the settings screen: barRefreshIntervalMs (default 60000, at least 15000) sets how often the collector runs while the panel is closed. To change it, add the key to the plugin's entry in the bar layout in ~/.config/omarchy/shell.json, for example {"id": "brightwalker25.system", "barRefreshIntervalMs": 30000}.

From a terminal

Both scripts run fine on their own, which is useful when capturing a new machine or checking what the panel will show:

~/.config/omarchy/plugins/brightwalker25.system/bin/system-collect          # compact JSON, one line
~/.config/omarchy/plugins/brightwalker25.system/bin/system-collect --dump   # indented, for reading
~/.config/omarchy/plugins/brightwalker25.system/bin/system-fans status      # the fan profile row's state, as JSON
~/.config/omarchy/plugins/brightwalker25.system/bin/system-fans set boost   # quiet, balanced, boost or max

The collector needs only Python 3 and a Linux /sys. A new machine is worth capturing with system-collect --dump before assuming its sensors look like anything already seen.

Fan profile

Under the fan readings is a row of buttons. Which buttons it shows depends on the machine:

  • On a laptop whose firmware publishes a platform profile: Quiet, Balanced, Boost and, once set up, Max.
  • On a machine without one, such as most desktops: Normal and Max, once Max is set up. Normal leaves the fans on their usual automatic control.
Profile What changes
Quiet The firmware's quiet fan curve, with lower power limits and a CPU energy preference that favours saving power
Balanced The firmware's default curve
Boost Fans spin up earlier and faster, the power limits rise, and the CPU energy preference favours performance
Max Boost, with every fan that passed the installer's test held at full speed. Without a platform profile, only the fans change

Quiet, Balanced and Boost are power-profiles-daemon's power-saver, balanced and performance profiles. On a laptop with a firmware platform profile that one setting chooses the fan curve and the power limits, and a desktop session may change it without a password. Quiet, Balanced and Boost are shown only when power-profiles-daemon reports a platform driver behind the profiles; where it can adjust only the CPU, the fans would not change, so they are not offered. The curves themselves belong to the firmware and are not published. power-profiles-daemon also sets the CPU's energy performance preference with each profile, so Quiet and Boost change how eagerly the CPU raises its clock as well as the fan curve and the power limits.

Max also sets Boost, because it is meant for the fastest sustained work, so the power limits rise along with the fans. That adds heat as well as cooling. If the aim is a cooler or quieter machine rather than more speed, Boost or Balanced is the better choice. On a machine without a platform profile, Max holds the fans at full speed and changes nothing else: power-profiles-daemon is not touched.

The profile can also be changed from Omarchy's own menu, so the panel runs bin/system-fans status when it opens and again every 5 seconds while it stays open, rather than trusting its last click.

Measured on the dual-screen laptop under a full CPU load: about 4200 rpm on Balanced, about 5000 rpm on Boost, and 8600 to 8700 rpm on Max. On the RX 7900 XT desktop at idle, the GPU fan goes from stopped to about 3650 rpm within four seconds of picking Max, and stops again within six seconds of picking Normal.

Max

Max is optional. Quiet, Balanced and Boost work without it.

Pinning a fan at full speed means writing to sysfs, either a fan's pwmN_enable or, on recent AMD graphics cards, the card's overdrive fan curve. Only root may do either. A panel has nowhere to type a password, so a one-time installer sets up a small root helper that sudo will run without one.

Installing Max

Look at what it will do first. The dry run needs no root and changes nothing; it lists each action, though without root it cannot check whether anything is already in the way:

~/.config/omarchy/plugins/brightwalker25.system/bin/system-fans-install --dry-run

Then install:

sudo ~/.config/omarchy/plugins/brightwalker25.system/bin/system-fans-install

The account granted is the one that ran sudo; --user NAME grants another. The installer writes:

Path What it is
/usr/local/lib/brightwalker25-system/fan-max The helper, copied from system/fan-max rather than linked, so editing the plugin folder cannot change what root runs
/usr/local/lib/brightwalker25-system/installed.sha256 The SHA-256 of each file the installer wrote, so it can recognise them later
/etc/sudoers.d/brightwalker25-system The sudoers rule, checked with visudo before it is put in place

The rule lets one account run the helper with on or off and nothing else; neither verb takes a value. For an account called alice it reads:

# Managed by brightwalker25.system system-fans-install
# Removed by system-fans-install --uninstall. Do not edit by hand.
alice ALL=(root) NOPASSWD: \
    /usr/local/lib/brightwalker25-system/fan-max on, \
    /usr/local/lib/brightwalker25-system/fan-max off

bin/system-fans-install --print-sudoers NAME prints the rule for any account without installing anything.

The fan test described below writes its results to /var/lib/brightwalker25-system/fan-max.json. While Max is on, what to restore is kept in /run/brightwalker25-system, which is empty again after a reboot.

The fan test

After writing the files, the installer has the helper test each fan control on a supported driver: the fan is set to full speed for about six seconds and then put back. Expect to hear the fans. Each control is judged by its own fan's tachometer, not by whether the machine got louder:

What the fan did How it is recorded
Rose by at least 800 rpm Verified; Max will pin it
Started at 500 rpm or more and fell below half that Rejected as slowed, since the control is turning it down rather than up (pwmN_enable fans only; a graphics card's fan can dip while its firmware changes curves)
Was parked (0 rpm) and stayed there Parked and untested, not failed, since many firmwares stop a fan at idle and some will not start it on request
Anything else Not verified

During each control's test the probe also records every other tachometer on the same chip, so the result shows which fan, if any, the control actually moved. On the dual-screen ASUS laptop, under load, the installer printed:

asus-nb-wmi fan1: 2900 rpm -> 8600 rpm, responds, fan2 up to 3300 rpm
asus-nb-wmi fan2: 3300 rpm -> 3300 rpm, slowed instead, fan1 up to 8600 rpm

On the RX 7900 XT desktop, at idle with the GPU fan stopped:

amdgpu card1 fan curve: 0 rpm -> 3652 rpm, responds

Max appears in the panel once at least one fan is verified, and it touches only those fans.

Keeping Max up to date

Run the installer again:

  • after omarchy plugin update, so the installed copy of the helper matches the plugin;
  • under load, if it reported a parked fan, so the firmware is running that fan when it is tested (a long build or render is enough);
  • after a kernel or firmware update, since either can change how the fans respond.

Re-running is safe. It replaces only files that still match what it wrote, turns Max off first if it is on, and probes again.

How Max behaves

On the pwmN_enable path, only fans in one of their driver's automatic modes are pinned: 2 to 5 for most drivers, 2 only for dell_smm_hwmon. Mode 1 is manual, and handing a manual fan back would not give it its duty cycle back: writing 0 replaces it (nct6775 sets it to 255), and the helper has nothing it could restore it from. A fan someone has put under manual control is left alone, by the probe and by Max.

The helper records a fan in /run before it first writes to it, so an interrupted probe, or a hand-back that failed, never leaves a fan pinned with nobody knowing. The next run of the helper, for any verb, puts that fan back first. The panel treats such a leftover the way it treats Max: it says a fan is still at full speed, and picking any profile releases it. The panel reads these files only when they are plain files owned by root and writable by nobody else, and otherwise behaves as though they were not there.

Firmware may take the fans back across a suspend. The panel detects a suspend since Max was set from the kernel's count of successful suspends, /sys/power/suspend_stats/success, and says so. Clicking Max again pins the fans again, even when Max is already selected. A hibernation is not counted there, and the firmware may have taken the fans back after one as well, so after resuming from hibernation click Max again.

Supported drivers

Max drives fans in two ways.

Through pwmN_enable, for drivers whose kernel documentation says which value means full speed and which means automatic, matched by the name of the driver the device is bound to:

Driver Notes
asus-nb-wmi Only its hwmon named asus; the asus_custom_fan_curve hwmon uses pwmN_enable differently and is never touched
thinkpad_hwmon Needs the thinkpad_acpi fan_control=1 module parameter; the installer says so if it is missing
nct6775 Many desktop motherboards
it87 Many desktop motherboards
dme1737 Also the SCH311x and SCH5027
gpd_fan GPD handhelds
dell_smm_hwmon Full speed is 1 here, not 0. Machines whose fan switch cannot be read back are skipped
amdgpu Older Radeon cards, without the overdrive fan curve

Through the overdrive fan curve, for AMD Radeon RX 7000 and RX 9000 cards (RDNA3 and RDNA4), which refuse pwm1_enable. Max stages three changes and commits them together: the zero-RPM stop temperature at its lowest, zero-RPM off, and every point of the curve at full speed. They must go in one commit: the driver sends the firmware only the settings changed since the last commit, and a curve committed on its own leaves the fan stopped at idle. Releasing Max sends the reset command to every fan setting the card publishes, so the card is back on its own defaults, and then puts back every fan setting that differed from those defaults before Max was set: a custom curve, zero-RPM settings, minimum fan speed, target temperature and acoustic limits, as set by a tool such as LACT or CoreCtrl. The tachometer and the values the card reports are not proof that the firmware has let go, which is why the reset covers every setting and not only the ones Max changed.

The overdrive files exist only when the amdgpu overdrive feature is enabled on the kernel command line: bit 14 (0x4000) of amdgpu.ppfeaturemask, for example amdgpu.ppfeaturemask=0xfff7ffff. The installer says so when it finds an AMD card without them, and does not change the boot configuration itself. With the overdrive feature enabled the kernel marks itself tainted, which matters only for kernel bug reports.

Not supported: NVIDIA graphics cards, whose driver offers no fan control through hwmon (the installer says so), nct6683, which has no pwm_enable to write, and pwm-fan, where 0 switches the fan off. No hwmon binds to asus_wmi itself.

Three things about ASUS laptops, all found on the dual-screen one, a UX8402ZE:

  • asus-wmi initialises its cached mode for the CPU fan (pwm1) but never for the GPU and middle fans (pwm2 and pwm3), so a freshly loaded driver reports those two as mode 0, full speed, while the firmware runs them on its own curve. The helper reads 0 as automatic for fans 2 and 3 on this driver only.
  • On that laptop the GPU fan cannot be forced. Its control (pwm2) drives the CPU fan: in the test shown above, setting it to full speed sent the CPU fan to 8600 rpm while the GPU fan slowed, so the probe rejected it. Max therefore holds the CPU fan only, and the GPU fan stays on the firmware's curve. The GPU fan also stops at idle, which is why a probe on an idle machine records it as parked.
  • Setting a fan mode on asus-wmi disables any custom fan curve. If you use asusctl to set your own curve, releasing Max gives you the firmware's automatic curve back, not yours; set your curve again afterwards.

On ThinkPads, Max is thinkpad_acpi's disengaged mode, which runs the fan above level 7, the highest speed the driver's documentation recommends. Without the fan_control=1 module parameter the helper's write fails. Tachometer readings there can lag a mode change by up to two minutes, so the probe may misjudge a ThinkPad fan.

Removing

If you installed Max, remove it first, while the plugin folder (which holds the uninstaller) is still there:

sudo ~/.config/omarchy/plugins/brightwalker25.system/bin/system-fans-install --uninstall
omarchy plugin remove brightwalker25.system

The uninstaller removes the sudoers rule first, so the panel cannot pin a fan again partway through, then has the helper hand every fan back to the firmware, and only then removes the helper and its files. If Max is on and the installed helper is missing or has been changed, it refuses and removes nothing, since nothing else could hand the fans back. Files it did not write, or that have changed since, are left in place and listed.

If the plugin was removed before Max, add it again with omarchy plugin add, run the uninstaller as above, and then remove the plugin.

Troubleshooting

The fan profile row is missing. power-profiles-daemon reports no platform profile driver on this machine, so the profiles would change only the CPU, not the fans, and Max has not been set up. Install Max to get the Normal and Max row. On a laptop, check that power-profiles-daemon is running; bin/system-fans status shows what the panel sees, including any error.

Max is missing from the row. Either the installer has not been run, or no fan passed the test. The installer's last lines say which; run it again under load if it reported a parked fan. If it stops with "No fan on this machine publishes a pwm control or a fan curve", the fans are not controllable through hwmon and Max cannot be offered. On an AMD card, read the installer's note about the overdrive feature.

Clicking Max says it "needs bin/system-fans-install". sudo refused to run the helper without a password, which means the sudoers rule is missing or was written for another account. Run the installer again with sudo from the account that uses the panel, or pass --user NAME.

The installer refuses, listing paths that "are not what this installer wrote". Something already exists at one of its paths, or a file it wrote has been changed since. Nothing has been changed. If the listed files are left over from an earlier install and nothing else uses them, remove them and run the installer again.

Max seems to have stopped after a suspend. Firmware may take the fans back across a suspend; the panel says so, and clicking Max again pins them again. After a hibernation the panel cannot tell, so click Max again.

Design notes

A collector script prints one normalised JSON snapshot; the QML panel renders it and does no discovery of its own. This is the same shape Omarchy uses for its own agent-usage widget, and it means every machine-specific quirk lives in one testable file that runs fine from a terminal.

The collector is stateless and instantaneous. Cumulative counters (network bytes, /proc/stat jiffies) are emitted raw next to a monotonic timestamp, and the panel takes deltas between polls to derive rates. Nothing sleeps and nothing shells out: one poll is a single pass over /proc and sysfs. On the dual-screen laptop a run takes about a tenth of a second, Python start-up included, and prints under 6 KB; the fanless laptop's low-power CPU makes it slower there.

Two headline temperatures, not one

The hottest sensor in a machine and the sensor closest to its own limit are usually not the same sensor, so the collector reports both and leaves the choice to the panel. On the dual-screen laptop the SSD sits at about 60% of its 84.8 °C crit while the CPU package and the wifi chip both read several degrees hotter against a 100 °C crit and no crit at all respectively. Picking either one alone hides the other.

  • thermal.hottest: highest reading in the box, from either class.
  • thermal.closestToLimit: governed sensor with the least headroom left. Absent when nothing publishes a threshold.

On the fanless laptop the two are the same sensor. With no fan and one dominant heat source, whichever of the CPU package and the NVMe drive leads does so on both counts at once, so the panel would spend a caption line restating the row directly above it. When the two coincide the panel folds them into one caption carrying the limit. The collector still emits both, because which machine it is running on is not something it should have to know.

Used and free, as figures and as shares

A percentage on its own does not say whether 8% free is 30 GB or 300 MB, and a figure on its own does not say whether 30 GB is comfortable. The panel gives both for each side: how much is used out of the total, then how much is free with each side's share of the whole.

Those two shares do not add up to 100%, and the panel says why rather than fudging one of them. freeBytes is what an unprivileged process can actually write (f_bavail), not what is unallocated; the difference is the reserved blocks, emitted as reservedBytes and shown as their own line when they are large enough to make the arithmetic look wrong.

Inode exhaustion fills a filesystem that still reports free bytes, so inodesUsedFraction is emitted where the filesystem accounts for inodes at all (btrfs and xfs allocate them dynamically and report none), and the panel mentions it only once it is close enough to matter.

One row per filesystem, not per mount

A mount is included when its source stats as a block device. That is a discovered property rather than a list of filesystem names, so btrfs, ext4, xfs and f2fs all arrive without being named in code, while tmpfs, proc, cgroup, overlay and the rest do not: none of them has a device behind it. Network mounts are excluded by the same rule, which matters because statvfs on a dead NFS server blocks, and this runs on a timer behind a bar panel.

Filesystems are keyed on the block device rather than on the mountpoint, because one filesystem is very often mounted several times. A btrfs root subvolume layout puts /, /home, /var/log and /var/cache/pacman/pkg on one device, and every one of them reports the same pool-wide free space; listing four identical rows would say four times over what is true once. The mountpoint kept is / where the device holds it and the shortest path otherwise, and bind mounts collapse under the same rule.

Each filesystem also carries the physical drive it ultimately sits on, found by following sysfs rather than by trimming digits off a device name: a partition through its parent directory, and a LUKS or LVM mapping through slaves/, which for an encrypted volume on a partition is two hops. That is what lets a filesystem be put next to the temperature of the drive holding it, and for /dev/mapper/... that drive is not the device the filesystem is mounted from.

Portability

The plugin targets laptops with very different sensors, so nothing is hardcoded:

  • Sensors are discovered by walking /sys/class/hwmon. No sensor is ever named in code (TPCD is meaningless outside an Apple SMC).
  • Labels come from sysfs *_label files, so lm_sensors is not a dependency.
  • Attributes are read from the hwmon directory and from its device target, since drivers on the older hwmon API expose nothing in the hwmon directory itself and a naive walk finds none of their sensors.
  • Disk temperatures are looked for both directly under the device (device/hwmon3, which is what NVMe gives) and inside a hwmon/ container.
  • Published thresholds above 200 °C are discarded. NVMe reports an unset threshold as 0xFFFF Kelvin, which arrives as 65261.85 °C.
  • Temperatures split into two classes, because the hardware is not consistent. Governed sensors publish a crit threshold, so headroomC and critFraction are real figures, while ambient sensors publish none and can only honestly show a raw reading. Four of the dual-screen laptop's twenty sensors are ambient, including acpitz and the wifi chip. The fanless laptop has no acpitz hwmon at all; it exposes coretemp, nvme and iwlwifi_1 and nothing else, so its one ambient sensor out of eleven is the wifi chip. The single-fan laptop has an acpitz that publishes no threshold either, so that is ordinary rather than particular to one machine.
  • Sensor ids carry the device the chip hangs off when a chip name repeats (nvme/nvme0/temp1), because two NVMe drives register two chips both called nvme, and nvme/temp1 would otherwise name a sensor on each. The device basename is used rather than the hwmon number, which depends on probe order. Where a chip name is already unique the id is just chip/attr.
  • An empty fan list is explained rather than left to speak for itself, because fans: [] means two different things. The fanless laptop has no fan; the single-fan laptop has one that a vendor driver owns over an ioctl and no hwmon publishes. fanReporting says which was found: reported, declared (an ACPI PNP0C0B device or a Fan cooling device, but no readable speed), vendor (a driver known to own fans out of band), or none. That way the panel can say "no fan" on one machine and "fan present, no driver reporting speed" on the other. Nothing here names a machine, and an unrecognised case is left unsaid rather than guessed.
  • Block devices reporting zero sectors are skipped. An empty SD card reader is still a block device, and the fanless laptop listed two phantom drives with no size and no temperature. The filter is on size rather than on a name prefix, so the reader appears again once it actually holds a card.
  • Filesystems are found through mounts whose source is a block device and are deduplicated by device, as described above.
  • Drive capacity and filesystem capacity are kept apart. A drive's size is the hardware's, before any partitioning, and its temperature belongs to the drive; how full a filesystem is is a different question with a different answer.
  • Battery watts are tagged wattsDirection, since the same reading is draw when discharging and charge rate when charging.
  • Peripherals that register as batteries (a stylus, a wireless keyboard) are skipped. They report scope=Device and would otherwise show as extra batteries stuck at 0%.

Tests

Both suites run as an ordinary user, without root, and touch nothing outside a temporary directory:

python3 tests/test_fan_max.py       # the helper against a fake sysfs with simulated fans and a simulated AMD card (69 tests)
python3 tests/test_system_fans.py   # the fan profile script in both row layouts, with stub commands (22 tests)
bash tests/sandbox-install.sh       # the installer against a temporary tree (109 checks)

Acknowledgements

The bar widget and parts of the panel are derived from Omarchy's own shell plugins, which are MIT licensed: Copyright (c) David Heinemeier Hansson, https://github.com/basecamp/omarchy. The weather plugin in particular is the model this was built from; its author is the Omarchy project itself rather than a separate third party.

  • BarWidget.qml follows omarchy.weather's bar widget closely. The injectPanel / open / close / closeForPopoutSwitch contract is what the bar requires of any widget that hosts a panel, and 51 of this file's 64 non-comment lines are identical to it. This is a derivative of that file rather than something merely inspired by it.
  • The panel's Meter component, its colour bindings and its IPC scaffolding come from omarchy.agents.
  • The collector's shape (a script that prints one JSON snapshot, with the QML rendering it and discovering nothing itself) follows omarchy-agent-usage-*.

Omarchy's copyright and permission notice is reproduced in LICENSE.

Written with AI help

Yes, an AI helped write this. No, it is not Skynet (or is it? 😉). Either way, I have checked the code to make sure it is not plotting Judgment Day. If that still puts you off, no hard feelings. The whole point of Linux is that you decide what runs on your computer.

Licence

MIT

About

Read-only system vitals panel for the Omarchy bar (WIP)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages