Files
komorebi/docs/index.md
T
LGUG2Z 05de20749b feat(wm): maximize
A window could be given the work area only as a tile of the layout, which has
padding around it. `komorebic toggle-maximize` has KWin maximize the focused
window instead: it gets the work area of its monitor with the panels left alone,
and it leaves the layout, so that it is in no container. Toggled again, the
window is restored, put in a container of its own at the index it was taken
from, and the workspace is tiled again.

The window is kept in the workspace as its maximized window, with the index it
goes back to, and the state shows both. While it is maximized the workspace asks
KWin to maximize it again on every tiling, and does not move the containers
behind it. The messages that are about the tiles (move, stack, resize, promote,
preselect, lock, float, monocle, and the ones that send a container to another
monitor or workspace) are dropped before they are handled, since there is no
tile to act on. Focusing in a direction finds no container on any side of it, so
the focus goes to the monitor on that side, where a maximized window or a
monocle is given the focus whole. Showing the workspace again restores the
maximized window and focuses it ahead of the containers' windows. A window in
monocle that is maximized leaves the monocle, and one that closes takes the
maximize with it. Backend gets a maximize command, which does nothing unless a
backend implements it; the fake desktop and the KWin backend do, and the bridge
carries it out with KWin's own `setMaximize`. A maximize also makes the bridge
forget the position it was last asked to put the window at, which it would
otherwise set again on the work area's size when the window's frame changed
within a second of a tiling.

komorebi/tests/maximize.rs and maximize_commands.rs drive it against the fake
desktop, with one monitor and with two. The bridge's tests and the backend's
tests read the maximize command from the same fixture, so that what one sends is
what the other carries out. vm-features is a new session suite that reads
screenshots: the first thing it checks is that the maximized window fills the
work area, is the one on top, and goes back to its tile; the vm-commands sweep
runs the new command.
2026-10-28 07:20:37 -07:00

6.0 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

Installing komorebi explains how to install the two programs: on NixOS with the flake's module, which also starts komorebi with every Plasma session, and from source anywhere else. Running komorebi explains how to start and stop the daemon, ask it what it is doing and read its log. Focusing windows explains how to give the focus to another window, Moving windows how to move the focused window to another tile, Stacking windows how to put windows on one tile, have the others wait out of sight and bring one of them to the front, Layouts how to change the arrangement of the tiles, Resizing windows how to change the size of one, Floating windows how to take a window out of the layout, Monocle how to give one window the whole work area, Maximizing windows how to have KWin maximize one, Managing windows how to minimize, close and unmanage the focused window and pause the daemon, and Padding and work area offsets how to put gaps around the tiles and keep parts of a monitor free of them. Rules explains how to keep an application out of the layout, always tile it, or float its windows. Workspaces explains how each monitor shows one of its workspaces, which are KWin's virtual desktops, and how to show another or move a window to one. Subscribing to notifications explains how a program such as a status bar follows what komorebi does. 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.