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.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:39:49 -07:00
1 parent 8b9cde08d0
commit 70c2affa9d
12 files changed
+2146 -61

No files matched your search

+16
View File
@@ -98,6 +98,22 @@ the KWin), and its message says which run that was and which suites ran.
flake. `min` changes with the code, in the commit that starts to use something an
older KWin does not have.
## The comparison
[`docs/dev/COMPARE.md`](docs/dev/COMPARE.md) compares komorebi for KDE with komorebi
for Windows and komorebi for Mac, and its tables are generated by
[`scripts/compare-gen.py`](scripts/compare-gen.py) (Python 3 and nothing else) from
this checkout and from checkouts of the other two, `~/komorebi` and
`~/komorebi-for-mac` unless `--kfw` and `--kfm` say otherwise. Continuous
integration has neither checkout, so it does not run the script. A change to a
`komorebic` command, a `SocketMessage`, a key of `komorebi.json`, a
`WindowManagerEvent`, a method of `Backend` or a list of keys in `check.rs` is
followed by `python3 -I scripts/compare-gen.py --check docs/dev/COMPARE.md`, and
by `--update` when it reports a stale block, in the same commit. The script stops
and says what when a command, key, event or method has no note about why it
differs, and when a sentence of the document stops being true; the text around an
updated block is read again each time.
## VM tests
A change that needs a real KWin to be checked comes with a VM test, next to
+8 -5
View File
@@ -102,11 +102,12 @@ without a checkout of the toolchain.
[`komorebi-hotkeys/tests/fixtures`](komorebi-hotkeys/tests/fixtures), where
each case is written in every format that can express it.
- [`komorebic`](komorebic): the command line. A subcommand that asks something
of the daemon is one message on its socket; `quickstart`, `enable-autostart`,
`disable-autostart`, `start`, `check`, `configuration`, `log`, `data-directory`,
`completions` and the hidden `docgen` work without the daemon, and so do
`export-kde-shortcuts` and `hotkeys compile`, which write the bindings of a
key binding file that KDE can run by itself as shortcut files.
of the daemon is one message on its socket, and the others work without the daemon:
`start` and the autostart commands start it, `check` looks at the files and the
desktop, `quickstart` writes files, `export-kde-shortcuts` and `hotkeys compile`
write the bindings of a key binding file that KDE can run by itself as shortcut
files, and `configuration`, `log`, `data-directory`, `completions`, the schema
printers and the hidden `docgen` print.
- [`version`](version): the version string every binary reports.
The layouts, which turn a work area and a number of containers into a rectangle
@@ -355,6 +356,8 @@ and [`docs/cli`](docs/cli) has a page for every `komorebic` subcommand, which
[`docs/dev/ARCHITECTURE.md`](docs/dev/ARCHITECTURE.md) describes the model,
[`docs/dev/DESIGN.md`](docs/dev/DESIGN.md) says why it is built that way,
[`docs/dev/PLATFORM.md`](docs/dev/PLATFORM.md) what it needs from KDE Plasma,
[`docs/dev/COMPARE.md`](docs/dev/COMPARE.md) what is the same and what is different in
komorebi for Windows and komorebi for Mac,
[`docs/dev/vm-tests.md`](docs/dev/vm-tests.md) how the VM tests work, and
[`docs/dev/utm.md`](docs/dev/utm.md) how to develop in a Plasma guest.
+23 -16
View File
@@ -11,9 +11,13 @@ how an event about a window becomes a tile, how workspaces are the compositor's
a stack hides its windows, how the window manager follows a monitor that changes and sets the
desktop in order after a sleep or a lock, how a message on the daemon's socket is answered, how
subscribers are notified of all three, what the orders a message gives do, what a drag with the
pointer does, how the compositor is asked to draw the borders, how `komorebi.json` configures the
daemon, and how the NixOS module runs the daemon. It grows with the code: each part of the daemon
that is added has its place here.
pointer does, how `komorebi.json` configures the daemon and is checked, how the compositor is
asked to draw the borders and to animate the windows, how a theme, a wallpaper, transparency and
focus follows mouse reach it, how the NixOS module runs the daemon, and how a key binding file
becomes shortcuts that run commands. It grows with the code: each part of the daemon that is
added has its place here.
[DESIGN.md](DESIGN.md) says why it is built this way, and [COMPARE.md](COMPARE.md) what is the
same and what is different in komorebi for Windows and komorebi for Mac.
## Vocabulary
@@ -290,8 +294,7 @@ and cycling the stack or focusing a window of it by its index.
A monocle hides the other containers in the same way. Turning it on hides every window of each
of them ([`Container::hide`]), turning it off restores the window in front of each
([`Container::restore`]), and cycling it hides the container it gave up. While a monocle is on,
[`Workspace::restore`] restores its window and no other, and [`Workspace::hide`] hides it with
the rest.
[`Workspace::restore`] restores its window and no other.
[`Window::hide`] puts the window's id in [`HIDDEN_WINDOWS`] before it asks the backend, and
[`Window::restore`] takes it out, so that when the compositor reports something about the window
@@ -626,9 +629,12 @@ closes while it is maximized leaves the workspace like any other. `FocusWindow`
container on any side of the maximized window, so the focus goes to the monitor on that side and
fails where there is none, and a maximized window, or a monocle, on the workspace it reaches is
given the focus whole. `CycleFocusWindow` is not dropped: it gives the focus to the next
container's window (the code has a TODO for what it should do). A maximized window is hidden
with the rest of its workspace, and restored and focused ahead of the containers' windows when
the workspace is shown again ([`Workspace::hide`], [`Workspace::restore`]).
container's window and leaves the maximized window as it is, where komorebi for Windows
maximizes the window the focus cycles to
([`WindowManager::focus_container_in_cycle_direction`]). When the workspace is shown,
[`Workspace::restore`] restores the maximized window and gives it the focus ahead of the
containers' windows. Nothing hides it when the workspace is left: KWin hides the windows of a
desktop that no monitor shows.
A window the user maximizes, with its title bar, a double click or a shortcut, is the same from
then on. KWin does it without komorebi's being asked, and the bridge reports it as a `maximized`
@@ -1415,7 +1421,7 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
| A window komorebi does not manage is never moved | framework path: `handle_event` asks [`Window::should_manage`] before it acts on any event but a destroy | `dialogs_and_other_non_normal_windows_are_left_alone`, `an_ignore_rule_keeps_a_window_unmanaged` | `ManageRule` |
| A window the user unmanaged stays out of the layout until it is managed again | framework path: `handle_event` checks the list of unmanaged windows before it acts on any event but a removal | `unmanage_takes_the_focused_window_out_until_manage_takes_it_back` | none |
| A paused window manager moves no window | framework path: `handle_event` returns before anything else, and [`read_commands_uds`] drops every message but `TogglePause`, `State`, `GlobalState` and `Stop` | `while_paused_no_event_changes_the_layout_and_manage_takes_in_a_window_it_missed`, `while_paused_only_toggle_pause_state_and_stop_are_handled` | none |
| A destroyed window leaves whichever workspace has it | framework path: the destroy is looked up in the index of managed windows, which is rebuilt at startup and before and after every event | `a_window_that_was_open_before_komorebi_started_is_removed_when_it_closes` | none |
| A destroyed window leaves the workspace that has it | framework path: the destroy is looked up in the index of managed windows, which is rebuilt at startup and before and after every event | `a_window_that_was_open_before_komorebi_started_is_removed_when_it_closes` | none |
| The daemon does not start without KWin, unless it is told to run against the fake | startup check: [`connect`] fails, and the daemon exits with the error, code 1 | `without_a_session_bus_komorebi_exits_with_an_error_naming_it` | `--fake-backend` |
| One komorebi per session | startup check: the session bus gives `org.komorebi.Bridge` to one connection | none | none |
| A komorebi that cannot connect to KWin leaves the socket of the running one alone | startup order: `main.rs` connects to KWin before [`WindowManager::new`] binds the socket | `without_kwin_komorebi_leaves_the_socket_it_finds_alone` | `--fake-backend` asks no bus, and takes the socket |
@@ -1595,7 +1601,7 @@ A window is shown, and ends up on a tile:
depend on the daemon. Its model is the content of a key binding file of any of three hotkey
daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
### The model
### The key binding model
- **Keymap**: one file: its modes, the applications in which no binding is active (a
blacklist), a binding that turns the others off and on (a pause binding), and the names the
@@ -1622,7 +1628,7 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
- **Effect**: what the caller of the engine does after an event: activate or deactivate a combo,
or run a command.
### The parts
### The parts of the key bindings
- [`qt`](../../komorebi-hotkeys/src/qt.rs): key names to Qt key codes, in the vocabulary of each
format (skhd's literals and macOS keycodes, whkd's virtual key names, sxhkd's X keysyms), and
@@ -1725,12 +1731,12 @@ plan needs no engine. A failure to start is logged, and the window manager runs
holds and whether a chain is pending, or `null` when no engine runs; `komorebic hotkeys
state` adds the actions kglobalaccel has for the component.
### What is guaranteed, and by what
### What is guaranteed for the key bindings, and by what
| Rule | Enforced by | Proof | Escape hatch |
|---|---|---|---|
| A combo is in the form KWin matches (the shifted symbol rule is applied) | type system: `Combo`'s fields are private, and `Combo::new` applies the rule | `compile_fail,E0451` on `Combo`; `shift_on_a_symbol_key_is_the_symbol_it_types` | none |
| A key has the same code whichever vocabulary names it | test | `the_three_vocabularies_name_the_same_keys` | none |
| A key has the same code in every vocabulary that names it | test | `the_three_vocabularies_name_the_same_keys` | none |
| Positional key names (macOS keycodes, `oem_*`) are read as on a US layout | convention only | none | none |
| Reading a file returns a keymap, whatever the text | type system: a reader returns `Parsed`, not a `Result` | none | none |
| Text that is left out has a diagnostic that points at it | test | `what_cannot_be_read_is_reported_and_left_out`, `reading_goes_on_after_an_error`, `diagnostics_point_at_the_text_they_are_about` | none |
@@ -1969,6 +1975,10 @@ plan needs no engine. A failure to start is logged, and the window manager runs
[`nix/tests/nixos-module.nix`](../../nix/tests/nixos-module.nix), its scenarios, evaluated in
real NixOS systems; and [`nix/tests/vm/suites/module`](../../nix/tests/vm/suites/module/test.py),
a Plasma session in which the module's unit runs the daemon.
- [`scripts/compare-gen.py`](../../scripts/compare-gen.py): writes the tables of
[COMPARE.md](COMPARE.md) from this checkout and from checkouts of komorebi for Windows and
komorebi for Mac, and checks them. Continuous integration has neither checkout and does not run
it.
[`nixos-module.nix`]: ../../nix/nixos-module.nix
[`supported-kwin.nix`]: ../../nix/supported-kwin.nix
@@ -2067,8 +2077,6 @@ plan needs no engine. A failure to start is logged, and the window manager runs
[`Workspace::new_container_for_focused_window`]: ../../komorebi/src/workspace.rs
[`Workspace::remove_window`]: ../../komorebi/src/workspace.rs
[`Workspace::focus_container_by_window`]: ../../komorebi/src/workspace.rs
[`Workspace::restore`]: ../../komorebi/src/workspace.rs
[`Workspace::hide`]: ../../komorebi/src/workspace.rs
[`Workspace::window_container_behaviour`]: ../../komorebi/src/workspace.rs
[`Workspace::float_override`]: ../../komorebi/src/workspace.rs
[`WindowManager::add_window_to_container`]: ../../komorebi/src/window_manager.rs
@@ -2210,7 +2218,6 @@ plan needs no engine. A failure to start is logged, and the window manager runs
[`kwin::power`]: ../../komorebi/src/kwin/power.rs
[`MonitorNotification::Wake`]: ../../komorebi/src/monitor_reconciliator.rs
[`wake_up`]: ../../komorebi/src/monitor_reconciliator.rs
[`WindowManager::retile_all`]: ../../komorebi/src/window_manager.rs
[`kwin::connect`]: ../../komorebi/src/kwin/mod.rs
[`WindowManager::evacuate_monitor`]: ../../komorebi/src/reconcile.rs
[`WindowManager::follow_windows_to_their_monitors`]: ../../komorebi/src/reconcile.rs
+827
View File
@@ -0,0 +1,827 @@
# komorebi for KDE Plasma compared with komorebi for Windows and for macOS
This document compares komorebi for KDE Plasma on KWin and Wayland (kfde) with komorebi for
Windows (kfw), the original, and komorebi for macOS (kfm). It is written for a reader who knows
komorebi on one of those two systems and wants to know what is the same on KDE, what is different,
what KDE does by itself that komorebi does on the other systems, and what is not supported.
It states facts that can be checked against the code, and does not assign value judgments. "kfw
draws the borders itself and kfde asks the compositor to" is a fact. "The compositor's borders are
better" is not, and is not said here. The reasons behind kfde's choices are in
[DESIGN.md](DESIGN.md), where they are opinions and say so.
It is written for kfde, so it leans toward kfde, and it was written from the sources of the three
programs, not from running them side by side. Where something could not be verified, it says so.
A correction is welcome.
## How to read this document
Every table in a marked block is generated by `scripts/compare-gen.py` from the source trees
of the three programs, so a count or a name in it is what the code had when the block was last
generated. The text around the tables is written by hand and states what the tables say.
```sh
python3 -I scripts/compare-gen.py --update docs/dev/COMPARE.md # rewrite the blocks
python3 -I scripts/compare-gen.py --check docs/dev/COMPARE.md # exit 1 when one is stale
```
The script reads this checkout and checkouts of [kfw](https://github.com/LGUG2Z/komorebi) and
[kfm](https://github.com/LGUG2Z/komorebi-for-mac) (`~/komorebi` and `~/komorebi-for-mac` by
default; `--kfw` and `--kfm` name others). Continuous integration has neither checkout, so it
does not run the script: a change to a command, a message, a key of `komorebi.json`, an event or
a method of `Backend` is followed by `--check` on a machine that has them, and by `--update` and
a read of the text around the block when it reports a stale one. The script also checks the
hand-written notes it holds (why a Windows command has no counterpart, which KWin call stands in
for a Win32 one) against the sources, and the sentences of this document that depend on a
generated fact, and stops on a note or a sentence that is no longer true. The revisions it read
are:
<!-- gen:sources -->
| Name | What | Read from | Revision |
|---|---|---|---|
| kfw | komorebi for Windows, the upstream | `~/komorebi` | 173aa802, 2026-10-27 |
| kfm | komorebi for macOS | `~/komorebi-for-mac` | 125a9a5, 2026-10-27 |
| kfde | this project | this repository | the commit that has this document |
<!-- /gen:sources -->
kfm changes often, so the numbers for kfm in particular are those of that revision.
Terms used below:
- **KWin's script** (the bridge) is a small JavaScript program that komorebi loads into KWin. It is
the only code of kfde that runs inside the compositor, and it contains no window manager logic.
- **A workspace** is komorebi's name for one of the desktops of a monitor, in all three programs.
- **A parking desktop** is a KWin virtual desktop that nobody looks at, which kfde moves windows to
in order to hide them.
- **The strip** is the scrolling layout of kfm, in the crate `komorebi-scrolling`. It is not the
`Scrolling` layout of `komorebi-layouts`.
## What is the same
### One tiling model, and the same layouts
The model is the same in all three programs: a list of monitors, each with workspaces, each with
containers, each with windows. kfde adds no layer to it. The layouts come from the crate
`komorebi-layouts`, which kfw owns and kfm and kfde use as a git dependency:
<!-- gen:layouts -->
| `DefaultLayout` | kfw | kfm | kfde |
|---|---|---|---|
| `BSP` | yes | yes | yes |
| `Columns` | yes | yes | yes |
| `Rows` | yes | yes | yes |
| `VerticalStack` | yes | yes | yes |
| `HorizontalStack` | yes | yes | yes |
| `UltrawideVerticalStack` | yes | yes | yes |
| `Grid` | yes | yes | yes |
| `RightMainVerticalStack` | yes | yes | yes |
| `Scrolling` | yes | yes | yes |
The crate each tree builds: kfw: `komorebi-layouts` in the tree; kfm: `komorebi-layouts` at git rev `f08aa55`; kfde: `komorebi-layouts` at git rev `f08aa55`.
Compared file by file with the crate of kfw, kfm: 0 of 13 source files differ from the ones of kfw; kfde: 0 of 13 source files differ from the ones of kfw.
<!-- /gen:layouts -->
The layouts of `komorebi-layouts` are calculated by the same code in the three programs, so the same
windows in the same order get the same rectangles, apart from what the window manager takes off for
the work area, the padding and the borders. The exception is the `Scrolling` layout of kfm, which kfm
lays out with the strip (see the section on configuration). What differs between the programs is
what the system does with the rectangles: the next sections.
### One configuration file, largely portable
A `komorebi.json` written for kfw or kfm loads in kfde. The keys that kfde does not read are
accepted and ignored, not rejected. The tables of the sections on configuration say which keys
those are, and why.
## Commands
`komorebic` has the same shape in the three programs: a command writes a message on the socket of the
daemon, and the message is a variant of the `SocketMessage` of `komorebi-client`. A command's name is
the variant of `SubCommand` in kebab case, which is what the pages of `docs/cli` are named after.
<!-- gen:commands-counts -->
| | kfw | kfm | kfde |
|---|---|---|---|
| Commands `komorebic` has | 192 | 158 | 158 |
| In all three | 148 | 148 | 148 |
| Also in kfw, not in kfm | 7 | - | 7 |
| Also in kfm, not in kfw | - | 1 | 1 |
| Only in kfde | - | - | 2 |
| In kfw or kfm, not in kfde | 37 | 9 | - |
| Same command under another name | - | - | 0 |
<!-- /gen:commands-counts -->
No command of kfw or kfm is kept in kfde under another name, not even as an alias.
### kfde has the commands kfw and kfm share
These commands exist in all three programs, with the same name. The ones that the tiling and the
workspaces are driven with do the same on KDE; where they do it differently (a workspace is a KWin
desktop) the section on workspaces says how.
<!-- gen:commands-all3 -->
`adjust-container-padding`, `adjust-workspace-padding`, `animation`, `animation-duration`, `animation-fps`, `animation-style`, `application-specific-configuration-schema`, `border`, `border-colour`, `border-offset`, `border-width`, `cancel-preselect`, `change-layout`, `clear-all-workspace-rules`, `clear-named-workspace-layout-rules`, `clear-named-workspace-rules`, `clear-session-float-rules`, `clear-workspace-layout-rules`, `clear-workspace-rules`, `close`, `close-workspace`, `configuration`, `container-padding`, `cross-monitor-move-behaviour`, `cycle-empty-workspace`, `cycle-focus`, `cycle-layout`, `cycle-monitor`, `cycle-move`, `cycle-move-to-monitor`, `cycle-move-to-workspace`, `cycle-move-workspace-to-monitor`, `cycle-send-to-monitor`, `cycle-send-to-workspace`, `cycle-stack`, `cycle-stack-index`, `cycle-workspace`, `data-directory`, `disable-autostart`, `display-index-preference`, `docgen`, `eager-focus`, `enable-autostart`, `enforce-workspace-rules`, `ensure-named-workspaces`, `ensure-workspaces`, `flip-layout`, `focus`, `focus-last-workspace`, `focus-monitor`, `focus-monitor-at-cursor`, `focus-monitor-workspace`, `focus-named-workspace`, `focus-stack-window`, `focus-workspace`, `focus-workspaces`, `focused-workspace-container-padding`, `focused-workspace-padding`, `generate-static-config`, `global-state`, `global-work-area-offset`, `ignore-rule`, `initial-named-workspace-rule`, `initial-workspace-rule`, `layout-ratios`, `load-resize`, `log`, `manage`, `manage-rule`, `minimize`, `monitor-information`, `monitor-work-area-offset`, `monocle-focus-behaviour`, `mouse-follows-focus`, `move`, `move-to-last-workspace`, `move-to-monitor`, `move-to-monitor-workspace`, `move-to-named-workspace`, `move-to-workspace`, `move-workspace-to-monitor`, `named-workspace-container-padding`, `named-workspace-layout`, `named-workspace-layout-rule`, `named-workspace-padding`, `named-workspace-rule`, `named-workspace-tiling`, `new-workspace`, `notification-schema`, `preselect-direction`, `promote`, `promote-focus`, `promote-swap`, `promote-window`, `query`, `quick-load-resize`, `quick-save-resize`, `quickstart`, `replace-configuration`, `resize-axis`, `resize-delta`, `resize-edge`, `retile`, `save-resize`, `scrolling-layout-columns`, `send-to-last-workspace`, `send-to-monitor`, `send-to-monitor-workspace`, `send-to-named-workspace`, `send-to-workspace`, `session-float-rule`, `session-float-rules`, `socket-schema`, `stack`, `stack-all`, `start`, `state`, `static-config-schema`, `stop`, `subscribe-socket`, `swap-workspaces-with-monitor`, `toggle-cross-monitor-move-behaviour`, `toggle-float`, `toggle-float-override`, `toggle-lock`, `toggle-monocle`, `toggle-monocle-focus-behaviour`, `toggle-mouse-follows-focus`, `toggle-pause`, `toggle-tiling`, `toggle-window-based-work-area-offset`, `toggle-window-container-behaviour`, `toggle-workspace-float-override`, `toggle-workspace-layer`, `toggle-workspace-window-container-behaviour`, `unmanage`, `unmanaged-window-operation-behaviour`, `unstack`, `unstack-all`, `unsubscribe-socket`, `visible-windows`, `workspace-layout`, `workspace-layout-rule`, `workspace-name`, `workspace-padding`, `workspace-rule`, `workspace-tiling`, `workspace-work-area-offset`
<!-- /gen:commands-all3 -->
### kfde has the commands kfw has and kfm lacks, for the features it took from kfw
kfm has no counterpart for these. kfde has them because it has the feature:
<!-- gen:commands-adopted -->
| Command | What the help of kfw says |
|---|---|
| `check` | Check komorebi configuration and related files for common errors |
| `focus-follows-mouse` | Enable or disable focus follows mouse for the operating system |
| `toggle-focus-follows-mouse` | Toggle focus follows mouse for the operating system |
| `toggle-maximize` | Toggle native maximization for the focused window |
| `toggle-transparency` | Toggle transparency for unfocused windows |
| `transparency` | Enable or disable transparency for unfocused windows |
| `transparency-alpha` | Set the alpha value for unfocused window transparency |
<!-- /gen:commands-adopted -->
`focus-follows-mouse` and `toggle-focus-follows-mouse` are hidden from `--help` in kfw and kfde
alike.
### kfde has the command kfm has and kfw lacks
<!-- gen:commands-kfm -->
| Command | What it does |
|---|---|
| `completions` | Generate komorebic CLI completions for the target shell |
<!-- /gen:commands-kfm -->
### kfde has commands that neither has
These commands are about KDE: a key binding file is turned into KDE's global shortcuts, and the
keys the daemon registers itself are looked at and let go.
<!-- gen:commands-kde -->
| Command | What it does |
|---|---|
| `export-kde-shortcuts` | Turn an skhdrc into KDE global shortcuts (they work over RDP, unlike evdev hotkey daemons) |
| `hotkeys` | Key bindings: KDE global shortcuts from a key binding file, and the keys of the daemon |
<!-- /gen:commands-kde -->
[The user guide on key bindings](../usage/keybindings.md) describes them. `hotkeys` has
subcommands: `komorebic hotkeys compile` does what `export-kde-shortcuts` does for all three
formats, and `state`, `reload` and `release` act on the keys the daemon has registered.
### kfde does not start helper programs
`komorebic start` of kfw can start whkd, AutoHotkey, the bar and masir along with the daemon. In
kfde the daemon reads the key binding files itself and there is no bar, so `start` has one flag the
others share and none of the flags that launch another program:
<!-- gen:commands-flags -->
| Command | Flag | kfw | kfm | kfde |
|---|---|---|---|---|
| `start` | `--ahk` | yes | - | - |
| `start` | `--await-configuration` | yes | - | - |
| `start` | `--bar` | yes | yes | - |
| `start` | `--clean-state` | yes | - | - |
| `start` | `--config` | yes | yes | yes |
| `start` | `--ffm` | yes | - | - |
| `start` | `--masir` | yes | - | - |
| `start` | `--tcp-port` | yes | - | - |
| `start` | `--whkd` | yes | - | - |
| `stop` | `--ahk` | yes | - | - |
| `stop` | `--bar` | yes | yes | - |
| `stop` | `--ignore-restore` | yes | yes | yes |
| `stop` | `--masir` | yes | - | - |
| `stop` | `--whkd` | yes | - | - |
| `check` | `--configuration-only` | - | no command | yes |
| `check` | `--komorebi-config` | yes | no command | yes |
<!-- /gen:commands-flags -->
### kfde has no counterpart for these commands
Every command that kfw or kfm has and kfde lacks is here, with the reason. A group that is a
"Win32 quirk" is a workaround for how Windows treats windows, which a Wayland compositor does not
need.
<!-- gen:commands-missing -->
| Group | Command | In | Why kfde has no counterpart |
|---|---|---|---|
| AutoHotkey and PowerShell | `ahk-app-specific-configuration` | kfw | Writes application rules for `komorebi.ahk`. |
| AutoHotkey and PowerShell | `complete-configuration` | kfw | Part of the legacy `komorebi.ahk` and `komorebi.ps1` configurations. |
| AutoHotkey and PowerShell | `pwsh-app-specific-configuration` | kfw | Writes application rules for a PowerShell script. |
| AutoHotkey and PowerShell | `reload-configuration` | kfw | Part of the legacy `komorebi.ahk` and `komorebi.ps1` configurations. |
| AutoHotkey and PowerShell | `watch-configuration` | kfw | Part of the legacy `komorebi.ahk` and `komorebi.ps1` configurations. `komorebi.json` is watched always. |
| Win32 quirks | `alt-focus-hack` | kfw | Works around the rules Windows has for taking the foreground. |
| Win32 quirks | `force-focus` | kfw | Works around the rules Windows has for taking the foreground. |
| Win32 quirks | `identify-layered-application` | kfw | A Win32 window style. There is no counterpart in a Wayland compositor. |
| Win32 quirks | `identify-object-name-change-application` | kfw | A Win32 event some applications send on launch. |
| Win32 quirks | `identify-tray-application` | kfw | A Win32 notion: an application that closes to the system tray. |
| Windows tooling | `bar-configuration` | kfw | `komorebi-bar` is not ported: the Plasma panel is used, and the work area accounts for it. |
| Windows tooling | `gui` | kfw | Launches `komorebi-gui`, which is not ported. |
| Windows tooling | `kill` | kfw | Stops the helper programs `komorebic start` launches on Windows (whkd, AutoHotkey, the bar, masir). It launches none on KDE. |
| Windows tooling | `toggle-shortcuts` | kfw | Toggles `komorebi-shortcuts`, which is not ported. |
| Windows tooling | `whkdrc` | kfw | Shows the path of the whkd file. The daemon reads key binding files itself. |
| borders | `border-implementation` | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| borders | `border-style` | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| borders | `identify-border-overflow-application` | kfw | A border window that overflows is a Win32 problem. The compositor draws the border. |
| borders | `invisible-borders` | kfw | The size of the invisible frame Windows adds around a window. |
| custom layouts | `load-custom-layout` | kfw | Not supported yet. |
| custom layouts | `named-workspace-custom-layout-rule` | kfw | Not supported yet. |
| custom layouts | `named-workspace-custom-layout` | kfw | Not supported yet. |
| custom layouts | `workspace-custom-layout-rule` | kfw | Not supported yet. |
| custom layouts | `workspace-custom-layout` | kfw | Not supported yet. |
| hiding | `restore-windows` | kfw | Debugging command for windows komorebi hid itself. On KDE `stop` and the next start send parked windows home. |
| hiding | `window-hiding-behaviour` | kfw | One native mechanism hides windows, so there is nothing to choose. |
| kfm scrolling strip | `center-focus` | kfm | Belongs to the scrolling strip of kfm (`komorebi-scrolling`). The Scrolling layout of kfde is the one of `komorebi-layouts`. |
| kfm scrolling strip | `consume` | kfm | Belongs to the scrolling strip of kfm (`komorebi-scrolling`). |
| kfm scrolling strip | `expel` | kfm | Belongs to the scrolling strip of kfm (`komorebi-scrolling`). |
| kfm scrolling strip | `scrolling-layout-full-width` | kfm | Belongs to the scrolling strip of kfm (`komorebi-scrolling`). |
| kfm scrolling strip | `toggle-column-stack` | kfm | Belongs to the scrolling strip of kfm (`komorebi-scrolling`). |
| license | `license` | kfw and kfm | No license check was ported. |
| license | `splash` | kfw and kfm | No splash screen was ported. |
| macOS | `permissions` | kfm | Shows the System Settings dialogs macOS asks for. KDE asks for none. |
| monitors | `monitor-index-preference` | kfw | Identifies a monitor by its size. kfde has `display-index-preference`, which names the display, as kfm does. |
| named pipes | `subscribe-pipe` | kfw | A named pipe is a Windows facility. Subscribers use a Unix domain socket. |
| named pipes | `unsubscribe-pipe` | kfw | A named pipe is a Windows facility. Subscribers use a Unix domain socket. |
| stackbar | `stackbar-mode` | kfw | komorebi draws the tab bar of a stack on Windows. KDE has no counterpart; a stack is cycled with `cycle-stack` and `focus-stack-window`. |
| title bars | `remove-title-bar` | kfw | A window without a title bar has no shadow in KWin, and so no border. |
| title bars | `toggle-title-bars` | kfw | A window without a title bar has no shadow in KWin, and so no border. |
| upstream applications file | `convert-app-specific-configuration` | kfw | Maintains the YAML file of the Windows applications list. |
| upstream applications file | `fetch-app-specific-configuration` | kfw and kfm | Not supported yet: there is no applications file for KDE upstream, so there is nothing to fetch. |
| upstream applications file | `format-app-specific-configuration` | kfw | Maintains the YAML file of the Windows applications list. |
<!-- /gen:commands-missing -->
The groups "hiding", "borders" and "title bars" are Windows workarounds that KDE does natively,
which is the reason the project recorded when it decided not to port them
([DESIGN.md](DESIGN.md#what-is-komorebi-for-kde-the-port-of)). The other reasons say what the code
of kfw and kfm shows each command is for. For "upstream applications file": at time of writing
(2026-10-28) no applications file for KDE exists upstream, so `fetch-app-specific-configuration`
has nothing to fetch. The configuration key that points at a file of application rules works (see
the section on keys), and the user supplies the file.
## The socket protocol
The messages that `komorebi-client` sends are the variants of `SocketMessage`. The counts follow
the ones of the commands, since nearly every command is one message.
<!-- gen:messages-counts -->
| | kfw | kfm | kfde |
|---|---|---|---|
| `SocketMessage` variants | 187 | 153 | 156 |
| In all three | 148 | 148 | 148 |
| In kfde and kfw, not kfm | 6 | - | 6 |
| In kfde and kfm, not kfw | - | 0 | 0 |
| Only in kfde | - | - | 2 |
| In kfw or kfm, not in kfde | 33 | 5 | - |
<!-- /gen:messages-counts -->
Of the messages kfde has, these are not in both of the other programs:
<!-- gen:messages-only -->
- Only in kfde: `HotkeysState`, `ReloadHotkeys`.
- In kfde and kfw, not in kfm: `FocusFollowsMouse`, `ToggleFocusFollowsMouse`, `ToggleMaximize`, `ToggleTransparency`, `Transparency`, `TransparencyAlpha`.
- In kfde and kfm, not in kfw: none.
<!-- /gen:messages-only -->
The two messages that only kfde has are the ones behind `komorebic hotkeys state` and
`komorebic hotkeys reload`. The names of the variants are the same in the programs that share them.
Whether every variant has the same payload in the three programs was not compared. Subscribers use
a Unix domain socket, as in kfm and, next to named pipes, in kfw.
## Configuration
### kfde reads the keys of komorebi.json that both others read
The counts, by struct of `static_config.rs`. "Not read by kfde" is the number of keys that kfw or
kfm has and kfde does not:
<!-- gen:keys-counts -->
| Struct | kfw | kfm | kfde | All three | kfw and kfde | kfm and kfde | kfde only | Not read by kfde |
|---|---|---|---|---|---|---|---|---|
| `StaticConfig` (top level) | 53 | 34 | 37 | 30 | 4 | 3 | 0 | 20 |
| `WorkspaceConfig` (workspace) | 22 | 19 | 20 | 19 | 1 | 0 | 0 | 2 |
| `MonitorConfig` (monitor) | 8 | 9 | 9 | 8 | 0 | 1 | 0 | 0 |
| Total | 83 | 62 | 66 | 57 | 5 | 4 | 0 | 22 |
<!-- /gen:keys-counts -->
The keys that kfw, kfm and kfde all read, which mean the same, apart from what the next
sections say:
<!-- gen:keys-same -->
- top level (`StaticConfig`): `animation`, `app_specific_configuration_path`, `border`, `border_colours`, `border_offset`, `border_width`, `cross_boundary_behaviour`, `cross_monitor_move_behaviour`, `default_container_padding`, `default_workspace_padding`, `display_index_preferences`, `float_override`, `float_override_placement`, `float_rule_placement`, `floating_applications`, `floating_layer_behaviour`, `floating_layer_placement`, `floating_window_aspect_ratio`, `global_work_area_offset`, `ignore_rules`, `layout_defaults`, `manage_rules`, `monitors`, `monocle_focus_behaviour`, `mouse_follows_focus`, `resize_delta`, `theme`, `toggle_float_placement`, `unmanaged_window_operation_behaviour`, `window_container_behaviour`.
- workspace (`WorkspaceConfig`): `apply_window_based_work_area_offset`, `container_padding`, `float_override`, `floating_layer_behaviour`, `initial_workspace_rules`, `layout`, `layout_flip`, `layout_options`, `layout_options_rules`, `layout_rules`, `name`, `tile`, `wallpaper`, `window_container_behaviour`, `window_container_behaviour_rules`, `work_area_offset`, `work_area_offset_rules`, `workspace_padding`, `workspace_rules`.
- monitor (`MonitorConfig`): `container_padding`, `floating_layer_behaviour`, `wallpaper`, `window_based_work_area_offset`, `window_based_work_area_offset_limit`, `work_area_offset`, `workspace_padding`, `workspaces`.
<!-- /gen:keys-same -->
### kfde reads keys from kfw and keys from kfm
kfde reads the keys kfw has for the features it took from kfw, and the ones kfm has that kfw does
not:
<!-- gen:keys-adopted -->
| Key | Level | Also in | What it is |
|---|---|---|---|
| `focus_follows_mouse` | top level | kfw | Focus the window under the pointer. |
| `transparency` | top level | kfw | Add transparency to unfocused windows (default: false) |
| `transparency_alpha` | top level | kfw | Alpha value for unfocused window transparency [[0-255]] (default: 200) |
| `transparency_ignore_rules` | top level | kfw | Individual window transparency ignore rules |
| `border_radius` | top level | kfm | Radius of window borders |
| `tabbed_applications` | top level | kfm | Accepted so that a configuration written for another platform loads, and ignored: a KWin window has no native tabs |
| `titleless_applications` | top level | kfm | Accepted so that a configuration written for another platform loads, and ignored: a KWin window is always a window |
| `initial_window_placement_rules` | workspace | kfw | Initial window placement rules that determine where new tiled windows are placed in the container list. |
| `window_hiding_position` | monitor | kfm | Accepted so that a configuration written for another platform loads, and ignored: there is no hiding position on KDE Plasma |
<!-- /gen:keys-adopted -->
### No key of komorebi.json is read only on KDE
<!-- gen:keys-kde-only -->
none
<!-- /gen:keys-kde-only -->
That is by decision: a file should load on every platform that has the feature
([why](DESIGN.md#why-does-one-komorebijson-work-on-every-platform)). The keys that mean something
else on KDE, or do less, are these:
<!-- gen:keys-differ -->
| Key | Level | What is different on KDE |
|---|---|---|
| `border_width` | top level | At most 20 px: the effect draws the ring in the window's shadow, and a window without a shadow has none. While borders are drawn, the layout leaves `border_width` plus `border_offset` on each side of a window, also past 20. |
| `border_colours` | top level | Six colors, one for each kind of window, when komorebi's build of the border effect is installed. With the stock effect only `single` and `unfocused` take effect, and komorebi says so once in its log. |
| `animation` | top level | `style` is the Qt easing curve of that name (`EaseInOutSine` is `InOutSine`) and a custom cubic Bezier curve is an ease out, when komorebi's build of the Geometry Change effect is installed; the stock effect always eases out exponentially. `fps` is read and ignored: the compositor animates at the refresh rate of the screen. |
| `focus_follows_mouse` | top level | Both implementations kfw names (`Windows` and `Komorebi`) ask KWin for the same thing: its focus policy, put back as the user had it when it is turned off or komorebi exits. |
| `transparency` | top level | KWin's window opacity, set for the unfocused windows of each monitor's shown workspace by kfw's rules (the focused window and a monocled one stay opaque). |
| `theme` | top level | A theme by name or a palette of your own gives the six border colors, and the palette of a wallpaper takes over from it when its workspace is shown. |
| `wallpaper` | workspace | Set through the Plasma shell, which keeps one wallpaper for each screen and not for each desktop, so komorebi changes it as the workspace in front changes. The picture fills the screen. |
| `workspaces` | monitor | Workspace `i` is KWin's desktop `i` on every monitor, so every monitor has as many desktops as the largest workspace count, and where the names differ the desktop takes the first monitor's. |
| `app_specific_configuration_path` | top level | Read as in kfm and kfw. There is no applications file for KDE upstream, so komorebi has none to download. |
<!-- /gen:keys-differ -->
### Some keys are read and do nothing on KDE
They are read so that a file written for another platform loads, and `komorebic check` lists them
once as accepted and ignored:
<!-- gen:keys-no-effect -->
| Key | Level | Also in | Effect on KDE |
|---|---|---|---|
| `tabbed_applications` | top level | kfm | Read, so that a file written for kfm loads, and does nothing on KDE. |
| `titleless_applications` | top level | kfm | Read, so that a file written for kfm loads, and does nothing on KDE. |
| `window_hiding_position` | monitor | kfm | Read, so that a file written for kfm loads, and does nothing on KDE. |
| `animation.fps` | nested | kfw, kfm | Read, and ignored: the compositor animates at the refresh rate of the screen. |
<!-- /gen:keys-no-effect -->
### Some keys are not read at all
These are keys of kfw or kfm that kfde does not have. They are not an error: serde skips a key it
does not know, so the file loads, and `komorebic check` tells them apart from a typo.
<!-- gen:keys-not-read -->
| Key | Level | In | Why kfde does not read it |
|---|---|---|---|
| `bar_configurations` | top level | kfw | `komorebi-bar` is not ported. |
| `border_implementation` | top level | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| `border_overflow_applications` | top level | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| `border_style` | top level | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| `border_z_order` | top level | kfw | How a Win32 border window is drawn. The compositor draws the border. |
| `invisible_borders` | top level | kfw | The size of the invisible frame Windows adds around a window. |
| `layered_applications` | top level | kfw | A Win32 window style. There is no counterpart in a Wayland compositor. |
| `minimum_window_height` | top level | kfw | Marked DISCOURAGED in komorebi for Windows. Commented out in kfde. |
| `minimum_window_width` | top level | kfw | Marked DISCOURAGED in komorebi for Windows. Commented out in kfde. |
| `monitor_index_preferences` | top level | kfw | Identifies a monitor by its size. kfde reads `display_index_preferences`, which names the display, as kfm does. |
| `object_name_change_applications` | top level | kfw | A Win32 event some applications send on launch. |
| `object_name_change_title_ignore_list` | top level | kfw | A Win32 event some applications send on launch. |
| `remove_titlebar_applications` | top level | kfw | A window without a title bar has no shadow in KWin, and so no border. |
| `scrolling` | top level | kfm | The `ScrollingConfig` of the strip in kfm (`komorebi-scrolling`). kfde has the Scrolling layout of `komorebi-layouts`, tuned with `layout_options`. |
| `slow_application_compensation_time` | top level | kfw | A Win32 workaround for applications that are slow to move. |
| `slow_application_identifiers` | top level | kfw | A Win32 workaround for applications that are slow to move. |
| `stackbar` | top level | kfw | KDE has no counterpart of the tab bar komorebi draws on Windows. |
| `tray_and_multi_window_applications` | top level | kfw | A Win32 notion: an application that closes to the system tray. |
| `window_handling_behaviour` | top level | kfw | A Win32 quirk of how windows are moved. |
| `window_hiding_behaviour` | top level | kfw | One native mechanism hides windows, so there is nothing to choose. |
| `custom_layout` | workspace | kfw | Custom layouts are not supported yet. |
| `custom_layout_rules` | workspace | kfw | Custom layouts are not supported yet. |
<!-- /gen:keys-not-read -->
The nested structs have the same keys, except for these:
<!-- gen:keys-nested -->
| Struct | kfw | kfm | kfde | In kfw, not kfde | In kfm, not kfde |
|---|---|---|---|---|---|
| `BorderColours` | 6 | 6 | 6 | - | - |
| `ThemeOptions` | 11 | 8 | 8 | `stackbar_background`, `stackbar_focused_text`, `stackbar_unfocused_text` | - |
| `Wallpaper` | 3 | 3 | 3 | - | - |
| `AnimationsConfig` | 5 | 4 | 4 | `ghost_movement` | - |
<!-- /gen:keys-nested -->
There is one more difference that is not a key. kfm has a scrolling strip, with columns that
hold several windows, a `scrolling` key and the commands in the "kfm scrolling strip" group above.
kfde has the `Scrolling` layout of `komorebi-layouts`, tuned with `layout_options` and the command
`scrolling-layout-columns`, which kfw and kfm have too. A `scrolling` key in a file written for kfm
is skipped by kfde.
## Events, and what drives them
The window manager reacts to events about windows. In kfw the operating system raises them, through
`SetWinEventHook`, and in kfm through the accessibility API and the notification center. In kfde
the script in KWin connects to the signals of KWin's `workspace` and of each window and sends every
one to the daemon as a JSON string over D-Bus. The daemon turns a signal into a
`WindowManagerEvent`, the way kfw and kfm turn what they get.
<!-- gen:event-sources -->
| Tree | What the OS layer reports | Kinds |
|---|---|---|
| kfw | `WinEvent`, the events of `SetWinEventHook` | 84 |
| kfm | `AccessibilityNotification` and `AppKitWorkspaceNotification` | 41 and 21 |
| kfde | `KWinNotification`, the signals of the KWin script | 16 |
<!-- /gen:event-sources -->
The events follow kfw's model: each is about a window, and a window is a small `Copy` handle. kfm's
events carry a process id and a window id instead. The table puts the events of kfde next to the
ones of the other two that play the same part:
<!-- gen:events -->
| kfde event | Source on KDE | kfw | kfm |
|---|---|---|---|
| `Show` | `workspace.windowAdded` | `Show`, `Uncloak` | `Show` |
| `Destroy` | `workspace.windowRemoved` | `Destroy` | `Destroy` |
| `FocusChange` | `workspace.windowActivated` | `FocusChange`, `Raise` | `FocusChange` |
| `Minimize` | `window.minimizedChanged`, to true | `Minimize` | `Minimize` |
| `Restore` | `window.minimizedChanged`, to false | - | `Restore` |
| `TitleUpdate` | `window.captionChanged` | `TitleUpdate` | - |
| `Manage` | komorebi itself (`manage`, a rule) | `Manage` | `Manage` |
| `Unmanage` | komorebi itself (`unmanage`, a rule) | `Unmanage` | `Unmanage` |
| `MoveStart` | `window.interactiveMoveResizeStarted`, for a move | `MoveResizeStart` | `MoveStart` |
| `MoveEnd` | `window.interactiveMoveResizeFinished`, after a move | `MoveResizeEnd` | `MoveEnd` |
| `ResizeStart` | `window.interactiveMoveResizeStarted`, for a resize | `MoveResizeStart` | `ResizeStart` |
| `ResizeEnd` | `window.interactiveMoveResizeFinished`, after a resize | `MoveResizeEnd` | `ResizeEnd` |
| `ResizeStep` | `window.interactiveMoveResizeStepped` | - | - |
| `WorkspaceChange` | `workspace.currentDesktopChanged` | - | `SpaceChange` |
| `WorkspaceMove` | `window.desktopsChanged` | - | - |
| `OutputChange` | `window.outputChanged` | - | - |
| `MaximizeChange` | `window.maximizedChanged` | - | - |
| `FullscreenChange` | `window.fullScreenChanged` | - | - |
| Event with no counterpart in kfde | In | Why |
|---|---|---|
| `Hide` | kfw | Win32 hides and cloaks windows; kfde has no counterpart because KWin shows and hides windows by desktop, and says so with `WorkspaceChange`. |
| `Cloak` | kfw | Win32 hides and cloaks windows; kfde has no counterpart because KWin shows and hides windows by desktop, and says so with `WorkspaceChange`. |
| `MouseCapture` | kfw | Windows tells komorebi that a mouse button went down on a window. KWin reports the start of a move or resize instead. |
| `ScreenLock` | kfm | KDE locks and unlocks the screen with `org.freedesktop.ScreenSaver`; komorebi hears it in `kwin/power.rs` and reconciles, with no event of this kind. |
| `ScreenUnlock` | kfm | KDE locks and unlocks the screen with `org.freedesktop.ScreenSaver`; komorebi hears it in `kwin/power.rs` and reconciles, with no event of this kind. |
<!-- /gen:events -->
Three things about this are worth knowing:
- A signal reaches the daemon in 0 to 1 ms, from `Date.now()` in the script to the receipt in the
daemon ([the spikes](PLATFORM.md#vocabulary), 2026-10-26, KWin 6.8.1 in a virtual machine on
HVF).
- KWin emits `windowActivated` before `windowAdded` for a new window, so the script announces the
window from the activation, and no event mentions a window before the event that adds it.
- The script contains no logic. [Why](DESIGN.md#why-does-the-bridge-hold-no-logic) and
[why the commands come back to the script as the answer to a held call](DESIGN.md#why-do-commands-go-to-the-bridge-as-the-answer-to-a-held-call)
are in DESIGN.md.
### What the operating system layer is
kfw calls Win32 from `WindowsApi`, kfm calls the accessibility API and Core Graphics from
`MacosApi` and its modules. kfde puts the whole of what the window manager needs behind one trait,
`Backend`, which a test replaces with `FakeBackend` (a desktop in memory). The sizes are not a
measure of the effort: the Win32 and macOS calls are scattered over more modules than the ones the
counts name.
<!-- gen:backend-counts -->
| Tree | The operating system layer | Size |
|---|---|---|
| kfw | `WindowsApi` in `windows_api.rs` | 92 public functions |
| kfm | `MacosApi` in `macos_api.rs`, and the `accessibility`, `core_graphics` and `skylight` modules | 14 public functions in `MacosApi` |
| kfde | `Backend`, with `FakeBackend` for tests and `KWinBackend` for KWin | 31 methods (27 are required, 4 are provided), and a script of 684 lines that runs inside KWin |
<!-- /gen:backend-counts -->
What each method of `Backend` is on KDE, and the function of kfw and kfm that does the same job,
where there is one:
<!-- gen:backend -->
| `Backend` method | On KDE | kfw function | kfm function |
|---|---|---|---|
| `windows` | `workspace.windowList()` once, then the events of the bridge | `enum_windows` | `window_elements` |
| `window` | the table the bridge keeps, fed by events | `window_rect`, `exe_path` | `window_by_title` |
| `foreground_window` | `workspace.activeWindow` | `foreground_window` | `foreground_window` |
| `monitors` | `workspace.screens` and `clientArea(KWin.PlacementArea, ...)`, which leaves out the panel | `load_monitor_information` | `load_monitor_information` |
| `cursor_pos` | `workspace.cursorPos` | `cursor_pos` | `cursor_pos` |
| `drag_origin` | the frame the bridge saw at `interactiveMoveResizeStarted` | none | none |
| `drag_end` | the frame the bridge saw at the last `interactiveMoveResizeStepped` | none | none |
| `set_rect` | `frameGeometry`, and a second request for the position once the size settles | `position_window` | `set_position` |
| `focus` | `workspace.activeWindow = w` | `raise_and_focus_window` | `focus` |
| `raise` | `workspace.raiseWindow(w)` | `raise_window` | `raise` |
| `hide` | moves the window to the parking desktop (`desktops`) | `hide_window` | `hide` |
| `restore` | moves the window back from the parking desktop (`desktops`) | `restore_window` | `restore` |
| `minimize` | `minimized = true` | `minimize_window` | `minimize` |
| `unminimize` | `minimized = false` | `restore_window` | `unminimize` |
| `close` | `closeWindow()` | `close_window` | `close` |
| `center_cursor_in` | the "Move Mouse to Focus" action (`MoveMouseToFocus`) | `center_cursor_in_rect` | `center_cursor_in_rect` |
| `ensure_workspaces` | `createDesktop` on `org.kde.KWin.VirtualDesktopManager` | none | none |
| `switch_workspace` | `setCurrentDesktopForScreen` | none | none |
| `set_window_workspace` | `desktops` of the window | none | none |
| `window_workspace` | `desktops` of the window | none | none |
| `current_workspaces` | `currentDesktopForScreen` | none | none |
| `apply_look` | writes the effects' groups of `kwinrc`, `loadEffect` and `reconfigureEffect` | none | none |
| `set_border_colours` | `org.komorebi.BorderColours1`, which only komorebi's build of the border effect has | none | none |
| `set_opacity` | `opacity` | `set_transparent` | none |
| `set_focus_follows_mouse` | the `FocusPolicy` of `kwinrc`, then `reconfigure` | `enable_focus_follows_mouse` | none |
| `set_wallpaper` | `org.kde.PlasmaShell` `setWallpaper` | `set_wallpaper` | `set_wallpaper` |
| `maximize` | `setMaximize` | `maximize_window` | none |
<!-- /gen:backend -->
A method with "none" in both columns is something kfw and kfm do not need an operating system call
for, because the window manager keeps its own workspaces there, or something they do not have.
[Why everything is behind one trait](DESIGN.md#why-is-everything-the-window-manager-needs-behind-one-trait)
is in DESIGN.md.
## What KDE does by itself
The table lists what kfw and kfm do themselves and what KDE does, for the features where the
compositor, the shell or the desktop has a mechanism of its own. The sections below say what is
different for each.
<!-- gen:native -->
| What | kfw | kfm | On KDE |
|---|---|---|---|
| Workspaces | komorebi's own workspaces; the windows of the other workspaces are hidden | komorebi's own workspaces; the windows of the other workspaces are hidden | KWin's virtual desktops, one set per output (Plasma 6.8): workspace `i` is desktop `i` on every monitor |
| Hiding windows (a stack, a monocle) | `window_hiding_behaviour`: cloak, hide or minimize | moves the window to a corner of the screen | a virtual desktop nobody looks at (`komorebi-park`) |
| Borders | a topmost tool window per border, drawn by komorebi with Direct2D | an `NSWindow` per border, drawn by komorebi | the KDE Rounded Corners effect, with komorebi's patch for one color per kind of window |
| Animation | komorebi moves the window step by step | komorebi moves the window step by step | the Geometry Change effect, with komorebi's patch for the easing curve |
| Transparency of unfocused windows | `SetLayeredWindowAttributes`, called by komorebi | no key or command | KWin's window opacity, through the same patched effect as the borders |
| Focus follows mouse | the Windows setting, or komorebi's own implementation (`focus_follows_mouse`) | no key or command | KWin's focus policy; the user's policy is put back when it is turned off or komorebi exits |
| Maximize | `toggle-maximize`: the Win32 maximize | no key or command | `toggle-maximize`: KWin's maximize, which respects the panel. A window the user maximizes is taken out of the layout until restored |
| Fullscreen windows | no handling of its own in the sources | no handling of its own, except that the reaper keeps a window that fails to move | left alone, and put back in its tile when it leaves fullscreen |
| Wallpapers | the desktop wallpaper of each monitor | the desktop picture of each display | the Plasma shell, asked over D-Bus, one wallpaper per screen |
| Hotkeys | a separate program: `whkd` (or AutoHotkey) | a separate program: `skhd` | KDE global shortcuts: `.desktop` files for plain bindings, and the daemon through KGlobalAccel for modes, chords and scopes |
| Monitors added, removed or changed | a reconciliator thread, fed by `WM_DISPLAYCHANGE` in a hidden window | a reconciliator thread, fed by the display reconfiguration callback | the same thread, fed by the script (when KWin's list of outputs changes) and by `kwin/power.rs`; `reconcile.rs` follows the windows the compositor moved |
| Sleep, wake and lock | power setting and session notifications (`register_power_setting_notification`, `wts_register_session_notification`) | `ScreenLock` and `ScreenUnlock` events | `PrepareForSleep` of logind and `ActiveChanged` of the KDE screen saver, on D-Bus |
| Reloading the configuration | `watch-configuration` is about `komorebi.ahk` and `komorebi.ps1`; `komorebi.json` is watched | `komorebi.json` is watched | `komorebi.json` is watched |
<!-- /gen:native -->
### Workspaces are KWin's virtual desktops
kfw and kfm have a workspace layer of their own: komorebi keeps a list of workspaces for each
monitor, and when one is left it hides the windows of that workspace, because Windows and macOS
have no virtual desktop API to ask. On KDE, KWin 6.8 can give each output its own current desktop,
so komorebi's workspace `i` is KWin's desktop `i` on every monitor, and each monitor shows one at a
time. A switch is one request per monitor, and KWin shows, hides and focuses. komorebi
follows a switch made by something else (the pager, a shortcut, an application raising a window)
and answers it with no command. [Why](DESIGN.md#why-are-komorebis-workspaces-kwins-virtual-desktops)
is in DESIGN.md.
This has consequences that are measured, or read from KWin's sources:
- A switch made by an application raising a window produces one focus event and one switch
(spike 10, 2026-10-27). Answering a switch with commands makes KWin and komorebi fight: a design
in which komorebi did the hiding flipped between two workspaces about 280 times a second, because
KWin delivered focus events it had generated before it applied the commands, and komorebi read
them as new intent. komorebi therefore issues no commands in reply to a switch.
- The workspaces are visible in the pager and in the overview: they are the user's desktops, and a
stop leaves them in place (it removes the parking desktop).
- Desktops are global: every monitor has as many as the largest workspace count, and the name of a
desktop is shared by the monitors (the first monitor's, where they differ).
- A window that komorebi does not manage (a dialog, an ignored application) belongs to the desktop it
opened on, and goes out of view with it. kfw and kfm hide what a workspace holds (its containers,
its floating windows and its monocle) when they leave it, so a window they do not manage stays
visible across workspaces.
- The floor is KWin 6.8, because per-output desktops arrived there. Older KWin versions were not
tested. At time of writing (2026-10-27) the version measured is 6.8.1, in Plasma 6.8.1.
- komorebi turns `PerOutputVirtualDesktops` on in `kwinrc` when it starts and puts it back when it
exits. It edits the file itself: `kwriteconfig6` was not on the path of the user service in the
first live run.
### Hiding windows: cloaking, a corner, or a parking desktop
komorebi hides windows for a stack (the other windows of a container) and for a monocle (the other
containers). kfw offers three ways, chosen with `window_hiding_behaviour`: cloak (an undocumented
Win32 call), minimize, and the end-of-life `SW_HIDE`. kfm moves the window to a bottom corner of
its display, which `window_hiding_position` of a monitor chooses. kfde moves the window to a
parking desktop and moves it back, and there is nothing to choose. The scrolling layout needs none
of this: KWin keeps a window at a position outside the screen when it is moved there.
Three ways were measured on six tiled windows (spike 3, 2026-10-26, KWin 6.8.1):
| Way | Spurious focus events | Geometry restored |
|---|---|---|
| minimize | 2 (KWin picks a new active window as each window minimizes) | 6 of 6 |
| parking desktop | 0 | 6 of 6 |
| a position outside the screen | 0, but the windows stay mapped on the current desktop (task switcher, overview) | 6 of 6 |
KWin saves a virtual desktop in `kwinrc` the moment it is made, so a run that dies leaves the
parking desktop for the next session. komorebi removes it on exit, and the next start finds a stale
one, sends its windows home and removes it. A parked window still appears in the task manager unless
that is set to show the current desktop only (by construction, not measured).
[Why a parking desktop](DESIGN.md#why-are-the-windows-behind-the-front-one-of-a-stack-moved-to-a-parking-desktop)
is in DESIGN.md.
### Borders: komorebi draws them, or the compositor does
kfw draws a topmost tool window for each border, with Direct2D, and kfm an `NSWindow` for each. kfde draws nothing: the
KDE Rounded Corners effect draws the outer outline of every window, and komorebi writes its settings
to `kwinrc` and tells it to read them again. KWin keeps the copy of `kwinrc` it read at start, so
komorebi asks for a reconfiguration every time, also straight after it loads the effect.
The limits, as of 2026-10-27:
- The ring is drawn in the window's shadow, so a window without a shadow has none, and its thickness
is at most 20 px. That is why kfde has no counterpart of `remove_titlebar_applications`: removing
the title bar removes the shadow.
- The stock effect has a color for the active window and one for the others. komorebi's build of it
takes a color for each window over D-Bus (`org.komorebi.BorderColours1`), which gives the six kinds
of kfw's rules: `single`, `stack`, `monocle`, `floating`, `unfocused` and `unfocused_locked`.
Without that build, every kind falls back to `single` and `unfocused`, and komorebi says so once in
its log.
- At time of writing (2026-10-27) nixpkgs has KDE Rounded Corners 0.10.0, which draws the ring about
24 px too low on KWin 6.8 (measured on screenshots of KWin 6.8.1). kfde builds 0.11.0 instead.
- KWin finds effects when it starts, so an effect installed later is not loaded until the next
login.
[Why the compositor draws the borders](DESIGN.md#why-does-the-compositor-draw-the-borders-and-not-komorebi),
[why the effects are patched](DESIGN.md#why-are-the-effects-patched) and
[why the border is the outer outline](DESIGN.md#why-is-the-border-the-outer-outline-of-the-effect)
are in DESIGN.md.
### Animation: komorebi moves the window step by step, or the compositor animates
kfw and kfm animate by moving the window a little at a time, at `animation.fps`. kfde sends the final
rectangle and the Geometry Change effect animates the move, so `fps` has nothing to map to: the
compositor animates at the refresh rate of the screen. The styles are Qt's easing curves of the same
name, which komorebi's build of the effect reads from a `Curve` setting. The stock effect eases out
exponentially, whatever the style says. Cross-fading is off.
KWin refuses effects that animate under software rendering, which includes every virtual machine the
tests run in, unless `KWIN_EFFECTS_FORCE_ANIMATIONS=1` is in KWin's environment. A screenshot cannot
show a short animation, because `spectacle` takes seconds and the curve is front-loaded: the look test
uses a 30 s animation to see the effect at work.
### Transparency, themes and wallpapers
Transparency is KWin's window opacity, set from the same rules as kfw. A window drawn through the
border effect comes from a texture with its opacity in it, which the effect redrew only when the
contents changed. komorebi's build redraws it when the opacity changes.
A wallpaper is set through the Plasma shell, over D-Bus (`org.kde.PlasmaShell`), for one screen. The
shell keeps one wallpaper for each screen, not for each virtual desktop, so komorebi sets it when a
workspace comes into view, as kfw and kfm do. If the shell is not running, komorebi tries again for
about half a minute and then says once that it leaves wallpapers alone. A palette made from a
wallpaper is cached in `$XDG_CACHE_HOME/komorebi`, by the name of the picture and a hash of its
path, size and time of change; a large picture takes seconds (not measured further).
### Focus follows mouse
kfw has two implementations to choose from, `Windows` and `Komorebi`, and calls the first legacy. kfm
has none. kfde asks KWin to use its focus policy, "focus follows mouse", with the same result for
both names, and puts the user's policy back when the setting is turned off or komorebi exits. KWin
waits for the pointer to settle before it moves the focus: `DelayFocusInterval`, 300 ms by default
in KWin 6.8.1. kfde sets it to 0 while the setting is on, and puts the user's value back with the
policy; why 0 is not recorded
([DESIGN.md](DESIGN.md#why-is-focus-follows-mouse-kwins-own-focus-policy)).
### Maximize and fullscreen
`toggle-maximize` is kfw's command, and does KWin's maximize on KDE: the window leaves the layout
and goes back to its tile when toggled again, and the panel is respected. A window that the user
maximizes (the title bar, a double click, a shortcut) is the same from then on: the commands that act
on the layout do nothing until it is restored. [Why](DESIGN.md#why-does-a-maximized-window-leave-the-layout-instead-of-being-given-the-work-area)
is in DESIGN.md. A fullscreen window covers its monitor, komorebi never moves it, and it is put back
in its tile when it leaves fullscreen. kfw has no code for fullscreen, and kfm has one
mention of it in its reaper.
## Dragging
All three programs let the user move a tile by dragging it and resize it by dragging an edge. KWin
reports where the pointer has the edge at every step of a resize
(`interactiveMoveResizeStepped`), so in kfde the neighbors follow the edge while it is dragged, and
not only when it is let go. The way a drag is measured, from the frame the window had when the drag
began, and granted as far as the layout can take it, is written down in
[drag-resize.md](../drag-resize.md), for the three programs. The frame KWin reports at the end of a
resize lags the pointer by a moment ([PLATFORM.md](PLATFORM.md#how-clients-answer-a-frame)). kfm
reads the frame of a window with an accessibility call when it needs it (`MacosApi::window_rect`);
whether that frame lags was not measured.
## Key bindings
kfw and kfm leave the keys to a separate program: kfw uses whkd, or AutoHotkey, kfm uses skhd, and
the program runs `komorebic`. On Plasma under Wayland no program sees the keys of another, so kfde
cannot do that: the keys are KDE's global shortcuts, in one of two ways, and komorebi reads the same
three formats a hotkey daemon would (`skhdrc`, `whkdrc`, `sxhkdrc`).
| | kfw | kfm | kfde |
|---|---|---|---|
| Who sees the keys | whkd, or AutoHotkey | skhd | KWin, through KDE's global shortcuts |
| The file the user writes | `whkdrc` | `skhdrc` | `skhdrc`, `whkdrc` or `sxhkdrc`, each read by a parser written for komorebi |
The measurements that decide when each is used, at time of writing (2026-10-27), on aarch64 under HVF
with four cores, KWin 6.8.1:
| What | Result |
|---|---|
| A static shortcut, key to the start of its `Exec` | 165 to 436 ms, median 233 ms, 8 runs of 8 |
| The daemon, key to the signal it gets | median 2.5 ms (min 2.2, max 3.9), 20 of 20 delivered |
| 60 calls to `setInactive` and `setShortcutKeys`, pipelined | answered in 2.4 ms in total |
| A native multi-key shortcut (`Meta+A, B`) | did not fire: the second key reached the focused client |
| A client killed after registering a key | the grab stays, and the key is swallowed, until `unRegister` |
The last two are why the daemon emulates chord chains, and why the module's unit releases the keys
when the daemon stops. A static shortcut works with the daemon stopped and shows in System Settings,
but costs about 0.2 seconds on each press; the daemon's keys are only as reliable as the daemon. The
default mode is the daemon for every binding (`keybindings.mode = "engine"`), which these
measurements favor ([why](DESIGN.md#why-does-the-engine-handle-every-binding-by-default), which
also says that the default is still open for a decision), and `auto` and `static` use shortcut
files for the bindings that can be one.
What is not emulated, and approximated, is listed in
[the user guide](../usage/keybindings.md#what-is-realized-and-what-is-not): side-specific modifiers,
mouse buttons, skhd's `fn`, and the sxhkd chain that a wrong key does not end. The reasons are in
DESIGN.md: [why some bindings are shortcut files](DESIGN.md#why-are-some-bindings-shortcut-files-and-the-others-the-engines)
and [why the engine grabs keys instead of using KDE's key sequences](DESIGN.md#why-does-the-engine-grab-and-give-back-keys-instead-of-using-kdes-own-key-sequences).
Keystrokes over RDP: KDE's shortcuts sit inside KWin's input pipeline and see them, and `swhkd`
reads the kernel's input devices and would not (read from the sources of KRDP and swhkd, not run).
Keys sent over RDP to a session were not verified end to end: the scripted client fails NTLM
against KRDP, and a real client was not tried.
## Multiple monitors, sleep and lock
All three programs have a monitor reconciliator: a thread that takes notifications one at a time to
move the windows of a monitor that went away and to bring them back. In kfw a hidden window
(`WM_DISPLAYCHANGE`) feeds it, and in kfm a display reconfiguration callback. In kfde the script feeds
it, with the whole list of outputs whenever KWin's changes, and so does the code that hears of a wake
or an unlock. The daemon takes the windows of an unplugged monitor over (each container, a stack whole, to the workspace of the same number), keeps what is left
of the monitor for when it comes back, and follows a window that something else moved to another
output. A moment after each notification (1.5 s) it looks at every window again, because KWin has
moved some. A monitor that changes size or scale is tiled again: every coordinate komorebi uses is
KWin's logical one. [Why](DESIGN.md#why-does-komorebi-take-the-windows-of-an-unplugged-monitor-over-itself)
is in DESIGN.md.
For the screen lock, kfm has `ScreenLock` and `ScreenUnlock` events, and kfw registers for power and
session notifications. kfde listens on D-Bus: logind's `PrepareForSleep` for a wake, and KDE's screen
saver `ActiveChanged` for a lock. With the screen off or locked KWin sends clients no frame callbacks,
so what komorebi asked for in that time is not done: komorebi waits 600 ms after an unlock and 2.5 s
after a wake and looks at every window again. The lock screen is a window of KWin's that is in no
task list and on every desktop; komorebi does not manage it.
At time of writing (2026-10-27) a real suspend and resume was not tested: the QEMU guests have no
way to wake from one. The signals are tested on private buses, and the lock screen against a real
KWin in a Plasma session. [PLATFORM.md](PLATFORM.md#sleep-and-lock) says so too.
## Checking the configuration
kfw and kfde have `komorebic check`, and kfm has none. kfw's reads the files in the configuration
home (`komorebi.json`, `komorebi.ahk` and `whkdrc` among them) and shows what is wrong with them.
kfde's reads `komorebi.json` the way the daemon will, tells a key of another platform from a typo
(with the nearest key that is a setting), looks at the key binding file and at whether it has been
made into KDE shortcuts, and then looks at the desktop: a Plasma session on Wayland, KWin 6 on the session bus, komorebi's
script in KWin, which build of each effect is installed, the Plasma shell when there are wallpapers,
and what starts komorebi at login. It exits with status 1 when something stops komorebi from working
(a file that is not JSON, no KWin), and 0 with warnings when it only will not do what was meant.
`--komorebi-config FILE` checks another file and `--configuration-only` leaves the desktop out; the
first flag is kfw's too.
kfw's `check` also asks GitHub for the latest release. kfde's does not look for a newer release, and
it does not know the AutoHotkey and PowerShell files of Windows.
## What kfw and kfm have that kfde does not
From the tables above, and from what has no row in them:
- The bar. `komorebi-bar` is not ported: the Plasma panel is used, and the work area accounts for it
(a panel moved is a change of the work area, and the tiles are made again).
- The stackbar and its settings. A stack is cycled with `cycle-stack` and `focus-stack-window`.
- Custom layouts, which kfw has and kfm does not. Not supported yet.
- The Win32 workarounds of the "Win32 quirks" group, the AutoHotkey and PowerShell configurations,
the named-pipe subscribers, and whkd as a separate program.
- The license check and the splash screen of the macOS and Windows builds.
- kfm's scrolling strip: columns that hold several windows, and its commands.
- The tab and title bar commands (`remove-title-bar`, `toggle-title-bars`).
## What kfde has that kfw and kfm do not
- Native workspaces: they show in KWin's pager and overview, and KWin focuses the window of the
desktop it switches to.
- Borders, animation, transparency and focus follows mouse as a compositor does them, and `check`
for a desktop.
- Key bindings that work from a physical keyboard, the QEMU console and RDP, with modes, chords and
scopes realized by the daemon, and the `skhdrc`, `whkdrc` and `sxhkdrc` formats.
- A NixOS module (`services.komorebi`) with a user unit, the effects, and the key bindings as options,
and a version check of KWin. kfm has a module for nix-darwin, in its own form.
- A test suite that runs the window manager against a real KWin in virtual machines, and a `Backend`
that tests replace with a desktop in memory. [vm-tests.md](vm-tests.md) describes it.
## Costs, measured
At time of writing (2026-10-27), on an Apple silicon Mac, in virtual machines under HVF, KWin 6.8.1
(Plasma 6.8.1, nixpkgs `d3b13ad` of 2026-10-24). No number here compares kfde with kfw or kfm:
nothing of the same kind was measured on them.
| What | Result | Source |
|---|---|---|
| A retile of 10 `foot` windows on a 3840x2160 output, from the answer to `Poll` to the last frame KWin reported (5.5 windows moved on average) | p50 17.3 ms, p95 27.7 ms, max 31.4 ms | `vm-latency`, [PLATFORM.md](PLATFORM.md#how-long-a-retile-takes) |
| The same channel alone, 20 windows in each batch | p50 16 ms, p95 19 ms, max 20 ms | [the spikes](PLATFORM.md#vocabulary) |
| A client's answer to a frame | exact for Qt, GTK 4 down to its minimum, XWayland; `foot` rounds to its cells; GTK 4 Calculator and Firefox keep a minimum size | `vm-client-geometry`, [PLATFORM.md](PLATFORM.md#how-clients-answer-a-frame) |
| A window resized off the screen | KWin keeps 100 px of it on an output | [PLATFORM.md](PLATFORM.md#how-clients-answer-a-frame) |
| KWin restarting under a running daemon | the script is loaded again about 1 s after KWin is back | [the spikes](PLATFORM.md#vocabulary) |
What was not measured is listed in [PLATFORM.md](PLATFORM.md#what-was-not-measured): a real suspend
and resume, KWin before 6.8, activities, outputs beyond a second one, applications in a sandbox,
keys from an RDP client and graphics other than software rendering, among others.
+29 -25
View File
@@ -8,13 +8,15 @@ It grows with the code: a decision is added in the commit that makes it.
## What is komorebi for KDE the port of?
komorebi has a Windows implementation, the original, and a macOS one. The Windows one is
the reference. I used it as the reference for what to adapt, and I prefer what KDE and
Wayland do natively over a workaround that the other two platforms need. The events the
window manager reacts to follow the Windows ones (a window is shown, destroyed, focused,
minimized, moved, resized), and a window is a small `Copy` handle, as there. The model the
window manager tiles is the one both platforms have: monitors, each with workspaces, each
with containers, each with windows.
komorebi has a Windows implementation, the original, and a macOS one, and both were read for
what to adapt. I wanted to keep things as close to komorebi for Windows and for Mac as
possible, so that one configuration file is largely portable across all the platforms, and to
drop the hacks that Windows or macOS needed and Linux does not, relying on what KDE and
Wayland do natively. The events the window manager reacts to follow the Windows ones (a
window is shown, destroyed, focused, minimized, moved, resized), and a window is a small
`Copy` handle, as there. The model the window manager tiles is the one both platforms have:
monitors, each with workspaces, each with containers, each with windows. What the three
programs have in common and where they differ is in [COMPARE.md](COMPARE.md).
## Why is everything the window manager needs behind one trait?
@@ -138,7 +140,7 @@ so `tsc` refuses anything else.
Because a KWin script cannot move the pointer, and KWin can. Its "Move Mouse to Focus" action
puts the pointer in the middle of the window that has the focus, and it can be invoked over
D-Bus, through `kglobalaccel`: in the spikes it moved the pointer from the middle of the screen
D-Bus, through `kglobalaccel`: in [the spikes](PLATFORM.md#vocabulary) it moved the pointer from the middle of the screen
to the middle of the focused window, for two different windows. The backend asks for it once
KWin reports the window it focused as active, so the action finds the right one. The cost is
that the pointer can go to the middle of the focused window and nowhere else, which is what
@@ -264,14 +266,13 @@ and the next run puts it back.
Because a container has one tile, so the windows of a stack that are not in front have to be out
of sight, and a virtual desktop nobody looks at was the one way to do that which the spikes found
to cost no focus change. The first spike hid six tiled windows and showed them again three ways.
Minimizing
them gave the geometry back exactly, but KWin picked a new active window as each one minimized,
to cost no focus change. Spike 3 hid six tiled windows and showed them again three ways.
Minimizing them gave the geometry back exactly, but KWin picked a new active window as each one minimized,
two focus events nobody asked for. Moving them to a virtual desktop of their own gave no focus
event and the geometry back exactly. Moving them off the screen worked too, since KWin does not
clamp a scripted move, but the windows stay mapped on the current desktop, in the window switcher,
the overview and the task manager, so it was not offered. KWin has nothing else: `Window.hidden`
cannot be set by a script. The spike's source reading, KWin 6.8.1, is in
cannot be set by a script. The reading of KWin's sources (6.8.1) is in
[PLATFORM.md](PLATFORM.md#the-parking-desktop). The other platforms have a setting that chooses
how windows are hidden; on KDE there is one way, and so no such setting.
@@ -320,7 +321,7 @@ adjustment of the container in monocle would be lost when it came back (the comm
Because KWin has a maximize of its own, and komorebi asks for it. The window gets the work area of
its output with the panels left alone, and a restore goes back to where the window was
(`docs/kde.md`, and the comment in the bridge where it carries the command out). It is the work
(see the comment in the bridge where it carries the command out). It is the work
area and not the padded one that [`Workspace::update`](../../komorebi/src/workspace.rs) maximizes
a window to ("the compositor's own maximize, which is the work area and not the padded one"), so
the window cannot be a container: a layout would give it a tile, less the padding. It is held in
@@ -331,13 +332,16 @@ tile's size that it has to get back, not the compositor's idea of its old size"
## Why does one `komorebi.json` work on every platform?
Spike 8 asked whether it could, and it can. With the `StaticConfig` of komorebi for Mac, the
example of komorebi for Windows loaded and read back, and so did a file with every key that only
Windows has, a real file of komorebi for Mac, and this repository's example; what serde dropped
was the keys that mean nothing outside their platform. So a key that does nothing on KDE Plasma is accepted and
ignored, and `config_parity` checks that the keys it ignores are the Windows-only ones and, until
the features are in, the ones of features that are not. Where the Mac struct had no key that the
native mapping needs (`focus_follows_mouse`, `transparency`), the KDE struct has the Windows one.
Because a file written for one platform should load on the others, and a key that means
nothing on one of them is no reason to refuse the file. `StaticConfig` has the keys of komorebi
for Windows and for Mac that mean something on KDE Plasma, and serde skips a key it does not
know, so a key that does nothing here is accepted and ignored. The fixtures of `config_parity`
(spike 8) are the evidence: the example of komorebi for Windows, a file with every key that only
Windows has, a real file of komorebi for Mac and this repository's example all load and read
back, and the test checks that the keys the serializer drops are the Windows-only ones
(`WINDOWS_ONLY`) and no others. Where komorebi for Mac has no key that KDE needs
(`focus_follows_mouse`, `transparency`), `StaticConfig` has the one komorebi for Windows has.
[COMPARE.md](COMPARE.md#configuration) lists the keys of the three programs.
## Why does komorebi reload its configuration when the file changes?
@@ -737,11 +741,11 @@ too.
## Why does the engine handle every binding by default?
The plan was to make static shortcuts the default and to switch the default if a static
shortcut turned out to be slow to start its command. It did: on KWin 6.8.1 (in a virtual
machine, on 2026-10-27) a static shortcut ran its command 165 to 436 ms after the key, 233 ms
at the median, while the engine was told of the key 3 ms after it. So the default is
`PlanMode::Engine`, and `PlanMode::Auto` and `PlanMode::Static` stay selectable.
A static shortcut starts its command later than the engine is told of the key: on KWin 6.8.1
(in a virtual machine, on 2026-10-27) a static shortcut ran its command 165 to 436 ms after the
key, 233 ms at the median, while the engine was told of the key 2.5 ms after it, at the
median. So the default is `PlanMode::Engine`, and `PlanMode::Auto` and `PlanMode::Static` stay
selectable.
The cost is the robustness of static shortcuts: the engine works only while komorebi runs,
and a komorebi process that was killed leaves its keys registered and dead until they are
+37 -1
View File
@@ -25,6 +25,13 @@ was measured with KWin 6.8.1, Plasma 6.8.1 and Qt 6.12.0 from nixpkgs `d3b13ad`
a stack, and the windows behind a monocle, on. It is not a workspace.
- **Headless KWin**: `kwin_wayland --virtual`, a KWin with virtual outputs and no display,
which the VM tests run ([vm-tests.md](vm-tests.md)).
- **The spikes**: throwaway measurements made before komorebi for KDE was written, each
answering one question about KWin (the event stream, the command channel, how to hide
windows, how clients answer a frame, the effects, the native actions, finding KWin again
after a restart, whether one `komorebi.json` can be shared, per-output desktops), numbered
from 1 to 10. They ran on KWin 6.8.1 in NixOS virtual machines under QEMU on an Apple silicon
Mac. Their numbers are quoted where they are used, with the date, and where a VM test repeats
a measurement the test is named. `spikes/config-parity/fixtures` is spike 8's.
## What komorebi needs
@@ -573,7 +580,7 @@ test `vm-scrolling` checks that the columns out of view stay where komorebi put
The same holds for a frame the user asks for. While the user drags an edge of a window, KWin reports
at every step of the drag the frame the pointer asks for (`interactiveMoveResizeStepped`), and the
window's frame follows once the client has drawn at that size. When the user lets go, the frame can
be well short of where they took the edge: at time of writing (2026-10-27), in the spike, the frame
be well short of where they took the edge: at time of writing (2026-10-27), in the spikes, the frame
at the end of a 72-pixel drag of a terminal's edge had moved 12 or 48 pixels. KWin goes on reporting
the client's frames after the end of the drag: in a run of `vm-drag-resize` at time of writing
(2026-10-28), a frame of 660 pixels, which is what `foot` had drawn of the 672 asked for, came 1 ms
@@ -827,3 +834,32 @@ and KRDP 6.8.1 and FreeRDP 3.32.2:
script keys, fails NTLM against KRDP, FreeRDP's client cannot script keys, and a client inside
the session would send each key back to itself. Whether a key pressed in an RDP client reaches a
global shortcut is therefore not known; no check from a real client has been recorded.
## What was not measured
At time of writing (2026-10-28) these are gaps, not findings. Nothing on this page says that
they work or that they do not.
- KWin before 6.8: only 6.8.1 was run ([KWin 6.8 or newer](#kwin-68-or-newer)).
- Activities.
- More outputs than a second one to the right of the first: the geometry was checked, the
pixels were not.
- Whether a window of a Qt or KDE application is drawn smaller than the minimum size it reports,
or overflows its frame: the frames were measured, not the pixels
([How clients answer a frame](#how-clients-answer-a-frame)).
- What a window on the parking desktop does to the task manager and the overview, and whether
hiding and showing windows flickers. By construction a parked window stays in the task manager
unless the task manager shows only the current desktop.
- The rule identity of an application in a sandbox (Flatpak), which comes from
`/proc/<pid>/exe`; the `class` and the `pid` were checked.
- A real suspend and resume ([Sleep and lock](#sleep-and-lock)).
- A key pressed in an RDP client ([RDP into the session](#rdp-into-the-session)).
- Whether the progress of the stock Geometry Change effect follows `QEasingCurve.OutExpo` against
the clock in a session: one capture four seconds into a 30 s animation showed no progress, where
the curve gives about 60 % ([KWin effects](#kwin-effects)). The log evidence and the comparison
with animation off do not depend on it.
- Graphics other than llvmpipe: every render measured was in software.
- The scrolling layout on a monitor that has another beside it. A strip spills onto the
neighbor when that monitor shows the same workspace number, and a window whose middle is on a
monitor that shows another desktop is not drawn. This is read from KWin's sources, not
checked with pixels.
+3
View File
@@ -86,6 +86,9 @@ 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
+3 -2
View File
@@ -1,7 +1,8 @@
# Monitors that change
komorebi follows the outputs KWin has. There is nothing to configure and no command to run: this
page says what komorebi does when a monitor changes.
komorebi follows the outputs KWin has, and a change of them needs no command: this page says
what komorebi does when a monitor changes. The one thing to set is where a monitor goes in
komorebi's order, [`display_index_preferences`](#a-monitor-is-plugged-in).
## A monitor changes size
+1 -1
View File
@@ -27,7 +27,7 @@ the monitor on the right. With no monitor there either, nothing happens, and the
[`komorebic cycle-monitor`](../cli/cycle-monitor.md) the next or the previous one, and
[`komorebic focus-monitor-at-cursor`](../cli/focus-monitor-at-cursor.md) the one the pointer is
on. [`komorebic eager-focus`](../cli/eager-focus.md) focuses the first window komorebi manages of
an executable, whichever workspace of whichever monitor it is on, and shows its workspace.
an executable, on any workspace of any monitor, and shows its workspace.
```sh
komorebic focus-monitor 1
+1 -1
View File
@@ -69,7 +69,7 @@ monitor and its own index, and
for each name it is given, in order. The name is komorebi's, for the commands that find a
workspace by its name: KWin's desktop keeps the name it has.
[`komorebic focus-named-workspace`](../cli/focus-named-workspace.md) shows the workspace with that
name, on whichever monitor has it, and focuses that monitor. A name no workspace has changes
name, on the monitor that has it, and focuses that monitor. A name no workspace has changes
nothing. `komorebic query focused-workspace-name` prints the name of the workspace in front, or its
index when it has none.
+2 -10
View File
@@ -2651,17 +2651,12 @@ impl WindowManager {
direction: CycleDirection,
) -> eyre::Result<()> {
tracing::info!("focusing container");
// let mut maximize_next = false;
let mut monocle_next = false;
let mouse_follows_focus = self.mouse_follows_focus;
if self.focused_workspace_mut()?.maximized_window.is_some() {
// TODO: maximized window stuff
// maximize_next = true;
// self.unmaximize_window()?;
}
// A maximized window is left as it is: komorebi for Windows maximizes the window the
// focus cycles to, and this does not.
if self.focused_workspace_mut()?.monocle_container.is_some() {
monocle_next = true;
self.monocle_off()?;
@@ -2675,9 +2670,6 @@ impl WindowManager {
workspace.focus_container(new_idx);
// if maximize_next {
// self.toggle_maximize()?;
// } else
if monocle_next {
self.toggle_monocle()?;
} else {
File diff suppressed because it is too large. Load diff