<!--
SPDX-FileCopyrightText: 2026 mtmn
SPDX-License-Identifier: BSD-3-Clause
-->
# laguna
laguna is a window manager client for the non-monolithic `river` compositor.
It requires river v0.4.8 or compatible and uses stable river protocols only.
This repository builds `laguna` only. Install river separately.
## Design
river owns Wayland clients, rendering and frame synchronisation. laguna owns
window management: tags, focus, keybindings, layout policy and window rules.
The two programs communicate over the stable `river-window-management-v1`
protocol. Input configuration uses stable river input protocols.
## Requirements
- Zig 0.16
- wayland
- wayland-protocols
- xkbcommon 1.12 or newer
- pkg-config
- scdoc (man pages)
## Build and install
```text
zig build -Doptimize=ReleaseSafe --prefix ~/.local install
```
## Run
1. Start `river` from your session startup command.
2. Start `laguna` from `$XDG_CONFIG_HOME/river/init` or
`$HOME/.config/river/init`.
## Configuration
laguna reads its configuration from `$XDG_CONFIG_HOME/river/laguna.zon`. It
falls back to `$HOME/.config/river/laguna.zon`. A missing file leaves
defaults in place. An invalid file is fatal: unknown fields are rejected, so
typos fail loudly at startup.
Top-level options include `main_ratio`, `main_count`, `main_location`,
`attach_mode`, `output_attach_mode`, `spawn_tagmask`, `border_width`,
`border_color_focused`, `border_color_unfocused`, `gap_color`,
`focus_follows_cursor`, `csd`, `cursor_warp`, `xcursor_theme`, `repeat`,
`keyboard_layout`, `keyboard_layout_file`, `modes`, `inputs` and `rules`.
See `example/laguna.zon` for a complete annotated configuration with
keybindings, input settings, rules and theme.
Reload the configuration without restarting by sending SIGHUP to the laguna
process:
```text
pkill -HUP laguna
```
## Commands
Commands are bound in the `modes` section of the configuration or mapped at
runtime. Unknown commands fail synchronously.
- exit, close
- focus-view, zoom, swap, snap
- set-focused-tags, toggle-focused-tags
- set-view-tags, toggle-view-tags
- focus-previous-tags, send-to-previous-tags
- focus-output, send-to-output
- declare-mode, enter-mode
- map, map-pointer, unmap, unmap-pointer
- main-ratio, main-count, main-location
- attach-mode, default-attach-mode, output-attach-mode
- move, resize, toggle-float, toggle-fullscreen
- rule-add, rule-del
- spawn, spawn-tagmask
- set-repeat, input, keyboard-layout, keyboard-layout-file
- border-width, border-color-focused, border-color-unfocused, gap-color
- focus-follows-cursor, set-cursor-warp, xcursor-theme, csd
## Layout
Tiled windows fill the usable output area with no gaps. Borders draw above
window content and do not change tile size.
A terminal can snap to whole character cells and take fewer pixels than its
tile. laguna covers the remaining strip with a solid surface in `gap_color`.
## Title bars
Windows have no title bar by default. laguna asks every window to use
server-side decorations and draws none. It also tells clients when they are
tiled, so well-behaved clients drop their shadows as well.
To let clients draw their own title bars, set `csd = true`. To do this for
some windows only, add a `csd` rule. A client that only supports client-side
decorations draws its own title bar whatever you set.
## Limits
Features without a protocol surface are not supported:
- external layout generators
- compositor background and cursor hiding
- lid-switch bindings
- keyboard groups
