Omahub
← All plugins
C

Oma JuiceMaxx

by Cagan Orsun / @0nagac

Agentic, hardware-aware battery diagnostics and safe, measured power optimization.

GitHub

Security review

Review recommended · 2 findings

Deterministic scan — not a security guarantee

Medium
Risk level
Medium
Analyzed commit
8b20e66
Scanned
1 month ago
  • medium eval tests/test-model.js:16

    Dynamic code execution via eval().

    eval(ByteArray.toString(loaded[1]).replace(/^\.pragma library\s*/, ""));
  • medium package_manager …/workflows/ci.yml:16

    System-wide Python package installation (not --user).

    pip install --disable-pip-version-check jsonschema

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
8b20e66
Reviewed
1 month ago

The deterministic scan flagged two medium items, but both are benign and not part of the plugin's runtime path. The `eval()` call appears only in `tests/test-model.js`, a test harness for validating the QML model logic; it is never used in production code. The `pip install` in `.github/workflows/ci.yml` is a CI-only step to install `jsonschema` for schema validation; it does not affect the plugin's operation. The plugin itself is carefully engineered with strong safety boundaries: it uses a bounded Python backend with fixed argument arrays, refuses arbitrary shell fragments, enforces output size limits, requires explicit consent for any mutation, and restricts writes to a typed power-profile change via `powerprofilesctl`. The shell scripts are read-only or explicitly refuse mutation. The QML code uses `Process` with controlled arguments and output limits. The plugin is intentionally unsandboxed because it reads `/sys` and `/proc`, but the code demonstrates defensive practices (e.g., no sudo, no package installation, no arbitrary sysfs writes). The flagged items do not introduce runtime risk, and the overall design appears safe for installation.

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/cagano/omarchy-juicemaxx --enable
System #ai #power-management #system

Oma JuiceMaxx

Oma JuiceMaxx is a local Omarchy bar widget for honest battery-power diagnostics and one carefully constrained optimization action. System watts are measured from readable discharging-battery telemetry; process “drains” are activity attribution, not direct per-process power sensors.

Created by Cagan Orsun / @0nagac. The stable marketplace ID is oma.juicemaxx and the public source is github.com/cagano/omarchy-juicemaxx.

What it does

  • Discovers batteries, CPU frequency driver, DRM cards/connectors, physical block devices, wireless interfaces, Bluetooth state, and advertised power profiles without hardware-name assumptions.
  • Uses Omarchy/Quickshell's existing UPower subscription for live bar percentage and discharge rate, so the closed widget does not launch Python on a timer.
  • Runs a bounded local Python 3 standard-library measurement using monotonic timing and trapezoidal integration.
  • Keeps static hardware/profile context outside the sampling loop; fast samples use direct battery, kernel counters, process activity, and optional read-only powercap counters. The helper reports its own CPU/RSS/subprocess overhead separately and never converts that overhead to watts.
  • Ranks redacted process activity across adjacent /proc samples using (pid,starttime) identities, including process starts, exits, and counter resets.
  • Shows measured system watts separately from estimated process watts. Process watt estimates appear only with a fresh, condition-matched multi-sample baseline; otherwise the UI shows activity ranking and unallocated measured residual.
  • Runs a deterministic observe → measure → attribute → explain → propose → consent → apply → verify → rollback flow.
  • Uses Quickshell's optional UPower subscription for live bar percentage, state, and changeRate; older hosts fall back to the last explicit backend result. Power Profile state is taken from the backend at explicit boundaries; no unconfirmed live profile hint is shown.
  • Watches a user-only assistant completion marker instead of launching a Python poller while the widget is closed. NVIDIA nvidia-smi is queried only when an NVIDIA-family DRM device is already runtime-active.
  • Keeps Recommend as the default. It requires visible consent before applying an advertised power-saver profile. Guarded Automatic is opt-in and requires a valid persisted policy, matched baseline, quality/coverage, battery, cooldown, and daily-limit checks; it can execute at most one typed power-profile action per run.

Bluetooth, display persistence, Wi-Fi/runtime-PM, GPU/driver, ASPM, boot/initramfs, and other privileged or vendor-specific tuning remain manual or recommendation-only. Agent Assistance is enabled by default, but each analysis still requires an explicit user action; it explains redacted evidence and suggests fixed diagnostic IDs, and has no action authority. See docs/llm-assistance.md.

Vendor GPU tools never run on the idle widget path. NVIDIA telemetry is queried only during an explicit diagnostic and only when its DRM device is already runtime-active, avoiding an accidental wake of a suspended GPU.

Installing it

omarchy plugin add https://github.com/cagano/omarchy-juicemaxx.git --enable
omarchy bar move oma.juicemaxx --section right

The plugin is intentionally unsandboxed because it reads /sys, /proc, and optional local diagnostics. Review docs/safety.md and docs/privacy-safety.md before enabling it. Missing batteries, tools, permissions, or telemetry produce degraded/unknown status rather than fabricated zeroes.

Compatibility

The backend uses only Python 3 standard-library code and fixed executable argument arrays. The legacy shell helpers remain as read-only/compatibility interfaces; mutation requests through scripts/power-action are refused so they cannot bypass typed transaction safety.

Quickshell UPower is preferred for lightweight live presentation. Direct /sys/class/power_supply remains authoritative for short diagnostic sampling and works when UPower has no usable display device. Power Profile state, powercap, DRM, /proc, and vendor telemetry all degrade independently when absent or unreadable. No package is installed and no root permission is requested.

The manifest follows Omarchy’s first-party service + bar-widget contract with a keep-loaded Service.qml coordinator and BarWidget.qml UI. The widget consumes the injected/bar.shell.serviceFor("oma.juicemaxx") singleton and falls back to one serialized, one-shot local backend process only on older hosts without the service API. A prior installed-host filename case-mismatch remains a compatibility condition to verify during installation; it is documented in docs/compatibility.md and is not silently treated as successful service loading.

Removing it

omarchy plugin disable oma.juicemaxx
omarchy plugin remove oma.juicemaxx

The backend stores local history, policy, proposals, and recovery records below ${XDG_STATE_HOME:-$HOME/.local/state}/omarchy-battery-optimizer/. Remove that directory separately if you also want to delete local state. If an interrupted transaction is reported, inspect the recorded target and recovery status before using the explicit rollback path.

Development

From the plugin directory:

jq empty manifest.json
python3 -m unittest discover -s tests -p 'test_*.py'
gjs tests/test-model.js Model.js
python3 -m py_compile bin/battery-optimizer
bash -n scripts/power-audit scripts/power-measure scripts/power-action scripts/lib/common.sh
bash tests/test-audit.sh
bash tests/test-service.sh
python3 tests/test_agent_features.py
python3 tests/validate_schemas.py

Use fixture tests for deterministic work. Read-only live checks are safe; do not run apply or rollback during development validation.

License

MIT. See LICENSE.