Rules

Windows
macOS

komorebi has a flexible rules system which aims to allow users to handle any problematic applications they encounter via configuration rather than requiring upstream code changes.

Matching Rules

Applications or windows are identified using either simple or composite matching rules .

Simple matching rules use a matching strategy against a user-provided identifier targeting an application identifier .

{
    "kind": "Exe",
    "id": "Discord",
    "matching_strategy": "Equals"
}

{
    "kind": "Title",
    "id": "Cloudflare Dashboard",
    "matching_strategy": "Contains"
}

{
    "kind": "Class",
    "id": "Ableton Live Window Class",
    "matching_strategy": "Equals"
}

Composite matching rules consist of multiple simple matching rules which must all evaluate to true to identify an application or window.

[
  {
    "kind": "Exe",
    "id": "zen.exe",
    "matching_strategy": "Equals"
  },
  {
    "kind": "Title",
    "id": "Cloudflare Dashboard",
    "matching_strategy": "Contains"
  }
]

Workspace Rules

Workspace rules and initial workspace rules a are used to identify applications or windows which should be put on a specific workspace.

{
  "monitors": [
    {
      "workspaces": [
        {
          "name": "Chat",
          "layout": "Columns",
          "workspace_rules": [
            {
              "kind": "Exe",
              "id": "Discord",
              "matching_strategy": "Equals"
            }
          ],
          "initial_workspace_rules": [
            {
              "kind": "Exe",
              "id": "Slack",
              "matching_strategy": "Equals"
            }
          ]
        },
      ]
    }
  ]
}

Workspace rules will apply all the time, effectively making it impossible to move the identified application or window to another workspace.

Initial workspace rules will only apply once when the identified application or window is first created, allowing it to be moved to another workspace later.

Workspace rules (including initial workspace rules) can be enforced in realtime using the komorebic enforce-workspace-rules command.

Application Handling Rules

Ignore Rules

Ignore rules are used to identify applications or windows which should be completely ignored by komorebi. Ignored applications cannot be targeted by any komorebic commands.

Floating Applications

Floating application rules are used to identify applications or windows which should be put on the floating layer.

Manage Rules

Manage rules are used to identify applications or windows which should be forcibly managed. This is typically a nuclear option for extremely uncooperative applications.

Tray and Multi-Window Applications

Tray and multi-window application rules are used to identify multi-window applications and applications which minmize to the system tray.

Slow Application Identifier Rules

Slow application identifier rules are used to identify applications which are slow to send initial event notifications.

Layered Applications

Layered application rules are used to identify applications have the WS_EX_LAYERED extended window style, but should still be managed.

Object Name Change Applications

Object name change application rules are used to identify applications which send EVENT_OBJECT_NAMECHANGE on launch. This is very rare, but includes popular applications such as Firefox (and derivatives), as well as JetBrains IDEs.

Slow Applications

Slow application identifier rules are used to identify applications which are slow to send initial event notifications.

Tabbed Applications

Tabbed application rules are used to identify applications which use native macOS tabs (Finder, Ghostty etc.) - these are identified using their application name.

Titleless Applications

Titleless application rules are used to identify applications which launch without a title - these are identified using their application name.