The interface is branded Noctalia Minimize. Existing command names, plugin IDs, NixOS options and data paths remain unchanged for compatibility.
Reversible window minimization for the Niri Wayland compositor, as a native Noctalia Shell v5 plugin.
Niri is a scrollable-tiling compositor and has no "minimized" window state. This plugin emulates it safely with workspace parking: a minimized window is moved (without focus) to a reserved, named workspace and remembered together with its original workspace. Restoring moves it back. Applications keep running the whole time; nothing is closed, killed or hidden from Niri.
Screenshot from the earlier branding; the current panel is titled Noctalia Minimize.
Super+M |
Minimize the focused window |
Super+Shift+M |
Open the Noctalia Minimize panel |
| Panel | List minimized windows with app icon, title, app id and the workspace each returns to; restore one, restore all, minimize the active window, minimize all (with confirmation) |
| Keyboard | ↑/↓ select · Enter restore · Ctrl+A restore all · Ctrl+R refresh · Esc close |
| Bar widget | Left click minimizes, right click opens the panel |
| Control-center tile | "Noctalia Minimize · Minimize active window" |
| Taskbar restore | Selecting a parked window in Noctalia's taskbar/switcher restores it (optional) |
| Optional bindings | Minimize all, restore all, restore last (NixOS module options) |
Behaviour details:
- Multiple windows, workspaces and monitors. Each window remembers its own origin workspace (by Niri workspace id), including workspaces on other outputs. The parking workspace is an empty workspace on the focused output.
- Origins are kept alive. If minimizing empties an unnamed workspace, it is temporarily named
Restore <id>so Niri does not delete it; the name is removed again when its last window returns or closes. Workspace names you set yourself are never changed. - Closed windows. A window closed while minimized is dropped from the list automatically and any temporary names are released.
- Focus. Minimizing never moves focus to the parked window. Restoring a single window focuses it; Restore all leaves focus where it is.
- Restarts. State is kept in
$XDG_STATE_HOME/noctalia-minimizer/windows.json(mode 0600) and survives Noctalia restarts. A new Niri session invalidates old window ids, so stale state is discarded. - Migration. Windows parked by the older "Desk Tools" plugin in the same Niri session are adopted once (its state file is read, never modified).
- Niri with JSON IPC (developed and tested on Niri 26.04).
- Noctalia v5, plugin API 24 or later (tested on 5.0.1, API 30).
- Python 3 (standard library only; supplied by the Nix package).
- Linux. Other compositors are not supported; the panel says so instead of failing silently.
# flake.nix
{
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
inputs.noctalia-minimizer.url = "github:SwashX-dev/Noctalia-Minimize";
inputs.noctalia-minimizer.inputs.nixpkgs.follows = "nixpkgs";
outputs = { nixpkgs, noctalia-minimizer, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
./configuration.nix
noctalia-minimizer.nixosModules.default
{ programs.noctalia-minimizer.enable = true; }
];
};
};
}The module does not depend on flake inputs, so it can be imported directly from a checkout:
# configuration.nix
{
imports = [ ./vendor/noctalia-minimizer/nix/module.nix ]; # a copy kept next to configuration.nix
programs.noctalia-minimizer.enable = true;
}Keep the checkout somewhere only root can modify (for example /etc/nixos/vendor), because the
module is evaluated by nixos-rebuild.
Then build first, and switch only if the build succeeds:
sudo nixos-rebuild build && sudo nixos-rebuild switchnix profile add github:SwashX-dev/Noctalia-MinimizeThis installs noctalia-minimizer, noctalia-minimizer-setup and the plugin under
~/.nix-profile/share/noctalia-minimizer/plugins. Key bindings are then set up with the setup tool
(below), using the shipped binding file.
| Path | Purpose |
|---|---|
bin/noctalia-minimizer |
JSON CLI used by the plugin (status, minimize, minimize-all, restore --id N, restore-all, restore-last) |
bin/noctalia-minimizer-setup |
Per-user Noctalia + Niri integration helper |
share/noctalia-minimizer/plugins/minimizer/ |
The Noctalia plugin (local/minimizer) |
share/noctalia-minimizer/niri-binds.kdl |
Default Niri bindings |
/etc/noctalia-minimizer/niri-binds.kdl |
Bindings generated from the module options (NixOS) |
No service, daemon, root helper or PolicyKit rule is installed.
After installing, run once as your normal user (inside your Niri session):
noctalia-minimizer-setup checkIt prints the Niri config it found, the keys it wants, any conflicting bindings (including in
included files) and whether the plugin is registered. Then:
noctalia-minimizer-setup applyapply:
- refuses to continue if a key is already bound (nothing is changed);
- backs up your Niri config to
~/.local/state/noctalia-minimizer/backups/<time>/; - appends one marked line,
include optional=true "/etc/noctalia-minimizer/niri-binds.kdl"(or the profile's binding file), and validates the result withniri validatebefore writing; - registers the plugin directory as a Noctalia path source and enables
local/minimizerthrough Noctalia's IPC (noctalia msg plugins source add …,noctalia msg plugins enable …).
Niri reloads its config automatically. Because the include is optional=true, uninstalling the
package later never breaks your Niri config.
Conflicts:
--replace-desk-toolsreplaces only theMod+M/Mod+Shift+Mlines inside an existing// BEGIN DESK TOOLS … // END DESK TOOLSblock (the original plugin this project came from).--replace KEYcomments out (does not delete) a conflicting binding in your main config.- Or choose different keys (module options below, or edit the binding file).
Manual alternative: add the include line yourself, and in Noctalia's settings add a path source
pointing at /run/current-system/sw/share/noctalia-minimizer/plugins, then enable "Noctalia Minimize".
To put the button on a bar, add a widget of type local/minimizer:minimize-button:
# ~/.config/noctalia/config.toml (merge with your existing bar lists)
[widget.minimize]
type = "local/minimizer:minimize-button"
[bar.default]
start = ["workspaces", "minimize"]The binding file contains:
binds {
Mod+M hotkey-overlay-title="Minimize active window" { spawn "noctalia" "msg" "plugin" "local/minimizer:actions" "all" "minimize"; }
Mod+Shift+M hotkey-overlay-title="Noctalia Minimize" { spawn "noctalia" "msg" "plugin" "local/minimizer:actions" "all" "windows"; }
}The service also accepts the events minimize-all, restore-all and restore-last.
| Option | Default | |
|---|---|---|
programs.noctalia-minimizer.enable |
false |
Install the package and plugin |
programs.noctalia-minimizer.package |
built from this repository | |
programs.noctalia-minimizer.keybindings.enable |
true |
Generate /etc/noctalia-minimizer/niri-binds.kdl |
….keybindings.minimize |
"Mod+M" |
null to omit |
….keybindings.panel |
"Mod+Shift+M" |
null to omit |
….keybindings.minimizeAll |
null |
Minimize every window, no confirmation |
….keybindings.restoreAll |
null |
|
….keybindings.restoreLast |
null |
Most recently minimized window |
The module asserts that the chosen chords are distinct. It cannot see your per-user Niri config,
so use noctalia-minimizer-setup check to detect conflicts there.
| Key | Default | |
|---|---|---|
enabled |
true |
Disables every action when off |
auto_restore |
true |
Restore a parked window when it is focused from the taskbar. Uses one idle niri msg --json event-stream process while the plugin is loaded; reload the plugin after changing it |
confirm_minimize_all |
true |
Ask before Minimize all in the panel |
Environment: NOCTALIA_MINIMIZER_PARKING_NAME changes the reserved workspace name (default
Noctalia Minimized).
- "Window parking requires a running Niri session" — run inside Niri; if several sessions
exist, set
NIRI_SOCKET. Another user's socket is never used. - "A workspace named 'Noctalia Minimized' already exists without this session's state" — the
plugin will not take over a workspace it did not create. Move its windows out with Niri's normal
workspace navigation and unname it (
niri msg action unset-workspace-name "Noctalia Minimized"). - "No empty Niri workspace is available" — Niri normally keeps an empty workspace at the end of each output; switch to it once or open a new workspace.
- A window is stuck on the parking workspace — it is an ordinary workspace: navigate to it and
move the window, or run
noctalia-minimizer restore-all. - Nothing happens on Super+M —
noctalia-minimizer-setup check;noctalia msg plugins listmust showlocal/minimizer … enabled; check~/.cache/noctalia/noctalia.log.
Flakes: nix flake update noctalia-minimizer, then rebuild. Channels: update your copy of the
repository, then rebuild. Profile: nix profile upgrade noctalia-minimizer. State files are
forward compatible; restore parked windows first if you want to be extra careful.
- Restore parked windows:
noctalia-minimizer restore-all. noctalia-minimizer-setup undorestores the Niri config backed up byapply(it refuses if the file was edited afterwards; inspect the backup or pass--force) and disables the plugin and its source.noctalia-minimizer-setup removeinstead removes only the managed include line.- Remove the module (or
nix profile remove noctalia-minimizer) and rebuild. A NixOS rollback (sudo nixos-rebuild switch --rollback, or an older generation in the boot menu) returns to the previous system at any time; theoptional=trueinclude keeps Niri working either way. - Delete
~/.local/state/noctalia-minimizeronce nothing is parked.
- This is workspace-based emulation, not a native hidden state: the parking workspace is visible in Niri's workspace list and overview.
- Restoring returns a window to its original workspace; exact column position, tab grouping and floating coordinates are not restored (Niri IPC offers no way to re-insert a window at a saved column index).
- Restoring into a workspace that Niri removed (for example after an output was unplugged) falls back to the focused workspace.
- Only Niri is supported.
nix flake check -L # unit tests, Luau compile, Noctalia linter, niri validate, module, NixOS VM test
nix build .#default -L
PYTHONPATH=backend python3 -m unittest discover -s tests -v # without NixWhat is tested and how:
| Test | Kind |
|---|---|
tests/test_windows.py (minimize/restore, multiple windows, two outputs, closed windows, new windows, renamed workspaces, IPC failures, legacy adoption, private files) |
Mocked Niri IPC |
tests/test_cli.py, tests/test_setup.py (conflicts, includes, backup/undo, replace) |
Mocked / temporary files |
checks.plugin |
Real luau-compile and noctalia plugins lint on the installed plugin |
checks.niri-binds |
Real niri validate on both binding files |
checks.vm |
NixOS VM: module install, CLI error handling without Niri, setup apply/undo |
tests/live/niri_live_test.py |
Live: real Niri 26.04 (nested session, disposable windows). Run manually; refuses to touch non-test windows |
The live test passed during development (16/16 checks: minimize active, restore one, restore last,
restore all across two workspaces, closed minimized window, focus behaviour, IPC failure). The
panel, bar button and the Super+M command path were also exercised in a real Noctalia 5.0.1
instance inside that nested session; the screenshot above is from it.
MIT — see LICENSE.
