2026-03-16
machi - river-based window manager with cascading windows, horizontal panels and vertical workspaces
machi [OPTIONS]
machi is a minimalist window manager with cascading windows, horizontal panels and vertical workspaces. It works on top of river's window management protocol.
-version
Show version.
In machi, resources are layered out hierarchically as follows:
(1) Output → (n) Workspaces → (n) Panels → (n) Windows
Because of that, it's only possible to move resources that are directly connected. For example, a window inside a panel containing multiple windows cannot be individually moved out of its panel to a different workspace, as only panels can be moved to workspaces. Therefore, if it's desirable to move out only a single window, first that window needs to be moved to a new panel, which will only contain that single window, and only then that panel can be moved to the new workspace.
At first it might look counterintuitive, but this speeds up moving groups of windows or panels around, while still allowing moving them individually with a few extra steps but without the need of keybinding bloat.
Maps 1:1 to Wayland outputs. Removing outputs with existing resources will cause those resources to be inherited by another output, if available. If another output is not available, those resources will be inherited by the first output that gets detected.
A single output can hold multiple workspaces. Outputs can be interacted with independently by different seats.
A logical space that spans vertically within an output. Can hold multiple panels, where only one is visible at a time.
Moving out of an empty workspace will cause it to be removed.
A logical space that spans horizontally within a workspace. Can hold multiple windows, where only one or two are visible at a time depending on the current mode. See MODES for more details.
Windows inside a panel are stacked in a way that form a window cascade. This serves as visual cue to show that there are other windows open in a panel other than the one currently focused.
Moving out of an empty panel will cause it to be removed.
The actual window created as a result of a program being run. Only one window can be focused at a time per output. Spawns inside the current panel for the output where the user seat is currently focused on.
Sometimes windows are considered to be "floating". On machi, this simply means that the dimensions of a window are not what the window manager wanted it to be in order for it to fit the cascading layout nicely. When a window is "floating", it will be centralized in the panel.
When in this mode, newly created windows stack on top of each other, where only one window is visible at a time. This is the default mode.
In this mode, changing windows is done through cycling them.
This mode works similarly to single view mode, but two windows are visible at a time, which can be toggled/swapped.
Changing windows in this mode is also done via cycling, but only the unfocused side gets cycled with what's left in the window pool (so the focused window is never cycled out).
When there's only one window, acts as if it's in single view mode.
Only one window is seen and its content occupies the full output surface. Newly created windows will not be focused while in fullscreen mode, in order to preserve focus on the current window.
Cycling windows will leave fullscreen immediately, and focus will be lost.
When it comes to changing what's being seen, it's possible to:
machi(5)
Developed and maintained by Gabriel Sanches <gabriel@gsr.dev>.
Source code is located at <https://codeberg.org/machi/machi>.