config.adoc

Kanata Configuration Guide

This document describes how to create a kanata configuration file. The kanata configuration file will determine your keyboard behaviour upon running kanata.

How to read the guide

See the triple bullet-lines at the upper right to open or close a Table of Contents sidebar.

You may want to view the guide rendered to HTML. Link to guide.

The Reference sections are shorter and are intended for reviewing how precisely to configure different sections. The Description sections are longer and contain more details such as advice, motivation, and examples.

The configuration guide you are reading may have content not applicable to the version you are using. See below for links to specific guide versions.

• v1.7.0

• v1.6.1

• v1.6.0

Preamble

The configuration file uses S-expression syntax from Lisps. If you are not familiar with any Lisp-like programming language, do not be too worried. This document will hopefully be a sufficient guide to help you customize your keyboard behaviour to your exact liking.

Useful terminology to learn early:

string	A sequence of characters. Optionally surrounded by quotes. Examples: backspace, "string with spaces and 1 number".
list	A sequence of strings or nested lists within round brackets. List items are separated by any amount of whitespace characters, or by round brackets. Examples: (lrld-num 1), (tap-dance 200 (f1(unicode 😀)f2(unicode 🙂))).

If you have any questions, confusions, suggestions, etc., feel free to start a discussion or file an issue. If you have ideas for how to improve this document or any other part of the project, please be welcome to make a pull request or file an issue.

Forcefully exit kanata

Though this isn’t configuration-related, it may be important for you to know that pressing and holding all of the three following keys together at the same time will cause kanata to exit:

• Left Control

• Space

• Escape

This mechanism works on the key input before any remappings done by kanata.

Comments

You can add comments to your configuration file. Comments are prefixed with two semicolons. E.g:

;; This is a comment in a kanata configuration file.
;; Comments will be ignored and are intended for you to help understand your
;; own configuration when reading it later.

You can begin a multi-line comment block with #| and end it with |#:

#|
This is
a multi-line comment block
|#

Required configuration entries

defsrc

Reference

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

Syntax:

(defsrc $key1 $key2 ... $keyN)

$key	The name of a key. This can be a default key name or one defined in deflocalkeys. When physically pressing this input key, the action defined at the same order position on the active layer will activate.

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:

• Pressing an excluded key will type a letter while a prior tap-hold decision is still pending, resulting in potentially incorrect results.

• Excluded keys do not trigger early activation in actions such as tap-hold-press or tap-dance

• Excluded keys cannot be read by fork or switch logic.

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:

Example:

(defsrc
  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
  caps a    s    d    f    g    h    j    k    l    ;    '    ret
  lsft z    x    c    v    b    n    m    ,    .    /    rsft
  lctl lmet lalt           spc            ralt rmet rctl
)

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.

deflayer

Reference

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

Syntax:

(deflayer $layer-name $action1 $action2 ... $actionN)

$layer-name	A string representing the layer name. This name is used to reference this layer in other actions.
$action	The action that activates while this layer is active when the corresponding defsrc input key is pressed.

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:

Example:

(defsrc
  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
  caps a    s    d    f    g    h    j    k    l    ;    '    ret
  lsft z    x    c    v    b    n    m    ,    .    /    rsft
  lctl lmet lalt           spc            ralt rmet rctl
)

(deflayer dvorak
  grv  1    2    3    4    5    6    7    8    9    0    [    ]    bspc
  tab  '    ,    .    p    y    f    g    c    r    l    /    =    \
  caps a    o    e    u    i    d    h    t    n    s    -    ret
  lsft ;    q    j    k    x    b    m    w    v    z    rsft
  lctl lmet lalt           spc            ralt rmet rctl
)

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

deflayermap

Reference

An alternative method for defining a layer exists: deflayermap. This method maps inputs to actions by defining input-output pairs, ignoring defsrc entirely.

You will likely want to either enable process-unmapped-keys or define most of your keyboard keys within defsrc when using deflayermap. Otherwise many actions do not behave as intended. See one of the links for more context.

Syntax:

(deflayermap ($layer-name)
 $input1 $action1
 $input2 $action2
 ...
 $inputN $actionN)

$layer-name	A string representing the layer name. This name is used to reference this layer in other actions.
$input	The input key mapped to the corresponding output.
$action	The action that activates while this layer is active when the corresponding input key is pressed.

Description

The deflayermap variant has the advantage of terser configuration when only a few keys on a layer need to be mapped. When practicing a new configuration, the standard deflayer has an advantage of looking more like a physical keyboard layout, which may be helpful to some.

Within deflayermap, the very first item must be the layer name. The layer name must be in parentheses unlike with deflayer. After the layer name, the layer is configured via pairs of items:

• input key

• output action

An example complete configuration that maps Caps Lock to Escape is:

;; defsrc is still necessary
(defsrc)
(deflayermap (base-layer)
  caps esc)

The input key takes the same role as defsrc keys. The output action takes the role that items in the normal deflayer have.

As special input names, you can use one of _, __, or ___ to map all the keys that are not explicitly mapped in the layer, e.g. in the example above, these affect keys other than caps.

_	Map all unmapped keys in this layer that are defined in defsrc.
__	Map all unmapped keys in this layer that are not defined in defsrc.
___	Map all unmapped keys in this layer.

Review of required configuration entries

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

• defsrc

• deflayer

An example minimal configuration is:

(defsrc a b c)

(deflayer start 1 2 3)

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

Note	Please have a read through the known platform issues because they may have implications on what you should include/exclude in defsrc. The Windows LLHOOK I/O mechanism has the most issues by far.

Key names for defsrc and deflayermap

The source of truth for all default key names are the functions str_to_oscode and add_default_str_osc_mappings in the keys/mod.rs file.

This online tool will also work for most keys to tell you the key name. It will be shown as the event.code field in the web page after you press the key.

Non-US keyboards

For non-US keyboard users, you may have some keys on your keyboard with characters that are not allowed in defsrc by default, at least according to the symbol shown on the physical keys. The two sections below can help you understand how to remap all your keys.

Browser event.code

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.

Important

On Windows, you should use either kanata_winIOv2.exe or Interception when using key names according to the browser event.code. The default kanata.exe does not do mappings according to the browser event.code key names.

deflocalkeys

Reference

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

Syntax:

(deflocalkeys-$variant
  $key-name1 $key-number1
  $key-name2 $key-number2
  ...
  $key-nameN $key-numberN)

$variant	One of: win winiov2 wintercept linux macos
$key-name	A key name of your choice that can be used in the rest of the configuration.
$key-number	A key number that varies based on the kanata variant you are using.

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:

• deflocalkeys-win

• deflocalkeys-winiov2

• deflocalkeys-wintercept

• deflocalkeys-linux

• deflocalkeys-macos

Example:

(deflocalkeys-win
  ì 187
)

(deflocalkeys-winiov2
  ì 187
)

(deflocalkeys-wintercept
  ì 187
)

(deflocalkeys-linux
  ì 13
)

(deflocalkeys-macos
  ì 13
)

(defsrc
  grv  1    2    3    4    5    6    7    8    9    0    -    ì    bspc
)

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

Introduction to defcfg

Your configuration file may include a single defcfg entry. The defcfg can be empty or omitted. There are options that change kanata’s behaviour, but this introduction will introduce only the most prevalent entry: process-unmapped-keys. All other options can be found later in the defcfg options section.

Example of an empty defcfg:

(defcfg)

process-unmapped-keys

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:

• The early hold for prior tap-hold-press actions will not

• Prior one-shot actions will not be released

• fork and switch logic will not see the key

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. A known issue being AltGr/ralt/Right Alt; see Windows only: windows-altgr.

Example:

(defcfg process-unmapped-keys yes)
(defcfg process-unmapped-keys (all-except lctl ralt))

Aliases and variables

Before learning about actions, it will be useful to first learn about aliases and variables.

Aliases

Reference

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

Syntax:

(defalias
  $alias-name1 $action1
  $alias-name2 $action2
  ...
  $alias-nameN $actionN)

$alias-name	The chosen name for the shortcut label for the action. It can be used in the rest of the configuration by prefixing the name with the @ character.
$action	The ouput action used wherever the alias name is referenced.

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.

Example:

(defalias
  ;; tap for caps lock, hold for left control
  cap (tap-hold 200 200 caps lctl)
)

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.

(deflayer example
  @cap a s d f
)

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.

Example:

(defalias one (tap-hold 200 200 caps lctl))
(defalias two (tap-hold 200 200 esc lctl))
(defalias
  three C-A-del ;; Ctrl+Alt+Del
  four (tap-hold 200 200 @three ralt)
)

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.

Example:

(deflayer example
  ;; this is equivalent to the previous deflayer example
  (tap-hold 200 200 caps lctl) a s d f
)

Variables

Reference

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

Syntax:

(defvar
  $var-name1 $var-value1
  $var-name2 $var-value2
  ...
  $var-nameN $var-valueN)

$var-name	The chosen name for the shortcut label for the action. It can be used in the rest of the configuration by prefixing the name with the @ character.
$var-value	An arbitrary string or list that will be substituted wherever the variable is used. A variable can be used by prefixing the variable name with $.

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 cannot be used in defcfg, defsrc, or deflocalkeys

• variables cannot be used to substitute an action name

Variables are referred to by prefixing their name with $.

Example:

(defvar
  tap-timeout   100
  hold-timeout  200
  tt $tap-timeout
  ht $hold-timeout
)

(defalias
  th1 (tap-hold $tt $ht caps lctl)
  th2 (tap-hold $tt $ht spc  lsft)
)

concat in defvar

Within the second item of defvar, a list that begins with the special keyword concat will concatenate all subsequent items in the list together into a single string value. Without using concat, lists are saved as-is.

Example:

(defvar
  rootpath "/home/myuser/mysubdir"
  ;; $otherpath will be the string: /home/myuser/mysubdir/helloworld
  otherpath (concat $rootpath "/helloworld")
)

Actions

The actions kanata provides are what make it truly customizable. This section explains the available actions.

Live reload

Reference

Live reload variants:

