kanata — Advanced Cross-Platform Keyboard Remapping

Introduction

kanata is a cross-platform software keyboard remapper written in Rust. It intercepts keyboard input at the OS level and transforms it according to rules defined in a text configuration file, enabling features like layers, tap-hold dual-function keys, and mouse emulation — all without flashing firmware.

What kanata Does

• Remaps any key to any other key, modifier, or action across all applications
• Supports tap-hold keys that send one keycode on tap and another when held
• Implements multiple keyboard layers switchable via dedicated keys
• Emulates mouse movement and clicks from the keyboard
• Runs as a background process with hot-reloadable configuration

Architecture Overview

kanata is a single Rust binary that hooks into the OS input system: on Linux it reads from /dev/input and writes to a virtual uinput device, on Windows it uses the Interception driver or a low-level keyboard hook, and on macOS it uses the IOKit HID framework. Input events pass through a state machine that evaluates the current layer, pending tap-hold timers, and macro sequences before emitting transformed events.

Self-Hosting & Configuration

• Install via cargo or download prebuilt binaries for Linux, macOS, and Windows
• Configuration uses a Lisp-inspired .kbd text format for defining layers and key behaviors
• On Windows, the Interception driver provides the most reliable input interception
• Hot-reload support: edit the config file and kanata picks up changes without restarting
• Run at startup via systemd (Linux), launchd (macOS), or Task Scheduler (Windows)

Key Features

• True cross-platform support with native input interception on each OS
• Tap-hold, tap-dance, one-shot, and combo key behaviors
• Unlimited layers with transparent and blocked key pass-through
• Built-in mouse emulation for keyboard-driven cursor movement
• Live config reload without dropping any keystrokes

Comparison with Similar Tools

• QMK/ZMK — firmware-level remapping for specific keyboards; kanata works with any keyboard
• kmonad — similar concept in Haskell; kanata offers broader OS support and active development
• AutoHotkey — Windows-only scripting tool; kanata is cross-platform and purpose-built for remapping
• Karabiner-Elements — macOS-only; kanata works on Linux, macOS, and Windows
• xremap — Linux-only; kanata adds Windows and macOS support

FAQ

Q: Does kanata work with any keyboard? A: Yes. It intercepts input at the OS level, so it works with any USB, Bluetooth, or built-in keyboard.

Q: Will it conflict with my keyboard's firmware remapping? A: No. kanata operates on top of whatever the keyboard sends, so firmware and software remapping stack.

Q: Can I use different configs for different keyboards? A: On Linux, you can target specific devices by path. On Windows with the Interception driver, device-specific targeting is also supported.

Q: Is there a GUI? A: kanata is configured via text files. Community-built GUI wrappers exist but the official tool is CLI-based.

Sources

• https://github.com/jtroo/kanata
• https://github.com/jtroo/kanata/blob/main/docs/config.adoc