v1.6.1-prerelease-1

Configuration guide

Link to the appropriate configuration guide version: guide link.

Changelog (since v1.6.0)

• Fixed: some major issues with defchordsv2-experimental usability
• 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

50f909e882703cb121b8dd038bc561e588a1793f0585b62bd4dd50bfbd816f1c  kanata
ea4908d41f191beb7a43ab212f000e501910b301b76b0222fe480fb29c94b6bc  kanata.exe
75619c377a5609f4d1426d9f316fde1cd6a3f48b9950269823485401f833f22e  kanata.kbd
a7cba50a4ccc0bc7e48ff5fdbd04e5e429ae40819f8b677b92b0cf4d8e1e3d28  kanata_cmd_allowed
c3ab7f7ecf4244304cd9ca84b88de23d497a75e0bd97ee913f4c9a3f986f3145  kanata_cmd_allowed.exe
f343aee021901716f63ee9089a8e4fcda1d42ba505e8a5cb3372de781ba381dc  kanata_macos_arm64
54693decc2a0640c42ec321b36ad38e6e6473effc51aea6a08d7a90b09df1130  kanata_macos_cmd_allowed_arm64
4964e5cb9bdda99d357bf5be19439f4f2de1892a543918b54d51feff32428fd5  kanata_macos_cmd_allowed_x86_64
2c397c591f12c8081feb3e36798f527d7f35ab4b9499ff8b9db44ad4804e0337  kanata_macos_x86_64
43f095428c7305b5edd745885f8fc9846cf6aec9456517439672eea45e4b613f  kanata_scancode_experimental.exe
de641bb24cfe4572d67498bdd0ca8c999c504e3b95556b1c477623a12a0caff9  kanata_winIOv2.exe
54c35a78c532aad8dd7490e79d612d343f0edde36c95a101696e9cf90c9cd159  kanata_wintercept.exe
0c309d0229004ca24e3629f2169eef0f8d4c2d6df4f3c2b25b1f47ed60ba32ab  kanata_wintercept_cmd_allowed.exe