kanata

Improve keyboard comfort and usability with advanced customization.

What does this do?

This is a software keyboard remapper for Linux and Windows. A short summary of the features:

Here's a demo video showcasing multi-layer functionality. The demo video has a lot going on in a short period of time. To help understand what's going on, here's a description of what's happening:

To see all of the features, see the features section.

The most similar project is kmonad, which served as the inspiration for kanata. Here's a comparison document.

Usage

This is tested on Windows 10 and Debian 10. See the releases page for executables.

Using cargo install:

# Note: on Linux you may need to install libevdev manually; see below.
cargo install kanata
kanata --cfg <conf_file> # may not have permissions on Linux, see below

Build and run yourself in Linux:

# evdev-sys is dependency that uses a C library: libevdev. evdev-sys can
# find and use your system's libevdev; otherwise you need to have the
# dependencies required to build libevdev from scratch.
#
# Here is an example Debian for how to install your system's libevdev:
sudo apt install libevdev-dev pkg-config

cargo build   # release optional, not really perf sensitive

# sudo is used because kanata opens /dev/ files
#
# See below if you want to avoid needing sudo:
# https://github.com/kmonad/kmonad/blob/master/doc/faq.md#linux
sudo target/debug/kanata --cfg <conf_file>

Build and run yourself in Windows:

cargo build   # release optional, not really perf sensitive
target\debug\kanata --cfg <conf_file>

Sample configuration files are found in cfg_samples. The simple.kbd file contains a basic configuration file that is hopefully easy to understand but does not contain all features. The kanata.kbd contains an example of all features with documentation. The latest release assets also has a kanata.kbd file that is tested to work with that release. All key names can be found in the keys module.

Other installation methods

Arch user repository (AUR)

You can install it from AUR:

git clone https://aur.archlinux.org/kanata-bin.git
cd kanata-bin
makepkg -si

Or simply use your preferred AUR helper (e.g. paru):

paru -S kanata-bin

Features

Contributing

Contributions are welcome!

Unless explicitly stated otherwise, your contributions will be made under the LGPL-3.0-only[*] license.

The keyberon project contains all of the heavy keyboard state logic, so if you want new keyboard mapping functionality, it's recommended to add it to keyberon first.

Here's a basic low-effort design doc of kanata

How you can help

What does the name mean?

I wanted a "k" word since this relates to keyboards. According to Wikipedia, kanata is an indigenous Iroquoian word meaning "village" or "settlement" and is the origin of Canada's name.

There's also PPT✧.

Motivation

I have a few keyboards that run QMK. QMK allows the user to customize the functionality of their keyboard to their heart's content.

One great use case of QMK is its ability map keys so that they overlap with the home row keys but are accessible on another layer. I won't comment on productivity, but I find this greatly helps with my keyboard comfort.

For example, these keys are on the right side of the keyboard:

7 8 9
u i o
j k l
m , .

On one layer I have arrow keys in the same position, and on another layer I have a numpad.

arrows:       numpad:
- - -         7 8 9
- ↑ -         4 5 6
← ↓ →         1 2 3
- - -         0 * .

One could add as many customizations as one likes to improve comfort, speed, etc. Personally my main motivator is comfort due to a repetitive strain injury in the past.

However, QMK doesn't run everywhere. In fact, it doesn't run on most hardware you can get. You can't get it to run on a laptop keyboard or any mainstream office keyboard out there. I believe that the comfort and empowerment QMK provides should be available to anyone with a computer on their existing hardware, instead of having to purchase an enthusiast mechanical keyboard. (which are admittedly very nice — I own a few — but can be costly)

The best alternative solution that I've found for keyboards that don't run QMK is kmonad. This is an excellent project and I recommend it if you want to try something similar.

The reason for this project's existence is that kmonad is written in Haskell and I have no idea how to begin contributing to a Haskell project. From an outsider's perspective I think Haskell is a great language but I really can't wrap my head around it. And there are a few outstanding issues at the time of writing that make kmonad suboptimal for my personal workflows.

This project is written in Rust because Rust is my favourite programming language and the awesome keyberon crate exists.

I've tried compiling kmonad myself and it was quite the slog, though I was able to get it working eventually. Comparing the process to cargo build though, it was a huge contrast. My hope is that using Rust will lower the barrier to entry for contributions to a project like this.

Similar Projects