komokana
Automatic application-aware keyboard layer switching for Windows
About
komokana is a daemon that listens to events emitted by komorebi and communicates with kanata to switch keyboard layers based on a set of user defined rules.
komokana allows you associate different kanata keyboard layers with specific applications, and automatically switch to that keyboard layer when the windows of those applications are focused in the foreground.
You may join the komorebi Discord server for any komokana-related discussion, help, troubleshooting etc. If you have any specific feature requests or bugs to report, please create an issue in this repository.
Articles, blog posts, demos and videos about komokana can be added to this section of the readme by PR.
Description
komokana communicates with komorebi using Named Pipes, and with kanata via a TCP server that can be optionally started by passing the --port flag when launching the kanata process.
If either the komorebi or kanata processes are stopped or killed, komokana will attempt to reconnect to them indefinitely. However, komokana will not launch successfully if either one of those processes is not running.
Getting Started
Prerequisites
- The latest version of
komorebiscoop install komorebi(from theextrasbucket)
- The latest version of
kanatacargo install kanata
GitHub Releases
Prebuilt binaries of tagged releases are available on the releases page in a zip archive.
Once downloaded, you will need to move the komokana.exe binary to a directory in your Path ( you can see these directories by running $Env:Path.split(";") at a PowerShell prompt).
Alternatively, you may add a new directory to your Path using setx or the Environment Variables pop up in System Properties Advanced (which can be launched with SystemPropertiesAdvanced.exe at a PowerShell prompt), and then move the binaries to that directory.
Scoop
If you use the Scoop command line installer, you can run the following commands to install the binaries from the latest GitHub Release:
scoop bucket add extras
scoop install komokana
If you install komokana using Scoop, the binary will automatically be added to your Path.
Building from Source
If you prefer to compile komokana from source, you will need a working Rust development environment on Windows 10. 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 binary for komokana:
cargo install --path . --locked
Configuring
komokana is configured using a YAML file that can be specified using the -c flag.
Consider the following kanata.kbd file which defines our keyboard layers:
(defalias
;; these are some convenient aliases to send the letter on tap, or toggle the
;; "firefox" layout on hold
ft (tap-hold 50 200 f (layer-toggle firefox))
jt (tap-hold 50 200 j (layer-toggle firefox))
;; these are some convenient aliases for us to switch layers
qwr (layer-switch qwerty)
ff (layer-switch firefox)
)
;; imagine this is our default layer, passed as "-d qwerty" when launching komokana
;; the only two keys overriden here are f and j, which when held, will toggle
;; our "firefox" layer
(deflayer qwerty
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ @ft _ _ @jt _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _
)
;; this is our firefox layer which lets us navigate webpages using hjkl
(deflayer firefox
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ left down up rght _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _
)
;; this is our editor layer for use in windows where the vim editor or vim extensions
;; in a text editor are running. the only thing we do here is ensure that the tap-hold
;; not present on j, so that when we hold down j we can zoom all the way down the file
;; that we are editing
(deflayer editor
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ @ft _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _
)
Based on the kanata layers defined above, we can have a komokana.yaml configuration file that looks like this:
- exe: "firefox.exe" # when a window with this exe is active
target_layer: "firefox" # switch to this layer, a vim-like layer just for browsing!
title_overrides: # unless...
- title: "Slack |" # the window title matches this
# valid matching strategies are: starts_with, ends_with, contains and equals
strategy: "starts_with" # matching with this matching strategy
target_layer: "qwerty" # if it does, then switch to this layer for chatting
- title: "Mozilla Firefox" # new firefox tab, we'll probably want to switch to qwerty mode to type a url!
strategy: "equals"
target_layer: "qwerty"
virtual_key_overrides: # unless...
# list of key codes and their decimal values here: https://cherrytree.at/misc/vk.htm
- virtual_key_code: 18 # this key is held down (alt in this case) when the window becomes active
targer_layer: "qwerty" # if it is, then switch to this layer, so that we can continue switching window focus with alt+hjkl
virtual_key_ignores: # alternatively
- 18 # if this key is held down (alt in this case), then don't make any layer switches
# your normal layer might have a tap-hold on j since it's a such convenient and ergonomic key
# but it sucks to be in vim, holding down j to move down and have nothing happen because of the hold...
# no worries! let's just switch to a layer which removes the tap-hold on the j when we are in windows
# where we use vim or vim editing extensions!
- exe: "WindowsTerminal.exe"
target_layer: "editor"
- exe: "idea64.exe"
target_layer: "editor"
Running
Once you have either the prebuilt binaries in your Path, or have compiled the binaries from source (these will already be in your Path if you installed Rust with rustup, which you absolutely should), you can run komokana -p [KANATA_PORT] -d [DEFAULT_LAYER] -c [PATH_TO_YOUR_CONFIG] at a Powershell prompt, and you should start to see log output.
Remember, both komorebi and kanata must be running before you try to start komokana, and kanata must be running with the --port flag to enable the TCP server on the given port.
This means that komokana is now running and listening for notifications sent to it by komorebi.
yasb Widget
When running komokana with the -t flag, a plaintext file will be updated whenever the layer changes at the following location: ~/AppData/Local/Temp/kanata_layer
You may optionally use this file to construct a simple yasb widget which polls and displays the contents of that file to provide a visual indicator of the currently :
# 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"
1.1k Jan 3, 2023
5 Jan 26, 2023
51 Dec 29, 2022
5 Nov 11, 2023
22 Apr 4, 2023
7.7k Dec 30, 2022
172 Dec 10, 2022
6 Jan 31, 2023
6 May 21, 2023
3 Sep 24, 2023
95 Dec 14, 2022
46 May 6, 2023
6 Nov 13, 2023
4 Aug 17, 2024
525 Jan 8, 2023
7 Jan 2, 2023
8 Apr 23, 2023
95 Feb 22, 2023