v1.6.0-prerelease-1

Configuration guide

Link to the appropriate configuration guide version: guide link.

Changelog (since v1.5.0)

BREAKING FIX: dynamic-macro now records and simulates delays by default to reproduce tap-hold effects correctly. It can be turned off via an undocumented defcfg entry.

BREAKING FIX: TCP server messages now emit newline terminators for easier message differentiation.

BREAKING FIX: Add concat keyword for defvar that enables appending strings together. This will only break you if you happened to use concat as the very first string in a list value in defvar, which seems unlikely.

Change log

• Added: concurrent-tap-hold to defcfg, allowing tap-hold actions to time out in parallel
• Added: --check argument to verify config file without starting kanata
• Added: lrld-num action, allowing live reloading a specific config argument position
• Added: block-unmapped-keys to defcfg
• Added (Windows Interception): windows-interception-keyboard-hwids to specify specific keyboards to intercept
• Added (macOS): kext support for macOS version 10
• Fixed (Linux): exit on SIGTSTP to prevent locking out users from using the keyboard

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>

NOTE: The kanata_scancode_experimental.exe file contains a change for this issue where kanata does not operate correctly in 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. Testing would be helpful!

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

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 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

8d67e60b7a56dd1c2b67db1b7c100b01cdf3b0fd176be279809687d546ceeaac  kanata
e608f1930df2b6c7824b15bdb34fb0a9c14ebff964d179ca3fa5393b2a41f5b6  kanata.exe
6db41e5c10a7bda8956ea91662ce954612a0e980db88f51d778c476ef54d355c  kanata.kbd
0b04ee496b179a3799d348976c301a8d5682695ad5f5baeb235c2803285a6de7  kanata_cmd_allowed
ffdbaf8634378494b5a2a51de4477578fee2bdfd7c66713a622916089ed21718  kanata_cmd_allowed.exe
3f13241b5a5e13f7888085c8a1c1adccb1ef8c0009b3c4f794ceeedb53e93bf1  kanata_macos
8131d583e48dd2af0328a2e65a018c56848a289e40f078d97bbdcf10b2689de5  kanata_macos_cmd_allowed
a77ba4cc9d48b0fe0b670a01ad82d089cad7a97509001c25fb4d3cda858b1be7  kanata_scancode_experimental.exe
85a03298b21c588192d95458be1f2e098405618425788510f94f53caceb5032c  kanata_wintercept.exe
b188c600ff238559354d1245fc0eb682a9337b5a43eb3cc877013bb8c3b9ccb5  kanata_wintercept_cmd_allowed.exe

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

v1.5.0-prerelease-3

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
• 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

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.

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

b06ddd8ad23a95be2b1ff8c8d91dfd4082b61a6f21d6825c615d7729d69736de  kanata
61c600b133941899177d358fdc4babedf650eeda56f2636b151ad8cb9906c1d7  kanata.exe
85dc28a5d83b514484414365a46c97863771b44c2b12178beeadf4c34b434bff  kanata.kbd
0f502a019169e2bdd070ea3865543b44b86729c324bb5c02e0f024cc3f165893  kanata_cmd_allowed
ff8f4a04b4af4ece130262ec1707d2f2da438e7b527413e6f6014c72f44bcd34  kanata_cmd_allowed.exe
dcd9ff220ea0145b9f325f01d10f427aef87663df00274fbe32c7f8a3fe3d9e6  kanata_wintercept.exe
ded65e0b616b36f8033fabf0936dc5a7450aa57eb187c304946f61a672d168d6  kanata_wintercept_cmd_allowed.exe

v1.5.0-prerelease-2

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

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
• 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 (Windows-Interception): mbck/mfwd up/down were switched, making Windows behave strangely
• Fixed (Linux): maybe-fixed an issue around high CPU and memory consumption due to the rustix dependency

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.

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

