komorebi

komorebi is a tiling window manager for Windows 10 and above that acts as an extension to Microsoft's Desktop Window Manager (DWM). It allows users to manage application windows, virtual workspaces, and display monitors via a Command Line Interface (CLI).

To set up custom keyboard shortcuts, the CLI can be used in conjunction with third-party software such as whkd or AutoHotKey. By default, komorebi aims to make minimal modifications to the OS; any desktop environment modifications are opt-in via user configuration files.

komorebi organizes the desktop using a hierarchical structure of monitors, workspaces, and containers:

1. Monitor: A physical monitor representing a rectangle of the available work area. Each monitor contains one or more virtual workspaces.
2. Workspace: A virtual area within a monitor. Workspaces manage containers and their dimensions, but they do not track individual application windows directly.
3. Container: A rectangle within a workspace that holds one or more application windows.

Key Rules:

• Every monitor has its own collection of virtual workspaces.
• Every application window must belong to a container (even if the container only holds that single window).
• Multiple application windows can be stacked and cycled through within the same container inside a workspace.

Komorebi is designed with privacy in mind: no data regarding your device or usage of the software leaves your local machine.

All data maintained by Komorebi is stored locally in the following directory, which is owned by the user running the process: $Env:LOCALAPPDATA\komorebi\

This directory contains:

1. Log files: Used for debugging and process monitoring.
2. Temporary window handles (HWNDs): A list of the window handles currently being managed by the Komorebi process.

komorebi uses the Komorebi 2.0.0 license (a fork of PolyForm Strict 1.0.0).

Personal Use

• You are free to use the software for personal use.
• Redistribution or distribution of new works (hard-forks) is not permitted.
• You may fork the project for personal use or to submit pull requests upstream.
• Commercial use (e.g., using it at work) is NOT permitted under the standard license.

Commercial Use

• If you need to use komorebi for work, you must acquire an Individual Commercial Use License.
• This license permits commercial use for the licensed individual only for the duration of a valid paid subscription.
• Pricing and purchase information can be found at lgug2z.com/software/komorebi.

Widgets are the building blocks of the bar and are organized into three positional arrays: left_widgets, center_widgets, and right_widgets.

Each widget is defined as an object where the key is the widget type and the value is its specific configuration object.

{
  "left_widgets": [
    { "Komorebi": { "option": "value" } }
  ],
  "center_widgets": [],
  "right_widgets": []
}

If certain tray icons are 'zombie' icons (they register a callback but don't respond to clicks), you can define fallback shell commands that run instead of the native click action. Fallback commands always take priority.

Supported Fallback Logic:

• By Exe: Runs a command for a specific executable.
• By Tooltip Condition: Runs a command if the tooltip matches a specific pattern (e.g., EndsWith).

Example Fallback Scenarios:

• SecurityHealthSystray.exe (any tooltip) $\rightarrow$ start windowsdefender://
• explorer.exe (tooltip ends with %) $\rightarrow$ start ms-settings:apps-volume
• explorer.exe (empty tooltip) $\rightarrow$ start ms-settings:batterysaver

komorebi is a tiling window manager for Windows consisting of several key components:

• komorebi.exe: The core window manager binary.
• komorebic.exe: The primary CLI tool used to send commands to the window manager.
• komorebi-bar.exe: A customizable status bar deeply integrated with the manager.
• whkd: A simple hotkey daemon recommended for binding komorebic.exe commands to keyboard shortcuts.

Note on Key Bindings: komorebi does not handle hotkeys itself. While whkd is recommended for simplicity, it does not support certain Windows key combinations due to Microsoft restrictions. If you require complex Windows key bindings, use AutoHotKey instead.

Komorebi supports several tiling layouts to suit different monitor setups:

• BSP: Binary Space Partitioning.
• Vertical Stack: Windows stacked vertically.
• RightMainVerticalStack: A large main window on the right with a vertical stack on the left.
• Horizontal Stack: Windows stacked horizontally.
• Columns: Windows arranged in columns.
• Rows: Windows arranged in rows (recommended for vertical monitors).
• Ultrawide Vertical Stack: Optimized for ultrawide monitors.
• Grid: A grid-based layout (similar to LeftWM) that does not support resizing window tiles.

The meaning of column_ratios and row_ratios changes depending on the active layout:

Note for BSP: BSP only uses the first value ([0]) from each array. This single ratio is applied consistently to all splits of that type.

komorebi follows a decoupled architecture where it does not handle keyboard or mouse inputs directly. Instead, it responds to WinEvents and messages received via a dedicated socket.

To control komorebi, you must use a third-party program (such as whkd or ahk) to capture user input and translate it into commands for komorebic (the CLI), which then communicates with the komorebi process via a socket.

Architecture Flow: whkd/ahk (Input) $\rightarrow$ komorebic (CLI) $\leftrightarrow$ komorebi (Core Process)

          PROCESS                SOCKET
whkd/ahk  -------->  komorebic  <------>  komorebi