Files
komorebi/docs/usage/running-komorebi.md
T
LGUG2Z a86e2bdc63 build(nix): a NixOS module for komorebi
On NixOS, running komorebi should take one flake input and one module line. The
flake exports `services.komorebi` as nixosModules.default (and .komorebi). It
adds the flake's overlay, which gains komorebi-full, installs komorebi and
komorebic, and runs the daemon in every Plasma session as a systemd user unit,
wanted by plasma-workspace.target and ordered after plasma-core.target, which
Plasma orders after KWin. systemd starts a daemon that fails again; the exit
status of a SIGTERM (130) counts as success, so a stopped unit is not failed.
The unit's PATH is the one a terminal in the session has, instead of the few
store paths NixOS gives a unit.

The options are enable, package, logLevel and a read-only execStart, the command
line the unit runs. There is no configFile: the daemon reads no configuration
file yet, and an option that linked one would do nothing.

nixos-module-eval evaluates seven scenarios as real NixOS systems and checks
their assertions, the unit and execStart, with builtins.tryEval for the two that
must not evaluate. Nothing in it builds a Linux package, so it runs on a Mac as
well.

The VM nodes import the module, so every suite runs komorebi as the module
installs it. The headless node's komorebi@NAME runs execStart, which has
--log-level, so the nodes set logLevel to debug and the suites stop passing it;
latency, which times the daemon, keeps the default level. The session node
starts the module's unit at login; render-smoke turns it off, since a tiled
terminal would cover the desktop it looks at. A new fast suite, vm-module, logs
in to Plasma and checks that the unit runs the daemon with the module's log
level and PATH, that a window opened in the session is tiled, that a killed
daemon is started again, and that a stop is not a failure.

docs/installation.md covers NixOS first, and building from source on other
distributions. There is no binary cache: the Komorebi license does not allow
third parties to redistribute binaries.
2026-10-28 07:20:37 -07:00

4.6 KiB

Running komorebi

komorebi is the daemon that tiles your windows, and komorebic is the command line you control it with. This page covers starting and stopping the daemon, asking it what it is doing, and reading its log.

Getting the two programs

Installing komorebi covers NixOS, where the flake's module installs both and starts the daemon with every Plasma session, and building them from source. In a checkout of the repository, on Linux, nix build leaves them in result/bin, and nix profile install . puts them on your PATH. Without nix, build them with the Rust toolchain that rust-toolchain.toml selects:

cargo build --release --locked
export PATH="$PWD/target/release:$PATH"

With the NixOS module, the daemon is the user unit komorebi.service, which starts when you log in to Plasma. systemctl --user start komorebi starts it again after a komorebic stop, and journalctl --user -u komorebi shows what it wrote. Everything else on this page applies to it as it is.

Starting and stopping

komorebic start runs the komorebi on your PATH in the background, and checks three seconds later that it is running. It tries three times. If komorebi has not started by then, komorebic start runs it once more in the foreground and prints what it wrote on its standard error, which explains why it did not start. When a komorebi is running already, komorebic start does nothing.

komorebi manages the windows of the Plasma Wayland session it is started in: it connects to KWin on the session bus and loads a script into it, so start it from a terminal in that session. Outside a Plasma session it exits with an error that says what is missing, which komorebic start prints.

Everything after a -- is passed to komorebi. --fake-backend runs it against an in-memory desktop with one monitor and no windows instead of KWin, which is a way to try the daemon and komorebic without a compositor:

komorebic start
komorebic start -- --log-level debug
komorebic start -- --fake-backend

komorebic stop tells the daemon to stop. It asks KWin to unload its script, removes its socket and exits. Stopping the process with SIGINT or SIGTERM does the same.

Asking komorebi what it is doing

The daemon answers questions on its socket, and these commands print the answers:

  • komorebic state: every monitor, with its workspaces, their containers and the windows in them, as JSON.
  • komorebic monitor-information: the id, the name and the bounds of every monitor, as JSON.
  • komorebic query: one value, the answer to one question: the index of the focused monitor, workspace, container or window, the layout of the focused workspace, whether the focused container is a single window or a stack, or the version of the daemon.
komorebic query focused-workspace-index
komorebic state | jq '.monitors.elements[0].workspaces.elements[0].containers.elements | length'

komorebic retile tiles the windows of every monitor again, which puts a window that was moved by hand back on its tile.

When the daemon is not running, these commands fail: there is no socket to write to.

A program that wants to know what komorebi does without asking can subscribe to its notifications instead (Subscribing to notifications).

The socket and the data directory

The daemon listens on komorebi.sock in its data directory, $XDG_RUNTIME_DIR/komorebi (the local data directory, ~/.local/share/komorebi, when there is no runtime directory). komorebic data-directory prints the directory, if it exists.

The log

The daemon logs to its standard output and to a file a day in ~/.local/share/komorebi ($XDG_DATA_HOME/komorebi when that is set): komorebi.log.YYYY-MM-DD, with colors, and komorebi_plaintext.log.YYYY-MM-DD, without. The day is the UTC date.

komorebic log follows the file of the current day, with colors, until you press Ctrl-C. The --log-level of komorebi sets how much is logged: error, warn, info (the default), debug or trace.

Shell completions

komorebic completions prints a completion script for bash, elvish, fish, PowerShell or zsh:

komorebic completions fish > ~/.config/fish/completions/komorebic.fish
komorebic completions bash > ~/.local/share/bash-completion/completions/komorebic

Every command

docs/cli has a page for every komorebic command, generated from its help with just docgen.