Komorebi – Tiling Window Manager Runbook
bub.im · cheatsheet · windows
komorebi · Tiling Window Manager Runbook
Setup and daily driving of komorebi with whkd hotkeys and komorebi-bar on Windows 10/11. Catppuccin Mocha rice, Alt-based vim keys, tight 6 px gaps, config hot reload.
01 Stack at a glance
| Binary | Role | Notes |
|---|---|---|
| komorebi.exe | The window manager itself, an extension of the Windows DWM | No built-in keybindings by design |
| komorebic.exe | CLI that sends every command to the manager | Everything below goes through it |
| whkd.exe | Hotkey daemon, binds keys to komorebic calls | Cannot use the Windows key, Alt is the base modifier |
| komorebi-bar.exe | Status bar, reads the same theme as the WM | Reserves its own work area automatically |
License. komorebi is educational source software, free for personal use only. Any commercial use, including a work machine, requires an individual commercial use license, and MDM-enrolled devices show a splash reminder.
02 Install and bootstrap
Winget end to end. Steps 4 and 5 assume the three config files from section 03 are already in place. safe to re-run
:: 1. Packages winget install -e --id LGUG2Z.komorebi winget install -e --id LGUG2Z.whkd winget install -e --id DEVCOM.JetBrainsMonoNerdFont :: 2. Config home (open a new terminal after setx) setx KOMOREBI_CONFIG_HOME "%USERPROFILE%\.config\komorebi" :: 3. Deploy configs :: komorebi.json + komorebi.bar.json -> %KOMOREBI_CONFIG_HOME% :: whkdrc -> %USERPROFILE%\.config\whkdrc :: 4. Community application rules + config validation komorebic fetch-asc komorebic check :: 5. Autostart shortcut (shell:Startup) and first launch komorebic enable-autostart --whkd --bar komorebic start --whkd --bar
03 Files and paths
| File | Purpose | Path |
|---|---|---|
| komorebi.json | WM config: theme, borders, gaps, animation, workspaces | %USERPROFILE%\.config\komorebi\ |
| komorebi.bar.json | Status bar config, widgets and theme | %USERPROFILE%\.config\komorebi\ |
| whkdrc | Hotkey map | %USERPROFILE%\.config\whkdrc |
| applications.json | Community app rules, refreshed via fetch-asc | %KOMOREBI_CONFIG_HOME% |
| logs | Runtime logs and state | komorebic datadir |
| autostart | Startup shortcut created by enable-autostart | shell:Startup |
04 Keybindings
Alt is the base modifier throughout. whkdrc names keys by US-layout virtual key codes, so bindings stay on the same physical keys regardless of the active input language.
Focus and move
| Alt H J K L | Focus left / down / up / right |
| Alt Shift H J K L | Move window |
| Alt Shift Enter | Promote to main position |
| Alt Shift [ ] | Cycle focus through all windows |
| Alt Enter | Open Windows Terminal |
| Alt Q / M | Close / minimize |
Stacks
| Alt Arrows | Stack onto the neighbour in that direction |
| Alt ; | Pop out of the stack |
| Alt [ ] | Previous / next tab in the stack |
Resize
| Alt = – | Grow / shrink horizontally |
| Alt Shift = – | Grow / shrink vertically |
Workspaces and monitors
| Alt 1..8 | Focus workspace |
| Alt Shift 1..8 | Move window to workspace and follow |
| Alt , . | Focus previous / next monitor |
| Alt Shift , . | Move window to previous / next monitor |
Layouts and states
| Alt T | Toggle floating |
| Alt F | Toggle monocle |
| Alt Shift F | Toggle maximize |
| Alt Space | Cycle to next layout |
| Alt X / Y | Flip layout horizontally / vertically |
| Alt R | Force a retile |
| Alt P | Pause / resume tiling |
System
| Alt Shift O | Restart whkd, reloads whkdrc |
05 komorebic essentials
| Command | Does |
|---|---|
| komorebic start –whkd –bar | Launch WM, hotkey daemon and bar |
| komorebic stop –whkd –bar | Stop everything, windows return to normal |
| komorebic check | Validate configs, first stop after any edit |
| komorebic fetch-asc | Refresh community application rules |
| komorebic state | Dump full WM state as JSON |
| komorebic retile | Rebuild the layout on the focused workspace |
| komorebic toggle-pause | Suspend / resume tiling globally |
| komorebic datadir | Print the logs and state directory |
| komorebic disable-autostart | Remove the startup shortcut |
komorebic stop --whkd --bar komorebic start --whkd --bar
06 Reload after editing
| Edited | Reload | How |
|---|---|---|
| komorebi.json | automatic | Watched and hot-reloaded on save. Force with komorebic replace-configuration <path> if needed |
| komorebi.bar.json | automatic | The bar watches its config as well. Fallback: komorebic stop –bar then komorebic start –bar |
| whkdrc | manual | Alt Shift O, or taskkill /f /im whkd.exe && start whkd |
| applications.json | restart | Full stop / start to be safe |
Silent failures. A typo means the hot reload silently keeps the old config. komorebic check tells you exactly what is wrong instead of leaving you wondering why nothing changed.
07 Rice values in komorebi.json
The choices that define the look, pinned to schema v0.1.41. Theme overrides border_colours entirely once set.
| Setting | Value | Effect |
|---|---|---|
| theme | Catppuccin / Mocha | Drives borders, stackbar and bar from one place |
| single_border | Mauve | Focused window accent; stack Blue, monocle Peach, float Yellow |
| border_width / offset | 3 / -1 | Hairline frame that fits inside the 6 px gap |
| border_style | Rounded | Windows 11 rounded corners; use Square on Windows 10 |
| *_padding | 6 / 6 | Container and workspace gaps, minimum that still shows wallpaper |
| transparency_alpha | 245 | Barely-there dimming of unfocused windows |
| animation | 150 ms EaseOutCubic | Snappy movement, disable entirely for zero overhead |
| stackbar | OnStack / Title / 36 | Tab bar appears only on stacked containers |
| window_hiding_behaviour | Cloak | No minimize flicker on workspace switches |
| workspaces 1..8 | term www code files chat media vm misc | BSP mostly; code VerticalStack, chat Grid, misc floats everything |
08 Tuning quick refs
| Want | Change |
|---|---|
| Another flavour | theme.name to Latte, Frappe or Macchiato in both JSON files |
| Another accent | single_border + bar_accent in komorebi.json, accent in the bar config |
| Maximum snappiness | animation.enabled: false, transparency: false |
| Second monitor | Duplicate the object inside monitors; add a second bar config with “monitor”: {“index”: 1} to bar_configurations |
| No battery widget | Delete the Battery block from komorebi.bar.json on desktops |
"initial_workspace_rules": [
{ "kind": "Exe",
"id": "firefox.exe",
"matching_strategy": "Equals" }
]"default_workspace_padding": 0, "default_container_padding": 0, "border_width": 2, "border_implementation": "Windows"
09 Troubleshooting
| Symptom | Fix |
|---|---|
| Edit does nothing | komorebic check, hot reload keeps the old config on JSON errors |
| Some app tiles strangely | komorebic fetch-asc first, then an ignore_rules entry if it persists |
| Square corners look off | Windows 10 has no rounded corners, set border_style to Square |
| Bar shows tofu boxes | JetBrainsMono Nerd Font is missing, install it and restart the bar |
| Hotkeys dead | whkd is not running, start whkd or a full restart |
| Where are the logs | komorebic datadir |
10 Links
| What | Where |
|---|---|
| Documentation | lgug2z.github.io/komorebi |
| Source and releases | github.com/LGUG2Z/komorebi |
| Application rules repo | komorebi-application-specific-configuration |
| whkd | github.com/LGUG2Z/whkd |
| Catppuccin palette | github.com/catppuccin |
| Commercial license | lgug2z.com/software/komorebi |
komorebi Runbook · REV 2026.07 © 2026 · BUB.IM · made in vim
0 comments