lrld	String action that live-reloads the currently-used configuration file.
lrld-next	String action that live-reloads the configuration file specified consecutively later in the command line order. Cycles to the first-specified file if currently using the last file specified.
lrld-prev	String action that live-reloads the configuration file specified consecutively earlier in the command line order. Cycles to the last-specified file if currently using the first file specified.
(lrld-num $n)	List action that live-reloads the n’th file as specified in the command line order. The first file specified is n=1.

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.

Example:

(deflayer has-live-reload
  lrld a s d f
)

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:

(deflayer has-live-reloads
  lrld lrpv lrnx (lrld-num 3)
)

Example specifying multiple config files in the command line:

kanata -c startup.cfg -c 2nd.cfg -c 3rd.cfg

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

layer-switch

Reference

A list action that changes the active base layer.

Syntax:

(layer-switch $layer-name)

$layer-name

Layer name to switch to.

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.

Example:

(defalias dvk (layer-switch dvorak))

layer-while-held

Reference

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

Syntax:

(layer-while-held $layer-name)

$layer-name

Layer name to activate while 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.

Example:

(defalias nav (layer-while-held navigation))

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.

Transparent key

Reference

_	String action that activates the action of the layer "underneath" the active one.

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.

use-defsrc

Reference

use-defsrc

String action that outputs the corresponding defsrc input key.

Description

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

Example:

(defsrc a b c d)
(defalias src use-defsrc)
(deflayer remap-only-c-to-d
  _ _ d @src)

No-op

Reference

XX	String action that will output nothing.

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.

Example:

(deflayer contains-no-ops
  XX ✗ ∅ •)

Unicode

Reference

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

Syntax:

(unicode $unicode-codepoint)

$unicode-codepoint

One unicode codepoint. Be warned that many emojis/glyphs/graphemes are composed of multiple codepoints.

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 (🔣 😀)).

Note	The unicode action may not be correctly accepted by the active application.

Note	If using Linux, make sure to look at the unicode behaviour customization in defcfg.

Example:

(defalias
  sml (unicode 😀)
  😀 (🔣 😀)
  🙁 (unicode 🙁)
)
(deflayer has-happy-sad
  @sml @🙁 @😀 🔣😀 d f
)

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

Example with parentheses

(defalias
  lp (unicode "(")
  rp (unicode ")")
)

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

Example use of double-quote within a string

(defalias
  dq (unicode r#"""#)
)

Output chords/combos

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.

C-	Left Control
RC-	Right Control
A-	Left Alt
RA-	Right Alt, also known as AltGr
AG-	Also means Right Alt/AltGr
S-	Left Shift
RS-	Right Shift
M-	Left Meta
RM-	Right Meta

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:

• type a symbol, e.g. S-1 to output ! for the US layout.

• type an accented character, e.g. RA-a to output á for the US international layout.

• do a special action like C-c to send SIGTERM in the terminal

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:

• C-: Left Control (also ‹⎈ ‹⌃ or without the ‹ side indicator)

• RC-: Right Control (also ⎈› ⌃›)

• A-: Left Alt (also ‹⎇ ‹⌥ or without the ‹ side indicator))

• RA-: Right Alt, a.k.a. AltGr (also AG ⎇› ⌥›)

• S-: Left Shift (also ‹⇧ or without the ‹ side indicator))

• RS-: Right Shift (also ⇧›)

• M-: Left Meta, a.k.a. Windows, GUI, Command, Super (also ‹⌘ ‹❖ ‹◆ or without the ‹ side indicator))

• RM-: Right Meta (also ⌘› ❖› ◆›)

Example:

(defalias
  ;; Type exclamation mark (US layout)
  ex! S-1
  ;; Ctrl+C: send SIGINT to a Linux terminal program
  int C-c
  ;; Win+Tab: open Windows' Task View
  tsk M-tab
  ;; Ctrl+Shift+(C|V): copy or paste from certain terminal programs
  cpy C-S-c
  pst C-S-v
)

Repeat key

Reference

rpt	String action that outputs the single most-recently typed key.
rpt-any	String action that outputs the most-recently outputted action.

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.

Example:

(deflayer has-repeat
  rpt a s d f
)

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.

(deflayer has-repeat-any
  rpt-any a s d f
)

Release a key or layer

Reference

(release-key $key)	List action that releases the defined key from output actions. Notably this does not act on key inputs.
(release-layer $layer-name)	List action that releases layer-while-held activations for the given layer name.

Description

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

• release-key or key↑: release a key, accepts defsrc compatible names

• release-layer or layer↑: release a while-held layer

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.

multi

Reference

Activate multiple actions in sequence.

Syntax:

(multi $action1 $action2 ... $actionN)

$action

An output action.

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.

(defalias
  atl (multi alt (layer-while-held alted-with-exceptions))
  lft (multi (release-key alt) left) ;; release alt if held and also press left
  rgt (multi (release-key alt) rght) ;; release alt if held and also press rght
)

(defsrc
  alt  a    s    d    f
)

(deflayer base
  @atl _    _    _    _
)

(deflayer alted-with-exceptions
  _    _    _    @lft @rgt
)

Warning

