Files
komorebi/docs/usage/subscribing-to-notifications.md
T
LGUG2Z f530318cee feat(wm): outputs unplugged and plugged back
KWin takes the windows of an output that goes to the outputs that are left and
puts them where it likes, so komorebi's tiles for them were on a screen that was
gone and the windows sat untiled where they landed. The monitor reconciliator
now deals with a change in the set of monitors: the table announces it as a
display connection change instead of a resize, and reconcile_display_change
reads the monitors again, keeps each one that went (workspaces, layouts,
paddings, offsets) in a cache, has the window manager move what was on it to the
monitors that are left, and removes it.

The move is WindowManager::evacuate_monitor, in the new reconcile module: each
container and floating window goes to the workspace of the same number on the
monitor that holds the middle of its window, or on the first monitor that is
left when it is on none, and the workspaces that changed are tiled. A stack goes
as one container, and a monocle and a maximized window come as ordinary
containers. A monitor that is plugged in takes what was cached under its serial
number id, less the windows that closed or that the window manager has elsewhere
by now, so it comes back with its settings and none of the windows it had. A
monitor komorebi never saw gets workspaces of its own, and when the compositor
reports no output at all nothing is done.

The workspace rules of a monitor that goes are dropped, and those of the
workspaces of one that comes back apply again. komorebi.json fills the cache as
well: a monitor that has the entry its display index preference names is kept
with it, and so is the entry of each preference whose monitor is not connected,
which that monitor takes when it is plugged in.

vm-hotplug now sends two windows to the other monitor with komorebic, disables
that output, enables it again and sends a window over once more.
2026-10-28 07:20:57 -07:00

4.3 KiB

Subscribing to notifications

A program such as a status bar, a widget or a script can follow what komorebi does by subscribing to its notifications. After each event the window manager handles (a window was shown, closed, focused, minimized or restored), each message it takes on its socket and each change of the monitors, the daemon sends every subscriber a notification: the event, the message or the change, and the state of the window manager after it.

Subscribing

A subscriber listens on a Unix socket of its own in the daemon's data directory, $XDG_RUNTIME_DIR/komorebi (on NixOS and most systemd distributions, /run/user/<uid>/komorebi), and tells the daemon the name of the socket with komorebic subscribe-socket. The socket has to exist before it subscribes: the daemon sends the notification of the subscription at once, and removes a subscriber it cannot connect to.

With socat, a shell can subscribe and print every notification:

socat -u UNIX-LISTEN:"$XDG_RUNTIME_DIR/komorebi/bar.sock",fork STDOUT &
komorebic subscribe-socket bar.sock

komorebic unsubscribe-socket bar.sock stops the notifications.

Notifications

The daemon sends each notification on a new connection to the subscriber's socket: it connects, writes one JSON object, and closes the connection. There is no newline after the object. The first notification a subscriber receives is the one of its subscription.

A notification has two fields:

  • event: the event, the message or the change of the monitors. An event is a window event, with the signal it came from and the window, such as {"type":"Show","content":[{"type":"KWin","content":"WindowAdded"},{"id":...}]}. A message is written the way a client writes it on the daemon's socket, such as {"type":"Retile"}. A change of the monitors is the name of the change with its content: {"Resize":0} for a monitor that changed size, with the id of the monitor, or 0 when KWin does not say which, and {"DisplayConnectionChange":0} for a monitor that was unplugged or plugged in. Changing monitors says when each is sent.
  • state: the state of the window manager after it, with the same fields as what komorebic state prints, on one line.

An event about a window that komorebi does not manage, and a message that fails, are not sent.

Only when something changed

A subscriber can ask to be sent a notification only when the event or the message changed the state, with the filter_state_changes option. It is still sent the notification of a window that is shown, of every change of the monitors, of every new subscription, so it receives the state as soon as it subscribes, of a theme, which changes the colors of the borders and nothing in the state, and of every reload of komorebi.json. komorebic subscribe-socket has no option for it; a program writes the message on the daemon's socket itself:

printf '%s' '{"type":"AddSubscriberSocketWithOptions","content":["bar.sock",{"filter_state_changes":true}]}' |
  socat - UNIX-CONNECT:"$XDG_RUNTIME_DIR/komorebi/komorebi.sock"

When a subscriber goes away

A subscriber that the daemon cannot connect to, because its program has exited or its socket was removed, is removed at the next notification, and its socket file with it. The daemon does not try it again: a program that wants notifications again subscribes again. The daemon keeps its subscribers only while it runs, so after a restart every program has to subscribe again.

When the daemon stops, it connects to each subscriber and closes the connection without writing anything.

A subscriber should accept and read every connection as it comes. The daemon writes each notification while the window manager is locked, and waits when the socket's buffer is full, so a subscriber that stops reading can hold up the window manager. While it is held up, the window events KWin reports wait for it, and once 20 are waiting the daemon drops the ones that come after them.

In Rust

The komorebi-client crate has subscribe and subscribe_with_options, which listen on the socket, subscribe, and return the listener: each connection on it is one Notification. cargo doc --package komorebi-client --open shows their documentation, with an example.