Tiling Window Management for Windows.

komorebi is a tiling window manager that works as an extension to Microsoft's Desktop Window Manager in Windows 10 and above.

komorebi allows you to control application windows, virtual workspaces and display monitors with a CLI which can be used with third-party software such as AutoHotKey to set user-defined keyboard shortcuts.

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

Translations of this document can be found in the project wiki:

There is a Discord server available for komorebi-related discussion, help, troubleshooting etc. If you have any specific feature requests or bugs to report, please create an issue in this repository.

There is a YouTube channel where I livestream development on komorebi. If you would like to be notified of upcoming livestreams please subscribe and turn on notifications. Videos of previous livestreams are also made available in a dedicated playlist.

Articles, blog posts, demos, and videos about komorebi can be added to this list by PR:

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

I encourage you to make a charitable donation to Fresh Start Refugee before you consider sponsoring me on GitHub.

GitHub Sponsors is enabled for this project. Users who sponsor my work on komorebi at any of the predefined monthly tiers will be given access to a private fork of this repository where I push features-in-progress that are not yet quite ready to be pushed on the main repository.

There will never be any feature of komorebi that is gated behind sponsorship; every new feature will always be available for free in the public repository once it meets the requisite level of code quality and completion.

Features-in-progress that are available in early access will be tagged in the issues with an "early access" label.

@haxibami showing komorebi running on Windows 11 with a terminal emulator, a web browser and a code editor. The original video can be viewed here.

https://user-images.githubusercontent.com/13164844/163496447-20c3ff0a-c5d8-40d1-9cc8-156c4cebf12e.mp4

@aik2mlj showing komorebi running on Windows 11 with multiple workspaces, terminal emulators, a web browser, and the yasb status bar with the komorebi workspace widget enabled. The original video can be viewed here.

https://user-images.githubusercontent.com/13164844/163496414-a9cde3d1-b8a7-4a7a-96fb-a8985380bc70.mp4

komorebi only responds to WinEvents and the messages it receives on a dedicated socket.

komorebic is a CLI that writes messages on komorebi's socket.

komorebi doesn't handle any keyboard or mouse inputs; a third party program (e.g. whkd) is needed in order to translate keyboard and mouse events to komorebic commands.

This architecture, popularised by bspwm on Linux and yabai on macOS, is outlined as follows:

komorebi holds a list of physical monitors.

A monitor is just a rectangle of the available work area which contains one or more virtual workspaces.

A workspace holds a list of containers.

A container is just a rectangle where one or more application windows can be displayed.

This means that:

Make sure that you have either the Scoop Package Manager or WinGet installed, then run the following commands at a PowerShell prompt.

Thanks to @sitiom for getting komorebi added to both the popular Scoop Extras bucket and to WinGet.

Prebuilt binaries are available on the releases page in a zip archive. Once downloaded, you will need to move the komorebi.exe and komorebic.exe binaries to a directory in your Path ( you can see these directories by running $Env:Path.split(";") at a PowerShell prompt).

If you prefer to compile komorebi from source, you will need a working Rust development environment on Windows 10/11. The x86_64-pc-windows-msvc toolchain is required, so make sure you have also installed the Build Tools for Visual Studio 2019.

You can then clone this repo and compile the source code to install the binaries for komorebi and komorebic:

Run komorebic start --await-configuration at a Powershell prompt, and you will see the following output:

This means that komorebi is now running in the background, tiling all your windows, and listening for commands sent to it by komorebic. You can similarly stop the process by running komorebic stop.

If you followed the quickstart, komorebi will find the sample komorebi.ps1 file in your $Env:USERPROFILE directory and automatically load it. This file also starts whkd using the sample whkrc file in your $Env:USERPROFILE\.config directory.

Alternatively, if you have AutoHotKey installed and a komorebi.ahk file in $Env:UserProfile directory, komorebi will automatically try to load it when starting.

As previously mentioned, this project does not handle anything related to keybindings and shortcuts directly. I personally use whkd to manage my window management shortcuts, and have provided a sample whkdrc configuration that you can use as a starting point for your own.

You can run komorebic.exe to get a full list of the commands that you can use to customise komorebi and create keybindings with. You can run komorebic.exe --help to get a full explanation of the arguments required for each command.

You can run any configuration command in the komorebi.ps1 file, and you can bind any action command to your desired key combinations in the whkdrc file.

