Kanata
Improve keyboard comfort and usability with advanced customization
Install / Use
/learn @jtroo/KanataREADME
What does this do?
This is a cross-platform software keyboard remapper for Linux, macOS and Windows. A short summary of the features:
- multiple layers of key functionality
- advanced key behaviour customization (e.g. tap-hold, macros, unicode)
To see all of the features, see the configuration guide.
You can find pre-built binaries in the releases page or read on for build instructions.
You can see a list of known issues here.
Demo
Demo video
Showcase of multi-layer functionality (30s, 1.7 MB).
Online simulator
You can check out the online simulator to test configuration validity and test input simulation.
Why is this useful?
Imagine if, instead of pressing Shift to type uppercase letters, we had giant keyboards with separate keys for lowercase and uppercase letters. I hope we can all agree: that would be a terrible user experience!
A way to think of how Shift keys work is that they switch your input to another layer of functionality where you now type uppercase letters and symbols instead of lowercase letters and numbers.
What kanata allows you to do is take this alternate layer concept that Shift keys have and apply it to any key. You can then customize what those layers do to suit your exact needs and workflows.
Usage
Running kanata currently does not start it in a background process. You will need to keep the window that starts kanata running to keep kanata active. Some tips for running kanata in the background:
- Windows: https://github.com/jtroo/kanata/discussions/193
- Linux: https://github.com/jtroo/kanata/discussions/130#discussioncomment-10227272
- Run from tray icon: kanata-tray
Pre-built executables
See the releases page for executables and instructions.
Build it yourself
This project uses the latest Rust stable toolchain. If you installed the
Rust toolchain using rustup, e.g. by using the instructions from the
official website,
you can get the latest stable toolchain with rustup update stable.
Using cargo install:
cargo install kanata
# On Linux and macOS, this may not work without `sudo`, see below
kanata --cfg <your_configuration_file>
Build and run yourself in Linux:
git clone https://github.com/jtroo/kanata && cd kanata
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/jtroo/kanata/wiki/Avoid-using-sudo-on-Linux
sudo target/debug/kanata --cfg <your_configuration_file>
Build and run yourself in Windows.
git clone https://github.com/jtroo/kanata; cd kanata
cargo build # --release optional, not really perf sensitive
target\debug\kanata --cfg <your_configuration_file>
Build and run yourself in macOS:
First install the Karabiner driver by following the macOS documentation in the releases page.
Then you can compile and run with the instructions below:
git clone https://github.com/jtroo/kanata && cd kanata
cargo build # --release optional, not really perf sensitive
# sudo is needed to gain permission to intercept the keyboard
sudo target/debug/kanata --cfg <your_configuration_file>
The full configuration guide is found here.
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
release assets also have a kanata.kbd file that is tested to work with that
release. All key names can be found in the keys module,
and you can also define your own key names.
Feature flags
When either building yourself or using cargo install,
you can add feature flags that
enable functionality that is turned off by default.
If you want to enable the cmd actions,
add the flag --features cmd.
For example:
cargo build --release --features cmd
cargo install --features cmd
On Windows,
if you want to compile a binary that uses the Interception driver,
you should add the flag --features interception_driver.
For example:
cargo build --release --features interception_driver
cargo install --features interception_driver
To combine multiple flags,
use a single --features flag
and use a comma to separate the features.
For example:
cargo build --release --features cmd,interception_driver
cargo install --features cmd,interception_driver
Other installation methods
<details> <summary>Repositories for kanata</summary>
Notable features
- Human-readable configuration file.
- Live reloading of the configuration for easy testing of your changes.
- Multiple layers of key functionality
- Advanced actions such as tap-hold, unicode output, dynamic and static macros
- Vim-like leader sequences to execute other actions
- Optionally run a TCP server to interact with other programs
- Other programs can respond to layer changes or trigger layer changes
- Interception driver support (use
kanata_wintercept.exe)- Note that this issue exists, which is outside the control of this project: https://github.com/oblitum/Interception/issues/25
Contributing
Contributions are welcome!
Unless explicitly stated otherwise, your contributions to kanata will be made under the LGPL-3.0-only* license.
Some directories are exceptions:
- keyberon: MIT License
- interception: MIT or Apache-2.0 Licenses
Here's a basic low-effort design doc of kanata
How you can help
- Try it out and let me know what you think. Feel free to file an issue or start a discussion.
- Usability issues and unhelpful error messages are considered bugs that should be fixed. If you encounter any, I would be thankful if you file an issue.
- Browse the open issues and help out if you are able and/or would like to. If you want to try contributing, feel free to ping jtroo for some pointers.
- If you know anything about writing a keyboard driver for Windows, starting an open-source alternative to the Interception driver would be lovely.
Community projects related to kanata
- vscode-kanata: Language support for kanata configuration files in VS Code
- komokana: Automatic application-aware layer switching for
komorebi(Windows) - kanata-tray: Control kanata from a tray icon
- OverKeys: Visual layer display for kanata - see your active layers and keymaps in real-time (Windows)
- Application-aware layer switching:
- qanata (Linux)
- kanawin (Windows)
- window_tools (Windows)
- nata (Linux)
- kanata-vk-agent (macOS)
- hyprkan (Linux)
- kanata-switcher (Linux, all DEs)
- kwanata (Linux-KDE): A KDE Plasma companion for Kanata - Automatically activates Kanata's layers/virtualkeys and launches or raises apps.
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
TLDR: QMK features but for any keyboard, not just fancy mechanical ones.
<details> <summary>Long version</summary>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 comfo
