How Windows Enter the System
When a new window appears on the X server, the X server sends a MapRequest event to the window manager. This is the X protocol’s way of saying “a new window wants to be displayed, and you are responsible for deciding where it goes and whether it is allowed to be visible.” bspwm receives this event and must respond by either mapping the window (making it visible and assigning it geometry) or ignoring it.
The Rule System
bspwm’s first action is to consult its rule system. Rules are pattern-matching directives that associate window properties like class name, instance name, or title with consequences like state, desktop, monitor, split direction, or whether the window should be managed at all. Rules are set using the bspc rule command, typically in the bspwmrc script.
A rule might say “windows with class name Gimp should be floating” or “windows with class name Firefox should go to desktop three” or “windows with instance name scratchpad should be sticky and float above all other windows.” When a new window arrives, bspwm extracts its properties using X protocols like ICCCM and EWMH, then checks whether any rule matches those properties. If a match is found, the rule’s consequences are applied.
If you have defined an external rule command using the bspc config external_rules_command setting, bspwm will also execute that command, passing the window ID, class name, and instance name as arguments. The command can output additional consequences in key-value format. This allows rule logic to be implemented in any language and can depend on arbitrary external state.
Processing of the Rules
After rules are processed, bspwm must decide where in the tree to insert the new window. This decision depends on the insertion point and the insertion mode. The insertion point is the node that will be replaced or split to accommodate the new window. By default, the insertion point is the currently focused window’s node.
If the insertion point is in manual mode, meaning a preselection has been set, then bspwm follows the preselection. Preselection is when you explicitly tell bspwm “the next window should appear to the north of the currently focused window” by sending a command like bspc node --presel-dir north . This creates a visual indicator showing where the next window will appear and puts the node into manual mode. When a window arrives, bspwm splits the insertion point in the preselected direction, makes the new window one child and the insertion point the other child, and then clears the preselection and returns to automatic mode.
If the insertion point is in automatic mode, which is the default when no preselection is set, bspwm uses the automatic insertion scheme to decide how to split. As described earlier, this scheme can be longest side, alternate, or spiral. The scheme determines the split direction and which child position the new window receives. The existing node at the insertion point becomes an internal node, the new window becomes one of its children, and the previous content of that node moves into the other child.
This insertion process is where the tree’s structure is defined. Once a window is inserted as a leaf, its position in the tree is fixed unless you explicitly rearrange the tree later using commands like swap, rotate, or flip. The tree does not reorganize itself automatically based on window closing or opening. It grows organically as windows are added, and it is up to you to prune and reshape it when it becomes unwieldy.