Kanata Configuration Guide

Reference

Your configuration file must have exactly one defsrc list. This defines the order of keys that the deflayer entries will operate on.

Description

The defsrc configuration entry defines which of your key inputs will be processed by kanata and how the keys map to defined layers. Keys excluded from defsrc will not be processed by Kanata unless you have process-unmapped-keys yes in defcfg.

Keys not processed by Kanata has implications on various actions. For example:

The defsrc entry is treated as a long sequence. The amount of whitespace (spaces, tabs, newlines) are not relevant. You may use spaces, tabs, or newlines however you like to visually format defsrc to your liking.

The primary source of all key names are the str_to_oscode and default_mappings functions in the source. Please feel welcome to file an issue if you’re unable to find the key you’re looking for.

An example defsrc containing the US QWERTY keyboard keys as an approximately 60% keyboard layout:

Note that some keyboards have a Menu key instead of a right Meta key. In this case you can use menu instead of rmet.

For non-US keyboards, see the non-US keyboards section.

Reference

Your configuration file must have at least one deflayer entry. This defines how each physical key mapped in defsrc behaves when kanata runs.

Description

A deflayer configuration entry is followed by the layer name then a list of keys or actions. The usable key names are the same as in defsrc. Actions are explained further on in this document. The whitespace story is the same as with defsrc. The order of keys/actions in deflayer corresponds to the physical key in the same sequence position defined in defsrc.

The first layer defined in your configuration file will be the starting layer when kanata runs. Other layers can be temporarily activated or switched to using actions.

An example defsrc and deflayer that remaps QWERTY to the Dvorak layout would be:

A Windows tray menu build also allows specifying layer icons in deflayer and deflayermap to show in the tray menu on layer activation, see example config

If you’re reading in order, you have now seen all of the required entries:

An example minimal configuration is:

This will make kanata remap your a b c keys to 1 2 3. This is almost certainly undesirable but is a valid configuration.

Ensure kanata and other key remapping programs are not running. Then you can use this online tool and press the key. The event.code field tells you the key name to use in Kanata. Alternatively, you can read through this reference. Due to the lengthy key names, you may want to use deflayermap if remapping using these key names.

Reference

You can use deflocalkeys to define additional key names that can be used in defsrc, deflayer, and anywhere else in the configuration.

Only one of each deflocalkeys-* variant is allowed. The variants that are not applicable will be ignored, e.g. deflocalkeys-linux and deflocalkeys-wintercept are both ignored when using the default Windows kanata.exe binary.

Description

The deflocalkeys configurations are not strictly necessary. Their purpose is to help you match your physical keyboard’s appearance to your kanata configuration, in the hopes it will be more readable and less confusing. In the underlying hardware, all keyboard positions send the same scan codes according to their position, regardless of what is printed on the key cap. The scan code names are typically referred to by the corresponding US layout name. It is the job of the operating system to translate the same scan code to the correct outputs according to the configured locale and layout.

You can find configurations that others have made in this document. If you do not see your keyboard there and are not confident in using the available tools, please feel welcome to ask for help in a discussion or issue. Please contribute to the document if you are able!

There are five variants of deflocalkeys:

The number used for a custom key represents the converted value for an OsCode in base 10. This differs between Windows-hooks, Windows-interception, and Linux.

Running kanata with the --debug flag lets you read the correct number, shown in parenthesis of code in the KeyEvent log lines.

It also possible to use native tools, as described below.

In Linux, evtest will give the correct number for the physical key you press.

In Windows using the default hook mechanism, the non-interception version of the keyboard tester in the kanata repository will give the correct number in the code: <number> section. (prebuilt binary)

In Windows uning winIOv2, the winIOv2 executable variant will give the correct number in the code: <number> section.

In Windows using Interception, the interception version of the keyboard tester will give the correct number i the num: <number> section. Between the hook and interception versions, some keys may agree but others may not; do be aware that they are not compatible!

However, Interception and winIOv2 should generally agree with each other.

Ideas for improving the user-friendliness of this system are welcome! As mentioned before, please ask for help in an issue or discussion if needed, and help with this document is very welcome so that future users can have an easier time 🙂.

The process-unmapped-keys option in defcfg is probably the most generally impactful option. Enabling this configuration makes kanata process keys that are not defined in defsrc. This might be useful if you are only mapping a few keys in defsrc instead of most of the keys on your keyboard.

By default, keys excluded from defsrc will not work in various scenarios. Some examples:

This option is disabled by default. The reason this is not enabled by default is because some keys may not work correctly if they are intercepted. For example, see Windows only: windows-altgr.

Reference

Using the defalias configuration entry, you can introduce a shortcut label for an action.

Description

The defalias entry reads pairs of items in a sequence where the first item in the pair is the alias name and the second item is the action it can be substituted for.

A list is a sequence of strings or nested lists separated by whitespace, surrounded by parentheses. All of the configuration entries we’ve looked at so far are lists; defalias is where we’ll first see nested lists in this guide.

This alias can be used in deflayer as a substitute for the long action. The alias name is prefixed with @ to signify that it’s an alias as opposed to a normal key.

You may have multiple defalias entries and multiple aliases within a single defalias. Aliases may also refer to other aliases that were defined earlier in the configuration file.

You can choose to put actions without aliasing them right into deflayer. However, for long actions it is recommended not to do so to keep a nice visual alignment. Visually aligning your deflayer entries will hopefully make your configuration file easier to read.

Reference

Using the defvar configuration entry, you can introduce a shortcut label for an arbitrary string or list.

Description

