Skip to content

About

A theme-aware system monitor for Omarchy with live graphs, configurable bar metrics, and a customizable dashboard.

Resources

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

System QuikView

Your system, at a glance.

A native Omarchy system monitor with a compact bar readout, live graphs, and a dashboard you can make your own.

Install · Screenshots · Customize · Hardware support

System QuikView promotional cover showing a fictional dashboard, fan readings, and key features

The cover is promotional artwork with simulated readings. Native captures and artwork details are available separately.

A quick look, without opening another app

QuikView puts the essentials in your bar and the details one click away. See what is busy, what is warm, and where your memory is going—then collapse the sections you do not need.

  • Choose your bar reading. CPU, memory, GPU usage, temperatures, VRAM, download speed, disk usage, or an icon alone.
  • Keep the popup still. The bar fits its text naturally. The open dashboard stays anchored as readings and selections change.
  • Make the layout yours. Move sections up or down, including individual GPU cards. Your order and collapsed sections survive restarts.
  • Follow your theme. Text, highlights, graphs, and warning colors come from the active Omarchy theme, with live palette updates.
  • See both sides of the network. Separate download/upload graphs, per-interface rates, and transfer counters. Inactive interfaces are tucked behind a toggle.
  • Read temperatures by device. CPU, graphics, storage, and other sensors have grouped cards, gauges, and hardware-reported warning limits.
  • See fan readings honestly. Kernel fan tachometers appear in RPM inside Temperatures. A stopped fan reads 0 RPM; a missing reading stays unavailable.
  • Find busy processes. Ranked cards show process names, PIDs, CPU usage, memory, and comparison bars.

QuikView reads Linux telemetry directly. It does not require btop, a cloud account, a root service, or Python packages from pip.

Install

Requires Omarchy Shell/Quickshell, its native plugin API, and Python 3. This is an Omarchy Shell plugin, not a Waybar module. Tested on Omarchy 4.0.3-1 with Quickshell 0.3.1. The 0.4.7 popup was also rendered on Omarchy 4.0.5-1 with Quickshell 0.3.2 and Qt 6.12.0. Older shells may not provide the required APIs.

omarchy plugin add https://github.com/onelegdave/system-quikview.git --enable

Omarchy will prompt before installing and let you choose where to place it. If you installed without enabling:

omarchy plugin enable onelegdave.system-quikview --section right

Install from a local checkout

git clone https://github.com/onelegdave/system-quikview.git
cd system-quikview
python3 install.py
omarchy restart shell

The local installer backs up your shell configuration and any previous local plugin version, then copies the runtime files into ~/.config/omarchy/plugins/onelegdave.system-quikview. It also migrates the early onelegdave.btop prototype while preserving its placement and preferences.

The local installer refuses symlinked path components, targets, backup paths, and files, as well as unexpected owners/types, hard-linked files, and group/world-writable destinations. It uses directory-relative operations and atomic file replacement; it never writes through an existing destination file. A concurrent change to shell.json aborts the configuration update instead of overwriting that change.

Configuration reads are limited to 1 MiB. Backup trees are limited to 128 MiB, 4,096 entries, and 32 nesting levels, with a 32 MiB per-file limit. Unsafe or oversized paths cause installation to stop with an explanation; the installer does not automatically change their permissions or follow their links. Use the native Omarchy installer when a custom filesystem layout is incompatible.

Legacy prototype files are backed up and then retired under a hidden name in the plugins directory. File updates are atomic individually; a failure midway through an update can leave a mix of versions, with the previous files preserved in the backup.

onelegdave is the publisher namespace—not a requirement to use that username. Packaged Omarchy files are never modified.

Update or remove

For an installation made with omarchy plugin add:

omarchy plugin update onelegdave.system-quikview

For a local checkout, run git pull in the checkout, then python3 install.py and omarchy restart shell again. If Quickshell retains an old component after an update, run omarchy restart shell.

omarchy plugin disable onelegdave.system-quikview
# Or remove it entirely:
omarchy plugin remove onelegdave.system-quikview

Make it yours

Click the bar reading to open the dashboard. Right-click it, or use the Customize button, to open settings.

Control What it does
CPU / Memory / GPU overview card Pins that metric to the bar
Section heading Expands or collapses details
Customize → Section order Moves sections with ↑ and ↓
Customize → Top bar reading Selects the bar metric
Customize → GPU source Selects which GPU supplies its readings
GPU card → Pin temperature Pins that specific GPU’s temperature
Default order Restores the dashboard’s original section order
Done Returns to the dashboard

Use the mouse wheel or arrow/Page Up/Page Down keys to scroll. Escape closes the popup.

GPU selection

QuikView supports separate cards for multiple detected GPUs. The source selector controls the GPU, GPU temperature, and VRAM bar readings and the GPU overview card.

