my quickshell config, tailored for hyprland. Somewhat created with claude.
  • JavaScript 53.6%
  • QML 44.3%
  • HTML 1.6%
  • Nix 0.3%
  • Shell 0.2%
Find a file
Matthew Weber 61fff37479 notify: retire a toast when its app closes the notification
An application closing its own notification destroyed the object under
the toast. The entry stayed in `active`, and every read of the dead
object threw. `if (item.notification)` passes for a destroyed
notification, so dismiss threw before retire and the card sat on screen
blank and unclickable.

- Notifications.alive() asks whether the object can still be spoken to;
  entries are retired on the object's `closed` signal.
- Toasts snapshot appName/summary/body/appIcon/desktopEntry and fall back
  to them if the object dies mid-flight.
- Closing a collapsed group closes the whole group (dismissGroup).
- The toast's TapHandler accepts the right button, so right-click works.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 16:44:03 -05:00
design keybinds, launcher modes, new widgets, themes, and an idle-inhibit fix 2026-10-30 03:25:27 -04:00
docs localsend: pick files with an in-panel browser, not a FileDialog 2026-11-13 16:44:03 -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 notify: retire a toast when its app closes the notification 2026-11-13 16:44:03 -05:00
tests notify: retire a toast when its app closes the notification 2026-11-13 16:44:03 -05:00
themes keybinds, launcher modes, new widgets, themes, and an idle-inhibit fix 2026-10-30 03:25:27 -04: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 notify: give the entry its own deadline, and say when nothing is drawn 2026-11-02 02:29:06 -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.