Unlike an alias, a variable does not need to be a valid standalone action. In other words, a variable can be used as components of actions.

The most common use case is to define common number strings for actions such as tap-hold, tap-dance, and one-shot.

Similar to how defalias works, defvar reads pairs of items in a sequence where the first item in the pair is the variable name and the second item is a string or list. Variables are allowed to refer to previously defined variables.

Variables can be used to substitute most values. Some notable exceptions are:

Variables are referred to by prefixing their name with $.

Reference

Live reload variants:

Live reload does not read or apply changes to device-related configurations. Examples of device-related configurations: linux-dev, macos-dev-names-include, linux-use-trackpoint-property, windows-only-windows-interception-keyboard-hwids.

Description

You can put the lrld action onto a key to live reload your configuration file. If kanata can’t parse the file, the previous configuration will continue to be used. When live reload is activated, the active kanata layer will be the first deflayer defined in the configuration.

There are variants of lrld: lrld-prev and lrld-next. These will cycle through different configuration files that you specify on kanata’s startup. The first configuration file specified will be the one loaded on startup. The prev/next variants can be used with shortened names of lrpv and lrnx as well.

Another variant is the list action lrld-num. This reloads the configuration file specified by the number, according to the order that the configuration file arguments are passed into kanata’s startup command.

Example specifying multiple config files in the command line:

Given the above startup command, activating (lrld-num 2) would reload the 2nd.cfg file.

Reference

A list action that changes the active base layer.

Description

This action allows you to switch to another "base" layer. This is permanent until a layer-switch to another layer is activated. The concept of a base layer makes more sense when looking at the next action: layer-while-held.

This action accepts a single subsequent string which must be a layer name defined in a deflayer entry.

Reference

A list action that changes the active layer while the key is held.

Description

This action allows you to temporarily change to another layer while the key remains held. When the key is released, you go back to the currently active "base" layer.

This action accepts a single subsequent string which must be a layer name defined in a deflayer entry.

You may also use layer-toggle in place of layer-while-held; they behave exactly the same. The layer-toggle name is slightly shorter but is a bit inaccurate with regards to its meaning.

Reference

Description

If you use a single underscore for a key _ then it acts as a "transparent" key in a deflayer. The behaviour depends if _ is on a base layer or a while-held layer. When _ is pressed on the active base layer, the key will default to the corresponding defsrc key. If _ is pressed on the active while-held layer, the base layer’s behaviour will activate.

Reference

Description

A similar concept to transparent key is the use-defsrc action. When activated, the underlying defsrc key will be the output action.

Reference

Description

You may use the action XX as a "no operation" key, meaning pressing the key will do nothing. This might be desirable in place of a transparent key on a layer that is not fully mapped so that a key that is intentionally not mapped will do nothing as opposed to typing a letter.

Alternatively you can use ✗ ∅ • to mean no-op.

Reference

List action that outputs a single unicode codepoint. The unicode codepoint will not be repeatedly typed if you hold the key down.

Description

The unicode (or 🔣) action accepts a single unicode character (but not a composed character, so 🤲, but not 🤲🏿). If you want to output a glyph that is composed of multiple codepoints, you can use macro with multiple unicode actions.

You may use a unicode character as an alias if desired or in its simplified form 🔣😀 (vs the usual (🔣 😀)).

If you want output parentheses ( ) via unicode you can quote them.

If you want to output double quotes via unicode you need a special quoting syntax.

Reference

Prefixing a known key name with the following strings will output the key alongside the specified modifier. Multiple prefixes can be combined to add more modifiers to the same key output. Duplicate prefixes are not allowed.

A special behaviour of output chords is that if another key is pressed, all of the chord keys will be released before the newly pressed key action activates. The modifier keys are often not desired for subsequent actions and without this behaviour, rapid typing can result in undesired modified key presses. If you want keys to remain pressed, use multi instead.

Description

You may want to remap a key to automatically be pressed in combination with modifiers such as Control or Shift. Output chords are a way for you to achieve this.

Output chords are typically used do one-off actions such as:

It should be noted that output chords are not usable in all configuration items. If you get an unknown key error where you expected an output chord to be usable, you must split the output chord into its component keys. For example, (unmod C-l) is an error; instead you should use (unmod lctl l).

The output chord prefix strings are:

Reference

Description

The action rpt repeats the most recently typed key. Holding down this key will not repeatedly send the key. The intended use case is to be able to use a different finger or even thumb key to repeat a typed key, as opposed to double-tapping a key.

The rpt action only repeats the last key output. For example, it won’t output a chord like ctrl+c if the previous key pressed was C-c. The rpt action will only output c in this case.

There is a variant rpt-any which will repeat any previous action and would output ctrl+c in the example case.

Reference

Description

You can release a held key or layer via these actions:

A lower-level detail of these actions is that they operate on output states as opposed to virtually releasing an input key. This does have some practical significance. For example, if the action (macro-repeat a 50) were on the a key, activating (release-key a) will not stop the repeating macro.

An example practical use case for release-key is seen in the multi section directly below.

There is currently no known practical use case for release-layer, but it exists nonetheless.

Reference

Activate multiple actions in sequence.

Description

The multi action executes multiple keys or actions in order but also simultaneously. It accepts one or more actions.

An example use case is to press the "Alt" key while also activating another layer.

