# kanata — Advanced Cross-Platform Keyboard Remapping

> Software keyboard remapper for Linux, macOS, and Windows that supports layers, tap-hold, macros, and mouse emulation — all configured via a text file.

## Install

Save as a script file and run:

# kanata — Advanced Cross-Platform Keyboard Remapping

## Quick Use
```bash
# Install via cargo
cargo install kanata
# Or download a prebuilt binary from GitHub releases
# Create a config file and run:
kanata --cfg my-config.kbd
```

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

---
Source: https://tokrepo.com/en/workflows/asset-130abbdf
Author: Script Depot