a specific ultimus shell version for mattwm
  • JavaScript 53.2%
  • QML 44.7%
  • HTML 1.6%
  • Nix 0.3%
  • Shell 0.2%
Find a file
Matthew Weber 5960261cc8 workspaces: each workspace's apps beside it, folding away and open
The workspaces widget draws the windows on each workspace as small app icons
next to it, on a tray of their own. By default each bar shows the apps of the
workspace on its own monitor; a workspace on no monitor stays folded until
hovered, and hovering opens any workspace. Clicking focuses, clicking the
focused app minimises, middle-click closes. A minimised window stays beside
its workspace, greyed with a pulsing glow.

- Hypr.js: workspaceClientKeys, windowByAddress, clientsOpen and
  clientClickAction, with tests. Workspace entries carry here/shown/hasFocus.
- The widget's Repeater is now over a ListModel of workspace ids, and the
  icons over a string of window addresses, so a title or focus change no
  longer rebuilds them and replays their animation.
- The travelling focus highlight blends between the two slots' live
  positions instead of easing toward a target that moved mid-flight, which
  overshot and came back.
- `ipc call workspaces toggleClients` (and collapse/expand) folds them on
  every bar; an optional button does the same.
- Settings for all of it in the widget's GUI section; the styling ones are
  registered in Presets.WIDGET_STYLE and docs/reference.md is regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 03:46:39 -05:00
design keybinds, launcher modes, new widgets, themes, and an idle-inhibit fix 2026-10-30 03:25:27 -04:00
docs workspaces: each workspace's apps beside it, folding away and open 2026-11-20 03:46:39 -05:00
nix first commit 2026-10-03 19:57:15 -04:00
presets Jarvis widget: talk to Jarvis from the bar 2026-11-10 02:44:36 -05:00
src workspaces: each workspace's apps beside it, folding away and open 2026-11-20 03:46:39 -05:00
tests workspaces: each workspace's apps beside it, folding away and open 2026-11-20 03:46:39 -05:00
themes first commit 2026-11-19 17:39:28 -05:00
tools keybinds, launcher modes, new widgets, themes, and an idle-inhibit fix 2026-10-30 03:25:27 -04:00
ultimus first commit 2026-10-03 19:57:15 -04:00
.probe-focus.qml first commit 2026-10-03 19:57:15 -04:00
ATTRIBUTION.md first commit 2026-10-03 19:57:15 -04:00
flake.lock first commit 2026-10-03 19:57:15 -04:00
flake.nix first commit 2026-10-03 19:57:15 -04:00
gallery.qml first commit 2026-10-03 19:57:15 -04:00
greeter.qml first commit 2026-10-03 19:57:15 -04:00
lock.qml first commit 2026-10-03 19:57:15 -04:00
plan.md first commit 2026-10-03 19:57:15 -04:00
README.md first commit 2026-10-03 19:57:15 -04:00
settings.qml keybinds, launcher modes, new widgets, themes, and an idle-inhibit fix 2026-10-30 03:25:27 -04:00
shell.qml workspaces: each workspace's apps beside it, folding away and open 2026-11-20 03:46:39 -05:00

ultimus

A Quickshell bar where everything is data. Widgets, layout, colors, shapes and behaviour all come from a config document that a GUI edits live — reaching for a text editor is optional, never required.

Status: early but usable. M0–M16 are done and M17 begun: the data-driven core, shapes, the settings GUI, widgets and services, theming, notifications, system surfaces, live design mode, packaging and plugins, the surfaces beyond the bar — launcher, dashboard, lock screen and greeter — the rules engine, network and Bluetooth management, profiles, the NixOS widgets, the compositor set, the audio and time widgets, and the clipboard and screenshot utilities. See plan.md for the roadmap and for what each milestone left unfinished. 53 widgets so far.

Try it

nix run github:you/ultimus

Or from a checkout:

nix develop
quickshell -p ./shell.qml

The settings panel is a separate process:

quickshell -p ./settings.qml

Or click the cog in the bar, or bind a key to qs -p <shell> ipc call settings open.

The launcher and the dashboard have no keybinds of their own — a shell that grabbed one would be fighting your compositor for it:

bind = SUPER, SPACE, exec, qs -p ./shell.qml ipc call launcher toggle
bind = SUPER, D,     exec, qs -p ./shell.qml ipc call dashboard toggle
bind = SUPER, S,     exec, qs -p ./shell.qml ipc call settings open

