- Rust 83.9%
- HTML 5.1%
- Lua 3.9%
- QML 3.5%
- Nix 2.3%
- Other 1.3%
Qt only counts hours 1-12 when the format has AM/PM in it, so a 12-hour clock is [lock] clockFormat = "h:mm AP"; the Window face leaves the AM/PM off the numerals, as a phone's lock screen does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|---|---|---|
| .impeccable | ||
| crates | ||
| design/greeter | ||
| dev | ||
| dist | ||
| docs | ||
| greeter | ||
| nix | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| flake.lock | ||
| flake.nix | ||
| LICENSE | ||
| PLAN.md | ||
| README.md | ||
| rustfmt.toml | ||
| ZEUS-TESTING.md | ||
mattwm
A Wayland compositor (Rust, Smithay) with qtile/xmonad-style workspaces, scrolling, master/stack and Openbox-style floating layouts, and ultimus as its shell. It ships its own desktop portal, where yazi is the file chooser and screen sharing gets a live-preview picker.
PLAN.md has the design, the decisions and the milestones; docs/config.md is the configuration reference.
Status
| Milestone | State |
|---|---|
| M0: the nested dev loop | Done. |
| M1: yazi file chooser portal | Done. Works under any compositor. |
| Test VM | Done. nix run .#vm; see Testing. |
| M2: runs on real hardware | Done. DRM/KMS on a TTY, multiple monitors, master/stack, max and floating layouts, qtile-style workspaces, Lua config with hot reload, layer-shell (bars, launchers), linux-dmabuf, screen capture for grim. |
| M3: IPC and bars | Done. mattwmctl and a JSON IPC, ultimus running on mattwm (branch mattwm-backend of ultimus), and the standard workspace and window-list protocols for other bars. |
| M4: qtile parity | Done. Scrolling layout (niri style, optionally centred), qtile-style scratchpads, window rules (late titles too), Lua hooks on window and workspace events. |
| M5: daily-drivable | Built, tested in the VM; real monitors still to try. Screen lockers (ext-session-lock: ultimus's lock, swaylock, hyprlock), idle daemons (ext-idle-notify) and inhibitors, monitor power (mattwmctl dpms, wlr-output-power-management), hotplug memory, media keys that work on the lock screen. |
| M6: screen sharing | Built, tested in the VM. The portal's ScreenCast and Screenshot (with PickColor), a share picker where every monitor and window is a live preview, PipeWire streams made by mattwm itself (the pointer drawn in or sent as metadata), "always allow" restore tokens, a sharing indicator, and stopping a share from mattwm ends the app's session. |
| M7: Openbox floating | Built, tested in the VM. Titlebars drawn by mattwm (minimize, maximize and close dots; scroll to shade), resizing from any edge, snapping (moves and resizes), edge tiling with a preview, keyboard move and resize, per-app geometry memory, a right-click root menu with submenus and an applications menu (drawn by ultimus if you like), a window menu on the titlebar. |
| M8: effects | Built, tested in the VM. Rounded corners, rounded borders, soft shadows, open, move and close animations, sliding workspace switches, wallpaper blur behind see-through windows and bars; all optional. |
| M9: themes | Built, tested in the VM. ultimus's themes (its gallery and matugen palettes) restyle mattwm, its portal's dark/light and accent (GTK4, Qt) and the share picker live, through one exported file. A new lock screen is still open. |
| M10: release prep | Built, tested in the VM. X11 apps through xwayland-satellite (on demand), a non-Nix install script, the configuration reference, the GPL-3.0 licence. Not yet tested on NVIDIA or real hardware at all, and not published. |
Installing
NixOS (the flake):
# flake inputs
mattwm.url = "git+file:///path/to/mattwm"; # or the published repo
# configuration.nix
imports = [ inputs.mattwm.nixosModules.default ];
programs.mattwm = {
enable = true;
portal.enable = true;
};
homeManagerModules.default adds programs.mattwm.extraConfig (written to
nix.lua) and the portal's settings.
Other distros: build it and run the install script.
cargo build --release --workspace
sudo dist/install.sh # into /usr/local; `dist/install.sh /usr` for /usr
Build dependencies: Rust 1.89 or newer, pkg-config, clang (for
PipeWire's bindings), and the development files of libinput, libxkbcommon,
wayland, libseat (seatd), mesa (libgbm, EGL), libdrm, libdisplay-info,
libudev and PipeWire. On Arch: libinput libxkbcommon wayland seatd mesa libdrm libdisplay-info pipewire clang. On Fedora: the same names with
-devel, plus systemd-devel; on Debian and Ubuntu, lib…-dev.
At runtime it wants xwayland-satellite for X11 apps, and the portal wants
yazi and a terminal (file dialogs) and quickshell (the share picker).
Running it
- From a display manager: pick the "mattwm" session (the package ships
share/wayland-sessions/mattwm.desktop). - From a TTY:
mattwm. - Inside another session (for development):
mattwmopens as a window, with Alt as the modifier since the outer desktop keeps Super. mattwm -c footalso starts a command. Ctrl+Alt+F1–F12 always switch VTs.- X11 apps run through xwayland-satellite, which mattwm starts only when
the first X app connects (
DISPLAYis set from the start). - NVIDIA: untested so far. mattwm needs a GBM-capable driver (the proprietary one's GBM support, or nouveau).
Configuring
~/.config/mattwm/, reloaded every time you save a file there. The first
time mattwm starts it writes its default config into that folder, and from
then on the folder is the whole config: nothing is built in underneath, so
the keys you see in binds.lua are the keys there are, and you drop one by
deleting its line. A broken config never replaces a working one: the error
is logged (and mattwmctl reload prints it, file and line) and the running
config stays.
init.lua only requires the others, which are plain Lua and can be moved
around, split further or merged back into one file. Much of what mattwm
does is in them too, not only what it's set to: the layouts, the
floating keys, the window menu and the titlebar are Lua over a small API
(readers like get_focused() and actions like set_frame), so changing how
they behave is a save, with every window still open:
| File | Holds |
|---|---|
init.lua |
the list of the others |
apps.lua |
the terminal and launcher the rest start |
layouts.lua |
monadtall, monadwide and max, as Lua you can change, and room for your own |
settings.lua |
every mattwm.set setting, commented out at its default; the keyboard, the layout cycle, the workspaces |
monitors.lua |
positions, modes and scales (examples) |
rules.lua |
the file dialog's rule, and every key a rule can take |
scratchpads.lua |
the terminal scratchpad, and every key a scratchpad can take |
floating.lua |
what the floating keys do: tiling to halves and quarters, moving and resizing a step |
binds.lua |
every key binding, a list of every action, and the readers your own functions can use |
menu.lua |
the right-click desktop menu, the window menu, and what titlebar clicks and scrolls do |
autostart.lua |
programs started with the session (examples) |
hooks.lua |
Lua run on window, workspace and monitor events, and where new windows go and focus after a close (examples) |
The same files are in the repo at
crates/mattwm/src/config/default/, and
mattwm --default-config DIR writes a fresh copy, to compare with yours
after an upgrade. With no init.lua at all, mattwm runs that default from
inside the binary. docs/config.md is the full reference.
The default keys (mod is Super, or Alt when nested):
| Keys | Does |
|---|---|
| mod+Return / mod+d | terminal ($TERMINAL, else kitty) / fuzzel |
| mod+q, mod+f, mod+shift+f | close, fullscreen, float |
| mod+h/j/k/l, mod+space | focus left/down/up/right (across monitors), next |
| mod+shift+h/j/k/l, mod+shift+Return | move the window that way, swap with master |
| mod+ctrl+h/l, mod+ctrl+j/k, mod+ctrl+n | resize in the stack, master ratio, reset |
| mod+Tab, mod+shift+m | next layout (monadtall → scrolling → max → floating), max |
| mod+n | the terminal scratchpad (kitty, foot or alacritty) |
| mod+[ / mod+] / mod+\, mod+r | scrolling: pull the window into the column left / right, give it its own column, cycle column width |
| mod+1–9, mod+shift+1–9 | show workspace here (swapping, like qtile), move window there |
| alt+Tab, alt+shift+Tab | next/previous free workspace |
| mod+i / mod+o, mod+period / mod+comma | focus monitor 1 / 2, next / previous |
| mod+shift+period / comma | move window to the next / previous monitor |
| mod+drag, mod+right-drag | move, resize (the window floats) |
| mod+alt+h/j/k/l, mod+alt+shift+h/j/k/l | floating: move a step, resize (right/down grow) |
| mod+arrows | floating: tile like a drag to that edge (a half, then a quarter of it; up maximizes; back the way it came restores) |
| mod+s, mod+alt+f | floating: shade (roll up), maximize |
| mod+shift+r, mod+shift+x | reload config, quit |
On NixOS, homeManagerModules.default has programs.mattwm.extraConfig,
written to nix.lua, which loads before your init.lua (so where the two
bind the same key or set the same setting, yours wins).
Scripting: mattwmctl and the IPC
mattwm listens on $MATTWM_SOCKET, which it sets for everything it starts.
mattwmctl workspaces # * focused, @OUTPUT where each is shown
mattwmctl windows # ids, workspaces, app ids, titles
mattwmctl outputs
mattwmctl do greedy_view 3 # any action, as words
mattwmctl do spawn foot
mattwmctl do focus_window 12
mattwmctl dpms off # monitors off (on, toggle; add DP-2 for one)
mattwmctl cast output DP-1 # a PipeWire stream; prints its node, runs until ^C
mattwmctl do stop_cast # stop every screen share (the bar sees them in `casts`)
mattwmctl pick # click a pixel anywhere: prints #rrggbb
mattwmctl reload # prints the error if the new config is broken
mattwmctl events # a line per change (--json for the full state)
The protocol is JSON, one message per line (crates/mattwm-ipc documents
it). Send "state", {"do": ["greedy_view", "3"]}, {"action": ...} or
"reload_config" and get one reply line. Send "event_stream" and the
connection streams the whole state, again on every change.
Floating windows (Openbox style)
Floating windows (in the floating layout, or floated in any other) get a titlebar mattwm draws: the window's own background, the title centred, and three dots at the right (minimize, maximize, close) that show what they do while the pointer is on the bar:
- Drag the titlebar to move, any edge or corner to resize (or
mod+drag and mod+right-drag from anywhere in the window). Moves snap to
monitor edges and other windows within
snap_distance. - Drag to a monitor's edge to tile: left or right half, a quarter at a corner, maximized at the top. A faint preview shows where it'll go; dragging it away again gives it back its old size. mod+arrows do the same from the keyboard: left or right for a half, then up or down within it for a quarter, up from a free window to maximize, and the opposite arrow to put the window back where it was.
- Double-click the titlebar to maximize or restore; scroll on it to roll the window up (shade) and down.
- A floating workspace moved to a monitor of another size keeps its shape: each window is scaled to the new monitor (position, and size if you set one) and kept on it, so halves stay halves. Back on the monitor it was arranged on, everything returns exactly where it was; moving or resizing a window makes where it is now its new home.
- Each app's last floating size and place is remembered
(
~/.local/state/mattwm/floating.json) for its next window, and new windows cascade rather than cover each other. - Right-click the desktop for the root menu (
mattwm.menu); arrows or hjkl and Enter work too, Esc closes it.
mattwm.set {
titlebars = true, -- false: floating windows get borders only
titlebar_height = 34,
font = "/path/to/font.ttf", -- default: fontconfig's "sans"
font_size = 13,
titlebar_active = "#1e1e2e", titlebar_inactive = "#1e1e2e", -- the bar
titlebar_text = "#cdd6f4", titlebar_text_inactive = "#6c7086", -- says which has focus
titlebar_close = "#e0828f", -- the close dot
snap_distance = 12, -- 0 turns snapping off
edge_tiling = true,
move_step = 32, -- keyboard move/resize, in pixels
root_menu = "builtin", -- "shell": your bar draws it (IPC event); "off"
}
mattwm.menu {
{ "Terminal", mattwm.lazy.spawn("kitty") },
{ "Browser", mattwm.lazy.spawn("firefox") },
"-",
{ "Lock", mattwm.lazy.spawn("swaylock -f") },
{ "Exit mattwm", mattwm.lazy.quit() },
}
Themes
Themes come from ultimus, which is already the desktop's theme hub (21
palettes, a gallery, matugen palettes from wallpapers, exports for kitty,
GTK, neovim, btop and more). Its mattwm export target writes
~/.config/mattwm/theme.json, and three things follow it live:
- mattwm: borders, background, titlebars and the menu. The theme loads
between
nix.luaandinit.lua, so your own settings still win. - The portal's Settings: dark or light, and the accent colour, for
GTK4/libadwaita and Qt apps (routed as
Settings=mattwm;gtkunder mattwm). - The share picker: its colours.
Turn it on in ultimus under Theme → Export to other programs (or add
[[theme.exports]] enabled = true, target = "mattwm" to its config). Any
other tool can write the same file: a mode ("dark"/"light") and
ultimus's twelve roles (bg, bgAlt, surface, fg, muted, outline,
accent, accent2, accent3, success, warning, error).
Effects
All optional, and damage-tracked, so a still desktop costs nothing:
mattwm.set {
corner_radius = 8, -- 0: square
shadows = true, -- under floating windows
shadows_tiled = false, -- tiled ones too
shadow_size = 20,
shadow_color = "#00000073",
animations = true, -- windows fade in and glide when they move
animation_ms = 180,
}
Locking, idle and monitor sleep
mattwm speaks the standard protocols, so the usual tools work unchanged:
- Lockers: ext-session-lock (mattwm-lock, ultimus's lock, swaylock,
hyprlock). Once a locker asks, nothing else is drawn or gets input, and
the locker hears "locked" only after every lit monitor shows it. If the
locker crashes, the screen stays black and locked until a new locker takes
over; with
locker = "mattwm-lock"set, mattwm starts it again itself (up to three times), and it never unlocks on its own. - Idle daemons: ext-idle-notify (hypridle, swayidle). Apps holding an idle inhibitor (video players) keep the session awake while they're on screen.
- Monitor power: wlr-output-power-management (
wlopm, idle daemons) andmattwmctl dpms off|on|toggle [OUTPUT]blank and relight monitors. Any key, click or pointer movement lights them again. - Hotplug memory: a monitor that drops off (DisplayPort monitors do it going to sleep) is kept, with its workspace, for a few seconds in case it comes back, and then it's not the end: each monitor's last workspace is remembered by make, model and serial, so it gets it back on any connector.
A swayidle setup, for example:
swayidle -w timeout 300 'swaylock -f' \
timeout 330 'mattwmctl dpms off' \
before-sleep 'swaylock -f'
mattwm.set {
idle_inhibit_fullscreen = false, -- a fullscreen window keeps the session awake
wake_on_input = true, -- input relights monitors turned off
hotplug_grace = 3, -- seconds a monitor that dropped off is kept
}
Login and lock screen
mattwm has its own login screen and lock screen: one screen, two jobs. It shows the theme and wallpaper the session last had, blurred and darkened, with the clock cut out of it so the sharp picture shows through the numerals; the date and a prompt run along the bottom. It's keyboard-driven:
| Key | |
|---|---|
| any key | starts typing (the key is the first character) |
Enter |
sign in / unlock |
Esc |
clear, back to the clock |
Tab |
next session (login) |
F2 |
next user (login, when there's more than one) |
F12 |
power menu (↑↓ Enter, or s r p f); the lock offers suspend only |
Ctrl+Alt+F2... |
a text console, always |
On NixOS:
programs.mattwm = {
greeter.enable = true; # greetd + the login screen; turns SDDM off
lock.enable = true; # mattwm-lock and /etc/pam.d/mattwm-lock
};
Switch to the login screen with nixos-rebuild boot and a reboot, not
switch: stopping the old display manager ends the running session.
How it fits together:
-
greetd does the PAM conversation and starts the session; the login screen only answers greetd's questions, so it never touches PAM. Sessions are the system's (
services.displayManager.sessionPackages); each one is started throughmattwm-session-run, which keeps its output in~/.local/share/mattwm/session.log(and the one before as.old). -
mattwm --greeteris the compositor under it: no user config, no key bindings (only VT switching), no Xwayland, no IPC; the monitors laid out as the last session had them; dark after two idle minutes. -
mattwm-greeter-sync, a user service, saves the session's look to/var/lib/mattwm-greeter/users/$USER/(yours to write, the greeter's to read): the palette and clock formats from the running session's ultimus config ([lock] clockFormat, a Qt format:HH:mmfor 24-hour,h:mm APfor 12-hour, shown without the AM/PM), each monitor's wallpaper as awww shows it plus a blurred copy, and the monitor layout. It saves on every change and once more at logout. Which ultimus config a session's look comes from is~/.config/mattwm/greeter.toml:face = "window" # how the login and lock screens look [look_from] mattwm = "~/.config/ultimus-mattwm/config.toml" Hyprland = "~/.config/ultimus/config.toml" -
mattwm-lockis the same screen on ext-session-lock, checking the password through/etc/pam.d/mattwm-lock. One runs at a time. Point your idle daemon at it (lock_cmd = mattwm-lock && loginctl unlock-sessionfor hypridle) and setlocker = "mattwm-lock". -
If the login screen fails to start, tuigreet comes up on the same VT instead (
journalctl -b -t mattwm-greetersays why).
The screen is QML (greeter/): a controller that owns the states, the keys
and the greetd/PAM conversation, and faces that only draw
(greeter/faces/). Window is the first; design/greeter/mockups.html has
three more to come. Work on a face without greetd or a lock:
MATTWM_GREETER_MODE=preview MATTWM_GREETER_DIR=/path/with/users/$USER/look.json \
quickshell -p greeter/shell.qml # any password but "fail" works; Ctrl+Q quits
Screen sharing and screenshots
With the portal set up (below), apps that share the screen (browsers, OBS, Discord, video calls) and apps that take screenshots go through mattwm:
- The share picker shows every monitor and every window as a live preview. Arrows or hjkl move, Enter shares, Tab switches between monitors and windows, Space marks several (when the app allows it), r ticks "always allow", Esc cancels. With "always allow", the app gets that monitor (or that same window, if exactly one window has its app and title) without asking next time.
- mattwm makes the PipeWire stream itself: zero-copy dmabufs when the app takes them, shared memory otherwise. A shared window keeps streaming while its workspace is hidden. Nothing new is drawn while the screen is locked: a shared monitor shows the lock screen, a shared window pauses.
- Screenshots: a plain request captures every monitor as laid out (the
portal frontend asks you once whether the app may); an interactive one
shows the picker. They're saved in
$XDG_RUNTIME_DIR/mattwm-portal/screenshots. - The picker is a standalone Quickshell file
(dist/share-picker/shell.qml), so it needs
quickshellbut not ultimus. - Live window previews work in any Quickshell config: mattwm speaks
wlr-foreign-toplevel-management and hyprland-toplevel-export, which is
what Quickshell's
ScreencopyViewcaptures windows with.
Bars
- ultimus runs on mattwm from its
mattwm-backendbranch. It notices$MATTWM_SOCKETand takes workspaces, windows, the layout and actions from the IPC; under Hyprland nothing changes. - Other bars get
ext-workspace-v1(waybar'sext/workspaces, for example),ext-foreign-toplevel-list(window lists,lswt) and wlr-foreign-toplevel-management (waybar'swlr/taskbar). mattwm's workspaces are one pool shared by every monitor, so a bar sees one group with all of them, and the ones on a monitor are active. Clicking one pulls it onto the monitor you clicked on. - Bars, launchers and screen capture aren't offered to sandboxed (Flatpak) apps.
Development
nix develop # Rust, clippy, yazi, tmux, dbus, the portal frontend
cargo run -p mattwm # nested mattwm, running $TERMINAL (or kitty)
cargo run -p mattwm -- -c foot # ...or something else
cargo test --workspace # unit tests + portal end-to-end tests
cargo clippy --workspace --all-targets
The portal's end-to-end tests (crates/xdg-desktop-portal-mattwm/tests/e2e.rs)
run real yazi in a headless tmux on a private D-Bus bus that can't activate
anything, and drive it with keystrokes. One of them goes through the real
xdg-desktop-portal frontend, using the .portal and portals.conf files in
dist/. Nothing touches your session. The Nix build skips them (no tmux or
D-Bus in the sandbox).
Smithay is pinned to a git revision in Cargo.toml (master has protocols that
0.7.0 lacks).
Testing
There are three tiers, from fastest to most real:
- Nested (
cargo run -p mattwm): mattwm as a window in your desktop. This is the loop for layouts, keybinds and config. - The test VM (
nix run .#vm, from the repo root): a clean NixOS that your system config never sees. It boots to sway on tty1 (Alt is the modifier, Alt+Return is a terminal), with the portal routed for sway, and Firefox, zenity and gnome-text-editor for real file dialogs. The repo is mounted at/mattwmand the host's Nix store is shared, so aftercargo buildon the host,mattwm-devin the VM runs that build. Root is a tmpfs: every boot starts clean.MATTWM_VM_HEADS=4 nix run .#vmgives it four virtual monitors.dev/vm-headless,dev/vm-shanddev/vm-keyrun it with no window and drive it from scripts (screenshots viagriminto/mattwm/.vm/).dev/vm-headless --mattwmboots straight into your build of mattwm instead of sway; withMATTWM_VM_HEADS=2it gets two monitors.dev/vm-mouse to:X,Y down to:X,Y up click rclick scroll:updrives the pointer, through a uinput tablet in the VM (start it once withdev/vm-sh 'sudo -b vm-pointer'): QEMU's own pointer input doesn't reach a headless guest.
- Real hardware, last: monitor sleep, monitors dropping off DisplayPort, VRR, performance and GPU quirks only show up there.
The portal
xdg-desktop-portal-mattwm implements org.freedesktop.impl.portal.FileChooser
(under any compositor) and, under mattwm, ScreenCast and Screenshot (see
Screen sharing above).
The file chooser
When an app asks for a file dialog, yazi opens in a terminal with your own yazi config (theme, plugins, keys) plus a few picker keys:
| Dialog | Keys |
|---|---|
| Open | Enter picks the file under the cursor, or goes into a folder. In "several files" dialogs, Space selects, then Enter picks the selection. |
| Choose folder | Enter chooses the folder under the cursor; l goes into it; Ctrl+S chooses the folder you're in (or the selected folders). |
| Save | Ctrl+S asks for the name (pre-filled with the app's suggestion) and saves in the folder you're in. Enter goes into a folder, replaces an existing file after asking, and in an empty folder saves there like Ctrl+S. |
| Save several | Ctrl+S saves them all in the folder you're in; so does Enter anywhere but on a folder. |
a (or any key your keymap binds to create, such as create --dir) makes
a file, or a folder if the name ends in /, as in yazi, and puts the cursor on
it, so Enter right after chooses a new folder or goes into it.
yazi's other "open" keys (o, O, Shift+Enter, and any key your
own keymap binds to open) pick too. Esc (or q) cancels. If yazi has
something of its own going (a find, visual mode, a selection, a filter you
typed, a search), Esc backs out of that first, one per press, and cancels once
there's nothing left. When the app gives a file-type filter (say, images), only
matching files and folders are shown; F shows everything in that folder.
Each app's next dialog starts where its last one ended.
The portal needs XDG_RUNTIME_DIR (systemd sets it); the dialog's scratch
files live in $XDG_RUNTIME_DIR/mattwm-portal, never in /tmp.
The picker window's app id is mattwm-picker, so a window rule can float and
size it (in Hyprland: match class:^(mattwm-picker)$).
Configuration
~/.config/mattwm/portal.toml, all optional:
[file_chooser]
# The terminal yazi runs in. "{title}" becomes the dialog title; yazi's
# command line goes after the last element. Default: the first of kitty,
# foot, alacritty, wezterm or ghostty on PATH ($TERMINAL wins if it's one).
terminal = ["kitty", "--class", "mattwm-picker", "--title", "{title}", "-e"]
yazi = "yazi"
# Colour yazi from the current theme (~/.config/mattwm/theme.json, which
# ultimus rewrites on every theme change) instead of your own yazi flavor.
# Each dialog writes a "mattwm" flavor from it; your theme.toml's other
# settings still apply. Without a theme file yazi keeps your flavor. An
# open dialog repaints when the theme changes (see live-flavor below).
follow_theme = true
[share_picker]
# What shows the share and screenshot picker. Default: quickshell running
# the picker the package installs (share/mattwm/share-picker/shell.qml).
command = ["quickshell", "-p", "/path/to/share-picker/shell.qml"]
yazi outside the dialog
dist/yazi/live-flavor.yazi (installed as
share/mattwm/yazi/live-flavor.yazi) makes an open yazi repaint within a
second when the flavor its theme.toml chooses is rewritten, as ultimus's
yazi theme export does on every theme change. Link it into
~/.config/yazi/plugins/ and add require("live-flavor"):setup() to yazi's
init.lua. The main view, file names and icons follow; yazi's popups
(input, which-key, help, tasks) keep their colours until it restarts. The
file dialog uses the same plugin on its own flavor.
NixOS
# flake inputs
mattwm.url = "git+file:///path/to/mattwm"; # or the published repo
# configuration.nix
imports = [ inputs.mattwm.nixosModules.default ];
programs.mattwm.portal = {
enable = true;
fileChooserFor = [ "hyprland" ]; # desktops whose dialogs become yazi
};
fileChooserFor writes <desktop>-portals.conf routing FileChooser to
mattwm (and, for the mattwm desktop itself, ScreenCast and Screenshot too), and keeps that desktop's usual default (for Hyprland,
hyprland;gtk) so its other portals keep working. The Home Manager module
(homeManagerModules.default) has the same options plus
programs.mattwm.portal.settings for portal.toml.
Other distros
cargo build --release -p xdg-desktop-portal-mattwm
sudo dist/install-portal.sh /usr/local
It prints the portals.conf lines to add for your desktop.
Licence and credits
mattwm is free software under the GNU GPL, version 3 or later
(LICENSE). Its PipeWire screen-casting code follows
niri's (GPL-3.0-or-later), and niri was
the reference for much else. It's built on Smithay,
and it vendors the hyprland-toplevel-export-v1 protocol description
(BSD-3-Clause, © Vaxry) for Quickshell's window previews.