- JavaScript 53.2%
- QML 44.7%
- HTML 1.6%
- Nix 0.3%
- Shell 0.2%
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> |
||
|---|---|---|
| design | ||
| docs | ||
| nix | ||
| presets | ||
| src | ||
| tests | ||
| themes | ||
| tools | ||
| ultimus | ||
| .probe-focus.qml | ||
| ATTRIBUTION.md | ||
| flake.lock | ||
| flake.nix | ||
| gallery.qml | ||
| greeter.qml | ||
| lock.qml | ||
| plan.md | ||
| README.md | ||
| settings.qml | ||
| shell.qml | ||
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.