Omahub
← All plugins
S

SteelSeries Mouse Battery Widget

by Stian Busengdal

Battery level of a SteelSeries wireless mouse, read through rivalcfg.

GitHub

Security review

Review recommended · 5 findings

Deterministic scan — not a security guarantee

Medium
Risk level
Medium
Analyzed commit
80c824c
Scanned
1 month ago
  • medium sudo install.sh:100

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo rivalcfg --update-udev
  • medium sudo install.sh:103

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo rivalcfg --update-udev" ;;
  • medium sudo install.sh:104

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo rivalcfg --update-udev" ;;
  • Docs external_hosts README.md:43

    Downloads or connects to an external HTTP(S) host.

    git clone https://github.com/FadeCap/omarchy-steelseries-battery.git
  • Docs sudo README.md:36

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo rivalcfg --update-udev

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
80c824c
Reviewed
1 month ago

The plugin is a straightforward bar widget that shells out to rivalcfg to read a SteelSeries mouse battery, with clean, well-tested parsing logic and no obfuscation or hidden behavior. The deterministic scan's medium findings are explained by the README's documented `sudo rivalcfg --update-udev` step and the installer's non-escalating check that merely prints that command when udev rules are missing; the installer itself never elevates privileges. The only notable risk is that the installer copies files into the user's Omarchy config and modifies the bar layout, which is expected behavior for a plugin installer and is clearly disclosed.

  • install.sh runs `omarchy-shell shell rescanPlugins` and `omarchy plugin enable` to modify the user's bar layout, which is expected installer behavior but does change the user's shell configuration.
  • The installer's embedded Python probe imports rivalcfg and inspects its udev rules; it runs with the user's privileges and only reads, so it is not a privilege-escalation risk.
  • The README's `sudo rivalcfg --update-udev` is a documented prerequisite for rivalcfg itself, not something the plugin executes; the installer only prints that command as guidance.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/FadeCap/omarchy-steelseries-battery --enable
Widgets #bar #power-management

SteelSeries Mouse Battery Widget

Mouse battery level in the Omarchy bar.

The widget in the bar

SteelSeries only. The level is read with rivalcfg, so if rivalcfg --battery-level prints a percentage for your mouse, this widget will too — and if it doesn't, nothing here will help. Logitech, Razer, and Bluetooth mice are not supported.

Install

omarchy plugin add https://github.com/FadeCap/omarchy-steelseries-battery.git

It asks before enabling, and lets you pick the bar section.

Needs rivalcfg from the AUR:

yay -S rivalcfg

That's usually all of it — the AUR package's post_install hook runs rivalcfg --update-udev for you, and those udev rules are what let it read the mouse as your user instead of as root.

You only need to run that yourself in two cases: you installed rivalcfg with pip rather than from the AUR, or you upgraded rivalcfg and the rules went stale, since the packaging hooks post_install but not post_upgrade.

sudo rivalcfg --update-udev

Missing or stale rules make the widget show a dash forever with nothing to explain why, so the bundled installer checks before it installs anything:

git clone https://github.com/FadeCap/omarchy-steelseries-battery.git
cd omarchy-steelseries-battery
./install.sh                     # asks which section
./install.sh --section center    # or name it: left, center, right

Move it any time:

omarchy bar move io.github.fadecap.steelseries-battery --section center --after omarchy.clock

Uninstall

omarchy plugin remove io.github.fadecap.steelseries-battery

Or ./uninstall.sh, which also clears a stale bar entry if a previous removal was interrupted. Add --purge to delete the timestamped backups each removal leaves behind — worth it if you are cycling install and uninstall.

What it shows

State Bar Tooltip
Normal 󰍽 60% Mouse battery: 60% · Discharging
Charging 󰍽 60% Mouse battery: 60% · Charging
Low 󰍽 15% urgent-coloured Mouse battery: 15% · Discharging
Mouse off 󰍽 — dimmed Mouse battery: mouse is turned off
No dongle 󰍽 — dimmed Mouse battery: no supported device found
No battery support 󰍽 — dimmed Mouse battery: this device has no battery reporting

Left click re-polls. On a vertical bar the label stacks, icon over number.

Going low sends one notification, once — not once per poll, not once per monitor, and not again as it keeps dropping. It re-arms when the mouse charges or climbs 5 points clear of the threshold.

Configuration

Key Default Range
interval 300 30–3600 Seconds between polls
lowThreshold 20 5–50 Percent counted as low
notify true Send the low-battery notification
hideWhenAbsent false Hide rather than dim when there's no reading 
omarchy bar set io.github.fadecap.steelseries-battery interval 600

Each poll spawns rivalcfg and talks to the mouse over USB, which takes about half a second. A mouse battery moves over days, so the 5-minute default is already far more often than the value changes.

Troubleshooting

A dash means there's no reading — the mouse is off, the dongle is out, or the udev rules are missing. Run rivalcfg --battery-level: whatever that prints is all the widget has to work with, and if it errors the problem is between rivalcfg and your mouse rather than in this plugin.

Development

Logic lives in Model.js as pure functions — no QML, no I/O — so the suite runs without a compositor or a mouse attached:

node --test test/*.test.js
omarchy plugin validate .

test/fixtures.js holds every output shape rivalcfg produces. One earns special mention: with the mouse switched off it prints an error and exits 0, so state is decided from stdout and the exit code is only a tie-breaker.

Licence

MIT, see LICENSE. rivalcfg is a separate WTFPL project, called as a subprocess and neither vendored nor linked.