Configuration guide
Link to the appropriate configuration guide version: guide link.
Changelog (since v1.6.0)
- Fixed: some major issues with
defchordsv2-experimentalusability - Fixed: key repeat now works again for transparent/unmapped-but-processed keys in Windows and Linux TTY (macOS unknown if affected).
Sample configuration file
The attached kanata.kbd file is tested to work with the current version. The one in the main branch of the repository may have extra features that are not supported in this release.
Windows
Instructions
NOTE: All binaries are for x86-64 architectures only.
Download kanata.exe. Optionally, download kanata.kbd. With the two files in the same directory, you can double-click the exe to start kanata. Kanata does not start a background process, so the window needs to stay open after startup. See this discussion for tips to run kanata in the background.
You need to run kanata.exe via cmd or powershell to use a different configuration file:
kanata.exe --cfg <cfg_file>
NOTE: The kanata_winIOv2.exe variant contains an experimental breaking change that fixes an issue where the Windows LLHOOK+SendInput version of kanata does not handle defsrc consistently compared to other versions and other operating systems. This variant will be of interest to you for any of the following reasons:
- you are a new user
- you are a cross-platform user
- you use multiple language layouts within Windows and want kanata to handle the key positions consistently
This variant contains the same output change as in the scancode variant below, and also changes the input to also operate on scancodes.
NOTE: The kanata_scancode_experimental.exe variant has the same input defsrc handling as the standard kanata.exe file but contains a change for an issue where kanata outputs are not handled correctly by some applications. This has not yet been extensively tested but the hope is that it is a strict improvement in scenarios where kanata operates correctly.
Linux
Instructions
NOTE: All Windows binaries are compiled for x86 architectures only.
Download kanata.
Run it in a terminal and point it to a valid configuration file. Kanata does not start a background process, so the window needs to stay open after startup. See this discussion for how to set up kanata with systemd.
chmod +x kanata # may be downloaded without executable permissions
sudo ./kanata --cfg <cfg_file>`
To avoid requiring sudo, follow the instructions here.
macOS
Instructions
WARNING: feature support on macOS is limited.
For macOS 11 and newer:
- Install the Karabiner VirtualHiDDevice Driver.
To activate it:
/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate
For macOS 10 and older:
- Install the Karabiner kernel extension.
After installing the appropriate driver for your OS
Download a kanata_macos variant.
Run it in a terminal and point it to a valid configuration file. Kanata does not start a background process, so the window needs to stay open after startup.
Example
chmod +x kanata_macos_arm64 # may be downloaded without executable permissions
sudo ./kanata_macos_arm64 --cfg <cfg_file>`
cmd_allowed variants
Explanation
The binaries with the name cmd_allowed are conditionally compiled with the cmd action enabled.
Using the regular binaries, there is no way to get the cmd action to work. This action is restricted behind conditional compilation because I consider the action to be a security risk that should be explicitly opted into and completely forbidden by default.
wintercept variants
Explanation and instructions
Warning: known issue
This issue in the Interception driver exists: oblitum/Interception#25. This will affect you if you put your PC to sleep instead of shutting it down, or if you frequently plug/unplug USB devices.
Description
These variants use the Interception driver instead of Windows hooks. You will need to install the driver using the assets from the linked website or from the copy in this repo. The benefit of using this driver is that it is a lower-level mechanism than Windows hooks. This means kanata will work in more applications, including administrator-privileged apps.
Steps to install the driver
- extract the
.zip - run a shell with administrator privilege
- run the script
"command line installer/install-interception.exe" - reboot
Additional installation steps
The above steps are those recommended by the interception driver author. However, I have found that those steps work inconsistently and sometimes the dll stops being able to be loaded. I think it has something to do with being installed in the privileged location of system32\drivers.
To help with the dll issue, you can copy the following file in the zip archive to the directory that kanata starts from: Interception\library\x64\interception.dll.
E.g. if you start kanata from your Documents folder, put the file there:
C:\Users\my_user\Documents\
kanata_wintercept.exe
kanata.kbd
interception.dll
sha256 checksums
Sums
fd04643bf21f4cd0f805b31b5ef512e63251b815bae24ae4dc1839475c7de8fd kanata
27744c112a316e5d7efd0e90876f928f9900bae10a91cbb34fba303cbaffb762 kanata.exe
75619c377a5609f4d1426d9f316fde1cd6a3f48b9950269823485401f833f22e kanata.kbd
065c9abca2e3dc8c01956c2b11115f75a846c4e2cf13e693c2455c6e46508029 kanata_cmd_allowed
057eb7bf857b432671b30115cacf47757a37ac1ef588681ee5dd13ebbea2c77e kanata_cmd_allowed.exe
ea060822daa70c02a34c2b2ea85f35aa6bda62960b2798a97ad2a8ee55ef47f6 kanata_macos_arm64
492cb7b4eea7f1b43c33b6c82b9ca30bb3b4923843efe1fe7237039ec7491a60 kanata_macos_cmd_allowed_arm64
c231509cd8e7b775b94f7d1e2b2dc2a3b069cf4558ab6106fe97fe79bd91f902 kanata_macos_cmd_allowed_x86_64
1f6933fe767a711918c895052155e9de85e19b89e8855ad8c08dee9216cdc613 kanata_macos_x86_64
94f5f28d760bdd1022c45ec51b800975daf9523a868de0fbcab61d5171264553 kanata_scancode_experimental.exe
914f82fef1dd5ade6c823bbc44da6231c40fd3c4df6eb7db27e7a7209256586d kanata_winIOv2.exe
4bfe84d0275b82febf5e3f05879beeee743ba304f4a6f51c7fd406587a2a3e75 kanata_wintercept.exe
15d892ae23b80dd211dc1baf3462c45a2f651c456449f91c70fd9280cc03839e kanata_wintercept_cmd_allowed.exe