mesh-catalog/modules/i3

i3

The window manager as a module (novox/hq ADR 0208, research 026, to-be 42 phase 2, step 4).

• Claims node-display-session and serves its verbs reload, workspaces and windows.
• Requires x11-display, which only xorg on the same machine provides.
• Packages: i3-wm, and dex, which the configuration has always run for XDG autostart. dex was missing on the desktop, so its autostart entries never started there.
• Environment (ADR 0203): XDG_CURRENT_DESKTOP=i3 and XDG_SESSION_DESKTOP=i3. They reach shells, the session (through xorg's block) and the user manager (environment.d). The portal keys off the first.
• Session code (ADR 0208 §4): exec i3 --shmlog-size=26214400 in the xinitrc slot last. That is the end of xorg's block in ~/.xinitrc.

What it owns

path	class (ADR 0182)	what
~/.config/i3/	owned directory (move-out)	what the module declares, and scripts/ (named in knows: the screenshot binding in the main file runs scripts/screenshot.sh, kept until its owner exists); any other file is moved out by the node-engine to ~/.local/state/mesh-moved/i3/ with a list, never deleted (ADR 0422 §4)
~/.config/i3/config.d/	owned directory (move-out)	what the module declares, and 10-asus.conf and 20-g14.conf (named in knows, kept until the laptop's hardware module exists); any other file is moved out by the node-engine to ~/.local/state/mesh-moved/i3/ with a list, never deleted (ADR 0422 §4)
~/.config/i3/config	owned (the found file kept once)	the main configuration, from files/config
/etc/lemurs/wms/i3	owned	the login manager's session entry: exec systemd-cat -t x-session /bin/sh "$HOME/.xinitrc", the session's output in the journal (journalctl -t x-session) because the login manager's pipe has no reader

Drop-ins. ~/.config/i3/config.d/ holds what this module declares and the files named in knows; a file of yours put there is moved out (ADR 0422). The include is the last line of the main file, so every variable set there ($mod, $ws1…$ws10) is in scope. Files are read in name order.

The reload watcher

The bundle runs the watcher for as long as the runtime runs it (ADR 0198). It replaces the predecessor's i3-reload-watcher script and its user unit, so this needs no user-scoped unit:

• every 2 s it looks at config and config.d/*.conf (size and time);
• at its start, if the files differ from what the running i3 loaded, that counts as a change;
• after a change, once the files have been still for one more interval, it checks the result with i3 -C;
• it reloads only a configuration without errors. Otherwise it keeps the running one and records the errors.

What it has done is in the answers of reload and i3_config_check. It polls rather than using inotify, so a file replaced by rename and a directory created later are seen without a fresh watch. It reloads i3 only. Re-running the bar, the compositor and the notifier is each of those modules' own business.

Tools

tool		what
node-display-session.reload	a	checks, then reloads, keeping windows. Refused with the errors when the check fails; force reloads anyway
node-display-session.workspaces	r	number, name, output, visible, focused, urgent
node-display-session.windows	r	container id, X id, class, instance, role, title, workspace, output, focused, urgent, floating, fullscreen, scratchpad, marks; narrowed to one workspace
i3_focus	d	a window by criteria, or a workspace
i3_move	d	windows to a workspace or output; a workspace to an output
i3_layout_save	d	a workspace's arrangement as a named layout of placeholders (class, instance, role), in ~/.local/state/mesh/i3/layouts/
i3_layout_restore	d	lays a saved layout back; name: list lists them
i3_exec	d	starts a program as i3's child, optionally on a workspace
i3_kill	d	closes the matching windows, or the focused one when asked; with no arguments it closes nothing
i3_bindings	r	every binding by mode, with its command and file, from what i3 loaded
i3_config_check	r	i3 -C on the files on disk (errors with file and line), the files i3 loaded, the watcher's record
i3_marks	r	each mark and its window
i3_scratchpad	r/d	list, show or move into the scratchpad

The tools speak i3's IPC on its socket in the account's runtime directory, and need no display. Every value a caller gives is quoted before it reaches an i3 command. With no i3 running, the answer is {"error": "no-graphical-session", …}. The bundle's binary is i3-tools, so nothing that looks for i3 by name finds it.

What it improves over today's configuration

Both workstations ran the same configuration. These changes are against it:

• dead: exec lxpolkit (installed on neither machine), the unused $refresh_i3status, and the predecessor's rice_set comment;
• duplicates:
  • exec xdg-desktop-portal (it is D-Bus activated);
  • exec xrdb -merge ~/.Xresources (xorg's session start merges it);
  • the picom, nm-applet, blueman-applet and nextcloud execs. Each also has an XDG autostart entry that dex starts, and both machines carry those entries;
• font: JetBrainsMono Nerd Font 11 for titles, replacing Hack (research 026/04);
• terminal: $mod+Return runs i3-sensible-terminal, which starts whatever $TERMINAL names (the terminal module's contribution), instead of naming xterm;
• reloads: the watcher never reloads into a broken configuration.

Moved to their own modules' drop-ins (the companion modules of research 026). These leave this file because each module carries them now:

lines	now in
the launcher bindings ($mod+d, $mod+t, $mod+Shift+t) and the power menu ($mod+Escape)	rofi's 50-rofi.conf, which also adds $mod+Shift+w
the greenclip daemon and its menu ($mod+period)	clipmenu's 50-clipmenu.conf and its session line
the wallpaper key ($mod+Shift+b)	feh's 50-feh.conf
both bars	i3status-rust's 60-i3status-rust.conf
the keyring prompt (unlock-keyring.sh)	gone: gnome-keyring unlocks the keyring through PAM at login
the peripherals' tray (exec … polychromatic-tray-applet)	polychromatic's contribution to node-display-session

The theme picker ($mod+Shift+d) goes too. It was the predecessor's tool for its theme variables, and settings take its place once issue 168 closes. $mod+Delete (loginctl lock-session) stays here, because screen-lock relies on it. The test TestTheMainFileAndEveryModulesDropInLoadTogether loads this file with every catalogue module's drop-in through i3 -C, so no two of them bind one key.

Kept until their owners exist. A marked section holds the operator's own scripts: volume, games volume, the sessions launcher and the screenshot binding. Each leaves when the module that owns it is written. The peripherals' tray applet left it for the polychromatic module.

What it keeps, and what it moves out

Kept, because they work for the operator today: ~/.config/i3/scripts/ (the screenshot binding runs scripts/screenshot.sh), and config.d/10-asus.conf and 20-g14.conf, each until its owner exists. Both are named in knows. Anything else in ~/.config/i3/ (such as unlock-keyring.sh) or in config.d/ is moved out by the node-engine to ~/.local/state/mesh-moved/i3/ with a list, never deleted (ADR 0422 §4). Left alone, outside the folders: the /usr/share/xsessions entries (the package's, no longer offered by lemurs), and i3's restart state and logs.

The one-off migration (ADR 0182)

1. Before the push that assigns i3: do xorg's migration (its README). From that push on, your lines below xorg's block in ~/.xinitrc no longer run.
2. Disable the predecessor's watcher: systemctl --user disable --now i3-reload-watcher.service. Then remove ~/.config/systemd/user/i3-reload-watcher.service and ~/scripts/i3-reload-watcher. One thing reloads i3 now. Kept running, it would also i3-msg restart on every change, without checking first. Keep i3-bar-watchdog.service as it is: the bar is i3status-rust's, and that module decides.
3. Delete /etc/lemurs/wms/i3wm (see lemurs).
4. config.d/ fragments:
   • 10-asus.conf and 20-g14.conf (the laptop) belong to that machine model's hardware module. They are named in knows, so they stay until it exists. The desktop no longer carries them.
   • 50-slack.conf is not an i3 file: the Slack rule is dunst's (dunstrc.d, see dunst).
   • 99-tmp-wine-focus.conf (the desktop), a test of a predecessor change by its own comment, is moved out at the first look with a list; nothing is lost.
5. The main file's predecessor copy is kept once by the host and written over. Nothing to do.

What changes when it is assigned

	g14	shanks
packages	none (i3-wm and dex present)	dex installed
~/.config/i3/config	written: the improved configuration	the same
running i3	the watcher reloads it once the file changes. i3 keeps every window, and the title font becomes JetBrains Mono. Assigned without rofi, clipmenu, feh and i3status-rust, the reload takes away the bars and those keys until they are assigned too, so assign them in the same push. The dropped duplicate execs end nothing that runs	the same
/etc/lemurs/wms/i3	new: offered as i3 at the next boot	the same
~/.xinitrc	xorg's block now ends in exec i3: the lines below it stop running at the next login	the same
~/.config/environment.d/50-mesh.conf, environment.sh	gain XDG_CURRENT_DESKTOP=i3, XDG_SESSION_DESKTOP=i3	the same. Its user manager lacked them, and gets them at the next login
next login	XDG autostart as before	XDG autostart runs for the first time: Slack, JetBrains Toolbox, Nextcloud, the FortiClient tray, the print applet, the geoclue demo agent and snap's user daemon start from their entries

One reload on assignment is the one live change. To avoid it, assign during a session you are about to end, or accept it: a reload keeps every window and workspace.

Blockers

• fonts first (to-be 42 orders it first). Without ttf-jetbrains-mono-nerd, i3's titles and i3status-rust's bars fall back to pango's default face. On 2026-10-04 the laptop had the package, and the desktop only a hand-copied file of the face.
• None for the watcher. The runtime restarts with every push that changes it, after the push has written the files. So at its start the watcher compares the files on disk with what the running i3 loaded (GET_CONFIG), and reloads when they differ. The push that assigns i3, or changes its configuration, is therefore reloaded although it also restarted the watcher.

Other modules' lines are contributions (changed 2026-10-05, novox/hq ADR 0212)

node-display-session receives config contributions, and this module places them with ${contribution:node-display-session:config} near the end of its configuration, each module's under a line naming it. ~/.config/i3/config.d/ holds only what is declared and named in knows: the include at the very end reads it after the mesh's lines. The catalogue-wide test composes every module's contribution as the controller does and checks the result with i3 -C.

Files it does not know

Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).

• ~/.config/i3: holds only what this module declares and scripts/ (the main file's screenshot binding runs scripts/screenshot.sh; kept until its owner exists); anything else is moved out by the node-engine to ~/.local/state/mesh-moved/i3/ with a list, never deleted (ADR 0422 §4).
• ~/.config/i3/config.d: holds only what this module declares and 10-asus.conf, 20-g14.conf (the laptop's, kept until its hardware module exists); anything else is moved out by the node-engine to ~/.local/state/mesh-moved/i3/ with a list, never deleted (ADR 0422 §4).