Ruixen Shell

A connected bar, notch, and settings app for Omarchy — an OLED-black, unified visual layer that runs as plugins inside the Omarchy shell you already use.

What's included

• ruixen.bar — the top bar itself: app launcher, GNOME-style dot workspace indicator, pinned quick-launch apps, weather, clock, and a settings shortcut, all in one connected pill layout.
• ruixen.notch — a center-notch dashboard with metrics, wallpapers, storage, music control, a notification history card (attaches to Omarchy's own notification service, adding read/unread tracking and a deeper backlog on top of it), and a Kanban board (see below), expanding from the bar.
• ruixen.frame-widget — the OLED-black screen frame that ties the bar and notch together visually.
• ruixen.settings — a standalone settings app (Audio, Wi-Fi, Bluetooth, Display, Plugins) that can replace the default Omarchy settings panel entirely, or run on its own.
• ruixen.pinnedapps — quick-launch row for apps pinned in the notch's own app launcher.
• ruixen.pluginpins — a pin/unpin dropdown on the bar for any other installed bar-widget plugin (yours or a third party's) — install something new, pin it from here, no shell.json editing required.
• ruixen.peripherals — battery percentage for wireless mice, keyboards, headsets and controllers (Bluetooth and USB receivers alike), pin the ones you care about to show inline on the bar. Detection reads /sys directly rather than Quickshell's own Bluetooth/UPower bindings, which don't reliably cover every wireless peripheral — ported from xgborgeso/omarchy-peripheral-batteries (MIT license).
• Tray widgets — ruixen.tray, ruixen.stayawake, ruixen.quickactions, ruixen.weather, ruixen.applauncher, ruixen.settingsbutton. ruixen.stayawake (and any stock Omarchy widget it sits next to, like the AI usage indicator) is pinned on or off through ruixen.pluginpins above, not a separate settings toggle.

ruixen.media backs ruixen.notch's own music control as a background service — it never shows a bar icon of its own by design (an earlier, oversized play/pause badge was retired), so it's locked in Settings' Plugins list with no toggle.

Every plugin shares the same OLED-black background, corner radii, and motion language, so they read as one shell instead of a pile of separate widgets.

Documentation

• docs/KEYBINDS.md — ready-to-use Hyprland keybind recipes: Ruixen Settings (and jumping straight to one page), the notch dashboard, the app launcher.
• docs/CONTROL.md — how every plugin here is controllable over a plain CLI call (omarchy-shell <target> <method> [args]), the same mechanism a keybind, a script, or an AI agent all use identically, plus the Kanban board's full command reference as a worked example.

Install

Ruixen Shell targets Omarchy 4.0.0-1 (also confirmed working on 4.0.1-1). Install from source:

git clone https://github.com/gitcoder89431/ruixen-shell.git
cd ruixen-shell
./install.sh

An AUR package is planned but not yet published — cloning from source is the only install path right now.

The installer copies each plugin into ~/.config/omarchy/plugins/, backs up anything it would overwrite, merges Ruixen's bar/plugin config into your existing shell.json rather than replacing it outright (any unrelated bar widgets, plugins, or idle settings you already had survive), applies a matching Hyprland window look (rounded corners + blur, see below — also backed up if you already have a looknfeel.lua), and restarts the Omarchy shell.

After installing, add a keybind of your own for opening Ruixen Settings (and anything else — the app launcher, jumping straight to one settings page) — the installer deliberately doesn't touch your Hyprland config. See docs/KEYBINDS.md for ready-to-use recipes.

Want to see exactly what it would do first, without changing anything?

./install.sh --dry-run

Reports Omarchy version/dependency status, plugin manifest validation (run for real, read-only), which plugins would install fresh vs. replace an existing copy, whether shell.json would be created or merged (and what would actually change), and the Hyprland look'n'feel plan — then exits having touched nothing.

Updating

./update.sh

./update.sh --dry-run previews it first: current vs. candidate revision, then the same install plan above for whatever is currently on disk (pulling itself is skipped, so it can't preview code not yet checked out — noted explicitly in its own output).

Pulls the latest changes and reinstalls — same backup-then-merge behavior as install.sh itself, so it's always safe to re-run. Only works from your existing cloned checkout (it just wraps git pull + ./install.sh), so don't delete the folder after installing.

If something looks like it didn't update, or a plugin looks out of date:

./ruixen-doctor.sh

A read-only diagnostic report — checks nothing changes. Prints your git status vs the remote, whether each deployed plugin's actual file content matches this checkout's own source byte-for-byte (catches an update that silently didn't finish, even when nothing's version number changed), backup history, the current bar layout (ids only), and basic runtime health. Safe to paste the output anywhere — no paths, hostnames, or personal config values are ever printed.

If doctor finds drift, fix it directly:

./ruixen-repair.sh --dry-run   # report what's broken, change nothing
./ruixen-repair.sh             # actually fix it

Detects any plugin whose deployed files don't match this checkout (missing entirely or content mismatch) and a dangling looknfeel.lua symlink, then fixes them by running install.sh itself — the same deploy path every install/update already uses, so shell.json and any third-party bar entries are preserved exactly as they always are.

Disabling / going back to Omarchy defaults

Nothing here is a one-way door.

Turn individual plugins off, keep everything installed:

omarchy plugin disable ruixen.notch
omarchy plugin disable ruixen.frame-widget
omarchy plugin disable ruixen.settings
# same for any of the tray widgets: ruixen.tray, ruixen.weather, etc.

omarchy plugin enable ruixen.notch   # turns it back on

If a plugin stops updating after toggling it a few times, run omarchy restart shell — a full restart always clears it.

Switch the bar back to stock Omarchy:

omarchy bar defaults

Use omarchy bar defaults, not omarchy plugin enable omarchy.bar — that command only swaps the bar engine and leaves Ruixen's widget layout in place, which looks broken rather than default. omarchy bar defaults resets everything (id, layout, position, transparency) in one shot.

To bring Ruixen's own bar back afterward, just run ./install.sh again.

Fully remove a plugin's files:

omarchy plugin remove ruixen.bar

Backs the plugin up rather than deleting it outright (to ~/.config/omarchy/plugins/.<id>.bak.<timestamp>) — disable/enable and the bar reset just flip settings, this is the only step that touches files at all.

Uninstall everything in one shot:

./uninstall.sh

Switches back to the built-in Omarchy bar, removes every Ruixen plugin's files for real (unlike a bare omarchy plugin remove, which just backs a plugin up instead of deleting it — see above; this deletes those backups too, so nothing lingers), restores your original Hyprland window look (or Omarchy's own default if you never had one), and restarts the shell. Only works from your existing cloned checkout, same as update.sh — the checkout itself is left alone, delete it yourself afterward if you don't want it around. Same in-app path also lives in Ruixen Settings' own Plugins page, behind a typed confirmation.

./uninstall.sh --dry-run previews exactly what would happen first: the bar host it would restore, which of your own widgets it would preserve, which Ruixen plugin files it would remove, any leftover Ruixen entry it would sweep out of shell.json's plugins[] array, and the look'n'feel restore plan — nothing is changed.

Docked bar mode (experimental)

By default the left and right icon groups float as separate pills, inset from the frame. Docked mode merges each side into one continuous shape flush with the frame's corners instead — like the notch, just with one shoulder curve per side instead of two. Not the default look, but worth trying:

./ruixen-bar-mode.sh docked      # merged pills, flush with the frame
./ruixen-bar-mode.sh floating    # back to the default separate pills
./ruixen-bar-mode.sh status      # show which one is active

No restart needed either way — it's a live config reload.

Kanban board

ruixen.notch's dashboard has a 4th tab: a fixed 3-column board (Todo / In Progress / Done — Tab cycles through all 4 tabs, or click the column-icon in the left rail). It's agent-native — built to be driven programmatically rather than typed into by hand, so adding a card, renaming a column, and setting priority are all CLI-only. Full command reference and how the click model works: docs/CONTROL.md.

Window look'n'feel (Hyprland)

Ruixen also rounds window corners (24px) and adds blur, to match the frame/bar. Toggle it independently of the plugins above:

hyprland/ruixen-lookfeel.sh on      # rounded corners + blur, matches the frame
hyprland/ruixen-lookfeel.sh off     # stock Omarchy: square corners, no blur
hyprland/ruixen-lookfeel.sh square  # square corners, but keeps the thin border/blur/shadow/animations
hyprland/ruixen-lookfeel.sh status  # show which one is active

square is for anyone who wants stock Omarchy's own square corners without giving up the rest of Ruixen's look. The screen frame's own corner rounding follows whichever of the three is active automatically when the bar is floating. When the bar is docked, the frame's corner always stays rounded regardless of which variant is active -- docked mode's own wider gaps already keep real window corners well clear of that curve, so nothing clips, and it keeps the docked bar's own corner (always rounded) visually consistent with the frame right next to it.

Requirements

• Omarchy 4.0.0-1 (or a nearby build of the same shell generation) -- install.sh checks this and warns (doesn't block) if it detects something outside that range
• Quickshell, as provided by Omarchy
• jq -- the installer itself needs it to merge into your existing shell.json rather than overwrite it

install.sh also checks a few optional, feature-specific dependencies and warns (without failing) if any are missing, so you know up front rather than discovering it later when a feature quietly doesn't work:

Missing	What's unavailable
ffmpeg	Video wallpaper support (posters/playback)
curl	Weather data, avatar image download in Settings
python3	The bar's docked-mode toggle
fastfetch	Less detail on the health page's system-info panel

Running tests

./tests/run-all.sh

Runs everything CI runs (.github/workflows/ci.yml) in one go: shell script lint (bash -n + ShellCheck, when installed), plugin manifest validation, the JS model tests, and the installer lifecycle/config/ uninstall-restore tests. Each suite can also be run on its own -- see tests/*.sh, every file has its own header comment explaining what it covers.

The installer tests (tests/install-lifecycle.sh, tests/shell-json- merge.sh, tests/looknfeel-preserve.sh, tests/uninstall-bar- restore.sh) run against a throwaway fake $HOME/directory tree, never your real config, so they're safe to run anywhere including this repo's own checkout.

Credits

• Omarchy (github.com/basecamp/omarchy) — the Arch/Hyprland desktop this whole project is built on top of. omarchy-shell, Omarchy's own Quickshell-based bar/notch/notification runtime, is what every plugin here actually loads into.
• Ambxst (by Axenide) — UI/UX design inspiration for several ruixen.notch panels (the dashboard layout, calendar, metrics page, wallpapers picker). Ambxst's own code is AGPL-3.0 licensed; ruixen-shell's implementations are written independently, not derived from its source.
• xgborgeso/omarchy-peripheral-batteries (MIT) — ruixen.peripherals's detection logic is ported from this project (see above, and the plugin's own source header for the full attribution).

License

Released under the MIT License.