kanata

Improve keyboard comfort and usability with advanced customization

LGPL-3.0 License

Downloads
29.5K
Stars
2K
Committers
24
View Code on GitHub
Ecosystems: Rust, Linux, Windows, macOS

Bot releases are visible (Hide)

kanata - v1.7.0-prerelease-1 Latest Release

Published by jtroo 3 months ago

Configuration guide

Link to the appropriate configuration guide version: guide link.

Changelog (since v1.6.1)

Added: O-(...) for any-order overlapping keys in sequences.
Added: conditional configuration using environment variables via (environment (name val) ...)
Added: allow double-quotes within strings by adding Rust-style strings r#"<content>"#. Potentially breaking, but seems doubtful that anyone has a good reason to be doing this
Added: --log-layer-changes flag to override false configuration temporarily for testing
Added: parse numbers as a delay (unit milliseconds) for cmd-output-keys
Added: unmod can accept a modifier list as the first parameter to selectively undo only some modifiers
Added: option to eagerly release override output to help with some use cases
Added(Windows): capability to use Kanata as a library for AHK
Added(Windows): GUI tray app (gui variants of the executable)
Added(Windows-Interception): add device exclusion (include by default) in defcfg
Added(Linux): linux-use-trackpoint-property for middle mouse scrolling on ThinkPads
Added(macOS): unicode action is now implemented
Added(macOS): mouse actions are now implemented (some bugs still exist)
Fixed: chordsv2 now eagerly activates tap-hold-press|release
Fixed: block-unmapped-keys now only blocks unspecified actions, where before it would block explicitly transparent keys 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

NOTE: All Linux binaries are compiled 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.

The gui variants only use the winiov2 I/O mechanism.

NOTE: The kanata_legacy_output.exe variant has the same input defsrc handling as the standard kanata.exe file. It uses the same output mechanism as the standard kanata.exe variant in version 1.6.1 and earlier. In other words the formerly experimental_scancode variant is now the default binary. The non-legacy variants contain changes for an issue; the fix is omitted from this legacy variant. The legacy variant is included in case issues are found with the new output mechanism.

Linux

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

WARNING: feature support on macOS is limited.

For macOS 11 and newer:

To activate it:

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

For macOS 10 and older:

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

kanata_passthru.dll

The Windows kanata_passthru.dll file allows using Kanata as a library within AutoHotkey to avoid conflicts between keyboard hooks installed by both. You can channel keyboard input events received by AutoHotkey into Kanata's keyboard engine and get the transformed keyboard output events (per your Kanata config) that AutoHotkey can then send to the OS.

To make use of this, download kanata_passthru.dll, then the simulated_passthru_ahk folder with a brief example, place the dll there, open kanata_passthru.ahk to read what the example does and then double-click to launch it.

sha256 checksums