This action can sometimes behave in surprising ways with regards to simultaneity and order of actions. For example, an action like (multi sldr ') will not behave as expected. Due to implementation details, sldr will activate after the ' even though it is listed before. This example could instead be written as (macro sldr 10 '), and that would work as intended. It is recommended to avoid multi if it can be replaced with a different action like macro or an output chord.

reverse-release-order

Reference

String item that can be used inside of (multi …​) to reverse the release order of any keys that were pressed as part of multi.

Syntax:

(multi ... reverse-release-order)

Description

Within multi you can use include reverse-release-order to do what the action states: reverse the typical release order from if you have multiple keys in multi.

For example, pressing then releasing a key with the action: (multi a b c) would press a b c in the stated order and then release a b c in the stated order. Changing it to (multi a b c reverse-release-order) would press a b c in the stated order and then release c b a in the stated order.

Example:

(defalias
  S-a-reversed (multi lsft a reverse-release-order)
)

Mouse actions

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

Mouse buttons

Reference

You can activate mouse actions with the string actions below.

mlft	Hold left mouse button.
mmid	Hold middle mouse button.
mrgt	Hold right mouse button.
mfwd	Hold forward mouse button.
mbck	Hold backward mouse button.
mltp	Tap left mouse button.
mmtp	Tap middle mouse button.
mrtp	Tap right mouse button.
mftp	Tap forward mouse button.
mbtp	Tap backward mouse button.

In Linux and Windows-Interception, the hold actions can be used within defsrc and deflayermap to remap mouse buttons like keyboard keys.

Description

The mouse button actions are:

• mlft: left mouse button

• mmid: middle mouse button

• mrgt: right mouse button

• mfwd: forward mouse button

• mbck: backward mouse button

The mouse button will be held while the key mapped to it is held. Using Linux and Windows-Interception, the above actions are also usable in defsrc to enable remapping specified mouse actions in your layers, like you would with keyboard keys.

If there are multiple mouse click actions within a single multi action, e.g.

(multi mrgt mlft)

then all the buttons except the last will be clicked then unclicked. The last button will remain held until key release. In the example above, pressing then releasing the key mapped to this action will result in the following event sequence:

1. press key mapped to multi

2. click right mouse button

3. unclick right mouse button

4. click left mouse button

5. release key mapped to multi

6. release left mouse button

There are variants of the standard mouse buttons which "tap" the button. Rather than holding the button while the key is held, a mouse click will be immediately followed by the release. Nothing happens when the key is released. The actions are as follows:

• mltp: tap left mouse button

• mmtp: tap middle mouse button

• mrtp: tap right mouse button

• mftp: tap forward mouse button

• mbtp: tap bacward mouse button

Mouse wheel

Reference

The mwheel-* actions allow you to emulate a mouse wheel. Holding the action will repeatedly scroll according to the action configuration.

Syntax:

(mwheel-$variant $interval $distance)

$variant	One of up down left right representing the scroll direction to use.
$interval	Number of milliseconds between scroll actions.
$distance	Distance to travel per activation. The number 120 represents a complete notch on standard resolution mice and in some environments, 120 or a multiple of it should be what is used.

You may use these key names within defsrc to remap scroll events as if they were keys, corresponding to up, down, left, right respectively: mwu, mwd, mwl, mwr.

Description

The mouse wheel actions are:

• mwheel-up or 🖱☸↑: vertical scroll up

• mwheel-down or 🖱☸↓: vertical scroll down

• mwheel-left or 🖱☸←: horizontal scroll left

• mwheel-right or 🖱☸→: horizontal scroll right

All of these actions accept two number strings. The first is the interval (unit: ms) between scroll actions. The second number is the distance (unit: arbitrary). In both Windows and Linux, 120 distance units is equivalent to a notch movement on a physical wheel. You can play with the parameters to see what feels correct to you. Both numbers must be in the range [1,65535].

Note	In Linux, not all desktop environments support the REL_WHEEL_HI_RES event. If this is the case for yours, it will likely be a better experience to use a distance value that is a multiple of 120.

On Linux and Interception, you can also choose to read from a mouse device. When doing so, using the mwu, mwd, mwl, mwr key names in defsrc allow you to remap the mouse scroll up/down/left/right actions like you would with keyboard keys.

Note	If you are using a high-resolution mouse in Linux, only a full "notch" of the scroll wheel will activate the action.

Note	If you are using a high-resolution mouse with Interception, you will probably get way more events than you intended.

Mouse movement

Reference

The movemouse-* actions allow you to move the mouse cursor. Holding the action will repeatedly move the cursor according to the configuration.

Syntax:

(movemouse-$variant $interval $distance)

$variant	One of up down left right representing the direction to move.
$interval	Number of milliseconds between move activations.
$distance	Distance to travel per activation in unit of pixels.

There is a move mouse variant that increases distance per activation at a constant rate until a maximum is reached.

Syntax:

(movemouse-accel-$variant $interval $acceleration-time $min $max)

$variant	One of up down left right representing the direction to move.
$interval	Number of milliseconds between move activations.
$acceletaion-time	Number of milliseconds until max distance per activation is reached.
$min	Initial distance to travel per activation in unit of pixels.
$max	Maximum distance to travel per activation in unit of pixels.

Description

The mouse movement actions are:

• movemouse-up or 🖱↑

• movemouse-down or 🖱↓

• movemouse-left or 🖱←

• movemouse-right or 🖱→

Similar to the mouse wheel actions, all of these actions accept two number strings. The first is the interval (unit: ms) between movement actions and the second number is the distance (unit: pixels) of each movement.

The following are variants of the above mouse movements that apply linear mouse acceleration from the minimum distance to the maximum distance as the mapped key is held.

• movemouse-accel-up or 🖱accel↑

• movemouse-accel-down or 🖱accel↓

• movemouse-accel-left or 🖱accel←

• movemouse-accel-right or 🖱accel→

All these actions accept four number strings. The first number is the interval (unit: ms) between movement actions. The second number is the time it takes (unit: ms) to linearly ramp up from the minimum distance to the maximum distance. The third and fourth numbers are the minimum and maximum distances (unit: pixels) of each movement.

There is a toggable defcfg option related to movemouse-accel - movemouse-inherit-accel-state. You might want to enable it, especially if you’re coming from QMK.

Set absolute mouse position

The action setmouse or set🖱 sets the absolute mouse position.

Warning

This is only supported in Windows right now. For an interesting keyboard-centric mouse solution in Linux, try looking at warpd.

This list action takes two parameters which are x and y positions of the absolute movement. The values go from 0,0 which is the upper-left corner of the screen to 65535,65535 which is the lower-right corner of the screen. If you have multiple monitors, setmouse treats them all as a single large screen. This can make it a little confusing for how to set the x, y values to get the positions that you want. Experimentation will be needed.

Modify the speed of mouse movements

The action movemouse-speed or 🖱speed modifies the speed at which movemouse and movemouse-accel function at runtime. It does this by expanding or shrinking min_distance and max_distance while the action key is pressed.

This action accepts one number (unit: percentage) by which the mouse movements will be accelerated.

Warning

Due to the nature of pixels being whole numbers, some values such as 33 may not result in an exact third of the distance.

Example:

(defalias
  fst (movemouse-speed 200)
  slw (movemouse-speed 50)
)

Mouse all actions example

(defalias
  mwu (mwheel-up 50 120)
  mwd (mwheel-down 50 120)
  mwl (mwheel-left 50 120)
  mwr (mwheel-right 50 120)

  ms↑ (movemouse-up 1 1)
  ms← (movemouse-left 1 1)
  ms↓ (movemouse-down 1 1)
  ms→ (movemouse-right 1 1)

  ma↑ (movemouse-accel-up 1 1000 1 5)
  ma← (movemouse-accel-left 1 1000 1 5)
  ma↓ (movemouse-accel-down 1 1000 1 5)
  ma→ (movemouse-accel-right 1 1000 1 5)

  sm (setmouse 32228 32228)

  fst (movemouse-speed 200)
)

(deflayer mouse
  _    @mwu @mwd @mwl @mwr _    _    _    _    _    @ma↑ _    _    _
  _    pgup bck  _    fwd  _    _    _    _    @ma← @ma↓ @ma→ _    _
  _    pgdn mlft _    mrgt mmid _    mbck mfwd _    @ms↑ _    _
  @fst _    mltp _    mrtp mmtp _    mbtp mftp @ms← @ms↓ @ms→
  _    _    _              _              _    _    _
)

tap-dance

Reference

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

Syntax:

(tap-dance $timeout $action-list)

$timeout	Number of milliseconds after which the tap-dance ends.
$action-list	A list of actions that can be selected, ordered by number of taps.

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

Syntax:

(tap-dance-eager $timeout $action-list)

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:

• the timeout expires

• a different key is pressed

• the key is repeated up to the final action

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

Example:

(defalias
  ;; 1 tap : "A" key
  ;; 2 taps: Control+C
  ;; 3 taps: Switch to another layer
  ;; 4 taps: Escape key
  td (tap-dance 200 (a C-c (layer-switch l2) esc))
)

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:

1. type a

2. erase the a and type bb

3. erase the bb and type ccc

(defalias
  td2 (tap-dance-eager 500 (
    (macro a) ;; use macro to prevent auto-repeat of the key
    (macro bspc b b)
    (macro bspc bspc c c c)
  ))
)

one-shot

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.

Syntax:

($one-shot-variant $timeout $action)

Values for $variant:

one-shot-press	End on the first press of another key. This is also the variant selected by the name one-shot.
one-shot-release	End on the first release of a newly pressed key.
one-shot-press-pcancel	End on the first press of another key or on re-press of another active one-shot key
one-shot-release-pcancel	End on the first release of a newly pressed key or on re-press of another active one-shot key.

Other items:

$timeout	Number of milliseconds after which if not deactivated due to user input, one-shot will deactivate on its own.
$action	Layer action, key, or output chord.

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:

• press a modifier for exactly one following key press

• switch to another layer for exactly one following key press

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:

• one-shot-press or one-shot↓: end on the first press of another key

• one-shot-release or one-shot↑: end on the first release of another key

• one-shot-press-pcancel or one-shot↓⤫: end on the first press of another key or on re-press of another active one-shot key

• one-shot-release-pcancel or one-shot↑⤫: end on the first release of another key or on re-press of another active one-shot key

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.

Note	When using one-shot with keys that will trigger defoverrides, you will likely want to adjust override-release-on-activation to yes in defcfg.

Example:

(defalias
  os1 (one-shot 500 (layer-while-held another-layer))
  os2 (one-shot-press 2000 lsft)
  os3 (one-shot-release 2000 lctl)
  os4 (one-shot-press-pcancel 2000 lalt)
  os5 (one-shot-release-pcancel 2000 lmet)
)

one-shot-pause-processing

Reference

Pause one-shot processing of new input keypresses for a time, to allow actions that are not intended to consume one-shot to take place.

Syntax:

(one-shot-pause-processing $time)

time	Number of milliseconds to ignore processing. Something notable is that one virtual key press or releas (tap is a separate press and subsequent release) will take 1ms to process. If using virtual keys this number must be larger than the number of virtual key events that are taking place.

Description

The one-shot-pause-processing list action allows you to pause the key press processing of one-shot activations. An example of when this is useful the following sequence:

• Activate a layer-while-held

• Activate a one-shot action on that layer

• Release the layer-while-held key, which has an (on-release …​) action associated with it.

• The on-release action is not intended to consume one-shot activations

In the scenario above, by default the on-release activation would trigger deactivation of one-shot; thus the pause processing action must be used to stop this from happening.

tap-hold

Warning

The tap-hold action and all variants can behave unexpectedly on Linux with respect to repeat of antecedent key presses. The full context is in discussion #422. In brief, the workaround is to use tap-hold inside of multi, combined with another key action that behaves as a no-op like f24. Example: (multi f24 (tap-hold …​))

Reference

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

Syntax:

(tap-hold $tap-timeout $hold-timeout $tap-action $hold-action)

$tap-timeout	Number of milliseconds for the window that a tap into re-press with hold results in the $tap-action being held.
$hold-timeout	Number of milliseconds after which the $hold-action activates. Releasing the key before this elapses results in $tap-action activating.
$tap-action	Action to activate when the input is determined to be a "tap".
$hold-action	Action to activate when the input is determined to be a "hold".

Variants:

(tap-hold-press $tap-timeout $hold-timeout $tap-action $hold-action)
(tap-hold-release $tap-timeout $hold-timeout $tap-action $hold-action)
(tap-hold-press-timeout $tap-timeout $hold-timeout $tap-action $hold-action $timeout-action)
(tap-hold-release-timeout $tap-timeout $hold-timeout $tap-action $hold-action $timeout-action)
(tap-hold-release-keys $tap-timeout $hold-timeout $tap-action $hold-action $tap-keys)
(tap-hold-except-keys $tap-timeout $hold-timeout $tap-action $hold-action $tap-keys)

tap-hold-press	Activate $hold-action early if held and another input key is pressed.
tap-hold-release	Activate $hold-action early if held and another input key is pressed and released.
tap-hold-press-timeout	Activate $hold-action if held and another input key is pressed. If the defined timeout elapses, $timeout-action will activate.
tap-hold-release-timeout	Activate $hold-action early if held and another input key is pressed and released. If the defined timeout elapses, $timeout-action will activate.
tap-hold-release-keys	Activate $hold-action early if held and another input key is pressed and released. The $tap-keys parameter is a list of key names. Activates $tap-action early if a key within $tap-keys is pressed before hold activates.
tap-hold-except-keys	The $tap-keys parameter is a list of key names. Activates $tap-action if a key within $tap-keys is pressed or if the action key is released before hold timeout. No key is ever output until the action key is released or another key is pressed, which differs from the default tap-hold behaviour.

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:

1. tap timeout (unit: ms)

2. hold timeout (unit: ms)

3. tap action

4. hold action

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.

Tap timeout in more detail

The way a tap-hold action works with respect to the tap timeout is often unclear to newcomers. To make it concrete, the output event sequence of the tap-hold action (tap-hold $tap-timeout 200 a lctl) for varying values of $tap-timeout with a fixed input event sequence will be described.

The input event sequence is:

• press

• 50 ms elapses

• release

• 50 ms elapses

• press

• 300 ms elapses

• release

With (defvar $tap-timeout 0), the output event sequence is:

• 50 ms elapses

• press a

• release a

• 250 ms elapses

• press lctl

• 100 ms elapses

• release lctl

The above output sequence is the same for all $tap-timeout values between and including 0 and 99.

For a value of 100 or greater for $tap-timeout, the output event sequence is instead:

• 50 ms elapses

• press a

• release a

• 50 ms elapses

• press a

• 300 ms elapses

• release a

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

There are two additional variants of tap-hold:

• tap-hold-press or tap⬓↓

  • If there is a press of a different key, the hold action is activated even if the hold timeout hasn’t expired yet

• tap-hold-release or tap⬓↑

  • If there is a press+release of a different key, the hold action is activated even if the hold timeout hasn’t expired yet

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

Example:

(defalias
  anm (tap-hold         200 200 a @num) ;; tap: a      hold: numbers layer
  oar (tap-hold-press   200 200 o @arr) ;; tap: o      hold: arrows layer
  ech (tap-hold-release 200 200 e @chr) ;; tap: e      hold: chords layer
)

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

• tap-hold-press-timeout or tap⬓↓timeout

• tap-hold-release-timeout or tap⬓↑timeout

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.

• tap-hold-release-keys or tap⬓↑keys

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.

Example:

(defalias
  ;; tap: o    hold: arrows layer    timeout: backspace
  oat (tap-hold-press-timeout   200 200 o @arr bspc)
  ;; tap: e    hold: chords layer    timeout: esc
  ect (tap-hold-release-timeout 200 200 e @chr esc)
  ;; tap: u    hold: misc layer      early tap if any of: (a o e) are pressed
  umk (tap-hold-release-keys 200 200 u @msc (a o e))
)

• tap-hold-except-keys or tap-hold⤫keys

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.

Example:

(defalias
  ;; tap: o    hold: arrows layer    timeout: backspace
  oat (tap-hold-press-timeout   200 200 o @arr bspc)
  ;; tap: e    hold: chords layer    timeout: esc
  ect (tap-hold-release-timeout 200 200 e @chr esc)
  ;; tap: u    hold: misc layer      always tap if any of: (a o e) are pressed
  umk (tap-hold-except-keys 200 200 u @msc (a o e))
)

macro

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.

Syntax:

(macro $macro-action1 $macro-action2 ... $macro-actionN)

$macro-action

A delay, key, action within the subset allowed within macros, or an output-chord-prefixed list of more macro-actions.

Variants:

(macro-release-cancel ...)
(macro-cancel-on-press ...)
(macro-release-cancel-and-cancel-on-press ...)
(macro-repeat ...)
(macro-repeat-$cancel-variant ...)

macro-release-cancel	Cancel all active macros if the key is released.
macro-cancel-on-press	Cancel all active macros if a different key is pressed.
macro-release-cancel-and-cancel-on-press	Cancel all active macros if either the key is released or a different key is pressed.
macro-repeat	Repeat the macro while held.
macro-repeat-$cancel-variant	Repeat the macro while held. Cancels the final repeat according the the behaviour of one of the variants: release-cancel, cancel-on-press, release-cancel-and-cancel-on-press.

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.

Important

The number keys 0-9 will be parsed as millisecond delays whereas in other contexts they would be parsed as key names. To use the numbered keys they must be aliased or otherwise use the key names Digit0-Digit9.

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

The actions supported in macro are:

• cmd

• unicode

• mouse actions

• repeat

• live reload

• virtual key actions

• sequence leader

• arbitrary keycode

• dynamic macro

• unmod

Note	Some of these actions may need short delays between. For example, (macro a (unmod b) 5 (unmod c) d)) needs the delay of 5 to work correctly.

Example:

(defalias
  : S-;
  8 8
  0 0
  🙃 (unicode 🙃)

  ;; Type "http://localhost:8080"
  lch (macro h t t p @: / / 100 l o c a l h o s t @: @8 @0 @8 @0)

  ;; Type "I am HAPPY my FrIeNd 🙃"
  hpy (macro S-i spc a m spc S-(h a p p y) spc m y S-f r S-i e S-n d spc @🙃)

  ;; alt-tab(x3) and alt-shift-tab(x3) with macro
  tfd (macro A-(tab 200 tab 200 tab))
  tbk (macro A-S-(tab 200 tab 200 tab))
)

macro-release-cancel

The macro-release-cancel variant of the macro action will cancel all active macros upon releasing the key. Shorter unicode variant: macro↑⤫. This variant is parsed identically to the non-cancelling version. An example use case for this action is holding down a key to get different outputs, similar to tap-dance but one can see which keys are being outputted.

E.g. in the example below, when holding the key, first 1 is typed, then replaced by ! after 500ms, and finally that is replaced by @ after another 500ms. However, if the key is released, the last character typed will remain and the rest of the macro does not run.

(defalias
  1 1

  ;; macro-release-cancel to output different characters with visual feedback
  ;; after holding for different amounts of time.
  1!@ (macro-release-cancel @1 500 bspc S-1 500 bspc S-2)
)

macro-cancel-on-press

The macro-cancel-on-press variant of the macro action enables a cancellation trigger for all active macros including itself, which is activated when a physical press of any other key happens. The trigger is enabled while the macro is in progress.

(defalias
  1 1
  1!@ (macro-cancel-on-press @1 500 bspc S-1 500 bspc S-2)
)

macro-release-cancel-and-cancel-on-press

The macro-release-cancel-and-cancel-on-press variant combines the cancel behaviours of both the release-cancel and cancel-on-press.

(defalias
  1 1
  1!@ (macro-release-cancel-and-cancel-on-press @1 500 bspc S-1 500 bspc S-2)
)

macro-repeat

There are further macro-repeat variants of the three macro actions described previously. These variants repeat while held. The repeat will only occur once all macros have completed, including the held macro key. If multiple repeating macros are being held simulaneously, only the most recently pressed macro will be repeated.

(defalias
  mr1 (macro-repeat mltp)
  mr2 (macro-repeat-release-cancel mltp)
  mr3 (macro-repeat-cancel-on-press mltp)
  mr4 (macro-repeat-release-cancel-and-cancel-on-press mltp)
)

dynamic-macro

Reference

Record and replay key inputs.

Syntax:

(dynamic-macro-record $id)
(dynamic-macro-play   $id)
(dynamic-macro-record-stop)
(dynamic-macro-record-stop-truncate $count)

dynamic-macro-record	Record a dynamicro macro which will be saved with the defined $id.
dynamic-macro-play	Play back a macro saved with the defined $id.
dynamic-macro-record-stop	Stop and save a macro recording. This can also be achieved by recording a new macro or re-pressing record with the same $id.
dynamic-macro-record-stop-truncate	Stop and save a macro recording while truncating $count events from the end of the recording. This can be useful if the record/stop button is on a different layer.

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.

Example:

(defalias
  dr0 (dynamic-macro-record 0)
  dr1 (dynamic-macro-record 1)
  dr2 (dynamic-macro-record 2)
  dp0 (dynamic-macro-play 0)
  dp1 (dynamic-macro-play 1)
  dp2 (dynamic-macro-play 2)
  dms dynamic-macro-record-stop
  dst (dynamic-macro-record-stop-truncate 1)
)

caps-word

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.

Syntax:

(caps-word $timeout)
(caps-word-toggle $timeout)
(caps-word-custom $timeout $shifted-list $non-terminal-list)
(caps-word-custom-toggle $timeout $shifted-list $non-terminal-list)

$timeout	Number of milliseconds after which the caps-word state ends. The duration is refreshed upon typing a non-terminating character.
$shifted-list	List of keys that will be automatically shifted.
$non-terminal-list	List of keys that are not shifted but which do not terminate the caps-word state.

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:

• 0-9

• kp0-kp9

• bspc del

• up down left rght

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

Example:

(defalias
  cw (caps-word 2000)

  ;; This example is similar to the default caps-word behaviour but it moves the
  ;; 0-9 keys to the capitalized key list from the extra non-terminating key list.
  cwc (caps-word-custom
    2000
    (a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
    (kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 bspc del up down left rght)
  )
)

caps-word-toggle

There are -toggle variants of the caps-word actions. By default re-pressing caps-word will keep caps-word active. The -toggle variants will end caps-word if it is currently active, otherwise caps-word will be activate as normal.

Example:

(defalias
  cwt (caps-word-toggle 2000)
  cct (caps-word-custom-toggle
    2000
    (a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
    (kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 bspc del up down left rght)
  )
)

unmod

Reference

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

Syntax:

(unmod $key1 $key2 ... $keyN)
(unmod ($mod1 $mod2 ... $modN) $key1 $key2 ... $keyN)

$key	A key name to output while unmodded.
$mod	By default unmod will deactivate all modifier keys. An optional list as the first parameter allows specfying a subset of modifiers to deactivate during the action.

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.

Note	In case the modifiers to be undone are not part of defsrc, process-unmapped-keys needs to be enabled in defcfg in order for their states to be tracked correctly.

Example:

(defalias
  ;; holding shift and tapping a @um1 key will still output 1.
  um1 (unmod 1)
  ;; dead keys é (as opposed to using AltGr) that outputs É when shifted
  dké (macro (unmod ') e)

  ;; In ISO German QWERTZ, force unshifted symbols even if shift is held
  { (unshift ralt 7)
  [ (unshift ralt 8)
)

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

Example:

(defalias
	;; only unshift the alt keys
	unalt-a (unmod (lalt ralt) a)
)

fork

Reference

The fork action allows choosing between a default and an alternate action based on whether specific keys are active. fork is the equivalent of the basic key checks in switch, using none of the list logic items, i.e. virtual keys are not supported.

Syntax:

(fork $left-action $right-action $right-trigger-keys)

$left-action	Action to activate by default.
$right-action	Action to activate if any of $right-trigger-keys are active.
$right-trigger-keys	List of keys that, if active when fork activates, causes $right-action to happen in place of $left-action.

Tip	The keys nop0-nop9 can be used as no-op outputs that can still be checked within fork, unlike what XX does.

switch

Reference

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

Syntax:

(switch
  $logic-check1 $action1 $post-activate1
  $logic-check2 $action2 $post-activate2
  ...
  $logic-checkN $actionN $post-activateN)

$logic-check	The condition, which if it evaluates to true, will trigger the corresponding action.
$action	Action to activate when logic evaluates to true.
$post-activate	Valid values are fallthrough and break. With fallthrough, when an action activates switch will continue evaluating further logic checks and potentially trigger more actions. With break, further actions will not activate.

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.

Syntax of logic check:

($item1 $item2 ... $itemN)

Syntax of special checks:

(or  $item1 $item2 ... $itemN)
(and $item1 $item2 ... $itemN)
(not $item1 $item2 ... $itemN)
(key-history $key-name $key-recency)
(key-timing  $key-recency $comparator $time)
(input         $input-type $key-name)
(input-history $input-type $key-name $input-recency)
(layer      $layer-name)
(base-layer $layer-name)

or	Evaluates to true if any $item is true.
and	Evaluates to true if all of $item are true.
not	Evaluates to true if all of $item are false.
key-history	Evaluates to true if the key in the recency slot matches $key-name. A $key-recency of 1 is the most recent key pressed according to Kanata processing. The max recency is 8.
key-timing	The valid values for $comparator are less-than and greater-than, with lt and gt as shorthand if desired. This item evaluates to true if the key with the corresponding recency was pressed — for lt more recently than, or for gt later than — the defined $time with unit milliseconds.
input	Evaluates to true if the $key-name is currently pressed. The $input-type must be either real or virtual. If using real, this will check against the defsrc inputs. If using virtual, this will check against virtual key activations.
input-history	Evaluates to true if the input in the $input-recency slot matches $key-name. Two input types use the same history with respect to recency slots. A recency of 1 is the most recent input i.e. the input activating switch itself. The max recency is 8.
layer	Evaluates to true if the active layer matches $layer-name.
base-layer	Evaluates to true if the most-recently-switched-to layer from a layer-switch action matches $layer-name.

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:

• logic check

• action: to activate if logic check evaluates to true

• fallthrough|break: choose to continue vs. stop evaluating cases

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.

Tip	the keys nop0-nop9 can be used as no-op outputs that can still be checked within switch, unlike what XX does.

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.

Example:

(defalias
  swt (switch
    ;; case 1
    ((and a b (or c d) (or e f))) @ac1 break
    ;; case 2
    (a b c) @ac2 fallthrough
    ;; case 3
    () @ac3 break
  )
)

Below is a description of how this example behaves.

Case 1

((and a b (or c d) (or e f))) a break

Translating case 1’s logic check to some other common languages might look like:

(a && b && (c || d) && (e || f))

If the logic check passes, the action @ac1 will activate. No other action will activate since break is used.

Cases 2 and 3

(a b c) c fallthrough
() b break

Case 2’s key check behaves like that of fork, i.e.

(or a b c)

or for some other common languages:

a || b || c

If this logic check passes and the case 1 does not pass, the action @ac2 will activate first. Since the logic check of case 3 always passes, @ac3 will activate next.

If neither case 1 or case 2 pass their logic checks, case 3 will always activate with @ac3.

key-history and key-timing

In addition to simple keys there are two list items that can be used within the case logic check that compare against your typed key history:

• key-history

• key-timing

The key-history item compares the order that keys were typed. It accepts, in order:

• a key

• the key recency

The key recency must be in the range 1-8, where 1 is the most recent key that was pressed and 8 is 8th most recent key pressed.

Example:

(defalias
  swh (switch
    ((key-history a 1)) S-a break
    ((key-history b 1)) S-b break
    ((key-history c 1)) S-c break
    ((key-history d 8)) (macro d d d) break
    () XX break
  )
)

The key-timing compares how long ago recent key typing events occurred. It accepts, in order,

• the key recency

• a comparison string, which is one of: less-than|greater-than|lt|gt

• number of milliseconds to compare against

The key recency must be in the range 1-8, where 1 is the most recent key that was pressed and 8 is 8th most recent key pressed. Most use cases are expected to use a value of 1 for this parameter, but perhaps you can find a creative use for the other values.

The comparison string determines how the actual key event timing will be compared to the provided timing.

The number of milliseconds must be 0-65535.

Warning

The maximum milliseconds value of this configuration item across your whole configuration will be a lower bound of how long it takes for kanata to become idle and stop processing its state machine every approximately 1ms.

Example:

(defalias
  swh (switch
    ((key-timing 1 less-than 200)) S-a break
    ((key-timing 1 greater-than 500)) S-b break
    ((key-timing 2 lt 1000)) S-c break
    ((key-timing 8 gt 2000)) (macro d d d) break
    () XX break
  )
)

not

The examples presented so far have not included the not boolean operator. This operator will now be discussed. Syntactically, the not operator is used similarly to or|and. Functionally, it means "not any of" the list elements.

Example:

(defalias
  swn (switch
    ((not x y z)) S-a break
    ;; the above and below cases are equivalent in logic
    ((not (or x y z))) S-a break
  )
)

In potentially more familiar notation, both cases have the logic:

!(x || y || z)

input

Until now, all switch logic has been associated to key code outputs. It is also possible to operate on inputs. Inputs can be either real keys or "virtual" (fake) keys.

Example:

(defalias switch-input-example
  (switch
    ((input real lctl)) $ac1 break
    ((input virtual vk1)) $ac2 break
    () $ac3 break
  )
)

Similar to key-history for regular active keys, input-history also exists. A perhaps surprising, but hopefully logical, behaviour of input-history when compared to key-history is that, at the time of switch activation, the history of input-history for recency 1 will be the just-pressed input. In other words recency 1 is the input activating the switch action itself. Whereas with key-history for example, the key that will be next outputted may be determined by the switch logic itself, so is not in the history. The consequence of this is that you should use a recency of 2 when referring to the previously pressed input because the current input is in the recency 1 slot.

Example:

(defalias switch-input-history-example
  (switch
    ((input-history real lsft 2)) $var1 break
    ((input-history virtual vk2 2)) $var1 break
    () $ac3 break
  )
)

layer

The layer list item can be used in switch logic to operate on the active layer. It accepts a single layer name and evaluates to true if the configured layer name is the active layer, otherwise it evaluates to false.

Example:

(defalias switch-layer-example
  (switch
     ((layer base)) x break
    ((layer other)) y break
                 () z break
  )
)

base-layer

The base-layer list item evaluates to true if the configured layer name is the base layer. The base layer is the most recently switched-to layer from a layer-switch action, or the first layer defined in your configuration if layer-switch has never been activated.

Example:

(defalias switch-layer-example
  (switch
     ((base-layer base)) x break
    ((base-layer other)) y break
                 () z break
  )
)

cmd

Warning

This action does not work unless you use the appropriate binary or - if compiling yourself - the appropriate feature flag. Additionally you must add the danger-enable-cmd defcfg option.

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.

Syntax:

(cmd $binary $arg1 $arg2 ... $argN)
(cmd-log $stdout-log-level $stderr-log-level)
(cmd-output-keys $binary $arg1 $arg2 ... $argN)

$binary	Executable binary to run.
$arg	Argument passed into the binary.
$stdout-log-level	Log level for stdout of the command. Must be debug, info, warn, error, or none.
$stdout-log-level	Log level for stderr of the command. Must be debug, info, warn, error, or none.

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.

Example:

(defalias
  cm1 (cmd rm -fr /tmp/testing)

  ;; You can use bash -c and then a quoted string to execute arbitrary text in
  ;; bash. All text within double-quotes is treated as a single string.
  cm2 (cmd bash -c "echo hello world")

  ;; You can prefix commands with sudo -u USER
  ;; to execute commands as a different user.
  cm3 (cmd sudo -u other_user bash -c "echo goodbye")
)

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.

Example:

(defalias
  ;; The first two arguments are the log levels, then just the normal command
  ;; This will only error if `bash` is not found or something else goes
  ;; wrong with the initial execution. Any logs produced by bash will not
  ;; be shown.
  noisy-cmd (cmd-log none error bash -c "echo hello this produces a log")

  ;; This will only log the output of the command, but it won't start
  ;; because the command doesn't exist.
  ignore-failure-cmd (cmd-log info none thiscmddoesnotexist)

  verbose-only-log (cmd-log verbose verbose bash -c "echo yo")
)

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.

(defalias
  ;; bash: type date-time as YYYY-MM-DD HH:MM
  pdb (cmd-output-keys bash -c "date +'%F %R' | sed 's/./& /g' | sed 's/:/S-;/g' | sed 's/\(.\{20\}\)\(.*\)/\(\1 spc \2\)/'")

  ;; powershell: type date-time as YYYY-MM-DD HH:MM
  pdp (cmd-output-keys powershell.exe "echo '(' (((Get-Date -Format 'yyyy-MM-dd HH:mm').toCharArray() -join ' ').insert(20, ' spc ') -replace ':','S-;') ')'")
)

arbitrary-code

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!

Warning

This is not cross platform!

Warning

When using the Interception driver, this action is still sent over SendInput.

(defalias ab1 (arbitrary-code 700))

Global overrides

The defoverrides optional configuration item allows you to create global key overrides, irrespective of what actions are used to generate those keys. It accepts pairs of lists:

1. the input key list that gets replaced

2. the output key list to replace the input keys with

Both input and output lists accept 0 or more modifier keys (e.g. lctl, rsft) and exactly 1 non-modifier key (e.g. 1, bspc).

Only zero or one defoverrides is allowed in a configuration file.

Note	Depending on your use case you may want to adjust override-release-on-activation in defcfg.

Example:

;; Swap numbers and their symbols with respect to shift
(defoverrides
  (1) (lsft 1)
  (2) (lsft 2)
  ;; repeat for all remaining numbers

  (lsft 1) (1)
  (lsft 2) (2)
  ;; repeat for all remaining numbers
)

Include other files

The include optional configuration item allows you to include other files into the configuration. This configuration accepts a single string which is a file path. The file path can be an absolute path or a relative path. The path will be relative to the defined configuration file.

At the time of writing, includes can only be placed at the top level. The included files also cannot contain includes themselves.

Non-existing files will be ignored.

Example:

;; This is in the file initially read by kanata, e.g. kanata.kbd
(include other-file.kbd)

;; This is in the other file
(defalias
  included-alias XX
  ;; ...
)

;; This is in the other file
(deflayer included-layer
  ;; ...
)

Platform-specific configuration

If you put any top-level configuration item within a list beginning with platform, it will become a platform-specific configuration that is only active for the specified platforms.

Syntax:

(platform (applicable-platforms) ...)

The valid values for applicable platforms are:

• win

• winiov2

• wintercept

• linux

• macos

Example:

(platform (macos)
  ;; Only on macos, use command arrows to jump/delete words
  ;; because command is used for so many other things
  ;; and it's weird that these cases use alt.
  (defoverrides
    (lmet bspc) (lalt bspc)
    (lmet left) (lalt left)
    (lmet right) (lalt right)
  )
)

(platform (win winiov2 wintercept)
  (defalias run-my-script (cmd #| something involving powershell |#))
)

(platform (macos linux)
  (defalias run-my-script (cmd #| something involving bash |#))
)

Environment-conditional configuration

Syntax:

(environment (env-var-name env-var-value) ...)

The items env-var-name and env-var-value can be arbitrary strings. The name is the environment variable that is read for determining if the configuration is used or not. If the value of the environment variable (set only on kanata startup) matches env-var-value, the configuration is used; otherwise it is ignored. An empty string for env-var-value — "" — will use the configuration if the environment variable an empty string and also if the variable is unset/missing entirely.

Example:

(environment (LAPTOP lp1)
  (defalias met @lp1met)
)

(environment (LAPTOP lp2)
  (defalias met @lp2met)
)

Set environment variables in the current terminal process:

# powershell
$env:VAR_NAME = "var_value"

# bash
VAR_NAME=var_value

Input chords / combos (v2)

You may define a single defchordsv2 configuration item. This enables you to define global input chord behaviour. One might also find this functionality called another name of "combos" in other projects.

Input chords enables you to press two or more keys in quick succession to activate a different action than would normally be associated with those keys. When activating a chord, the order of presses is not important; when all keys belonging to a chord are pressed, the action activates regardless of press order.

The defchordsv2 feature is configured as shown below:

Syntax example

(defchordsv2
  (participating-keys1) action1 timeout1 release-behaviour1 (disabled-layers1)
    ...
  (participating-keysN) actionN timeoutN release-behaviourN (disabled-layersN)
)

The configuration is made up of 5-tuples of:

$participating-keys	These are key names you would use in defsrc. A minimum of two keys must be defined per chord. The list must be unique per chord.
$action	These are actions as you would configure in deflayer or defalias. The action activates if all participating keys are activated within the timeout.
$timeout	The time (unit: milliseconds) within which, if all participating keys are pressed, the chord action will activate; otherwise the key presses are handled by the active layer. The time begins when the first participant is pressed.
$release-behaviour	This must be either first-release or all-released; first-release means the chord action will be released when the first participant is released, while all-released means the chord action will be released only when all of the participants have been released.
$disabled-layers	A list of layer names on which this chord is disabled.

Input chords have a related defcfg item: chords-v2-min-idle. When any non-chord activation happens, a timeout begins with duration configured by chords-v2-min-idle (unit: milliseconds). Until this timeout expires, all inputs will immediately skip chords processing and be processed by the active layer.

Important

When opting into input chords v2, you must enable concurrent-tap-hold. This is enforced for a more responsive tap-hold experience when activated by a chord.

Example:

(defcfg concurrent-tap-hold yes)
(defchordsv2
  (a s)    c                200 all-released  (non-chord-layer)
  (a s d) (macro h e l l o) 250 first-release (non-chord-layer)
  (s d f) (macro b y e)     400 first-release (non-chord-layer)
)

Note	Also see v1 chords, which are configured differently and can be defined per-layer.

defcfg options

danger-enable-cmd

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.

Example:

(defcfg
  danger-enable-cmd yes
)

sequence-timeout

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

Example:

(defcfg
  sequence-timeout 2000
)

sequence-input-mode

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

The options are:

• visible-backspaced: types sequence characters as they are inputted. The typed characters will be erased with backspaces for a valid sequence termination.

• hidden-suppressed: hides sequence characters as they are typed. Does not output the hidden characters for an invalid sequence termination.

• hidden-delay-type: hides sequence characters as they are typed. Outputs the hidden characters for an invalid sequence termination either after a timeout or after a non-sequence key is typed.

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.

Example:

(defcfg
  sequence-input-mode visible-backspaced
)

sequence-backtrack-modcancel

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

(defseq
  fk1 (lsft a b)
  fk2 (S-(c d))
)

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

Example:

(defcfg
  sequence-backtrack-modcancel no
)

log-layer-changes

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.

Example:

(defcfg
  log-layer-changes no
)

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.

delegate-to-first-layer

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 #435.

Example:

(defcfg
  delegate-to-first-layer yes
)

movemouse-inherit-accel-state

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.

Example:

(defcfg
  movemouse-inherit-accel-state yes
)

movemouse-smooth-diagonals

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.

Example:

(defcfg
  movemouse-smooth-diagonals yes
)

dynamic-macro-max-presses

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

Example:

(defcfg
  dynamic-macro-max-presses 1000
)

concurrent-tap-hold

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.

Example:

(defcfg
  concurrent-tap-hold yes
)

block-unmapped-keys

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.

Note	this only functions correctly if you also set process-unmapped-keys to yes.

Example:

(defcfg
  block-unmapped-keys yes
)

rapid-event-delay

This configuration applies to the following events:

• the release of one-shot-press activation

• the release of the tapped key in a tap-hold activation

• a non-eager tap-dance activation from interruption by another key

• input chord activations, both v1 and v2

Key event processing is paused the defined number of milliseconds (approximate). The default value is 5.

There will be a minor input latency impact in the mentioned scenarios. Since 5ms is 1 frame at 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 key events. 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 reduce the value to a number between 0 and 4.

Example:

(defcfg
  ;; If your environment is particularly buggy, might need to delay even more
  rapid-event-delay 20
)

chords-v2-min-idle

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.

Example:

(defcfg
  chords-v2-min-idle 200
)

override-release-on-activation

This configuration item changes activation behaviour from defoverrides.

Take this example override:

(defoverrides (lsft a) (lsft 9))

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.

Example:

(defcfg
  override-release-on-activation yes
)

allow-hardware-repeat

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.

Example:

(defcfg
   allow-hardware-repeat false
)

alias-to-trigger-on-load

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.

Example:

(defcfg
  alias-to-trigger-on-load S
  danger-enable-cmd yes
)

(deffakekeys B (layer-while-held block))

(defalias
  P (on-press toggle-vkey B)
  S (macro @P (cmd beep))
)

(defsrc i o p )
(deflayer base o i @P )
(deflayer block • • _ )

Linux only: linux-dev

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.

Example:

(defcfg
  linux-dev /dev/input/by-path/platform-i8042-serio-0-event-kbd
)

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

Example:

(defcfg
  linux-dev /dev/input/dev1:/dev/input/dev2
)

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:

(defcfg
  linux-dev /dev/input/path-to\:device
)

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.

(defcfg
  linux-dev (
    /dev/input/path:to:device
    "/dev/input/path to device"
  )
)

Linux only: linux-dev-names-include

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:

registering /dev/input/eventX: "Name goes here"

Example:

(defcfg
  linux-dev-names-include (
    "Device name 1"
    "Device name 2"
  )
)

Linux only: linux-dev-names-exclude

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.

Example:

(defcfg
  linux-dev-names-exclude (
    "Device Name 1"
    "Device Name 2"
  )
)

Linux only: linux-continue-if-no-devs-found

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

Example:

(defcfg
  linux-continue-if-no-devs-found yes
)

Linux only: linux-device-detect-mode

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:

keyboard-only	Grab devices that seem to be a keyboard only.
keyboard-mice	Grab devices that seem to be a keyboard only and devices that declare both keyboard and mouse functionality.
any	Grab all keyboard-like and mouse-like devices.

The default behaviour is:

keyboard-mice	When no mouse events are in defsrc.
any	When any mouse buttons or mouse scroll events are in defsrc.

Linux only: linux-unicode-u-code

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.

Example:

(defcfg
  linux-unicode-u-code v
)

Linux only: linux-unicode-termination

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:

• enter

• space

• enter-space

• space-enter

Example:

(defcfg
  linux-unicode-termination space
)

Linux only: linux-x11-repeat-delay-rate

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.

Example:

(defcfg
  linux-x11-repeat-delay-rate 400,50
)

Linux only: linux-use-trackpoint-property

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.

Example:

(defcfg
  linux-use-trackpoint-property yes
)

Linux only: linux-output-device-bus-type

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.

Example:

(defcfg
   linux-output-device-bus-type USB
)

macOS only: macos-dev-names-include

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.

Example:

(defcfg
  macos-dev-names-include (
    "Device name 1"
    "Device name 2"
  )
)

Windows only: windows-altgr

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:

• cancel-lctl-press

  • This will remove the lctl press that is generated alonside ralt

• add-lctl-release

  • This adds an lctl release when ralt is released

Without these workarounds, you should use process-unmapped-keys (all-except lctl ralt)), or use process-unmapped-keys no and also omit both ralt and lctl from defsrc.

Example:

(defcfg
  windows-altgr add-lctl-release
)

For more context, see: #55.

Note	Even with these workarounds, putting lctl and ralt in your defsrc may not work properly with other applications that also use keyboard interception. Known application with issues: GWSL/VcXsrv

Windows only: windows-interception-mouse-hwid

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.

Example:

(defcfg
  windows-interception-mouse-hwid "70, 0, 60, 0"
)

Windows only: windows-interception-mouse-hwids

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.

Example:

(defcfg
  windows-interception-mouse-hwids (
    "70, 0, 60, 0"
    "71, 0, 62, 0"
  )
)

Windows only: windows-interception-keyboard-hwids

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.

Example:

(defcfg
  windows-interception-keyboard-hwids (
    "70, 0, 60, 0"
    "71, 72, 73, 74"
  )
)

Windows only: tray-icon

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:

• Default parent folders:

  • config file’s, executable’s

  • env vars: XDG_CONFIG_HOME, APPDATA (C:\Users\<Name>\AppData\Roaming), USERPROFILE /.config (C:\Users\<Name>\.config)

• Default config subfolders: kanata kanata-tray

• Default image subfolders (optional): icon img icons

• Supported image file formats: ico jpg jpeg png bmp dds tiff

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.

Example:

;; in a config file C:\Users\<U>\AppData\Roaming\kanata\kanata.kbd
(defcfg
  tray-icon base.png ;; will load C:\Users\<U>\AppData\Roaming\kanata\base.png
)

Windows only: icon-match-layer-name

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.

Windows only: tooltip-layer-changes

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

Windows only: tooltip-show-blank

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.

Windows only: tooltip-no-base

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

Windows only: tooltip-duration

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.

Windows only: tooltip-size

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.

Windows only: notify-cfg-reload

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

Windows only: notify-cfg-reload-silent

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

Windows only: notify-error

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

Using multiple defcfg options

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

(defcfg a 1 b 2)

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.

;; Don't actually use this exact configuration,
;; it's almost certainly not what you want.
(defcfg
  process-unmapped-keys yes
  danger-enable-cmd yes
  sequence-timeout 2000
  sequence-input-mode visible-backspaced
  sequence-backtrack-modcancel no
  log-layer-changes no
  delegate-to-first-layer yes
  movemouse-inherit-accel-state yes
  movemouse-smooth-diagonals yes
  dynamic-macro-max-presses 1000
  linux-dev (/dev/input/dev1 /dev/input/dev2)
  linux-dev-names-include ("Name 1" "Name 2")
  linux-dev-names-exclude ("Name 3" "Name 4")
  linux-continue-if-no-devs-found yes
  linux-unicode-u-code v
  linux-unicode-termination space
  linux-x11-repeat-delay-rate 400,50
  windows-altgr add-lctl-release
  windows-interception-mouse-hwid "70, 0, 60, 0"
)

Advanced features

Virtual keys

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:

• (on-press <action> <virtual key name>) or on↓: Activate a virtual key action when pressing the associated input key.

• (on-release <action> <virtual key name>) or on↑: Activate a virtual key action when releasing the associated input key.

• (on-idle <idle time> <action> <virtual key name>): Activate a virtual key action when kanata has been idle for at least idle time milliseconds.

• (hold-for-duration <hold time> <virtual key name>): Press a virtual key for hold time milliseconds. If hold-for-duration retriggered on a virtual key before release, the time will be reset with no additional press/release events.

The <action> parameter can be one of:

• tap-virtualkey | tap-vkey: Press and release the virtual key. If the key is already pressed, this only releases it.

• press-virtualkey | press-vkey: Press the virtual key. It will not be released until another action triggers a release or tap. If the key is already pressed, this does nothing.

• release-virtualkey | release-vkey: Release the virtual key. If it is not already pressed, this does nothing.

• toggle-virtualkey | toggle-vkey: Press the virtual key if it is not already pressed, otherwise release it.

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.

Example:

(defvirtualkeys
  ;; Define some virtual keys that perform modifier actions
  ctl lctl
  sft lsft
  met lmet
  alt lalt

  ;; A virtual key that toggles all modifier virtual keys above
  tal (multi
        (on-press toggle-virtualkey ctl)
        (on-press toggle-virtualkey sft)
        (on-press toggle-virtualkey met)
        (on-press toggle-virtualkey alt)
      )

  ;; Virtual key that activates a macro
  vkmacro (macro h e l l o spc w o r l d)
)

(defalias
  psf (on-press press-virtualkey   sft)
  rsf (on-press release-virtualkey sft)

  tal (on-press tap-vkey tal)
  mac (on-press tap-vkey vkmacro)

  isf (on-idle 1000 tap-vkey sft)
  hfd (hold-for-duration 1000 met)
)

(deflayer use-virtual-keys
  @psf @rsf @tal @mac a s d f @isf @hfd
)

Older fake keys documentation

The older configuration style of fake keys are still supported but the new style is preferred due to (hopefully) clearer naming.

Fake keys can be defined inside of deffakekeys.

The actions are:

• (on-press-fakekey <fake key name> <action>) or on↓fakekey: Activate a fake key action when pressing the key mapped to this action.

• (on-release-fakekey <fake key name> <action>) or on↑fakekey: Activate a fake key action when releasing the key mapped to this action.

• (on-idle-fakekey <fake key name> <action> <idle time>): Activate a fake key action when kanata has been idle for at least idle time milliseconds.

The aforementioned <key action> can be one of four values:

• press: Press the fake key. It will not be released until another action triggers a release or tap.

• release: Release the fake key. If it’s not already pressed, this does nothing.

• tap: Press and release the fake key. If it’s already pressed, this only releases it.

• toggle: Press the fake key if not already pressed, otherwise release it.

Example:

(deffakekeys
  ctl lctl
  sft lsft
  met lmet
  alt lalt

  ;; Press all modifiers
  pal (multi
        (on-press fakekey ctl press)
        (on-press-fakekey sft press)
        (on-press-fakekey met press)
        (on-press-fakekey alt press)
      )

  ;; Release all modifiers
  ral (multi
        (on-press-fakekey ctl release)
        (on-press-fakekey sft release)
        (on-press-fakekey met release)
        (on-press-fakekey alt release)
      )
)

(defalias
  psf (on-press-fakekey sft press)
  rsf (on-press-fakekey sft release)

  pal (on-press-fakekey pal tap)
  ral (on-press-fakekey ral tap)

  isf (on-idle-fakekey sft tap 1000)
)

(deflayer use-virtual-keys
  @psf @rsf @pal @ral a s d f @isf
)

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.

Sequences

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:

• A key is typed that does not match any sequence

• sequence-timeout milliseconds elapses since the most recent key press

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

Example:

(defseq git-status (g s t))
(defvirtualkeys git-status (macro g i t spc s t a t u s))
(defalias rcl (tap-hold-release 200 200 sldr rctl))

(defseq
    dotcom (. S-3)
    dotorg (. S-4)

    ;;     The shifted letters in parentheses means a single press of lsft
    ;;     must remain held while both h and then s are pressed.
    ;;     This is not the same as S-h S-s, which means that the lsft key
    ;;     must be released and repressed between the h and s presses.
    https (S-(h s))
)
(defvirtualkeys
    dotcom (macro . c o m)
    dotorg (macro . o r g)
    https (macro h t t p s S-; / /)
)

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.

Example:

(defsrc f7   f8   f9   f10)
(deflayer base
        sldr nop0 nop1 nop2)
(deftemplate seq (vk-name input-keys output-action)
        sldr(defvirtualkeys $vk-name $output-action)
        sldr(defseq $vk-name $input-keys)
)
;; template-expand has a shortened form: t!
(t! seq dotcom (nop0 nop1) (macro . c o m))
(t! seq dotorg (nop0 nop2) (macro . o r g))

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.

Example:

(defalias
  nop0 nop0
  ;; ...
  nop5 nop5
  nop6 (macro nop6 nop0)
  ;; ...
  nop11 (macro nop6 nop5)
  ;; ...
  nop18 (macro nop9 nop0)
  ;; ...
  nop23 (macro nop9 nop5)
)

Overlapping keys in any order

Within the key list of defseq configuration items, the special O- list prefix can be used to denote a set of keys that must all be pressed before any are released in order to match the sequence.

For an example, O-(a b c) is equivalent to O-(c b a).

Example:

(defvirtualkey hello (macro h (unshift e l) 5 (unshift l o)))
(defseq hello (O-(h l o)))

Warning

The way that sequences implements this functionality behind the scenes is by generating a sequence for every permutation of the overlapping keys. This can make kanata use up a lot of memory. Due to this, the maximum keys allowed in a given O-(…​) list is 6, but you are still permitted to add more to the sequence, including more O-(…​) lists. Doing the above can balloon kanata’s memory consumption.

Sample of more advanced usage

The configuration below showcases context-dependent chording with auto-space and auto-deleted spaces from typing punctuation.

For example, chording (d a y) and then (t u e) will output Tuesday, while chording (t u e) by itself does nothing.

Example configuration:

(defsrc f1)
(deflayer base lrld)
(defcfg process-unmapped-keys yes
	sequence-input-mode visible-backspaced
	concurrent-tap-hold true)
(deftemplate seq (vk-name in out)
	(defvirtualkeys $vk-name $out)
	(defseq $vk-name $in))

(defvirtualkeys rls-sft (multi (release-key lsft)(release-key rsft)))
(defvar rls-sft (on-press tap-vkey rls-sft))
(deftemplate rls-sft () $rls-sft 5)

(defchordsv2
	(d a y) (macro sldr d (t! rls-sft) a y spc nop0) 200 first-release ()
	(h l o) (macro h (t! rls-sft) e l l o sldr spc nop0) 200 first-release ()
)
(t! seq Monday (d a y spc nop0 O-(m o n)) (macro S-m $rls-sft o n d a y nop9 sldr spc nop0))
(t! seq Tuesday (d a y spc nop0 O-(t u e)) (macro S-t $rls-sft u e s d a y nop9 sldr spc nop0))
(t! seq DelSpace_. (spc nop0 .) (macro .))
(t! seq DelSpace_; (spc nop0 ;) (macro ;))

Try using the above configuration to type the text:

day;
Day;
Tuesday.
day hello
hello day
Hello day.
hello Tuesday
Hello Monday;

Override the global timeout and input mode

An alternative to using sldr is the sequence action. The syntax is (sequence <timeout>). This enters sequence mode with a sequence timeout different from the globally configured one.

The sequence action can also be called with a second parameter. The second parameter is an override for sequence-input-mode:

(sequence <timeout> <input-mode>)

Example:

;; Enter sequence mode and input . with a timeout of 250
(defalias dot-sequence (macro (sequence 250) 10 .))

;; Enter sequence mode and input . with a timeout of 250 and using hidden-delay-type
(defalias dot-sequence (macro (sequence 250 hidden-delay-type) 10 .))

More about sequences

For more context about sequences, you can read the design and motivation of sequences. You may also be interested in the document describing chords in sequences to read about how chords in sequences behave.

Input chords

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.

(defsrc a b c)
(deflayer default
  @cha @chb @chc
)

(defalias
  cha (chord example a)
  chb (chord example b)
  chc (chord example c)
)

(defchords example 500
  (a      ) a
  (   b   ) b
  (a     c) C-v
  (a  b  c) @three
)

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.

defaliasenvcond

Note	this configuration item is older and instead you may want to use the newer and more generalized Environment-conditional configuration configuration.

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.

Example:

(defaliasenvcond (LAPTOP lp1)
  met @lp1met
)

(defaliasenvcond (LAPTOP lp2)
  met @lp2met
)

Set environment variables in the current terminal process:

# powershell
$env:VAR_NAME = "var_value"

# bash
VAR_NAME=var_value

Templates

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:

• Template name

• List of template variables

• Template content (any combination of lists / strings)

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:

• template name

• parameters to substitute into the template

Note

Template expansion happens after file includes and before any other parsing. One consequence of this early parsing is that variables defined in defvar are not substituted when used inside of template-expand. This has consequences for condtional content, e.g. with if-equal. This is discussed further in Example 5.

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:

(deftemplate alt-fork (original-action new-action)
  (fork $original-action (multi (unmod (ralt lalt) nop0) $new-action) (lalt ralt))
)
(defsrc 1 2 3)
(defalias fn1 (template-expand alt-fork 1 f1))
;; Templates are a simple text substitution, so the above is exactly equivalent to:
;; (defalias fn1 (fork 1 (multi (unmod (ralt lalt) nop0) f1) (lalt ralt)))
(defalias fn2 (template-expand alt-fork 2 f2))
;; You can use t! as a short form of template-expand
(defalias fn3 (t! alt-fork 3 f3))
(deflayer default @fn1 @fn2 @fn3)

Example 2:

(defvar chord-timeout 200)
(defcfg process-unmapped-keys yes)

;; This template defines a chord group and aliases that use the chord group.
;; The purpose is to easily define the same chord position behaviour
;; for multiple layers that have different underlying keys.
(deftemplate left-hand-chords (chordgroupname k1 k2 k3 k4 alias1 alias2 alias3 alias4)
  (defalias
    $alias1 (chord $chordgroupname $k1)
    $alias2 (chord $chordgroupname $k2)
    $alias3 (chord $chordgroupname $k3)
    $alias4 (chord $chordgroupname $k4)
  )
  (defchords $chordgroupname $chord-timeout
    ($k1) $k1
    ($k2) $k2
    ($k3) $k3
    ($k4) $k4
    ($k1 $k2) lctl
    ($k3 $k4) lsft
  )
)

(template-expand left-hand-chords qwerty a s d f qwa qws qwd qwf)
;; t! is short for template-expand
(t! left-hand-chords dvorak a o e u dva dvo dve dvu)

(defsrc a s d f)
(deflayer dvorak @dva @dvo @dve @dvu)
(deflayer qwerty @qwa @qws @qwd @qwf)

Example 3:

;; This template defines a home row that customizes a single key's behaviour
(deftemplate home-row (j-behaviour)
  a s d f g h $j-behaviour k l ; '
)

(defsrc
  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
       ;; usable even inside defsrc
  caps (t! home-row j)                            ret
  lsft z    x    c    v    b    n    m    ,    .    /    rsft
  lctl lmet lalt           spc            ralt rmet rctl
)

(deflayer base
  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
                                 ;; lists can be passed in too!
  caps (t! home-row (tap-hold 200 200 j lctl))    ret
  lsft z    x    c    v    b    n    m    ,    .    /    rsft
  lctl lmet lalt           spc            ralt rmet rctl
)

if-equal

Within a template you can use the list item if-equal to have condiditionally-used items within a template.

It accepts a minimum of 2 parameters. The first two parameters must be strings and are compared against each other. If they match, the following parameters are inserted into the template in place of the if-equal list. Otherwise if the strings do not match then the whole if-equal list is removed from the template.

Example 4:

(deftemplate home-row (version)
  a s d f g h
  (if-equal $version v1 j)
  (if-equal $version v2 (tap-hold 200 200 j lctl))
   k l ; '
)

(defsrc
  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
  caps (template-expand home-row v1)                            ret
  lsft z    x    c    v    b    n    m    ,    .    /    rsft
  lctl lmet lalt           spc            ralt rmet rctl
)

(deflayer base
  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
  caps (template-expand home-row v2)                            ret
  lsft z    x    c    v    b    n    m    ,    .    /    rsft
  lctl lmet lalt           spc            ralt rmet rctl
)

Similar to if-equal are three more conditional operators for templates:

• if-not-equal

  • the content is used if the first two string parameters are not equal

• if-in-list

  • the content is used if the first string parameter exists in the second list-of-strings parameter

• if-not-in-list

  • the content is used if the first string parameter does not exist in the second list-of-strings parameter

Example 5:

;; defvar is parsed AFTER template expansion occurs.
(defvar a hello)

(deftemplate template1 (var1)
  a (if-equal hello $var1 b) c
)

;; Below will expand to: `a c` because the string
;; $a itself is compared against the string hello
;; and they are not equal.
(template-expand template1 $a)

(deftemplate template2 (var1)
  a (if-equal $a $var1 b) c
)

;; Below will expand to: `a b c` because the string
;; $a is compared against the string $a and they are equal.
;; But note that the variable $a is still not substituted
;; with its defvar value of: hello.
(template-expand template2 $a)

concat in deftemplate

Like concat in defvar, a list beginning with concat within the content of deftemplate will be replaced with a single string that consists of all the subsequent items in the list concatenated to each other.

Custom tap-hold behaviour

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.

Fancy key symbols

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

• hold ⎇› and tap Delete would insert ␡

Windows only: enable in elevated windows

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:

cargo build --win_manifest

Windows only: win-tray

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.

Test your config

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.

Warning

The format of this view may change. Emoji output may break vertical alignment.

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

Zippychord

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.

Configuration syntax within the kanata configuration

(defzippy-experimental
  $zippy-filename ;; required
  on-first-press-chord-deadline $deadline-millis  ;; optional
  idle-reactivate-time          $idle-time-millis ;; optional
  smart-space                   $smart-space-cfg  ;; optional
  smart-space-punctuation (                       ;; optional
    $punc1 $punc2 ... $puncN)
  output-character-mappings (    ;; optional
    $character1 $output-mapping1
    $character2 $output-mapping2
    ;; ...
    $characterN $output-mappingN
  )
)

$zippy-filename	Relative or absolute file path. If relative, its path is relative to the directory containing the kanata configuration file. This must be the first item following defzippy-experimental.
$deadline-millis	Number of milliseconds. After the first press while zippy is enabled, if no chord activates within this configured time, zippy is temporarily disabled.
$idle-time-millis	Number of milliseconds. After typing ends and this configured number of milliseconds elapses, zippy will be re-enabled from being temporarily disabled.
$smart-space-cfg	Determines the smart space behaviour. The options are none, add-space-only, and full. With none, outputs are typed as-is. With add-space-only, spaces are automatically added after outputs which end with neither a space or a backspace ⌫. With full, the add-space-only behaviour applies alongside additional behaviour: typing punctuation (default characters: , . ;) after a zippy activation will delete a prior automatically-added space.
$punc	A character defined in output-character-mappings or a known key name, which shall be considered as punctuation. The smart-space-punctuation configuration will overwrite the default punctuation list considered by smart-space; if you want to include the default characters, you must include them in this configuration.
$character	A single unicode codepoint for use in the output column of the zippy configuration file.
$output-mapping	Key or output chord to tell kanata how to type $character when seen in the zippy file output column. Must be a single key or output chord. The output chord may contain AG- to tell kanata to press with AltGr and may contain S- to tell kanata to press with Shift. The list items no-erase and single-output are also usable in this position.
no-erase	Accepts a single key or output chord as a parameter. The zippy system will not backspace this character in case of auto-erasure by a superset chord or followup chord. Use for dead keys or compose keys.
single-output	Accepts one or more keys or output chords as a parameter. The zippy system send only one backspace in case of auto-erasure by a superset chord or followup chord. Use for a dead key or compose key sequence with one output symbol.

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

    ")"    $right-paren-output
    "("    $left-paren-output
    r#"""# $double-quote-output

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

    ")"     S-0
    "("     S-9
    r#"""#  S-'

Configuration syntax within the zippy configuration file

// This is a comment.
//          inputs            ↹  outputs
$chord1 $follow-chord1.1...1.M	$output1
$chord2 $follow-chord2.1...2.M	$output2
// ...
$chordN $follow-chordN.1...N.M	$outputN

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

$chord	A set of characters. You can use space by including it as the first character in the chord; for an example see Alphabet in the sample below. With 0 optional follow chords, the corresponding output on the same line ($output) will activate when zippy is enabled and all the defined chord keys are pressed simultaneously. The order of presses is not important.
$chord-follow	0 or more chords, used the same way as $chord. Having follow chords means the $output on the same line will activate upon first activating the earlier chord(s) in the same line, releasing all keys, and pressing the keys in $chord-followN.M. Follow chords are separated from the previous chord by a space. If using a space in the follow chord, use two spaces; for an example see Washington in the sample below.
$output	The characters to type when the chord and optional follow chord(s) are all pressed by the user. This is separated from the input chord column by a single Tab character. The characters are typed in sequence and must all be singular-name key names as one would configure in defsrc. A capitalized single-character key name will be parsed successfully and these will be outputted alongside Shift to output the capitalized key. Additionally, output-character-mappings configuration can be used to inform kanata of additional mappings that may use Shift or AltGr.

Examples

Sample kanata configuration

(defzippy-experimental
  zippy.txt
  on-first-press-chord-deadline 500
  idle-reactivate-time          500
  smart-space-punctuation (? ! . , ; :)
  output-character-mappings (
    ;; This should work for US international.
    ! S-1
    ? S-/
    % S-5
    "(" S-9
    ")" S-0
    : S-;
    < S-,
    > S-.
    r#"""# S-'
    | S-\
    _ S--
    ® AG-r
    ’ (no-erase `)
    é (single-output ' e)
  )
)

Sample zippy file content

dy	day
dy 1	Monday
dy 2	Tuesday
 abc	alphabet
 w  a	Washington
gi	git
gi f p	git fetch -p

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:

gi	git

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

(press g) (press i)
(press i) (press g)

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

(press g) (release g) (press i)

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

gi	git␣
gi s	git␣status
gi c	git checkout␣
gi c b	git checkout -b␣
gi c a	git commit --amend␣
gi c n	git commit --amend --no-edit
gi c a m	git commit --amend -m 'FIX_THIS_COMMIT_MESSAGE'

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.