README.md

komorebi

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 whkd and 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.

Please refer to the documentation for instructions on how to install and configure komorebi, common workflows, a complete configuration schema reference and a complete CLI reference.

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 post komorebi development videos. If you would like to be notified of upcoming videos please subscribe and turn on notifications.

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 the Palestine Children's Relief Fund before you consider sponsoring me on GitHub.

GitHub Sponsors is enabled for this project. Unfortunately I don't have anything specific to offer besides my gratitude and shout outs at the end of komorebi live development videos and tutorials.

If you would like to tip or sponsor the project but are unable to use GitHub Sponsors, you may also sponsor through Ko-fi.

Installation

A detailed installation and quickstart guide is available which shows how to get started using scoop, winget or building from source.

Demonstrations

@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.

0vadqFOyIJHglPRY.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.

0e0dd7fc-7115-11ec-a064-42a1fbc2e1e9-v4_t10000011-wbjnuX5De6.mp4

Development

If you would like to contribute code to this repository, there are a few requests that I have to ensure a foundation of code quality, consistency and commit hygiene:

• Flatten all use statements
• Run cargo +nightly clippy and ensure that all lints and suggestions have been addressed before committing
• Run cargo +nightly fmt --all to ensure consistent formatting before committing
• Use git cz with the Commitizen CLI to prepare commit messages
• Provide at least one short sentence or paragraph in your commit message body to describe your thought process for the changes being committed

If you use IntelliJ, you should enable the following settings to ensure that code generated by macros is recognised by the IDE for completions and navigation:

• Set Expand declarative macros to Use new engine under "Settings > Langauges & Frameworks > Rust"
• Enable the following experimental features:
  • org.rust.cargo.evaluate.build.scripts
  • org.rust.macros.proc

Logs and Debugging

Logs from komorebi will be appended to %LOCALAPPDATA%/komorebi/komorebi.log; this file is never rotated or overwritten, so it will keep growing until it is deleted by the user.

Whenever running the komorebic stop command or sending a Ctrl-C signal to komorebi directly, the komorebi process ensures that all hidden windows are restored before termination.

If however, you ever end up with windows that are hidden and cannot be restored, a list of window handles known to komorebi are stored and continuously updated in %LOCALAPPDATA%/komorebi//komorebi.hwnd.json.

Restoring Windows

Running komorebic restore-windows will read the list of window handles and forcibly restore them, regardless of whether the main komorebi process is running.

Panics and Deadlocks

If komorebi ever stops responding, it is most likely either due to either a panic or a deadlock. In the case of a panic, this will be reported in the log. In the case of a deadlock, there will not be any errors in the log, but the process and the log will appear frozen.

If you believe you have encountered a deadlock, you can compile komorebi with --features deadlock_detection and try reproducing the deadlock again. This will check for deadlocks every 5 seconds in the background, and if a deadlock is found, information about it will appear in the log which can be shared when opening an issue.

Window Manager State and Integrations

The current state of the window manager can be queried using the komorebic state command, which returns a JSON representation of the State struct, which includes the current state of WindowManager.

This may also be polled to build further integrations and widgets on top of (if you ever wanted to build something like Stackline for Windows, you could do it by polling this command).

Window Manager Event Subscriptions

It is also possible to subscribe to notifications of every WindowManagerEvent and SocketMessage handled by komorebi using Named Pipes.

First, your application must create a named pipe. Once the named pipe has been created, run the following command:

komorebic.exe subscribe <your pipe name>

Note that you do not have to include the full path of the named pipe, just the name.

If the named pipe exists, komorebi will start pushing JSON data of successfully handled events and messages:

{"event":{"type":"AddSubscriber","content":"yasb"},"state":{}}
{"event":{"type":"FocusWindow","content":"Left"},"state":{}}
{"event":{"type":"FocusChange","content":["SystemForeground",{"hwnd":131444,"title":"komorebi – README.md","exe":"idea64.exe","class":"SunAwtFrame","rect":{"left":13,"top":60,"right":1520,"bottom":1655}}]},"state":{}}
{"event":{"type":"MonitorPoll","content":["ObjectCreate",{"hwnd":5572450,"title":"OLEChannelWnd","exe":"explorer.exe","class":"OleMainThreadWndClass","rect":{"left":0,"top":0,"right":0,"bottom":0}}]},"state":{}}
{"event":{"type":"FocusWindow","content":"Right"},"state":{}}
{"event":{"type":"FocusChange","content":["SystemForeground",{"hwnd":132968,"title":"Windows PowerShell","exe":"WindowsTerminal.exe","class":"CASCADIA_HOSTING_WINDOW_CLASS","rect":{"left":1539,"top":60,"right":1520,"bottom":821}}]},"state":{}}
{"event":{"type":"FocusWindow","content":"Down"},"state":{}}
{"event":{"type":"FocusChange","content":["SystemForeground",{"hwnd":329264,"title":"den — Mozilla Firefox","exe":"firefox.exe","class":"MozillaWindowClass","rect":{"left":1539,"top":894,"right":1520,"bottom":821}}]},"state":{}}
{"event":{"type":"FocusWindow","content":"Up"},"state":{}}
{"event":{"type":"FocusChange","content":["SystemForeground",{"hwnd":132968,"title":"Windows PowerShell","exe":"WindowsTerminal.exe","class":"CASCADIA_HOSTING_WINDOW_CLASS","rect":{"left":1539,"top":60,"right":1520,"bottom":821}}]},"state":{}}

You may then filter on the type key to listen to the events that you are interested in. For a full list of possible notification types, refer to the enum variants of WindowManagerEvent in komorebi and SocketMessage in komorebi-core.

An example of how to create a named pipe and a subscription to komorebi's handled events in Python by @denBot can be found here.

An example of how to create a named pipe and a subscription to komorebi's handled events in Rust can also be found in the komokana repository.

Subscription Event Notification Schema

A JSON Schema of the event notifications emitted to subscribers can be generated with the komorebic notification-schema command. The output of this command can be redirected to the clipboard or a file, which can be used with services such as Quicktype to generate type definitions in different programming languages.

Communication over TCP

A TCP listener can optionally be exposed on a port of your choosing with the --tcp-port=N flag. If this flag is not provided to komorebi or komorebic start, no TCP listener will be created.

Once created, your client may send any SocketMessage to komorebi in the same way that komorebic would.

This can be used if you would like to create your own alternative to komorebic which incorporates scripting and various middleware layers, and similarly it can be used if you would like to integrate komorebi with a custom input handler.

If a client sends an unrecognized message, it will be disconnected and have to reconnect before trying to communicate again.

Socket Message Schema

A JSON Schema of socket messages used to send instructions to komorebi can be generated with the komorebic socket-schema command. The output of this command can be redirected to the clipboard or a file, which can be used with services such as Quicktype to generate type definitions in different programming languages.

Appreciations

• First and foremost, thank you to my wife, both for naming this project and for her patience throughout its never-ending development

• Thank you to @sitiom for being an exemplary open source community leader

• Thank you to the developers of nog who came before me and whose work taught me more than I can ever hope to repay

• Thank you to the developers of GlazeWM for pushing the boundaries of tiling window management on Windows with me and having an excellent spirit of collaboration

• Thank you to @Ciantic for helping me bring the hidden Virtual Desktops cloaking function to komorebi