In the example below, holding the physical "Alt" key will result in a held layer being activated while also holding "Alt" itself. The held layer operates nearly the same as the standard keyboard, so for example the sequence (hold Alt)+(Tab+Tab+Tab) will work as expected. This is in contrast to having a layer where tab is mapped to A-tab, which results in repeated press+release of the two keys and has different behaviour than expected. Some special keys will release the "Alt" key and do some other action that requires "Alt" to be released. In other words, the "Alt" key serves a dual purpose of still fulfilling the "Alt" key role for some button presses (e.g. Tab), but also as a new layer for keys that aren’t typically used with "Alt" to have added useful functionality.

You can click the left, middle, and right buttons using kanata actions, do vertical/horizontal scrolling, and move the mouse.

Reference

The tap-dance action allows performing different actions based on number of consecutive taps of the same key.

The tap-dance-eager variant will eagerly perform actions. Use of macro and bspc can help to backtrack for the 2nd tap onwards.

Description

The tap-dance action allows repeated tapping of a key to result in different actions. It is followed by a timeout (unit: ms) and a list of keys or actions. Each time the key is pressed, its timeout will reset. The action will be chosen if one of the following events occur:

You may put normal keys or other actions in tap-dance.

There is a variant of tap-dance with the name tap-dance-eager. The variant is parsed identically but the difference is that it will activate every action in the sequence as the taps progress.

In the example below, repeated taps will, in order:

Reference

Activate keys or layers for a time without keeping the input key held, for one subsequent key. Activating other one-shot actions, while one or more are already active, will reset the timeout, and overlap the one-shot actions.

Values for $variant:

Other items:

Description

The one-shot action is similar to "sticky keys", if you know what that is. This activates an action or key until either the timeout expires or a different key is used. The one-shot action must be followed by a timeout (unit: ms) and another key or action.

Some of the intended use cases are:

If a one-shot key is held then it will act as the regular key. E.g. holding a key assigned with @os2 in the example below will keep Left Shift held for every key, not just one, as long as it’s still physically pressed.

Pressing multiple one-shot keys in a row within the timeout will combine the actions of those keys and reset the timeout to the value of the most recently pressed one-shot key.

There are four variants of the one-shot action:

It is important to note that the first activation of a one-shot key determines the behaviour with regards to the 4 variants for all subsequent one-shot key activations, even if a following one-shot key has a different configuration than the initial key pressed.

The default name one-shot corresponds to one-shot-press.

Reference

The tap-hold action lets you activate different actions depending it a key is tapped or held.

Description

The tap-hold action allows you to have one action/key for a "tap" and a different action/key for a "hold". A tap is a rapid press then release of the key whereas a hold is a long press.

The action takes 4 parameters in the listed order:

The tap timeout is the number of milliseconds within which a rapid press+release+press of a key will result in the tap action being held instead of the hold action activating.

The hold timeout is the number of milliseconds after which the hold action will activate.

There are two additional variants of tap-hold:

These variants may be useful if you want more responsive tap-hold keys, but you should be wary of activating the hold action unintentionally.

There are further additional variants of tap-hold-press and tap-hold-release:

These variants take a 5th parameter, in addition to the same 4 as the other variants. The 5th parameter is another action, which will activate if the hold timeout expires as opposed to being triggered by other key actions, whereas the non -timeout variants will activate the hold action in both cases.

This variant takes a 5th parameter which is a list of keys that trigger an early tap when they are pressed while the tap-hold-release-keys action is waiting. Otherwise this behaves as tap-hold-release.

The keys in the 5th parameter correspond to the physical input keys, or in other words the key that corresponds to defsrc. This is in contrast to the fork and switch actions which operates on outputted keys, or in other words the outputs that are in deflayer, defalias, etc. for the corresponding defsrc key.

This variant takes a 5th parameter which is a list of keys that always trigger a tap when they are pressed while the tap-hold-except-keys action is waiting. No key is ever output until there is either a release of the key or any other key is pressed. This differs from tap-hold behaviour.

The keys in the 5th parameter correspond to the physical input keys, or in other words the key that corresponds to defsrc. This is in contrast to the fork and switch actions which operates on outputted keys, or in other words the outputs that are in deflayer, defalias, etc. for the corresponding defsrc key.

Reference

The macro action taps the configured sequence of keys or actions. Numbers can be used to delay the sequence by the defined number of milliseconds.

Description

The macro action will tap a sequence of keys with optional delays. This is different from multi because in the multi action, all keys are held, whereas in macro, keys are pressed then released.

This means that with macro you can have some letters capitalized and others not. This is not possible with multi.

The macro action accepts one or more keys, some actions, chords, and delays (unit: ms). It also accepts a list prefixed with output chord modifiers where the list is subject to the aforementioned restrictions. The number keys will be parsed as delays, so they must be aliased to be used in a macro.

Up to 4 macros can be active at the same time.

The actions supported in macro are:

Reference

Record and replay key inputs.

Description

The dynamic-macro actions allow for recording and playing key presses. The dynamic macro records physical key presses, as opposed to kanata’s outputs. This allows the dynamic macro to replicate any action, but it means that if the macro starts and ends on different layers, then the macro might not be properly repeatable.

The action dynamic-macro-record accepts one number (0-65535), which represents the macro ID. Activating this action will begin recording physical key inputs. If dynamic-macro-record with the same ID is pressed again, the recording will end and be saved. If dynamic-macro-record with a different ID is pressed then the current recording will end and be saved, then a new recording with the new ID will begin.

The action dynamic-macro-record-stop will stop and save any active recording. There is a variant of this: dynamic-macro-record-stop-truncate This is a list action that takes a single parameter: the number of key actions to remove at the end of a dynamic macro. This variant is useful if the macro stop button is on a different layer.

The action dynamic-macro-play accepts one number (0-65535), which represents the macro ID. Activating this action will play the saved recording of physical keys from a previous dynamic-macro-record with the same macro ID, if it exists.