5d3245e092e5b4f0d42669cbe666210bccbfcc11fe700f8d3b3e0c475aef3cfd  kanata
fb58bbdc83f151199a0a990657f403baf08ddda532f1fe552f4e37db88671e8b  kanata.exe
f7e1543ffb7c2a610c60822b753d78c29e0ac501806ea3aba5192cecac02cb25  kanata.kbd
f290678681e91688a4ee662bdd3f3f03ccf7ba54e9b9683ffe0e96ab49cbe000  kanata_cmd_allowed
09c9119d8cd3df67a47cb040028977e26ba938572128eb1b2887baf0ed9f9d76  kanata_cmd_allowed.exe
36857288e9df2227b4378013998af64a0241a6f50d99a514cb8fe9be70fd5914  kanata_gui.exe
3669ebde601388cd2bcb3e9389be0c00b283520cad457211023e87854426dfa1  kanata_gui_cmd_allowed.exe
3669ebde601388cd2bcb3e9389be0c00b283520cad457211023e87854426dfa1  kanata_gui_wintercept.exe
b1acef7457be03e0143a3d8f5cfb0c43a63eb79ee20338a7ccdde33b96633316  kanata_gui_wintercept_cmd_allowed.exe
3c7ee427208886c7269cc1483abf363b3ce09f9105b5579fe59ba3416d997360  kanata_legacy_output.exe
cb7643f72801f124935692fd7b632a0df904a1c07e27f1188605048862ebdd23  kanata_macos_arm64
5509b1bf491287408e903fc729f6d3ad03643997f2b1ebdf088857aa098920b0  kanata_macos_cmd_allowed_arm64
c8345c43d2304ba8b9af1b5e7b8c2187705329532d02aa43611f8ecfca8d6288  kanata_macos_cmd_allowed_x86_64
69ad95857db5d33ec3170f4ad0acf535dea9e340e1962979ab2368a77e603360  kanata_macos_x86_64
33144159cef3b8d4e2a45d3b9ce58c763bf188f8ca6b86029dfbfea9d2dabbce  kanata_passthru.dll
8205ffb13bcd15a949d4c93d28d4c1fd48d1d749335cc7dedd566e549faaeec3  kanata_winIOv2.exe
9c07873c0fee8b23cbda2328d326290ab4f6bd13e7367cb5dcdb8120f66febc5  kanata_wintercept.exe
7e05bc70af1a82b529c89df7566fb98cb8cc2957249a731c92c68c3afcb32b6c  kanata_wintercept_cmd_allowed.exe
kanata - v1.6.1

Published by jtroo 6 months ago

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

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

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

WARNING: feature support on macOS is limited.

For macOS 11 and newer:

To activate it:

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

For macOS 10 and older:

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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
93065d246b1c302df3b98ae53827f2f182224181aa221f86debfd0b54fa63811  kanata_macos_cmd_allowed_x86_64
d99be3c45ca7772f6bb4c3918e279154797f51386d1a89dc5adffdff2c8b9b03  kanata_macos_x86_64
94f5f28d760bdd1022c45ec51b800975daf9523a868de0fbcab61d5171264553  kanata_scancode_experimental.exe
914f82fef1dd5ade6c823bbc44da6231c40fd3c4df6eb7db27e7a7209256586d  kanata_winIOv2.exe
4bfe84d0275b82febf5e3f05879beeee743ba304f4a6f51c7fd406587a2a3e75  kanata_wintercept.exe
15d892ae23b80dd211dc1baf3462c45a2f651c456449f91c70fd9280cc03839e  kanata_wintercept_cmd_allowed.exe
kanata - v1.6.1-prerelease-1

Published by jtroo 6 months ago

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

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

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

WARNING: feature support on macOS is limited.

For macOS 11 and newer:

To activate it:

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

For macOS 10 and older:

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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

Published by jtroo 6 months ago

Configuration guide

Link to the appropriate configuration guide version: guide link.

Known issues

  • Some major issues with defchordsv2-experimental usability
    • Fixed in main and in v1.6.1-prerelease-1
  • Key repeat stopped working for transparent/unmapped-but-processed keys in Windows and Linux TTY (macOS unknown if affected)
    • Fixed in main and in v1.6.1-prerelease-1

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.

BREAKING FIX: Input chord release behaviour has been improved but might affect existing workflows

BREAKING FIX: TCP server now only listens to localhost by default. This can be opted out of by specifying the server address (originally it was 0.0.0.0) as part of the -p command line argument.

