v1.5.0

Configuration guide

Link to the appropriate configuration guide version: guide link.

Changelog (since v1.4.0)

BREAKING FIX: change unicode yen key mapping to mean KEY_YEN instead of backslash.

BREAKING FIX: clear non-oneshot output chord (e.g. C-a) on next action.

BREAKING FIX: forcefully release all keys for a valid visible-backspaced sequence because modifiers can change the behaviour of backspace.

BREAKING FIX: add default (128) and configurable limit on dynamic macro recorded keys to protect users from forgetting to end and recording too many keys.

Change log

• Added: on-idle-fakekey action
• Added: toggle option for fake key actions
• Added: error message improvement when list action isnot ina list
• Added: movemouse-inherit-accel-state
• Added: movemouse-smooth-diagonals
• Added: mouse wheel events in defsrc for Linux and Interception
• Added: unmod and unshift actions
• Added: key-history in switch
• Added: tap-hold-except-keys
• Added (macOS): limited support
• Added (Linux): allow list syntax to define devices
• Fixed: avoid crash in an error case of macro parsing
• Fixed: change unicode yen key mapping to mean KEY_YEN instead of backslash
• Fixed: rpt-any works in more cases
• Fixed: allow unmodded list in macro
• Fixed (Windows-Interception): mbck/mfwd up/down were switched, making Windows behave strangely
• Fixed (Windows-Interception): send/release Esc for OsCode with unknown mapping instead of crashing
• Fixed (Linux): maybe-fixed an issue around high CPU and memory consumption due to the rustix dependency
• Fixed (Linux): fixed issue related to touchpad disable

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

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>

Linux

Instructions

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

WARNING: the provided binaries are only for x86 devices. If you are using ARM macs, e.g. M1/M2, you must compile kanata yourself

First, install the Karabiner VirtualHiDDevice Driver.

To activate it:

/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate

Download kanata_macos.

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.

chmod +x kanata_macos   # may be downloaded without executable permissions
sudo ./kanata_macos --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

864cd50f07dbb183070f7b5186539732ba2b713630adad05f06499a5bfcd3e62  kanata
74b7a0c751507a9d0e2774337053ac7961cdd8a52aeb1be01a3698fddaf8b423  kanata.exe
aae72ccffc983b379615ce82d4fee0ada5a50acfe4a2660ffbee0a5b1a21fc62  kanata.kbd
405010049a11ce7ab1c030688c7b13ad982014c7e3c29c4de7ba9355e44da6ab  kanata_cmd_allowed
972703233fcd9a24180ae738dbcf1d5f27d571f45337eafae832fde8585e6bb0  kanata_cmd_allowed.exe
6ac269ef08748a12f8ad4726d18cc362164d2d427958bc0a2c24b4a8ac8d225b  kanata_macos_x86
eb722e05c464fabf3fd31c46efbe41d218e7b88764e861e19db84f31b1405b28  kanata_macos_cmd_allowed_x86
f32f73fefc4627d86361a6134dff7f1ea009606cfb99a6dc426260880d4b8261  kanata_wintercept.exe
f589c04a4e2bc7b0fe1176d57ad5b70b79991bbe1ce256cbbfd7a9c5682ab6db  kanata_wintercept_cmd_allowed.exe