One can nest dynamic macros within each other, e.g. activate (dynamic-macro-play 1) while recording with (dynamic-macro-record 0). However, dynamic macros cannot recurse; e.g. activating (dynamic-macro-play 0) while recording with (dynamic-macro-record 0) will be ignored.

Reference

The caps-word action puts Kanata into a state where typed keys are automatically shifted by lsft. The state persists until terminated by timeout or by typing a key that ends the state. Typing a non-terminating key refreshes the timeout duration.

The -toggle variants will end the caps-word state if pressed while caps-word is active, whereas the re-pressing the standard variants will keep the state active and refresh the timeout duration.

Description

The caps-word or word⇪ action triggers a state where the lsft key will be added to the active key list when a set of specific keys are active. The keys are: a-z and -, which will be outputted as A-Z and _ respectively when using the US layout.

Examples where this is helpful is capitalizing a single important word like in IMPORTANT! or defining a constant in code like const P99_99_VALUE: …​. This has an advantage over the regular caps lock because it automatically ends so it doesn’t need to be toggled off manually, and it also shifts - to _ which caps lock does not do.

The caps-word state ends when the keyboard is idle for the duration of the defined timeout (1st parameter), or a terminating key is pressed. Every key is a terminating key except the keys which get capitalized and the extra keys in this list:

You can use caps-word-custom or word⇪-custom instead of caps-word if you want to manually define which keys are capitalized (2nd parameter) and what the extra non-terminal+non-capitalized keys should be (3rd parameter).

Reference

The unmod action will dactivate modifier keys while outputting one or more defined keys.

Description

The unmod action will release all modifiers temporarily and send one or more keys. After the unmod key is released, the released modifiers are pressed again. The affected modifiers are: lsft,rsft,lctl,rctl,lmet,rmet,lalt,ralt.

A variant of unmod is unshift or un⇧. This action only releases the lsft,rsft keys. This can be useful for forcing unshifted keys while AltGr is still held.

An list may optionally be used as the first parameter of unmod. The list must be non-empty and must contain only modifier keys, which are the keys in the affected modifiers list from earlier in this document section.

When this list exists, the action will temporarily release only the keys listed rather than all modifiers.

Reference

The fork action allows choosing between a default and an alternate action based on whether specific keys are active.

Reference

The switch action allows conditionally activating 0 or more actions, depending on conditional checks.

The logic check is a list. The items within the list can either be key names or a special list check. A key name item evaluates to true if that key name is a currently active key output of Kanata upon activating switch The outer-most list evaluates to true as whole if any of the items evaluates to true.

Description

Conceptually, the switch action is similar to fork but has more capabilities as well as more complexity. The switch action accepts multiple cases. One case is a triple of:

The default use of the logic check behaves similarly to fork.

For example, the the logic check (a b c) will activate the corresponding action if any of a, b, or c are currently pressed.

The logic check also accepts the boolean operators and|or|not to allow more complex use cases.

The order of cases matters. For example, if two different cases match the currently pressed keys, the case listed earlier in the configuration will activate first. If the early case uses break, the second case will not activate. Otherwise if fallthrough is used, the second case will activate sequentially after the first case. This idea generalizes to more than two cases, but the two case example is hopefully simple and effective enough.

Below is a description of how this example behaves.

Reference

The cmd action allows you to execute arbitrary binaries with arbitrary arguments. The cmd-log variant behaves similarly but allows customization of the stdout and stderr log levels within Kanata’s output logging. The cmd-output-keys is like cmd, but stdout of the command will be parsed as a list of keys, output chords, and delays similar to macro and be typed as kanata outputs.

Description

The cmd action executes a program with arguments. It accepts one or more strings. The first string is the program that will be run and the following strings are arguments to that program. The arguments are provided to the program in the order written in the config file. Lists may also be used within cmd which you may desire to do for reuse via defvar. Lists will be flattened such that arguments are provided to the program in the order written in the config file, regardless of list nesting. To be technical, it would be a depth-first flattening (similar to DFS).

Commands are executed directly and not via a shell, so you cannot make use of environment variables or symbols with special meaning. For example ~ or $HOME in Linux will not be substituted with your home directory. If you want to execute with a shell program use the shell as the first parameter, e.g. bash or powershell.exe.

The user executing the command is the user that kanata was started with. For example, if kanata was started by root, the command will be run by the root user. If you need to execute as a different user, on Unix platforms you can use sudo -u USER before the rest of your command to achieve this.

By default, cmd logs start of command, completion of command, stdout, and stderr. Using the variant cmd-log, these log levels can be changed, and even disabled. It takes two arguments, <log_level> and <error_log_level>. <log_level> will be the level where the command to run, stdout, and stderr are logged. The error channel is logged only if there is a failure with running the command (typically if the command can’t be found, or there is trouble spawning it).

The valid levels are debug, info, warn, error, and none.

There is a variant of cmd: cmd-output-keys. This variant reads the output of the executed program and reads it as an S-expression, similarly to the macro action. However — unlike macro — only delays, keys, chords, and chorded lists are supported. Other actions are not supported.

The arbitrary-code action allows sending an arbitrary number to kanata’s output mechanism. The press is sent when pressed, and the release sent when released. This action can be useful for testing keys that are not yet named or mapped in kanata. Please contribute findings with names and mappings, either in a GitHub issue or as a pull request!

This option can be used to enable the cmd action in your configuration. The cmd action allows kanata to execute programs with arguments passed to them.

