Files
komorebi/docs/index.md
T
LGUG2Z 70c2affa9d docs(repo): compare the three komorebi programs and fix what the docs got wrong
docs/dev/COMPARE.md says what komorebi for KDE shares with komorebi for Windows
and komorebi for Mac, what differs, what KDE does by itself and what is not
supported, for a reader who knows komorebi on one of them. Its tables are
generated by scripts/compare-gen.py from this checkout and from checkouts of the
other two, because a count or a name typed by hand is wrong after the next
change to a command, a key or an event. The script also checks the notes that
say why a command has no counterpart, and the sentences of the document that
depend on a table, and stops when one of them is no longer true. CI has neither
checkout and cannot run it; CONTRIBUTING says when to run it. The tables have no
column for the commit that added a row: the plan that numbered the commits is
not in the repository, and a number the script cannot derive for the next commit
would stop it.

The other documents had places that said something the repository does not carry
or does not do:

- DESIGN cited docs/kde.md, which no commit carries, said spike 8 "asked
  whether" one komorebi.json could be shared, and described the default of the
  key binding mode as a plan. Each entry now states the rule and the evidence.
  The first entry no longer says that the Windows implementation is the
  reference: both it and the macOS one were read, and the native thing is
  preferred where the other two need a workaround.
- "The spikes" was used in PLATFORM, DESIGN and COMPARE and defined nowhere.
  PLATFORM's vocabulary defines it, and PLATFORM has a list of what was not
  measured, which COMPARE links to.
- ARCHITECTURE said a maximized window is hidden with its workspace and shown
  with it, and that the code has a TODO for cycling the focus. A workspace
  switch hides nothing, since KWin shows and hides the desktop's windows, and
  the cycle leaves a maximized window as it is; the TODO and the commented-out
  code under it in window_manager.rs are replaced by a comment that says so. The
  Key bindings section no longer repeats the headings of the sections before it.
- README listed the subcommands that work without the daemon, and the list was
  short. It gives the rule and one example of each kind.
- The page on changing monitors opened with "nothing to configure" and then
  named display_index_preferences.
- COMPARE said KWin waits 300 ms for the pointer to settle before it moves the
  focus. That is KWin's default (DelayFocusInterval, in KWin 6.8.1), and
  komorebi sets it to 0 while focus follows mouse is on; the page now says so.
- ARCHITECTURE's opening list of what the page describes stopped at the borders
  and had no word of animation, themes, wallpapers, transparency, focus follows
  mouse or key bindings. Two link definitions that it had twice are there once.
- PLATFORM's list of what was not measured has the progress of the stock
  animation effect against the clock: one capture showed none four seconds into
  a 30 s animation, where the curve gives about 60 %.
- README, docs/index.md and ARCHITECTURE link COMPARE.md.
- COMPARE's list of the methods of Backend has drag_end, which the end of a
  resize is read through, and compare-gen.py has the row and the counts.
2026-10-28 07:39:49 -07:00

153 lines
8.8 KiB
Markdown

