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

108 lines
4.6 KiB
Markdown

# 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](../installation.md) 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:
```sh
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`](../cli/start.md) 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:
```sh
komorebic start
komorebic start -- --log-level debug
komorebic start -- --fake-backend
```
[`komorebic stop`](../cli/stop.md) 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`](../cli/state.md): every monitor, with its workspaces, their
containers and the windows in them, as JSON.
- [`komorebic monitor-information`](../cli/monitor-information.md): the id, the name and
the bounds of every monitor, as JSON.
- [`komorebic query`](../cli/query.md): 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.
```sh
komorebic query focused-workspace-index
komorebic state | jq '.monitors.elements[0].workspaces.elements[0].containers.elements | length'
```
[`komorebic retile`](../cli/retile.md) 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](subscribing-to-notifications.md)).
## 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`](../cli/data-directory.md) 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`](../cli/log.md) 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`](../cli/completions.md) prints a completion script for bash,
elvish, fish, PowerShell or zsh:
```sh
komorebic completions fish > ~/.config/fish/completions/komorebic.fish
komorebic completions bash > ~/.local/share/bash-completion/completions/komorebic
```
## Every command
[`docs/cli`](../cli/start.md) has a page for every `komorebic` command, generated from its
help with `just docgen`.