Files
komorebi/docs/usage/subscribing-to-notifications.md
T
LGUG2Z 5eaa613f50 feat(wm): configuration in komorebi.json
The daemon takes its settings from a komorebi.json: the file --config names, or
the one in the config home ($KOMOREBI_CONFIG_HOME, else ~/.config/komorebi).
Without a file it runs on its defaults, as before.

StaticConfig reads the file in three steps, because the monitors are known only
after the backend has been asked. preload makes the window manager and applies
the settings that are process-wide, postload gives each monitor and workspace
the entry of its place (by the index display_index_preferences gives a monitor's
serial number id, else in order), and main asks KWin for a desktop for each
workspace the file lists. A watcher on the file sends the daemon a
ReloadStaticConfiguration about two seconds after it changes, whether an editor
wrote the file in place or renamed a new one over it, and a file that does not
parse changes nothing.

A workspace can change its layout, its work area offset and its layout options
with the number of its containers, from the file or with komorebic
(workspace-layout-rule, its named form and the two that clear), and
layout_defaults gives every workspace of a layout the options it sets none of.
One file is meant to serve every platform, so a key that does nothing on Plasma
is accepted and ignored. config_parity checks the example and the files of other
platforms; the keys of features that are not in yet are listed there, and the
test fails when a list names a key that is read.

The file also sets what the stacks, the float override, the floating layer and
monocle set while the daemon runs: window_container_behaviour, with its rules by
container count in a workspace, float_override, float_override_placement,
floating_layer_behaviour (for a monitor and a workspace too),
floating_layer_placement and monocle_focus_behaviour. Their features come before
this commit, but a file to put the keys in does not, so they are part of this
one.

komorebic gains configuration, generate-static-config and start --config. The
NixOS module gets configFile, which the unit gives the daemon as --config.
2026-10-28 07:20:37 -07:00

3.8 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) and each message it takes on its socket, the daemon sends every subscriber a notification: the event or the message, 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 or the message. 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"}.
  • 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 new subscription, so it receives the state as soon as it subscribes, 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.