A fully functional wayland compositor that uses the ultimas shell and xdg-desktop-portal-mattwm
  • Rust 83.9%
  • HTML 5.1%
  • Lua 3.9%
  • QML 3.5%
  • Nix 2.3%
  • Other 1.3%
Find a file
Matthew Weber 43a5270a1c greeter: a 12-hour clock, without the AM/PM on the numerals
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>
2026-11-19 13:57:37 -05:00
.impeccable Design-checker ignores for the titlebar mockup (depicted UI, not page design) 2026-11-16 02:32:50 -05:00
crates greeter: package, NixOS options, and the greetd test VM 2026-11-19 03:05:18 -05:00
design/greeter docs: the login and lock screen (README), and the plan's as-built notes 2026-11-19 03:08:39 -05:00
dev greeter: package, NixOS options, and the greetd test VM 2026-11-19 03:05:18 -05:00
dist greeter: package, NixOS options, and the greetd test VM 2026-11-19 03:05:18 -05:00
docs Window policy hooks: place, refocus, the window menu, the titlebar 2026-11-16 22:12:00 -05:00
greeter greeter: a 12-hour clock, without the AM/PM on the numerals 2026-11-19 13:57:37 -05:00
nix greeter: package, NixOS options, and the greetd test VM 2026-11-19 03:05:18 -05:00
.gitignore mattwm: nested compositor, yazi file chooser portal, test VM 2026-11-14 01:23:26 -05:00
Cargo.lock greeter: mattwm --greeter, mattwm-greeter-sync, and the Window login/lock screen 2026-11-19 02:34:44 -05:00
Cargo.toml greeter: mattwm --greeter, mattwm-greeter-sync, and the Window login/lock screen 2026-11-19 02:34:44 -05:00
flake.lock mattwm: nested compositor, yazi file chooser portal, test VM 2026-11-14 01:23:26 -05:00
flake.nix greeter: package, NixOS options, and the greetd test VM 2026-11-19 03:05:18 -05:00
LICENSE M10: release prep (Xwayland, licence, install, docs) 2026-11-14 13:03:41 -05:00
PLAN.md The config is a folder of modules, with nothing built in underneath 2026-11-16 01:48:08 -05:00
README.md greeter: a 12-hour clock, without the AM/PM on the numerals 2026-11-19 13:57:37 -05:00
rustfmt.toml mattwm: nested compositor, yazi file chooser portal, test VM 2026-11-14 01:23:26 -05:00
ZEUS-TESTING.md The config is a folder of modules, with nothing built in underneath 2026-11-16 01:48:08 -05:00

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): mattwm opens as a window, with Alt as the modifier since the outer desktop keeps Super.
  • mattwm -c foot also 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 (DISPLAY is 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.lua and init.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;gtk under 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) and mattwmctl 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 through mattwm-session-run, which keeps its output in ~/.local/share/mattwm/session.log (and the one before as .old).

  • mattwm --greeter is 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:mm for 24-hour, h:mm AP for 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-lock is 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-session for hypridle) and set locker = "mattwm-lock".

  • If the login screen fails to start, tuigreet comes up on the same VT instead (journalctl -b -t mattwm-greeter says 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 quickshell but 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 ScreencopyView captures windows with.

Bars

  • ultimus runs on mattwm from its mattwm-backend branch. It notices $MATTWM_SOCKET and takes workspaces, windows, the layout and actions from the IPC; under Hyprland nothing changes.
  • Other bars get ext-workspace-v1 (waybar's ext/workspaces, for example), ext-foreign-toplevel-list (window lists, lswt) and wlr-foreign-toplevel-management (waybar's wlr/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:

  1. Nested (cargo run -p mattwm): mattwm as a window in your desktop. This is the loop for layouts, keybinds and config.
  2. 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 /mattwm and the host's Nix store is shared, so after cargo build on the host, mattwm-dev in the VM runs that build. Root is a tmpfs: every boot starts clean.
    • MATTWM_VM_HEADS=4 nix run .#vm gives it four virtual monitors.
    • dev/vm-headless, dev/vm-sh and dev/vm-key run it with no window and drive it from scripts (screenshots via grim into /mattwm/.vm/). dev/vm-headless --mattwm boots straight into your build of mattwm instead of sway; with MATTWM_VM_HEADS=2 it gets two monitors.
    • dev/vm-mouse to:X,Y down to:X,Y up click rclick scroll:up drives the pointer, through a uinput tablet in the VM (start it once with dev/vm-sh 'sudo -b vm-pointer'): QEMU's own pointer input doesn't reach a headless guest.
  3. 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.