BREAKING CHANGE: Transparent key behaviour now checks all active layers by default, as opposed to the old behaviour where it would only go to the base layer. This change can be opted out of by adding transparent-key-resolution to-base-layer to defcfg.

  • Added: deflayermap - an alternate way to define layers that may be more preferable to some
  • 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: rapid-event-delay as a mitigation around desktop environments incorrectly handling some rapid events
  • Added: template definition and expansion for reducing boilerplate
  • Added: more switch logic (not, key-timing, input, input-history)
  • Added: lrld-file action
  • Added: improved wording + syntax of fake key operations, changing name from fake to virtual
  • Added: more TCP client requests and server events
  • Added: platform top-level configuration item to conditionally use configurations depending on the running platform
  • Added: experimental V2 of chords, which is a global configuration and is a separate system from existing actions
  • Added: maximum layers is increased from 25 to 60000
  • Added: special nopX keys that can be used for sequences, fork, and switch
  • Added (Windows): binary now has a manifest that can be manipulated to allow LLHOOK-based binaries to operate in administrator-privileged windows
  • Added (Windows winIOv2): added deflocalkeys-winiov2 variant
  • Added (Windows Interception): windows-interception-keyboard-hwids to specify specific keyboards to intercept
  • Added (Windows Interception): windows-interception-mouse-hwids to specify multiple mice to intercept
  • Added (macOS): kext support for macOS version 10
  • Fixed: input chord key association for presses/releases
  • Fixed: input chords resulting in multiple tap-holds can now activate both holds
  • Fixed: permit optional UTF8 BOM at the beginning of a configuration file
  • Fixed: allow all symbols to be overridden in deflocalkeys
  • Fixed: right-hand modifiers are released properly for visible-backspaced sequences
  • Fixed: mouse buttons and wheel actions are now forwarded correctly with process-unmapped-keys yes, without explicit definition of mouse buttons, while grabbing the mouse
  • Fixed (Linux): exit on SIGTSTP to prevent locking out users from using the keyboard
  • Fixed (Windows LLHOOK): reduced blast radius of lsft workaround (properly this time)
  • Fixed (Windows LLHOOK): handling of locking via Win+L works correctly

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

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

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

WARNING: feature support on macOS is limited.

For macOS 11 and newer:

To activate it:

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

For macOS 10 and older:

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

f61c39c709adf5fd584c9646dfcadfa91bd235aad744dbf60c5815a61132c642  kanata
d51561b5701dc18971b4cb794694796577579513195a1354e3d7dd2a46f5b2e5  kanata.exe
75619c377a5609f4d1426d9f316fde1cd6a3f48b9950269823485401f833f22e  kanata.kbd
45c05d384a85c93dee4efc915ab06028f3390509af29c1c11fc39357c9a6c38e  kanata_cmd_allowed
e2f148fe7d4dfdba0ee26aa0dba8f70cbe69e1b89e1155b4eccfc63cd1ece641  kanata_cmd_allowed.exe
b0949f2a4374b40893fd75e17a319b2b79ab2fc52fbac3ade4aaf4e73393baec  kanata_macos_arm64
f21db1463ca057890a9c4dd49800eb4534e8d12c5f459465ffc6143ff46cd94d  kanata_macos_cmd_allowed_arm64
0cdb499ab6f7ef2fe3415642ddd58b12fbf037e77c745b8408a4595b50f68be3  kanata_macos_cmd_allowed_x86_64
5814d2e39fc96d8cbbaed9d26f46848ac0bd835b58b2c586da664b05f9ab4be8  kanata_macos_x86_64
19f8bda8fd184faf1892f0ac7e348673edf0ded07f356b702cc7a75ffd6930f8  kanata_scancode_experimental.exe
feeea20798767c449c89ade654ab5bc59b45a840034a2f57b98ee10be8b2ea0b  kanata_winIOv2.exe
6757a094a5b1b1f4be0dc1fbb9740be35ee15b38e3372e10ef9ff89bca48f19c  kanata_wintercept.exe
5830eeea31733fc5c01769fbec91e4b5c54228fd87de900be0b736aefef7ed23  kanata_wintercept_cmd_allowed.exe
kanata - v1.6.0-prerelease-4

Published by jtroo 6 months ago

Configuration guide

Link to the appropriate configuration guide version: guide link.

Notable changes since earlier v1.6.0 prereleases

BREAKING CHANGE: deflayermap no longer uses the mapping string - it now uses configuration pairs similar items like defvar and defalias, instead of triples.

Known Issue(s): = cannot be used in deflayermap. Fixed in latest main. Workarounds in this version: use eql or Equal.

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.

BREAKING FIX: Input chord release behaviour has been improved but might affect existing workflows

BREAKING FIX: TCP server now only listens to localhost by default. This can be opted out of by specifying the server address (originally it was 0.0.0.0) as part of the -p command line argument.