e77462f7cf98353fca95a37da2d3c083b26421af1fae2a174bded0a41714a415  kanata
5ab1ee4bccc4830c04777b061d1cb93f5c53284608b01b8976f64442a8bc968e  kanata.exe
c16f7ff77c65011a800ff5e466242f4960b7628dd72bb6edbda0d4cde9f8f443  kanata.kbd
e7825a5e3f47bf6396903bad333e37826952a6bba7ebfee4449923edf511cf8d  kanata_cmd_allowed
82bc0b87ded26414a5e773f7736b71305f731efa68b28c3c4b5297f1b6347b14  kanata_cmd_allowed.exe
60362cb2241c66d3c9619e46b5f03cc051be2bc17a392c1261a6f6f7d33af806  kanata_wintercept.exe
735f6995e3f2e3ad380bc26f089da5c142aa2c2dc46502ca3b04a3783cdd1186  kanata_wintercept_cmd_allowed.exe

v1.5.0-prerelease-1

Changelog (since v1.4.0)

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

KNOWN BUG: deflocalkeys has a bug. You should use a older build, or newer if available. Fixed in latest main branch.

Change log

• Added: on-idle-fakekey action
• Added: toggle option for fake key actions
• 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 (Windows-Interception): mbck/mfwd up/down were switched, making Windows behave strangely

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.

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

39c8e44fb3db41f9657a81068dbb18c06f20df0c462f261dd6436cf41fe26eba  kanata
892e66d9e784d7bc1aa8bec09dc1d1146a072e515c0664614368425fc3fc689e  kanata.exe
0f817f9244daed39d369609abf1f86840881ee5b72a9307d6e04f9c5ab1347c3  kanata.kbd
0d52fcddf9ab4f66da36407759af66c7ce5f7b5d7cd047d8b46d99dfdcb45310  kanata_cmd_allowed
ce849dffb7233775548cd86306af78c5474ae75d1aca5dfe4ca88db6c1273dd3  kanata_cmd_allowed.exe
3dab543272b985242ab6a4b512e42deacd0710a8a35dad5ad24b1a16dfee1fd7  kanata_wintercept.exe
295332b054d83e658effec7280a2e1457025cb0d692d034ba22b898d4017d5ce  kanata_wintercept_cmd_allowed.exe

v1.4.0

Changelog (since v1.3.0)

• BREAKING FIX: kanata now errors on unknown defcfg options instead of silently ignoring them.
• BREAKING FIX: kanata now errors on unknown defcfg boolean values (e.g. this-is-not-yes) instead of silently ignoring them.
• BREAKING FIX: kanata timer handling accuracy has improved. The accuracy should now be +-1ms of the configuration. It was slow before this version, meaning a value of 100 for a delay/timeout might result in 110 ms instead. This might mean your configured timeouts and delays are now too fast for what you're used to.

Change log

• Fixed: macro with delay at end now behaves correctly
• Fixed: trigger error on duplicate file name
• Fixed: time handling accuracy is now +- 1ms
• Fixed: crashing when combining certain actions with chords
• Fixed(Linux): kanata hi-res scroll now works properly
• Fixed(Linux): symlink path was incorrect
• Fixed(Windows): swiss $ key
• Fixed(Windows): kprt key behaviour with Interception
• Fixed(Windows): lsft-arrow workaround now triggers more accurately, breaking fewer use cases
• Added: chords in defseq
• Added: caps-word
• Added: macro-repeat
• Added: dynamic-macro-record-stop-truncate
• Added: defaliasenvcond
• Added: config directory discovery for kanata cfg file
• Added: rpt-any
• Added: flag to remove kanata startup delay
• Added: chord output key(s)/layer-while-held release only when all input keys are released
• Added: defcfg item to delegate transparent keys to first layer
• Added: include in configuration to include other files
• Added: movemouse-speed, to modify mouse speed at runtime
• Added: switch, a switch-case action evaluator
• Added: scnl, sequence cancel, and sequence, per-action sequence timeout
• Added(Windows): increase kanata process priority for better responsiveness
• Added(Linux): defcfg items for filtering by device name
• Added(Linux-X11): defcfg item for setting key repeat delay and rate

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.

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