This requires using a kanata program that is compiled with the cmd action enabled. The reason for this is so that if you choose to, there is no way for kanata to execute arbitrary programs even if you download some random configuration from the internet.

This configuration is disabled by default and can be enabled by giving it the value yes.

This option customizes the key sequence timeout (unit: ms). Its default value is 1000. The purpose of this item is explained in Sequences.

This option customizes the key sequence input mode. Its default value when not configured is hidden-suppressed.

The options are:

For visible-backspaced and hidden-delay-type, a sequence leader input will be ignored if a sequence is already active. For historical reasons, and in case it is desired behaviour, a sequence leader input using hidden-suppressed will reset the key sequence.

See Sequences for more about sequences.

This option customizes the behaviour of key sequences when modifiers are used. The default is yes and can be overridden to no if desired.

Setting it to yes allows both fk1 and fk2 to be activated in the following configuration, but with no, fk1 will be impossible to activate

See Sequences for more about sequences and this document for more context about this specific configuration.

By default, kanata will log layer changes. However, logging has some processing overhead. If you do not care for the logging, you can choose to disable it.

If --log-layer-changes is passed as a command line argument, a no in the configuration file will be overridden and layer changes will again be logged. This flag can be helpful when testing new configuration changes while keeping the default behaviour as "no logging" to save on processing, so that the defcfg item does not need to be adjusted back and forth when experimenting vs. stable usage.

By default, transparent keys on layers will delegate to the corresponding defsrc key when found on a layer activated by layer-switch.

This config entry changes the behaviour to delegate to the action in the same position on the first layer defined in the configuration, which is the active layer on startup.

For more context, see https://github.com/jtroo/kanata/issues/435.

By default movemouse-accel actions will track the acceleration state for vertical and horizontal axes separately.

When this setting is enabled, movemouse-accel will behave exactly like mouse movements in QMK, i.e. the acceleration state of new mouse movement actions will be inherited if others are already being pressed.

By default, mouse movements move one direction at a time and vertical/horizontal movements are on independent timers.

This can result in non-smooth diagonals when drawing a line in some app. This option adds a small imperceptible amount of latency to synchronize the mouse movements.

This configuration allows you to customize the length limit on dynamic macros. The default length limit is 128 keys.

This configuration makes multiple tap-hold actions that are activated near in time expire their timeout quicker. By default this is disabled. When disabled, the timeout for a following tap-hold will start from 0ms after the previous tap-hold expires. When enabled, the timeout will start as soon as the tap-hold action is pressed even if a previous tap-hold action is still held and has not expired.

If you desire to use only a subset of your keyboard you can use block-unmapped-keys to make every key other than those that exist in defsrc a no-op.

This configuration applies to the following events:

These events are delayed the defined number of milliseconds (approximate). The default value is 5.

While the release is delayed, further processing of inputs is also paused. This means that there will be a minor input latency impact in the mentioned scenarios. Since 5ms is 1 frame for a 200 Hz refresh rate, in most scenarios this will not be perceptible.

The reason for this configuration existing is that some environments do not process the scenarios correctly due to the rapidity of the release. Kanata does send the events in the correct order, so the fault is more in the environment, but kanata provides a workaround anyway.

If you are negatively impacted by the latency increase of these events and your environment is not impacted by increased rapidity, you can set reduce the value to a number 0 to 4.

This configuration affects the timer during which chords processing is disabled. NOTE: For more info, see Input chords / combos (v2).

The default (and minimum) value is 5 and the unit is milliseconds.

This configuration item changes activation behaviour from defoverrides.

Take this example override:

The default behaviour is that if lsft is released before releasing a, kanata’s behaviour would be to send a.

A future improvement could be to make the 9 continue to be the key held, but that is not implemented today.

The workaround in case the above behaviour negatively impacts your workflow is to enable this configuration. This configuration will press and then immediately release the 9 output as soon as the override activates, meaning you are unlikely as a human to ever release lsft first.

The effect of this configuration is that the 9 key cannot remain held when activated by the override which is important to consider for your use cases.

By default, any repeat-key events generated by the physical keyboard (or operating system) will be passed through to the application. On Linux, under Wayland, this is wasted effort since the DE handles key-repeat on its own. Such events can also be distracting when debugging your configuration with evtest, etc.

Setting this option to "false" will cause such events to be dropped, and not passed through. This is primarily meant for Linux, but may find some use on Mac. It is not implemented on Windows, and will be silently ignored.

Select an alias to execute when first starting, and after each live-reload of the config. You can use this to run external commands, or to stack layers (with layer-while-held).

The name of an alias, without a leading "@", is expected as a parameter. The example below will beep at startup (assuming your system has a beep command), and will already be blocking the swapped "i" and "o" keys.

By default, kanata will try to detect which input devices are keyboards and try to intercept them all. However, you may specify exact keyboard devices from the /dev/input directories using the linux-dev configuration.

If you want to specify multiple keyboards, you can separate the paths with a colon :.

Due to using the colon to separate devices, if you have a device with colons in its file name, you must escape those colons with backslashes:

Alternatively, you can use list syntax, where both backslashes and colons are parsed literally. List items are separated by spaces or newlines. Using quotation marks for each item is optional, and only required if an item contains spaces.

In the case that linux-dev is omitted, this option defines a list of device names that should be included. Device names that do not exist in the list will be ignored. This option is parsed identically to linux-dev.

Kanata will print device names on startup with log lines that look like below:

In the case that linux-dev is omitted, this option defines a list of device names that should be excluded. This option is parsed identically to linux-dev.