BREAKING CHANGE: Transparent key behaviour now checks all active layers by default, as opposed to the old behaviour where it would only go to the base layer. This change can be opted out of by adding transparent-key-resolution to-base-layer to defcfg.

  • Added: deflayermap - an alternate way to define layers that may be more preferable to some
  • 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: rapid-event-delay as a mitigation around desktop environments incorrectly handling some rapid events
  • Added: template definition and expansion for reducing boilerplate
  • Added: more switch logic (not, key-timing, input, input-history)
  • Added: lrld-file action
  • Added: improved wording + syntax of fake key operations, changing name from fake to virtual
  • Added: more TCP client requests and server events
  • Added: platform top-level configuration item to conditionally use configurations depending on the running platform
  • Added: experimental V2 of chords, which is a global configuration and is a separate system from existing actions
  • Added: maximum layers is increased from 25 to 30000
  • Added(Windows winIOv2): added deflocalkeys-winiov2 variant
  • Added (Windows Interception): windows-interception-keyboard-hwids to specify specific keyboards to intercept
  • Added (Windows Interception): windows-interception-mouse-hwids to specify multiple mice to intercept
  • Added (macOS): kext support for macOS version 10
  • Fixed: input chord key association for presses/releases
  • Fixed: input chords resulting in multiple tap-holds can now activate both holds
  • Fixed: permit optional UTF8 BOM at the beginning of a configuration file
  • Fixed: allow all symbols to be overridden in deflocalkeys
  • Fixed (Linux): exit on SIGTSTP to prevent locking out users from using the keyboard
  • Fixed (Windows LLHOOK): reduced blast radius of lsft workaround (properly this time)
  • Fixed (Windows LLHOOK): handling of locking via Win+L works correctly

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

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 and want kanata to handle the key positions consistently

This variant contains the same change as in the scancode variant below, and also changes the input to also handle scancodes instead of only the output.

NOTE: The kanata_scancode_experimental.exe variant has the same 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

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

WARNING: feature support on macOS is limited

For macOS 11 and newer:

To activate it:

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

For macOS 10 and older:

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

2fda915d56c962f74adb605ff11c64631722c2c7783d5fe9bffd0d3378ee8937  kanata
9f9e30516acb1ce56219f0e34e75aab4b6960a63534435435704dec2c97d10eb  kanata.exe
2a9b66957103c769baa9b0154dfac685ae30f79bf4e1224b9ed183be46b89db0  kanata.kbd
0befc6648a5a816699a33ad15208424108544e214dc439d9e72aa12b347a428f  kanata_cmd_allowed
4a96a0160a1f1af401521fd48d60c001306759fe4acb92dc1db7ed5c3e3a28bf  kanata_cmd_allowed.exe
74aa51cd279613753c47ecb10cd41a2322692d3cfb990b074c86f6eeec11f06e  kanata_macos_arm64
3da9bbfeb42bf38620a13ba4fee9fab9bea4f4684ff8858305c06015653d93d2  kanata_macos_cmd_allowed_arm64
01d538daa0ab9d707af8be3447ca4cdd56390b92337a263db0395fff418cab6d  kanata_macos_cmd_allowed_x86_64
cd096660f581ea36806bcd3fa0e1c873469e84460eaff0f429f54cf62b6b6668  kanata_macos_x86_64
cd103a1eab3db574223bf83b2cf7492c589053a5ee69b7e3afe34f8e7329b026  kanata_scancode_experimental.exe
6fee039fef4a34aff489b14d8c9bdc7e51d8767d969ceea87db67add5030789b  kanata_winIOv2.exe
8cf0289212e61fa871323721fa4524997c95b113b59c334e71f33f0cff218dac  kanata_wintercept.exe
b2710b845289119fafa52da95851f2e33d1e8094d99ae432974309ab888da5b4  kanata_wintercept_cmd_allowed.exe
kanata - Windows key code tester v0.3.0

Published by jtroo 7 months ago

Binaries to help test Windows keycodes without having to have a kanata config. Simply run the program and see the logs.

Notes for interception variant:

Running the binary has the same requirements as kanata. See the wintercept variants of the kanata release.

kanata - v1.6.0-prerelease-3

Published by jtroo 7 months ago

Configuration guide

Link to the appropriate configuration guide version: guide link.

Notable changes since prerelease-2

BREAKING CHANGE: deflayer-custom-map is renamed to deflayermap

Fix: kanata_winIOv2.exe now handles arrow keys and other "extended scancode" keys correctly at the input side.

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.

BREAKING FIX: Input chord release behaviour has been improved but might affect existing workflows

BREAKING CHANGE: Add web event.code names as usable configuration key names, making them no longer usable in deflocalkeys.

  • Added: deflayermap - an alternate way to define layers that may be more preferable to some
  • 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: rapid-event-delay as a mitigation around desktop environments incorrectly handling some rapid events
  • Added: template definition and expansion for reducing boilerplate
  • Added: more switch logic (not, key-timing, input, input-history)
  • Added: lrld-file action
  • Added: improved wording + syntax of fake key operations, changing name from fake to virtual
  • Added: more TCP client requests and server events
  • Added (Windows Interception): windows-interception-keyboard-hwids to specify specific keyboards to intercept
  • Added (Windows Interception): windows-interception-mouse-hwids to specify multiple mice to intercept
  • Added (macOS): kext support for macOS version 10
  • Fixed: input chord key association for presses/releases
  • Fixed: input chords resulting in multiple tap-holds can now activate both holds
  • Fixed (Linux): exit on SIGTSTP to prevent locking out users from using the keyboard
  • Fixed (Windows LLHOOK): reduced blast radius of lsft workaround (properly this time)
  • Fixed (Windows LLHOOK): handling of locking via Win+L works correctly

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

NOTE: All binaries are for x86 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. This 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 and want kanata to handle the key positions consistently