Source Behavior
Auto · prefer dedicated Prefers a dedicated GPU with an available reading, then falls back to another GPU
Dedicated / Integrated Uses the first device assigned that role
Hottest GPU Follows the GPU with the highest reported temperature
A named device Pins a specific GPU by its PCI address

Auto checks availability per metric, so usage and temperature can come from different devices. The GPU temperature tooltip names the source. Choose a named device when you want an exact match, especially with more than one dedicated GPU.

An explicitly selected device stays selected if it disconnects; the reading becomes unavailable instead of silently switching. Saved section preferences are retained for disconnected GPUs. New devices are added to the layout automatically.

GPU role overrides let you label a device as integrated or dedicated when its driver cannot identify the role. Direct device selection works independently of these labels.

At home in your theme

Catppuccin Gruvbox Catppuccin Latte
QuikView in the dark Catppuccin theme QuikView in the warm Gruvbox theme QuikView in the light Catppuccin Latte theme

Colors come from the installed theme: popup text and surfaces, the accent, named cyan/blue/yellow colors (or numbered palette colors 6/4/3), and the urgent color. Missing palette entries fall back to the theme accent. Translucent fills and borders derive from those same colors.

See the feature gallery →

Hardware support

QuikView reports what the running Linux kernel and drivers make available. A missing sensor displays —, not a false zero.

Area Source and support
CPU, RAM, swap, processes Linux /proc
Network /proc/net/dev and interface information in sysfs
Storage Mounted local block filesystems
Temperature sensors Linux hwmon, plus GPU temperature when supplied by the GPU collector
Fans Linux hwmon fanN_input tachometers in RPM; optional read-only fan-duty file when no RPM reading exists (see below)
AMD GPU sysfs readings; optional libdrm_amdgpu identifies integrated vs. dedicated
NVIDIA GPU nvidia-smi, when installed and working
Intel Xe (xe driver) Per-user utilization estimate from DRM activity counters; integrated/dedicated role from the driver configuration
Intel i915 Per-user utilization estimate from standard DRM busy-time counters; GPU role can be assigned manually
Other DRM GPUs Existing sysfs readings, with a per-user utilization fallback when the driver exposes standard busy-time or busy/total-cycle counters

Tested live on an AMD integrated / NVIDIA dedicated laptop and Intel Core Ultra 200V integrated graphics using xe. Intel i915, Intel discrete graphics, and other DRM fallback drivers are implemented where counters are available but are not yet hardware-validated. Software tests cover no GPU, a single GPU, multiple GPUs, missing readings, device selection, and reconnection-related layout behavior.

The DRM utilization fallback is a session estimate: QuikView sums readable clients owned by your user within each engine class, accounts for engine capacity, and shows the busiest class. It reads nanosecond busy-time counters (including Intel i915) or paired busy/total-cycle counters (including Intel xe). Existing sysfs and NVIDIA nvidia-smi utilization readings take priority; the fallback only fills an unavailable usage reading. Shared file descriptors are counted once. Other users' workloads and clients that disappear between samples can be missed. The first sample, inaccessible counters, and interrupted scans show unavailable rather than a made-up zero. No root access, performance-counter permissions, or extra monitoring packages are required. Device nodes are discovered dynamically, including non-PCI DRM devices. A driver that exposes neither supported counter format remains unavailable; a cycles-only counter without a total-cycle clock is not enough.

An integrated Xe GPU shares system RAM, so its card says Shared system memory · no dedicated VRAM. QuikView does not substitute total system RAM for VRAM or CPU temperature for GPU temperature. If the driver exposes no GPU temperature sensor, that reading remains unavailable. GPU identification cache entries expire within 30 seconds, allowing a temporary failed query to retry on a following sample; changing the driver or PCI device ID also triggers a new query. The collector follows the kernel's DRM client statistics interface and Xe counter format.

Fans

QuikView reads fan speed from the kernel's hwmon fanN_input files, in RPM. A reading of 0 RPM is shown as a real zero (not spinning); a fan reporting a fault, or an unreadable value, is left out rather than shown as zero. QuikView never controls fans.

Some laptops expose fan control but no tachometer, so the kernel has no RPM to read (for example HP EliteBooks using hp_wmi). Only when no hwmon RPM reading exists, QuikView looks for an optional file at the fixed path /run/omarchy-fan-speed, written by a separate root service you already run:

{"raw": 119, "percent": 47, "state": "on"}

raw is an integer 0–255 or null, percent a number 0–100 or null, and state one of on, off, or unknown. QuikView shows percent as duty, the publisher's own estimate, never as RPM, and it does not convert raw values, whose meaning varies by model. Only on or off makes percent a reading: off with 0 shows 0% duty, while an unknown state shows — with no gauge even if percent holds a number. A missing percentage also shows —, not 0. QuikView does not access the embedded controller, load modules, run a service, or write to this file.