The linux-dev-names-include and linux-dev-names-exclude options are not mutually exclusive but in practice it probably only makes sense to use one and not both.

By default, kanata will crash if no input devices are found. You can change this behaviour by setting linux-continue-if-no-devs-found.

Kanata on Linux automatically detects and grabs input devices when none of the explicit device configurations are in use. In case kanata is undesirably grabbing mouse-like devices, you can use a configuration item to change detection behaviour.

The configuration is linux-device-detect-mode and it has the options:

The default behaviour is:

Unicode on Linux works by pressing Ctrl+Shift+U, typing the unicode hex value, then pressing Enter. However, if you do remapping in userspace, e.g. via xmodmap/xkb, the keycode "U" that kanata outputs may not become a keysym "u" after the userspace remapping. This will be likely if you use non-US, non-European keyboards on top of kanata. For unicode to work, kanata needs to use the keycode that outputs the keysym "u", which might not be the keycode "U".

You can use evtest or kanata --debug, set your userspace key remapping, then press the key that outputs the keysym "u" to see which underlying keycode is sent. Then you can use this configuration to change kanata’s behaviour.

Unicode on Linux terminates with the Enter key by default. This may not work in some applications. The termination is configurable with the following options:

On Linux, you can tell kanata to run xset r rate <delay> <rate> on startup and on live reload via the configuration item linux-only-x11-repeat-rate. This takes two numbers separated by a comma. The first number is the delay in ms and the second number is the repeat rate in repeats/second.

This configuration item does not affect Wayland or no-desktop environments.

On linux, you can ask kanata to label itself as a trackpoint. This has several effects on libinput including enabling middle mouse button scrolling and using a different acceleration curve. Otherwise, a trackpoint intercepted by kanata may not behave as expected.

If using this feature, it is recommended to filter out any non-trackpoint pointing devices using Linux only: linux-dev-names-include, Linux only: linux-dev-names-exclude or Linux only: linux-dev to avoid changing their behavior as well.

Kanata on Linux needs to declare a "bus type" for its evdev output device. The options are USB and I8042, with the default as I8042. Using USB can break disable-touchpad-while-typing on Wayland. But using I8042 appears to break some other scenarios. Thus the output bus type is configurable.

This option defines a list of device names that should be included. By default, kanata will try to detect which input devices are keyboards and try to intercept them all. However, you may specify exact keyboard devices to intercept using the macos-dev-names-include configuration. Device names that do not exist in the list will be ignored. This option is parsed identically to linux-dev.

Use kanata -l or kanata --list to list the available keyboards.

There is an option for Windows to mitigate the strange behaviour of AltGr (ralt) if you’re using process-unmapped-keys yes or have the key in your defsrc. This is applicable for many non-US layouts. You can use one of the listed values to change what kanata does with the key:

Without these workarounds, you should instead ensure you set process-unmapped-keys no and also omit both ralt and lctl from defsrc.

For more context, see: https://github.com/jtroo/kanata/issues/55.

This defcfg item allows you to intercept mouse buttons for a specific mouse device. This only works with the Interception driver (the -wintercept variants of the release binaries).

The original use case for this is for laptops such as a Thinkpad, which have mouse buttons that may be desirable to activate kanata actions with.

To know what numbers to put into the string, you can run the variant with this defcfg item defined with any numbers. Then when a button is first pressed on the mouse device, kanata will print its hwid in the log; you can then copy-paste that into this configuration entry. If this defcfg item is not defined, the log will not print.

Hwids in Kanata are byte array representations of a concatenation of the ASCII hardware ids, which can be seen in Device Manager on Windows. As such, they are an arbitrary length and can be very long.

Relevant issue.

This item has a similar purpose as the singular version documented above, but is instead a list of strings that allows multiple mice to be intercepted.

If both the singular and list items are used, the singular version will behave as if added to the list.

This defcfg item allows you to intercept only specific keyboards. Its value must be a list of strings with each string representing one hardware ID.

To know what numbers to put into the string, you can run the variant with this defcfg item empty. Then when a button is first pressed on the keyboard, kanata will print its hwid in the log. You can then copy-paste that into this configuration entry. If this defcfg item is not defined, the log will not print.

Hwids in Kanata are byte array representations of a concatenation of the ASCII hardware ids, which can be seen in Device Manager on Windows. As such, they are an arbitrary length and can be very long.

Show a custom tray icon file for a Windows only: win-tray gui-enabled build of kanata on Windows. Accepts either the full path (including the file name with an extension) to the icon file or just the file name, which is then searched in the following locations:

If not specified, tries to load any icon file from the same locations with the name matching config name with extension replaced by one of the supported ones. See example config for more details.

When enabled, attempt to switch to a custom tray icon that matches the name of the active layer if the layer doesn’t specify an explicit icon. If no icon file is found, the default icon will be used (see Windows only: tray-icon). File search rules are the same as in Windows only: tray-icon. Defaults to true. See example config for more details.

Show a custom layer icon near the mouse pointer position. Defaults to false. Requires Windows only: win-tray gui-enabled build.

Show a blank square when instead of an icon if a layer isn’t configured to have one. Defaults to false. Requires Windows only: win-tray gui-enabled build.

Don’t show a tooltip layer icon for the base layer (1st deflayer). Defaults to true. Requires Windows only: win-tray gui-enabled build.

Set duration (in ms) for showing a custom layer icon near the mouse pointer position. 0 to never hide. Defaults to 500. Requires Windows only: win-tray gui-enabled build.

Set the size (comma-separated Width,Height without spaces) for a custom layer icon near the mouse pointer position. Defaults to 24,24. Requires Windows only: win-tray gui-enabled build.

