The Bspwm Wiki

Event Subscription and the Reactive Model

The subscribe command allows external programs to receive real-time notifications when bspwm’s state changes. bspc subscribe followed by event types opens a stream of events that are emitted as newline-separated text. Event types include node_add, node_remove, node_swap, node_focus, desktop_focus, monitor_focus, node_state, node_flag, node_layer, node_geometry, desktop_layout, and many others.

Each event message contains the event type and relevant data such as monitor ID, desktop ID, node ID, and event-specific parameters.

Note

For example, when focus changes to a new window, bspwm emits a node_focus event with the IDs of the monitor, desktop, and node that received focus. When a window’s geometry changes, a node_geometry event includes the new geometry values.

This event stream enables reactive programming. You can write a daemon that subscribes to events and responds to state changes with actions. For instance, you could subscribe to node_focus events and automatically adjust window opacity based on focus state, making the focused window fully opaque and all others semi-transparent. You could subscribe to desktop_focus events and change your status bar’s appearance based on which desktop is active. You could subscribe to node_add events and automatically balance the tree whenever a new window appears.

The Pattern :

The pattern is typically subscribe to events, parse the event stream, maintain internal state if necessary, and send commands back to bspwm based on event data. Since bspwm itself is stateless between commands—it only maintains the tree and current configuration—external daemons become the memory of your system, tracking history, learning patterns, and implementing policy.

Important

This is the third conceptual shift: bspwm is not a window manager that does things. It is a window manager that allows things to be done to it. Your desktop environment is the sum of all programs that communicate with bspwm’s socket.