5138efbacedbbec3dca05bd7fbc207c01afd3772d298081735b08d710ee78380  kanata
ada28db8b19dc8122f07d3daeaee02b5a4338ab977fde99471b01bac1c22dd79  kanata.exe
67666d0dc2c36be672e06e9267762a2be92d24dcd307bac6de33330cee3952bf  kanata.kbd
843443b218785cede0ec718704f8c6f9435c28337068c49abeaebdc0373f833b  kanata_cmd_allowed
da996710ce838b0667afa7bb24fd4eeca0eb2424109ddace883dcf940b6fd642  kanata_cmd_allowed.exe
eff969faf08d7bbefd717dd66438699dd27e466e323cb5606e8ad8460ae0bd2d  kanata_wintercept.exe
fd3a1450d99c3ee9fa7d6d18aa3712daf3f998cafdec51e4f141b26de0dc8eb9  kanata_wintercept_cmd_allowed.exe

v1.4.0-prerelease-3

Changelog (since v1.3.0)

• BREAKING FIX: kanata now errors on unknown defcfg options instead of silently ignoring them.
• BREAKING FIX: kanata timer handling accuracy has improved. The accuracy should now be +-1ms of the configuration. It was slow before this version, meaning a value of 100 for a delay/timeout might result in 110 ms instead. This might mean your configured timeouts and delays are now too fast for what you're used to.

Change log

• Fixed: macro with delay at end now behaves correctly
• Fixed: rpt now follows caps-word
• Fixed: trigger error on duplicate file name
• Fixed: time handling accuracy is now +- 1ms.
• Fixed(Linux): kanata hi-res scroll now works properly
• Fixed(Linux): symlink path was incorrect
• Fixed(Windows): swiss $ key
• Fixed(Windows): kprt key behaviour with Interception
• Fixed(Windows): lsft-arrow workaround now triggers more accurately, breaking fewer use cases
• Added: chords in defseq
• Added: caps-word
• Added: macro-repeat
• Added: dynamic-macro-record-stop-truncate
• Added: defaliasenvcond
• Added: config directory discovery for kanata cfg file
• Added: rpt-any
• Added: flag to remove kanata startup delay
• Added: chord output key(s)/layer-while-held release only when all input keys are released
• Added: defcfg item to delegate transparent keys to first layer
• Added: include in configuration to include other files
• Added(Windows): increase kanata process priority for better responsiveness
• Added(Linux): defcfg items for filtering by device name
• Added(Linux-X11): defcfg item for setting key repeat delay and rate

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.

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

5f1118dc6940afce56efa6ea8ec116f54a7ef136658f3ba58d5317e98f7c543b  kanata
8b2a3cac63d06663f9cd199b3a196b37e20cd1ea6a71a90686fc7a6eca5470c9  kanata.exe
d38b30b434c99249735940250c6d87afb75b670fef4f139428c636244effc086  kanata.kbd
7cda850f436c5ab5f8643e4b7c2faa1a55ca6e5d52f7f43cde3e89effa518081  kanata_cmd_allowed
ff34fc8aef5b6ee772462e43f5b3fcf76682bcd28ed9aabfbb0a45313b5cce4e  kanata_cmd_allowed.exe
7bb4651a76b83803b8995b84912e2ec11e5b7a854aa57ec2d0f9085b0610879d  kanata_wintercept.exe
441fcf935270d56032fa3f9db9d8278bde1e81251640d6c2c180a6735d4f444f  kanata_wintercept_cmd_allowed.exe

v1.4.0-prerelease-2

Changelog (since v1.3.0)

BREAKING CHANGE: kanata now errors on unknown defcfg options instead of silently ignoring them

Change log

• Fixed: macro with delay at end now behaves correctly
• Fixed: rpt now follows caps-word
• Fixed: trigger error on duplicate file name
• Fixed(Linux): kanata hi-res scroll now works properly
• Fixed(Windows): kprt key behaviour with Interception
• Fixed(Windows): lsft-arrow workaround now triggers more accurately, breaking fewer use cases
• Added: caps-word
• Added: macro-repeat
• Added: dynamic-macro-record-stop-truncate
• Added: defaliasenvcond
• Added: config directory discovery for kanata cfg file
• Added: rpt-any
• Added: flag to remove kanata startup delay
• Added: chord output key(s)/layer-while-held release only when all input keys are released
• Added(Linux): defcfg items for filtering by device name

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.

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