Show system notification message on config reload. Defaults to true. Requires Windows only: win-tray gui-enabled build.

Disable sound for the system notification message on config reload. Defaults to false. Requires Windows only: win-tray gui-enabled build.

Show system notification message on kanata errors. Defaults to true. Requires Windows only: win-tray gui-enabled build.

The defcfg entry is treated as a list with pairs of strings. For example:

This will be treated as configuration a having value 1 and configuration b having value 2.

An example defcfg containing many of the options is shown below. It should be noted options that are Linux-only, Windows-only, or macOS-only will be ignored when used on a non-applicable operating system.

You can define up to 767 virtual keys. These keys are not directly mapped to any physical key presses or releases. Virtual keys can be activated via special actions:

The <action> parameter can be one of:

A virtual key can be defined in a defvirtualkeys configuration entry. Configuring this entry is similar to defalias, but you cannot make use of aliases inside to shorten an action. You can refer to previously defined virtual keys.

Expanding on the on-idle action some more, the wording that "kanata" has been idle is important. Even if the keyboard is idle, kanata may not yet be idle. For example, if a long-running macro is playing, or kanata is waiting for the timeout of actions such as caps-word or tap-dance, kanata is not yet idle, and the tick count for the <idle time> parameter will not yet be counting even if you no longer have any keyboard keys pressed.

For more context, you can read the issue that sparked the creation of virtual keys.

Something notable about virtual keys is that they don’t always interrupt the state of an active tap-dance-eager. If a macro action is assigned to a virtual key, this won’t interrupt a tap dance. However, most other action types, notably a "normal" key action like rsft will still interrupt a tap dance.

The sldr action makes kanata go into "sequence" mode. The action name is short for "sequence leader". This comes from Vim which has the concept of a configurable sequence leader key. When in sequence mode, keys are not typed (by default) but are saved until one of the following happens:

Sequences are configured similarly to defvirtualkeys. The first parameter of a pair must be a defined virtual key name. The second parameter is a list of keys that will activate a virtual key tap when typed in the defined order. More precisely, the action triggered is:

(on-press tap-vkey <virtual key name>)

There are 10 special keys with names nop0-nop9 which kanata treats specially. Kanata will never send OS events for these keys but they can still participate in sequences.

See an example of using the nop keys alongside templates to define sequences below.

If 10 special nop keys do not seem sufficient, you can get creative with your sequences and treat some as a prefix modifier. For example, you can get 24 "keys" by treating nop0-nop5 as normal while treating nop6-nop9 as prefixes that are always followed by a second nop key.

Not to be confused with output chords, chord actions allow you to perform various actions based on which specific combination of input keys are pressed together. Such an unordered combination of keys is called a "chord". Each chord can perform a different action, allowing you to bind up to 2^n - 1 different actions to just n keys.

Input chords are configured similarly to defalias with two extra parameters at the beginning of each defchords group: the name of the group and a timeout value after which a chord triggers if it isn’t triggered by a key release or press of a non-chord key before the timeout expires.

The first item of each pair specifies the keys that make up a given chord. The second item of each pair is the action to be executed when the given chord is pressed and may be any regular or advanced action, including aliases. It currently cannot however contain another chord action.

Note that unlike with defseq, these keys do not directly correspond to real keys and are merely arbitrary labels that make sense within the context of the chord. They are mapped to real keys in layers by configuring the key in the layer to map to a (chord name key) action where name is the name of the chords group (above example) and key is one of these arbitrary labels.

It is perfectly valid to nest these chord actions that enter "chording mode" within other actions like tap-dance and that will work as one would expect. However, this only applies to the first key used to enter "chording mode". Once "chording mode" is active, all other keys will be directly handled by "chording mode" with no regard for wrapper actions; e.g. if a key is pressed and it maps to a tap-hold with a chord as the hold action within, that chord key will immediately activate instead of the key needing to be held for the timeout period.

Release behaviour

For single key actions and output chords — like lctl or S-tab — and for layer-while-held, an input chord will release the action only when all keys that are part of the input chord have been released. In other words, if even one key is held for the input chord then the output action will be continued to be held, but only for the mentioned action categories. The behaviour also applies to the actions mentioned above when used inside of multi but not within any other action.

An exception to the behaviour described above for the action categories that would normally apply is if a chord decomposition occurs. A chord decomposition occurs when you input a chord that does not correspond to any action. When this happens, kanata splits up the key presses to activate other actions from the components of the input chord. In this scenario, the behaviour described in the next paragraph will occur.

For chord decompositions and all other action categories, the release behaviour is more confusing: the output action will end when any key is released during the timeout, or if the timeout expires, the output action ends when the first key that was pressed in the chord gets released. This inconsistency is a limitation of the current implementation. In these scenarios it is recommended to hold down all keys if you want to keep holding and to release all keys if you want to do a release. This is because it will probably be difficult to know which key was pressed first.

If you want to bypass the behaviour of keys being held for chord outputs, you could change the chord output actions to be macros instead. Using a macro will guarantee a rapid press+release for the output keys.

There is a variant of defalias: defaliasenvcond. This variant is parsed similarly, but there must be an extra list parameter that comes before all of the name-action pairs.

The list must contain two strings. In order, these strings are: an environment variable name, and the environment variable value. When the environment variable defined by the name has the corresponding value when starting kanata, the aliases within will be active. Otherwise, the aliases will be skipped.

