arsenik/kanata/README.md

kanata

Pick Your Poison!

type	without homerow-mods	with homerow-mods	suitable layouts
ANSI	arsenik_easy_ansi.kbd	arsenik_hrm_ansi.kbd	QWERTY, Dvorak, Colemak, Workman…
AltGr	arsenik_easy_altgr.kbd	arsenik_hrm_altgr.kbd	Lafayette42, Ergo-L…

• “Easy” variants don’t use any homerow-mods and leave the left thumb key modifier unchanged — but they still use a Prog layer and put the Backspace and Return keys under the thumbs. A good starting point if you’re new to dual keys.
• ANSI variants assume all symbols in your keyboard layout are in their QWERTY-ANSI positions: works fine with most US layouts but Dvorak users will get a slightly different Prog layer.
• AltGr variants use your layout’s AltGr layer instead of the Prog layer: perfect for layouts that already have an optimized AltGr layer, such as QWERTY-Lafayette and Ergo-L.

Note that kanata can also use the laptop’s trackpoint buttons (e.g. ThinkPad) as two additional thumb keys. :-)

Installation

You can install kanata by either downloading a pre-built executable, or by running the following commands (if you have rustc installed):

rustup update stable
cargo install kanata

Linux users may want to run these extra steps:

Running kanata without sudo

kanata needs to intercept uinput signals, which it cannot do without the proper authorisations.

If you don’t want to run kanata with sudo, you’ll need to allow kanata to read from uinput. This requires the users to be part of both input and uinput groups. Update README.md For that, you first need to create a uinput group if it is not the case yet:

sudo groupadd -U $USERNAME uinput

Where $USERNAME is the target user (or users in a comma separated list), and add the target user (or users) to the group input:

sudo usermod -aG input $USERNAME

You can then check after relogin that both groups appear in the result of the groups command launched as the target user.

Finally, you need to add a udev rule in /etc/udev/rules.d/50-kanata.rules:

KERNEL=="uinput", MODE="0660", GROUP="uinput", OPTIONS+="static_node=uinput"

Making a user-side systemd service for kanata

Note: This only works if kanata is able to run without

sudo

(and are using systemd).

Using a systemd service allows running kanata as a daemon, possibly right after logging in. Here is a template for a service file:

[Unit]
Description=Kanata keyboard remapper
Documentation=https://github.com/jtroo/kanata

[Service]
Environment=PATH=/usr/local/bin:/usr/local/sbin:/usr/bin:/bin
Environment=DISPLAY=:0
Environment=HOME=/path/to/home/folder
Type=simple
ExecStart=/usr/local/bin/kanata --cfg /path/to/kanata/config/file
Restart=no

[Install]
WantedBy=default.target

Copy-paste it into ~/.config/systemd/user/kanata.service, fill in the placeholders, then run one of the following commands:

• systemctl --user start kanata.service to manually start kanata
• systemctl --user enable kanata.service so kanata may autostart whenever the current user logs in
• systemctl --user status kanata.service to check if kanata is running