# 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 read the keyboard or the mouse: a key runs a _komorebic_ command,
as a global shortcut of KDE. komorebi makes those shortcuts from a key binding file in the
format of skhd, whkd or sxhkd ([Key bindings](usage/keybindings.md)); the custom shortcuts of
Plasma's System Settings work too.
```text
PROCESS SOCKET
key bindings --------> komorebic <------> komorebi
```
## Getting started
[Installing komorebi](installation.md) 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](usage/running-komorebi.md) explains how to start and stop the
daemon, ask it what it is doing and read its log.
[Key bindings](usage/keybindings.md) explains how to bind keys to `komorebic` commands with
an skhdrc, a whkdrc or an sxhkdrc, and [Example configurations](example-configurations.md) has
a NixOS configuration and sample key bindings in the three formats.
[Focusing windows](usage/focusing-windows.md) explains how to give the focus to another window,
[Moving windows](usage/moving-windows.md) how to move a window to another tile,
[Stacking windows](usage/stacking-windows.md) how to put windows on one tile, have the others wait
out of sight and bring one of them to the front,
[Layouts](usage/layouts.md) how to change the arrangement of the tiles,
[Resizing windows](usage/resizing-windows.md) how to change the size of one (and
[Resizing a tile by dragging its edge](drag-resize.md) what a drag with the pointer does),
[Floating windows](usage/floating-windows.md) how to take a window out of the layout and work with
the floating ones,
[Monocle](usage/monocle.md) how to give one window the whole work area,
[Maximizing windows](usage/maximizing-windows.md) how to have KWin maximize one, and what
komorebi does when you maximize one yourself,
[Fullscreen windows](usage/fullscreen-windows.md) what komorebi does with one,
[Managing windows](usage/managing-windows.md) how to minimize, close and unmanage the focused
window and pause the daemon, and
[Padding and work area offsets](usage/padding-and-offsets.md) how to put gaps around the tiles
and keep parts of a monitor free of them.
[Rules](usage/rules.md) explains how to keep an application out of the layout, always tile it, or
float its windows.
[Initial window placement rules](initial-window-placement-rules.md) explains how to say where in the
layout a window goes when it opens.
[Workspaces](usage/workspaces.md) 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, and
[Workspace rules](usage/workspace-rules.md) how to have the windows of an application go to a
workspace by themselves.
[Configuration](usage/configuration.md) explains `komorebi.json`, where komorebi looks for it and
how it is reloaded when it changes, [Example configurations](example-configurations.md) has one to
start from, and [Application specific configuration](usage/application-specific-configuration.md)
explains the files of rules for particular applications it can name.
[Quickstart and autostart](usage/quickstart-and-autostart.md) explains how to write an example
configuration, how to start komorebi with Plasma without the module, and how to replace the
configuration of a running daemon.
[Borders](usage/borders.md) explains how komorebi has KWin draw a border around each window,
[Animation](usage/animation.md) how it has KWin animate the windows going to their places, and
[Transparency](usage/transparency.md) how it makes the windows that do not have the focus
see-through, [Focus follows mouse](usage/focus-follows-mouse.md) how it has KWin give the focus
to the window under the pointer, [Themes](usage/themes.md) how a theme gives the borders their
colors, and [Wallpapers](usage/wallpapers.md) how a monitor or a workspace shows a picture of its own,
and what it does to the borders.
[Changing monitors](usage/changing-monitors.md) explains what komorebi does when a monitor
changes size, is unplugged or is plugged in, and
[Sleeping and locking](usage/sleeping-and-locking.md) what it does when the machine wakes up and
the screen is unlocked.
[Checking the setup](usage/checking-the-setup.md) explains how `komorebic check` finds the
mistakes in a configuration and a key binding file, and what is missing from the desktop, before
the daemon does.
[Subscribing to notifications](usage/subscribing-to-notifications.md) explains how a program
such as a status bar follows what komorebi does. The [CLI reference](cli/start.md) has a page
for every `komorebic` command, generated from its help.
[Compared with komorebi for Windows and for Mac](dev/COMPARE.md) says, for someone who knows
komorebi on one of them, what is the same on KDE Plasma, what is different, what KDE does by
itself and what is not supported.
## Community
There is a [Discord server](https://discord.gg/mGkn66PHkx) available for
`komorebi`-related discussion, help, troubleshooting etc.
There is a [YouTube
channel](https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg) 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](https://github.com/LGUG2Z/awesome-komorebi) 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](https://github.com/LGUG2Z/komorebi-license), which is a fork
of the [PolyForm Strict 1.0.0 license](https://polyformproject.org/licenses/strict/1.0.0). 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](https://github.com/LGUG2Z/komorebi-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](https://pcrf1.app.neoncrm.com/forms/gaza-recovery) or to contribute
to a [Gaza Funds campaign](https://gazafunds.com) before you consider sponsoring
me on GitHub.
[GitHub Sponsors is enabled for this
project](https://github.com/sponsors/LGUG2Z). 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](https://ko-fi.com/lgug2z), 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](https://github.com/LGUG2Z/komorebi-license) continue to apply.
More information, pricing and purchase links for Individual Commercial Use
Licenses [can be found here](https://lgug2z.com/software/komorebi).