Known issues:

  • deflocalkeys-win does not work properly for this variant. It needs a different variant (or use the values you would use for deflocalkeys-wintercept

NOTE: The kanata_scancode_experimental.exe variant has the same defsrc handling as the standard kanata.exe file but contains an 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

NOTE: All binaries are 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

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:

To activate it:

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

For macOS 10 and older:

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

a26bb1bc8f30c407c16e96dd8010549f11e7fd340f5949ab4ca9f23841c61e3f  kanata
bd862b85a66fbd59c7de3183e16393fed1bd0a76c1cf76621259286248108cda  kanata.exe
989e64c5ba85f2930ba3e4b4bcac54c93412466529b7cc7de5c6bd3f299414f7  kanata.kbd
b78229867c90a05a0c214b018ed65044087b4ea4b702c33700e0afe2c0ee3f2d  kanata_cmd_allowed
aff4b2f1ea4169a2ee1294f99129fe7a09c911e853c88a41acca13c43c68ebe2  kanata_cmd_allowed.exe
3f03620db1480af4aee3035a8daf1f152bf88ada43d2ff3f5b8cd2caf5005b55  kanata_macos_cmd_allowed_x86
2002e97124f10542d3907a37d82ab94acc760c1080e931555e9410c3c8e06fbe  kanata_macos_x86
c053e0c278f90dc0bcf925cf69c9c1c8023ed6d4c6332b6ba8722ad3536132c2  kanata_scancode_experimental.exe
59041479ba1a2e5440ae9dd9904d31bf0097f30f7c4bc190167ea9b8d628dc58  kanata_winIOv2.exe
a2941cf08f6cb885bd96343eb16ec0f62c6c63e2093a62221ef66e660e7b97b8  kanata_wintercept.exe
ef4b3071a54ecab324b5890569adc01a6c4f03aff5f7cb88ad6dd5a8b0a9b9fb  kanata_wintercept_cmd_allowed.exe
kanata - v1.6.0-prerelease-2

Published by jtroo 7 months ago

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.

BREAKING FIX: Chord release behaviour has been improved but might affect existing workflows

BREAKING CHANGE: Add web event.code names as usable configuration key names, making them no longer usable in deflocalkeys.

  • 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: rapid-event-delay as a mitigation around desktop environments incorrectly handling some rapid events
  • Added: template definition and expansion for reducing boilerplate
  • Added: more switch logic (not, key-timing, input, input-history)
  • Added: lrld-file action
  • Added: improved wording + syntax of fake key operations, changing name from fake to virtual
  • Added: more TCP client requests and server events
  • Added (Windows Interception): windows-interception-keyboard-hwids to specify specific keyboards to intercept
  • Added (Windows Interception): windows-interception-mouse-hwids to specify multiple mice to intercept
  • Added (macOS): kext support for macOS version 10
  • Fixed: chord key association for presses/releases
  • Fixed: chords resulting in multiple tap-holds can now activate both holds
  • Fixed (Linux): exit on SIGTSTP to prevent locking out users from using the keyboard
  • Fixed (Windows LLHOOK): reduced blast radius of lsft workaround (properly this time)
  • Fixed (Windows LLHOOK): handling of locking via Win+L works correctly

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

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. This 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 and want kanata to handle the key positions consistently

Known issues:

  • deflocalkeys-win does not work properly for this variant. It needs a different variant (or use the values you would use for deflocalkeys-wintercept

NOTE: The kanata_scancode_experimental.exe variant has the same defsrc handling as the standard kanata.exe file but contains an 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

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

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:

To activate it:

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

For macOS 10 and older:

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

71998c18425b94359b12dc3e406654aa50dc9f79bf40c4a3c082ccbfbfbe7b28  kanata
1fdfe418c41f516507df3498929a28e4b0eece97f02071701a5f318fd28fb1bc  kanata.exe
0eaf5b61bf8357e238bdf80980e77e2639c0957cd66d5eaef327a6da11d27952  kanata.kbd
7d814cff7cda4692ebf3268e810c1ef668bae4bd345d90acea6fc1dac5b48cd1  kanata_cmd_allowed
5592cf8228fd9048c84b8e55c9f41756d90d5a11ed74fee403bdf44448d8a481  kanata_cmd_allowed.exe
35a99fe7aee6376252b29e5104b4fddc70e1c0ddf050c1365e8feb3b472aa089  kanata_macos_x86
348fc51b49b2aee23e6513013295a2ba5b409d821ca5435e186092d2a87218aa  kanata_macos_cmd_allowed_x86
9e7fa0400fcfc7495bfd69161deb08995f68b0fcf8eda4c261e0346233d3674d  kanata_scancode_experimental.exe
6a7fbab1d43be8ba1fd97b92832f5c9760bbcf0ae56b192f4246640e21f14a28  kanata_winIOv2.exe
1ffe166b019ceb7f1f74a562886016a891682be44d93320ab8f1fd111b989b60  kanata_wintercept.exe
43c7d52d31703371171ff1a19955bc22f21b394282b67f90fab8ea13f5590e7a  kanata_wintercept_cmd_allowed.exe
kanata - v1.6.0-prerelease-1

Published by jtroo 8 months ago

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.

  • 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

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

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

WARNING: feature support on macOS is limited

For macOS 11 and newer:

To activate it:

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

For macOS 10 and older:

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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
kanata - v1.5.0

Published by jtroo 10 months ago

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.

  • 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

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

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

WARNING: feature support on macOS is limited

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

864cd50f07dbb183070f7b5186539732ba2b713630adad05f06499a5bfcd3e62  kanata
74b7a0c751507a9d0e2774337053ac7961cdd8a52aeb1be01a3698fddaf8b423  kanata.exe
aae72ccffc983b379615ce82d4fee0ada5a50acfe4a2660ffbee0a5b1a21fc62  kanata.kbd
405010049a11ce7ab1c030688c7b13ad982014c7e3c29c4de7ba9355e44da6ab  kanata_cmd_allowed
972703233fcd9a24180ae738dbcf1d5f27d571f45337eafae832fde8585e6bb0  kanata_cmd_allowed.exe
6ac269ef08748a12f8ad4726d18cc362164d2d427958bc0a2c24b4a8ac8d225b  kanata_macos
eb722e05c464fabf3fd31c46efbe41d218e7b88764e861e19db84f31b1405b28  kanata_macos_cmd_allowed
f32f73fefc4627d86361a6134dff7f1ea009606cfb99a6dc426260880d4b8261  kanata_wintercept.exe
f589c04a4e2bc7b0fe1176d57ad5b70b79991bbe1ce256cbbfd7a9c5682ab6db  kanata_wintercept_cmd_allowed.exe
kanata - v1.5.0-prerelease-3

Published by jtroo 11 months ago

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.

  • 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

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

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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
kanata - v1.5.0-prerelease-2

Published by jtroo 12 months ago

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

  • 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

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

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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
kanata - v1.5.0-prerelease-1

Published by jtroo about 1 year ago

Changelog (since v1.4.0)

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

  • 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

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

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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
kanata - v1.4.0

Published by jtroo about 1 year ago

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

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

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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
kanata - v1.4.0-prerelease-3

Published by jtroo over 1 year ago

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

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

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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
kanata - v1.4.0-prerelease-2

Published by jtroo over 1 year ago

Changelog (since v1.3.0)

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

  • 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

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

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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
kanata - v1.4.0-prerelease-1

Published by jtroo over 1 year ago

Changelog (since v1.3.0)

  • 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

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

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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
kanata - v1.3.0

Published by jtroo over 1 year ago

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.

  • 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

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

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

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
kanata - v1.3.0-prerelease-3

Published by jtroo over 1 year ago

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.

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

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

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

a05d8176c2b6ca8a97beab317e1beaafd32fdfb97ed44c6e8bd3d72e439efef2  kanata
ba82f934ec56d54eff9a60262fae35d791b47ca3e23df6b0dce2816e0f5f2e96  kanata.exe
bf71d7a2b05b15bf3d61e68356ec3b054f1c40958fbd564aa126fc9db0652527  kanata.kbd
992ef35db54a5c2b2ffcac04a42e85c7c462f92dfb7c5c0f201e7a273fe8064b  kanata_cmd_allowed
86346d482ac3cefc27f366398f08c250e4c8abe73fb030b774ba130246142fd4  kanata_cmd_allowed.exe
f014b7aa701539117934754589bfb2219a915638f70bc380ca4abd5e5e8a24ee  kanata_wintercept.exe
7fdb7af98a431005c59dc42733334c5b33ebf59a93a2ab43da4e6004863823cc  kanata_wintercept_cmd_allowed.exe
kanata - v1.3.0-prerelease-2

Published by jtroo over 1 year ago

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.

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

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

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

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

Warning: known issue

This issue in the Interception driver exists: https://github.com/oblitum/Interception/issues/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

7e919063e29c85b6fe6a6bbb5e746da329bb04013a569246a85e1ed7c0bc9a14  kanata
87af0cb1612c55693c4aef62e66eba041863bbc0915954e6b80097e9abf7c93e  kanata.exe
b8605a1eb1e1cdfb73ee0cd2cc6fb39a39bc824984f7f31d3c49df9cf9629c1f  kanata.kbd
9bd5aa163b5d1cbf8fda84222a3d8626aad8ee6702c72fd1bef6a9c7955caaad  kanata_cmd_allowed
5d0f27ee95b1bb054b80c02d781bf3117635fe9a54031f313906e970f2759dfa  kanata_cmd_allowed.exe
20bf9b80721b8ef9ebd7fc4bb95e5bd765bad20efc0b7081038f90da64a7388d  kanata_wintercept.exe
f40e3938f081897b2670c55d3103f047fd8f032f9934636604c5fd74d66b434e  kanata_wintercept_cmd_allowed.exe
Package Rankings
Top 21.07% on Crates.io
Badges
Extracted from project README
Packaging status
Related Projects
VSCode-LaTeX-Inkscape

✍️ A way to integrate LaTeX, VS Code, and Inkscape in macOS

25 Sep 2021 332
pcfy-my-mac

Get a PC-like experience on macOS - keyboard shortcuts & windows management

19 Mar 2022 18