Files
komorebi/docs/index.md
T
LGUG2Z 6f657e53e3 feat(cli): komorebic
The daemon answers on its socket, but a person has no way to write a message on
it. komorebic is that way: each subcommand that asks something of the daemon is
one message, sent with komorebi-client, and a question's answer is printed.
komorebic is a separate program because the daemon takes no input but its
socket, so a key binding, a script and a terminal all drive it the same way.

It has what the daemon can answer so far: state, monitor-information, query,
retile and stop. Around them, start runs the komorebi on the PATH in the
background and passes it what follows a --, such as --fake-backend to try it
without a compositor; log follows the daemon's log, which the daemon now writes
to a file a day in LOG_DIR as well as to stdout; data-directory shows where the
socket is; completions prints a shell completion script. The hidden docgen
writes each subcommand's help to docs/cli, in fences that name their language
and wrapped at 100 columns whatever the width of the terminal, so that the pages
are the same wherever they are generated; just docgen runs it.

The user guide starts here: docs/index.md for KDE Plasma, and a page on running
komorebi. tests/cli.rs runs each subcommand against a socket the test serves in
place of the daemon. In the VM tests the guests get komorebic next to the
daemon, and vm-core-e2e reads the daemon's state with it (the windows it
manages, the one it focuses, after KWin restarts too) and stops it with
komorebic stop, which unloads the bridge and removes the socket.

In the VM test library, Kde.state asks again, a second (times the scale) after
an empty answer or a failed command, up to 10 times. The daemon drops a query
when it cannot take hold of the window manager within a second, and komorebic
then prints an empty line and succeeds; komorebic itself gives the daemon a
second to answer and fails when that is not enough. A daemon busy with the first
windows does either on a machine that is loaded or slow, and a suite that polled
the state died on JSONDecodeError. An answer that is not JSON still fails at
once.
2026-10-28 07:20:37 -07:00

4.5 KiB

komorebi for KDE

Overview

komorebi is a tiling window manager for KDE Plasma on Wayland. It decides where each window goes, and KWin, the window manager of Plasma, moves and draws the windows.

komorebi is a daemon that runs in the background, and it is controlled with a CLI, komorebic. Every komorebic command that asks something of the daemon is a message on its socket, so anything that can run a command can drive komorebi: a terminal, a script, or a program that binds keys, which is how a key is given an action.

komorebi aims to make as few modifications as possible to the operating system and desktop environment by default. Users are free to make such modifications in their own configuration files for komorebi, but these will always remain opt-in and off-by-default.

How it fits together

komorebi only responds to the events KWin reports about windows and to the messages it receives on a dedicated socket. komorebic is a CLI that writes messages on komorebi's socket. komorebi doesn't handle any keyboard or mouse inputs: a program that binds keys, such as the custom shortcuts in Plasma's System Settings, runs komorebic commands.

               PROCESS                SOCKET
key bindings  -------->  komorebic  <------>  komorebi

Getting started

Running komorebi explains how to get the two programs, start and stop the daemon, ask it what it is doing and read its log. The CLI reference has a page for every komorebic command, generated from its help.

Community

There is a Discord server available for komorebi-related discussion, help, troubleshooting etc.

There is a YouTube channel where I post komorebi development videos, feature previews and release overviews. Subscribing to the channel (which is monetized as part of the YouTube Partner Program) and watching videos is a really simple and passive way to contribute financially to the development and maintenance of komorebi.

There is an Awesome List which showcases the many awesome projects that exist in the komorebi ecosystem.

Licensing for Personal Use

komorebi is licensed under the Komorebi 2.0.0 license, which is a fork of the PolyForm Strict 1.0.0 license. On a high level this means that you are free to do whatever you want with komorebi for personal use other than redistribution, or distribution of new works (i.e. hard-forks) based on the software.

Anyone is free to make their own fork of komorebi with changes intended either for personal use or for integration back upstream via pull requests.

The Komorebi 2.0.0 License does not permit any kind of commercial use ( i.e. using komorebi at work).

Sponsorship for Personal Use

komorebi is a free and educational source project, and one that encourages you to make charitable donations if you find the software to be useful and have the financial means.

I encourage you to make a charitable donation to the Palestine Children's Relief Fund or to contribute to a Gaza Funds campaign before you consider sponsoring me on GitHub.

GitHub Sponsors is enabled for this project. Sponsors can claim custom roles on the Discord server, get shout-outs at the end of komorebi-related videos on YouTube, and gain the ability to submit feature requests on the issue tracker.

If you would like to tip or sponsor the project but are unable to use GitHub Sponsors, you may also sponsor through Ko-fi, or make an anonymous Bitcoin donation to bc1qv73wzspc77k46uty4vp85x8sdp24mphvm58f6q.

Licensing for Commercial Use

A dedicated Individual Commercial Use License is available for those who want to use komorebi at work.

The Individual Commercial Use License adds “Commercial Use” as a “Permitted Use” for the licensed individual only, for the duration of a valid paid license subscription only. All provisions and restrictions enumerated in the Komorebi License continue to apply.

More information, pricing and purchase links for Individual Commercial Use Licenses can be found here.