A use case for defaliasenvcond is when one has multiple devices which vary in layout of keys, e.g. different special keys on the bottom row. Using environment variables, one can use the same kanata configuration across those multiple devices while changing key behaviours to keep consistent behaviour of specific key positions across the multiple devices, when the hardware keys at those physical key positions are not the same.

The top-level configuration item deftemplate declares a template that can be expanded multiple times via the list item template-expand. The short form of template-expand is t!.

The parameters to deftemplate in order are:

Within the template content, variable names prefixed with $ will be substituted with the expression passed into template-expand.

The list item template-expand can be placed as a top-level list or within another list. Its parameters in order are:

Example 1:

In a simple example, let’s say you wanted to set a large group of keys to do something different when you’re holding alt. Yes, this could also be handled with remapping alt to a layer shift, but there are cases where you wouldn’t want this. Rather than retyping the code with fork and unmod (to release alt) a bunch of times, you could template it like so:

This is not currently configurable without modifying the source code, but if you’re willing and/or capable, there is a tap-hold behaviour that is currently not exposed. Using this behaviour, one can be very particular about when and how tap vs. hold will activate by using extra information. The available information that can be used is exactly which keys have been pressed or released as well as the timing in milliseconds of those key presses. The action tap-hold-release-keys makes use of some of this capability, but doesn’t make full use of the power of this functionality.

For more context, you can read the motivation for custom tap-hold behaviour.

Instead of using the same a-z letters for special keys, e.g., lsft for LeftShift you can use much shorter, yet more visible, key symbols like ‹⇧.

For more details see symbol list and example config, which not only uses these symbols in layer definitions, but also repurposes ⎇› and ⇧› ⎇› keys into "symbol" keys that allow you to insert these fancy symbols by pressing the key, e.g.,

The default kanata.exe binary doesn’t work in elevated windows (run with administrative privileges), e.g., Control Panel. However, you can use AutoHotkey’s "EnableUIAccess" script to self-sign the binary, move it to "Program Files", then launching kanata from there will also work in these elevated windows. See EnableUIAccess folder with the script and its required libraries (needs AutoHotkey v2 installed)

If compiling yourself, you should add the feature flag win_manifest to enable the use of the EnableUIAccess script:

Kanata can be compiled as a Windows GUI tray app with the feature flag gui. This can simplify launching the app on user login by placing a .lnk at %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup, show custom icon indicator per config

as well as dynamic icon indicator per layer (might need to click on the gif below to play)

(see Windows only: win-tray). It also supports (re)loading configs.

Currently the only configuration supported is tray icon per profile, all other configuration should be done by passing cli flags in the Target field of .lnk, e.g., "C:\Program Files\kanata\kanata.exe" -d -n to launch kanata without a delay in a debug mode

When launched from a command line, the app outputs log to the console, but otherwise the logs are currently only available via an app capable of viewing OutputDebugString debugs, e.g., TraceSpy.

Kanata has a kanata_simulated_input tool to help test your configuration in a predictable manner.

You can try it out on GitHub pages.

Code for the CLI tool can be found under simulated_input.

Instead of physically typing to test something and wondering whether you didn’t get the expected result because your config is wrong or because you mistyped something, you can write a sequence of key presses in a sim.txt file, run the tool with your config and get a "timeline" view of input/output events that can help understand how kanata translates your input into various key/mouse presses.

For more details download the files below and run kanata_simulated_input -c sim.kbd -s sim.txt
- example config with simple home row mod bindings
- example input sequence
- example output sequence

Input sequence file format: whitespace insensitive list of prefix:key pairs where prefix is one of:
- 🕐, t, or tick to add time between key events in ms
- ↓, d, down, or press
- ↑, u, up, or release
- ⟳, r, or repeat

And key names are defined in the str_to_oscode function, for example, 1 for the numeric key 1 or kp1/🔢₁ for the keypad numeric key 1

Using unicode symbols 🕐,↓,↑,⟳ allows skipping the : separator, e.g., ↓k ≝ ↓:k ≝ d:k

Reference

You may define a single defzippy-experimental configuration item. As suggested by the -experimental label, this feature is relatively recent. When using this you are at higher likelihood of bugs and breaking changes.

Regarding output mappings, you can configure the output of the special-lisp-syntax characters ) ( " via these lines:

As an example, for the US layout these should be the correct lines:

The format is two columns separated by a single Tab character. The first column is input and the second is output.

Examples

Description

Zippychord is yet another chording mechanism in Kanata. The inspiration behind it is primarily the zipchord project. The name is similar; it is named "zippy" instead of "zip" because Kanata’s implementation is not a port and does not aim for 100% behavioural compatibility.

The intended use case is shorthands, or accelerating character output. Within zippychord, inputs are keycode chords or sequences, and the outputs are also purely keycodes. In other words, all other actions are unsupported; e.g. layers, switch, one-shot.

Zippychord behaves on outputted keycodes, i.e. the key outputs after kanata has finished processing your inputs, layers, switch logic and other configurations. This is similar to how sequences operate and is unlike chords(v1) and chordsv2. Furthermore, outputs are all eager like visible-backspaced on sequences. If a zippchord activation occurs, typed keys are backspaced.

To give an example, if one configures zippychord with a line like:

then either of the following typing event sequences will erase the input characters and then proceed to type the output "git" like if it was (macro bspc bspc g i t).

Note that there aren’t any release events listed. To contrast, the following event sequence would not result in an activation:

Zippychord supports fully overlapping chords and sequences. For example, this configuration is allowed:

When you begin with the (g i) chord, you can follow up with various character sequences to output different git commands. This use case is quite similar to git aliases. One advantage of zippychord is that it eagerly shows you the true underlying command as you type.