❗️NOTE: This section is only relevant for people who wish to use AutoHotKey instead of whkd.

❗️NOTE: This helper library is only compatible with AutoHotKey v1.1, not with AutoHotKey v2.

Additionally, you may run komorebic.exe ahk-library to generate a helper library for AutoHotKey which wraps every komorebic command in a native AHK function.

If you include the generated library at the top of your ~/komorebi.ahk configuration file, you will be able to call any of the functions that it contains.

❗️NOTE: This section is only relevant for people who wish to use AutoHotKey instead of whkd.

The generated helper library for AutoHotKey currently only supports AutoHotKey v1.1.

The preferred way to install AutoHotKey for use with komorebi is to install it via scoop:

If you install AutoHotKey using a different method, the name of the executable file may differ from the name given by scoop, and thus what is expected by default in komorebi.

You may override the executable that komorebi looks for to launch and reload komorebi.ahk configuration files by setting the $Env:KOMOREBI_AHK_EXE environment variable.

Please keep in mind that even when setting a custom executable name using these environment variables, the executables are still required to be in your Path.

If you do not want to keep komorebi-related files in your $Env:USERPROFILE directory, you can specify a custom directory by setting the $Env:KOMOREBI_CONFIG_HOME environment variable.

For example, to use the ~/.config/komorebi directory:

If you already have configuration files that you wish to keep, move them to the ~/.config/komorebi directory.

The next time you run komorebic start, any files created by or loaded by komorebi will be placed or expected to exist in this folder.

A curated selection of application-specific configurations can be generated to help ease the setup for first-time users. komorebi-application-specific-configuration contains YAML definitions of settings that are known to make tricky applications behave as expected. These YAML definitions can be used to generate a ps1 or an ahk file which you can import at the start of your own komorebi.ps1 or komorebi.ahk files, leaving you to focus primarily on your desired keybindings and workspace configurations.

If you have settings for an application that you think should be part of this curated selection, please open a PR on the configuration repository.

In the event that your PR is not accepted, or if you find there are any settings that you wish to override, this can easily be done using an override file.

If you would like to add a visual border around the currently focused window, two commands are available:

It is important to note that the active window border will only apply to windows managed by komorebi.

If you would like to remove all gaps from a given workspace, both between windows themselves, and between the monitor edges and the windows, you can set the following two configuration options to 0 for the desired monitors and workspaces:

❗️NOTE: If you followed the quickstart and are using the sample configurations, this is already the default behaviour.

Depending on what is in your configuration, when komorebi is started, you may experience the layout rapidly being adjusted with many retile events.

If you would like to avoid this, you can start komorebi with a flag which tells komorebi to wait until all configuration has been loaded before listening to and responding to window manager events: komorebic start --await-configuration.

If you start komorebi with the --await-configuration flag, you must send the komorebic complete-configuration command at the end of the configuration section of your komorebi.ps1 (or komorebi.ahk config, before you start defining the key bindings). The layout will not be updated and komorebi will not respond to komorebic commands until this command has been received.

❗️NOTE: A significant number of floating window rules for the most common applications are already generated for you

Sometimes you will want a specific application to never be tiled, and instead float all the time. You can add rules to enforce this behaviour:

❗️NOTE: A significant number of force-manage window rules for the most common applications are already generated for you

In some rare cases, a window may not automatically be registered to be managed by komorebi. When this happens, you can manually add a rule to force komorebi to manage it:

❗️NOTE: A significant number of tray application rules for the most common applications are already generated for you

If you are experiencing behaviour where closing a window leaves a blank tile, but minimizing the same window does not , you have probably enabled a 'close/minimize to tray' option for that application. You can tell komorebi to handle this application appropriately by identifying it via the executable name or the window class:

❗️NOTE: Microsoft Office-specific application rules are already generated for you

Microsoft Office applications such as Word and Excel require certain configuration options to be set in order to be managed correctly. Below is an example of configuring Microsoft Word to be managed correctly by komorebi.

komorebi supports two focus-follows-mouse implementations; the native Windows Xmouse implementation, which treats the desktop, the task bar, and the system tray as windows and switches focus to them eagerly, and a custom komorebi implementation, which only considers windows managed by komorebi as valid targets to switch focus to when moving the mouse.

To enable the komorebi implementation you must start the process with the --ffm flag to explicitly enable the feature. This is because the mouse tracking required for this feature significantly increases the CPU usage of the process (on my machine, it jumps from