The file is untrusted input. QuikView reads it through one descriptor without following symlinks. It refuses FIFOs, devices, files over 4 KiB, files changed during the read, and files or parent directories that are not owned by root or are writable by group or other users. It also refuses malformed JSON, duplicate keys, non-finite numbers, booleans used as numbers, out-of-range values, and off with a nonzero percentage. The file must have been modified within the last 10 seconds (the publisher updates every 3 seconds), and a modification time more than 2 seconds in the future is refused. Atomic replacement is supported. Any refusal leaves the fan reading unavailable, and other readings continue.

Optional lspci improves device names. The collector only accepts /usr/bin/lspci and /usr/bin/nvidia-smi: root-owned, non-symlink ELF executables under root-owned directories that other users cannot write. Missing or rejected tools leave the corresponding optional readings unavailable.

Each invocation runs the verified executable file descriptor, with a fixed environment (PATH=/usr/bin, LANG=C, LC_ALL=C) and working directory /. Output is limited to 64 KiB stdout and 16 KiB stderr. Deadlines are 1 second for lspci and 1.5 seconds for nvidia-smi, followed by at most 0.5 seconds of waiting for process cleanup. The process group is killed on completion, timeout, or overflow, including descendants left behind by the tool. This is resource limiting, not a sandbox.

Nothing is installed automatically by the collector. The local installer launches no subprocesses; run omarchy restart shell yourself after installation to load the plugin.

What the numbers mean

  • CPU: overall utilization across threads. Process CPU uses 100% per fully occupied thread and may exceed 100%.
  • Memory: total RAM minus available RAM; reclaimable cache is excluded. Swap is separate.
  • History: the latest 60 samples, kept in memory. CPU/GPU/RAM graphs use a 0–100% scale. Network graphs scale independently to their recent peaks.
  • Fans: RPM comes from the kernel tachometer. Duty percentages from the optional fan file are labeled as duty, not RPM.
  • Temperatures: high/critical labels use valid limits reported by the hardware. Without a limit, a gauge uses a labeled 0–100°C visual scale. CPU temperature is the highest supported CPU sensor reading.
  • Network: bar and overview rates aggregate non-loopback interfaces. Virtual interfaces can double-count traffic. Received/sent totals are interface counters, not totals since opening QuikView.
  • Disks: one mount per local block device. The bar uses the first mount, normally /.
  • Processes: ranked by current CPU usage, then resident memory. Each comparison-bar column is scaled to its highest visible reading.

Change the refresh interval

Readings refresh every 2 seconds by default. To refresh every 5 seconds, run this in a terminal:

omarchy bar set onelegdave.system-quikview interval 5 --json

Replace 5 with any whole number from 1–30. The number is the time between updates in seconds. The setting saves automatically and applies without restarting.

To restore the 2-second default:

omarchy bar set onelegdave.system-quikview interval 2 --json

Collection continues while the popup is closed. Each bar instance currently runs its own collector; multi-monitor collection is not yet shared.

Troubleshooting

The plugin is installed but not visible: enable it with the command above, then check omarchy-shell shell ping.

A GPU reading is unavailable: check whether the driver exposes it. For NVIDIA, verify nvidia-smi works. Try selecting the device explicitly in Customize. Installing QuikView does not install GPU drivers.

Colors or code look stale after an update: run omarchy restart shell.

Settings location: the widget’s entry in ~/.config/omarchy/shell.json. Local-installer backups live beside that file and under ~/.config/omarchy/plugin-backups/.

Development

python3 -m unittest -v
node test_model.cjs
./lint-qml.sh
python3 monitor.py --once
omarchy-plugin-validate .

Node is used only for development tests. Runtime needs Python and Quickshell.

The main files are Panel.qml (dashboard and customization), monitor.py (telemetry), Model.js (selection and layout logic), ThemePalette.qml (theme palette), and Sparkline.qml (graphs).

Contributor notes and diagnostic commands

About and support

System QuikView is a native Omarchy monitor created by OneLegDave, built on Quickshell and Python.

Support my work

I build System QuikView as a free, open-source project. If you find it useful, you can buy me a coffee. Contributions are entirely optional and never required to use any feature.

AI assistance

Codex provided AI assistance during the development and documentation of this project, independent review, and preparation of fictional demo captures and promotional artwork. OpenAI's built-in image generation produced the marketplace cover. Claude provided AI assistance with the fan telemetry feature, its security tests and render validation, and documentation. AI assistance is acknowledged here; authorship, ownership, and maintenance remain with the human project maintainer.

License

MIT © OneLegDave

About

A theme-aware system monitor for Omarchy with live graphs, configurable bar metrics, and a customizable dashboard.

Resources

Contributing

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages