komokana

Concept: Application-Aware Layer Switching

komokana acts as a bridge between komorebi (a tiling window manager) and kanata (a keyboard remapper).

1. Event Listening: komokana listens to window focus events emitted by komorebi via Named Pipes.
2. Rule Matching: It compares the active window's executable name (exe) and title against your komokana.yaml rules.
3. Layer Switching: When a match is found, komokana sends a command to kanata via a TCP server to switch the keyboard to the specified target_layer.

Requirements for Communication

• komorebi: Must be running to provide window focus events.
• kanata: Must be running and started with the --port flag to allow komokana to send layer-switch commands via TCP.

You can install komokana using Scoop, WinGet, or by building from source.

Using Scoop

If you use the Scoop command line installer, run:

scoop bucket add extras
scoop install komokana

This automatically adds the binary to your Path.

Using WinGet

winget install LGUG2Z.komokana

Building from Source

Requires a Rust development environment on Windows 10 with the x86_64-pc-windows-msvc toolchain and Build Tools for Visual Studio 2019. Clone the repository and run:

cargo install --path . --locked

Configuration is handled via a YAML file. You can specify the path to your configuration file using the -c flag when running komokana.

Each rule in the configuration associates an executable (exe) with a target_layer in kanata. You can refine these rules using title_overrides or virtual_key_overrides (to switch layers based on window title or held keys) and virtual_key_ignores (to prevent layer switching if specific keys are held).

- exe: "firefox.exe"
  target_layer: "firefox"
  title_overrides:
    - title: "Slack |"
      strategy: "starts_with"
      target_layer: "qwerty"
  virtual_key_overrides:
    - virtual_key_code: 18
      targer_layer: "qwerty"
  virtual_key_ignores:
    - 18

komokana acts as a bridge between two components:

1. komorebi: komokana subscribes to a Unix socket (komokana.sock) to listen for window management events (e.g., Show, FocusChange).
2. kanata: When a window event triggers a rule match, komokana sends a JSON command over a TCP connection to the kanata server to change the active keyboard layer.

Layer Change Workflow

• Window Event: A window is shown or focused in komorebi.
• Rule Matching: komokana checks the window's executable name and title against the provided Configuration.
• Command Dispatch: If a match is found, komokana sends a ChangeLayer request to kanata via TCP:

  {
    "ChangeLayer": {
      "new": "target_layer_name"
    }
  }

• Reconnection: The tool automatically handles reconnections if the kanata TCP server or the komorebi socket becomes unavailable.

If you run komokana with the -t flag, it will update a plaintext file at ~/AppData/Local/Temp/kanata_layer whenever the layer changes. You can use this file to create a custom widget in yasb to visually indicate the active layer.

Example yasb configuration:

# in ~/.yasb/config.yaml
widgets:
  kanata:
    type: "yasb.custom.CustomWidget"
    options:
      label: "{data}"
      label_alt: "{data}"
      class_name: "kanata-widget"
      exec_options:
        run_cmd: "cat '%LOCALAPPDATA%\Temp\kanata_layer'"
        run_interval: 300
        return_format: "string"

The application configuration is defined as a list of Entry objects. Each entry maps a specific executable (exe) to a target_layer. You can also provide optional overrides for window titles and virtual key codes within each entry.

Key fields for an Entry:

• exe: The name of the executable to match.
• target_layer: The layer this application should be mapped to.
• title_overrides: An optional list of TitleOverride rules.
• virtual_key_overrides: An optional list of VirtualKeyOverride rules.
• virtual_key_ignores: An optional list of decimal virtual key codes to ignore for this application.

[
  {
    "exe": "example.exe",
    "target_layer": "gaming_layer",
    "title_overrides": [
      {
        "title": "Game",
        "strategy": "contains",
        "target_layer": "special_layer"
      }
    ],
    "virtual_key_ignores": [13, 27]
  }
]

When using title_overrides in your komokana.yaml, you can specify a strategy for matching the window title. The valid strategies are:

• starts_with
• ends_with
• contains
• equals

To run komokana, ensure both komorebi and kanata are already running. kanata must be started with the --port flag to enable the TCP server that komokana uses to communicate.

Use the following command structure:

komokana -p [KANATA_PORT] -d [DEFAULT_LAYER] -c [PATH_TO_YOUR_CONFIG]

Arguments:

• -p [KANATA_PORT]: The TCP port where kanata is listening.
• -d [DEFAULT_LAYER]: The default kanata layer to use.
• -c [PATH_TO_YOUR_CONFIG]: The path to your komokana.yaml configuration file.

komokana -p 1234 -d qwerty -c C:\path\to\komokana.yaml

When using title_overrides, you can specify a strategy to determine how the window title is matched against the provided title string. The available strategies are:

• starts_with: Matches if the window title begins with the specified string.
• ends_with: Matches if the window title ends with the specified string.
• contains: Matches if the specified string is found anywhere within the window title.
• equals: Matches only if the window title is exactly equal to the specified string.

// Strategy enum values (snake_case):
// "starts_with"
// "ends_with"
// "contains"
// "equals"

You can remap specific virtual key codes to different layers for a particular application using virtual_key_overrides.

Each override requires:

• virtual_key_code: The decimal value of the virtual key.
• targer_layer: The layer to which the key should be mapped (Note: the field name in the schema is targer_layer).

Additionally, you can use virtual_key_ignores to provide a list of decimal virtual key codes that should be ignored entirely for that application.

// Example VirtualKeyOverride structure:
{
  "virtual_key_code": 32,
  "targer_layer": "layer_name"
}

komokana is a CLI tool that orchestrates layer changes in kanata based on window events from komorebi. You can run it by providing the Kanata TCP port, a configuration file path, and a default layer to use when no rules match.

CLI Arguments

• -p, --kanata-port <PORT>: The port on which the kanata TCP server is running (Required).
• -c, --configuration <PATH>: Path to your komokana configuration file (Defaults to ~/komokana.yaml).
• -d, --default-layer <LAYER>: The layer to default to when an active window doesn't match any rules.
• --tmpfile: If set, the current layer will be written to ~/AppData/Local/Temp/kanata_layer.

# Example usage
komokana --kanata-port 8080 --configuration ~/my_config.yaml --default-layer base