afcaabe2ddbcb66edaeaaa5e3eec67dec8aa0bc42fc1830562bf0fb87fb902f8  kanata
4eb35425e2ce1ec89e30781e2048b7ca573db58f85d70621c77074e9ba0e20f9  kanata.exe
898e67be5eb3d4b679ac5f3e1604d0ed1459246cc8390ff5c2bead600e39f386  kanata.kbd
c09887e9efb47d276c161b27d0397cd7b774d5b74abfb268767381ef19b09ab7  kanata_cmd_allowed
bb44413f0992e3256bed248615a391c4f3060d4e8626c5f4d6ef15baeaf3968d  kanata_cmd_allowed.exe
b3ee781ecd0f42cf65f0c82379fb714ecb3bd9be1514a711fd756656e5041be5  kanata_wintercept.exe
f3102551b64134885e33efe1c93ca47ca89f8c8fbdd89850bb81971407e56408  kanata_wintercept_cmd_allowed.exe

v1.4.0-prerelease-1

Changelog (since v1.3.0)

Change log

• Fixed: kprt key behaviour with Windows Interception
• Added: caps-word
• Added: macro-repeat
• Added: dynamic-macro-record-stop-truncate

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.

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

7f9fe160b5dcef0b6ca312c6d69f157ce832b42503b5b86004d749def3e27be5  kanata
48ba78dae52a53f8707f7bd2bddd60da9b0d57be548181444300898d0abb2fb3  kanata.exe
099fe0ad037600191c30223057f438d57ba9f6d7831c92612c4cd90cf590f1e9  kanata.kbd
7d3a8bd309bfaf0302ea0272b6b29cd1b22b29f524a30c5c56f515fc650332aa  kanata_cmd_allowed
8a8f4a3c8417729bef0581f34aae0df1d743b04600439f49b738df3ab47b16f1  kanata_cmd_allowed.exe
a46b6347adcaa3ea9e6dab72f7f744c2cac27963305453f2457e6848668622d7  kanata_wintercept.exe
ba57f2f4b8d48350e52a1e28ce0ae0c6ae91df037e055eb66fc4c02d91f23fa2  kanata_wintercept_cmd_allowed.exe

v1.3.0

Changelog (since v1.2.0)

WARNING: Kanata now errors on invalid top-level config items. Kanata previously would ignore these and they would do nothing. Now they result in errors in the configuration.

---

Change log

• Fix: do not close immediately on error
• Fix: increase keyberon key queue size to help with long tap-hold durations
• Fix(Linux): change locking pattern causing unresponsiveness in some cases
• Fix(Linux): add accidentally uncfg'd key names
• Fix(Windows): release shift properly on shifted arrows
• Fix(Windows-Interception): correction of deflocalkeys-wintercept
• Fix(Windows-Interception): fix issue with Interception driver sending Esc
• Fix(Windows-Interception): use Interception mouse movement instead of SendInput

---

• Added: -timeout variants of tap-hold that add a third potential action
• Added: pretty errors using the miette crate
• Added: make defcfg optional
• Added: allow disabling of layer logging
• Added: ensure all keys are released at the end of a dynamic macro
• Added: tap-hold-release-keys
• Added: one-shot variants
• Added: defvar to allow defining variables
• Added: fork action that chooses left or right actions based on currently active keys
• Added(Linux): mouse move support to Linux
• Added(Linux): systemd notification when kanata has finished starting up
• Added(Windows-Interception): use SendInput for arbitrary-code in Interception as well

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.

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

561b58713d9b0967be17e782355766feca3fa9bed45e6b396fa0ba224eba36b5  kanata
a2848d43067de517855ca4321a90d6f3ff3bd0ea221aec52d0d6973df28c8760  kanata.exe
f862b7cad27d5d0bc4e7371bbb106fdb08453682f3729e63d45f62a7308ed7e6  kanata.kbd
5d8566211f0025c508397d7ff33f766ed3bb928556ef54c0ad536a07716bc18c  kanata_cmd_allowed
df2cab04eab5cb4fbd57e8ab72b7808e2bb3b93321f9c15a8e4f06dea3e5439d  kanata_cmd_allowed.exe
8fd91940772e790027e2e0024fff90db6c9e0b88f4641274dfa59148b663a3ca  kanata_wintercept.exe
2ad144c51c62f7af8c73af1d6ffd4454d559d5ccb3aa9e820a7d66d12008e859  kanata_wintercept_cmd_allowed.exe