On a Lua-configured Hyprland (0.5x) those lines do not parse — the whole config is Lua, and bind = … is the old .conf syntax. Same thing, their way:

local M = "SUPER"
hl.bind(M .. " + Space", hl.dsp.exec_cmd("qs -p /path/to/ultimus/shell.qml ipc call launcher toggle"))
hl.bind(M .. " + S",     hl.dsp.exec_cmd("qs -p /path/to/ultimus/shell.qml ipc call settings open"))

Use an absolute path: a keybind runs with the compositor's working directory, not yours.

You do not need a keybind to reach the settings panel — the settings-button widget is a cog you click, and a bar without one has no way in, so it is worth having.

Config is written to $XDG_CONFIG_HOME/ultimus/config.toml on first run. Set ULTIMUS_CONFIG_DIR to point somewhere else — useful for trying things without touching a working setup.

It coexists with other Quickshell shells (DMS included); instances are keyed by config path. Set exclusive = false on a bar to overlay rather than reserve screen space while experimenting.

Installing

Flake

{
  inputs.ultimus.url = "github:you/ultimus";

  # In your Home Manager configuration:
  imports = [ inputs.ultimus.homeManagerModules.default ];

  programs.ultimus = {
    enable = true;
    settings = {
      theme.name = "kanagawa";
      bars = [{
        id = "main";
        edge = "top";
        thickness = 34;
        groups = [
          { zone = "start"; widgets = [{ type = "workspaces"; }]; }
          { zone = "center"; widgets = [{ type = "clock"; format = "ddd HH:mm"; }]; }
          { zone = "end"; widgets = [{ type = "tray"; } { type = "settings-button"; }]; }
        ];
      }];
    };
  };
}

settings seeds the config rather than owning it. It is written on first activation and then left alone, because the settings panel edits the same file and a read-only store symlink would make every GUI edit fail silently — which would break the one rule this project is built on. Set manageConfig = true if you would rather Nix be authoritative and accept that GUI edits last until the next activation.

There is a NixOS module too (nixosModules.default), but it is deliberately thin: a bar is a per-user program. Its one real job is withBrightnessControl, which installs ddcutil and enables I2C — external monitor brightness needs group membership that a user-level module cannot grant.

Without Nix, quickshell -p /path/to/ultimus/shell.qml is the whole of it.

Documentation

Configuration The config file, the settings panel, presets and importing from Waybar
Appearance Shapes, themes, icons
Bars Auto-hide, bar modes, overflow, length and zone sizing
Widgets The catalogue, tooltips and popouts, services, writing one
Plugins Third-party widgets, loaded from your config directory
Notifications Toasts, the centre, per-app rules, do not disturb
Launcher Applications, the calculator, ranking, and the keyboard
Dashboard The full-screen control centre, built from config
Lock and login The lock screen and the greetd greeter
Getting more Installing widgets and themes from a catalogue
System control Brightness, OSD, quick settings, night light, session menu
Network and Bluetooth Joining a network, pairing a device, and what each costs
Design mode Editing the running bar, and undo
Utilities Clipboard, screenshots, the emoji and colour pickers, the account panel
From the internet Weather, news and prices — and why none of them needs an API key
Audio and time The mixer, the microphone, the pomodoro and progress toward a date
Primitives The generic gauge, the image widget, and the widgets that hold other widgets
Compositor The taskbar, window state, live previews, caffeine and capture indicator
NixOS Generations, flake staleness, backup status — things only this OS can answer
Profiles Named sets of changes, switched by hand or by condition
Rules Conditional visibility and style, over live facts
Actions and IPC The action vocabulary and compositor keybinds
Performance What it costs, measured
Development Architecture, tests, known limitations
Reference Every setting there is, generated from the descriptors

Rule 0

Nothing is config-file only. Every setting that exists is reachable from the settings GUI — including the ones inside nested structures like per-app notification rules, and including the ones a third-party plugin declares.

That is not maintained by discipline. Every property anywhere is declared as a typed descriptor; the GUI generates its editor from that declaration, the runtime resolves defaults through it, and a startup check fails any descriptor without a type, a default and a label. A property with no descriptor is not readable at all. The About page runs the same audit live.

Credits

Architecture and widget ideas owe a lot to DankMaterialShell (MIT). Anything derived from it is recorded in ATTRIBUTION.md.