Skip to main content
Kanata is a software keyboard remapper that allows you to customize your keyboard layout at a low level. This dotfiles configuration uses Kanata to implement advanced key remapping with tap-hold functionality.

​
Configuration

The Kanata configuration is located at .config/kanata/config.kbd. It uses a Lisp-like syntax to define key mappings and behaviors.

​
Tap-hold configuration

The configuration implements tap-hold functionality where a single key performs different actions based on whether it’s tapped or held:
.config/kanata/config.kbd
(defsrc
  caps
)

(defalias
  escctrl (tap-hold 100 100 esc lctrl)
  bspcctrl (tap-hold 100 100 bspc lctrl)
)

(deflayer base
  @bspcctrl
)
The tap-hold syntax is (tap-hold tap-timeout hold-timeout tap-action hold-action). Both timeouts are set to 100ms in this configuration.

​
Key mappings

The configuration remaps the Caps Lock key to:
  • Tap: Backspace
  • Hold: Left Control
This provides ergonomic access to both frequently-used keys without moving your hands from the home row.
The configuration also defines an alternative escctrl alias that maps to Escape on tap and Control on hold. You can swap this in the deflayer section if you prefer Escape over Backspace.

​
Systemd service setup

Kanata runs as a systemd user service to start automatically and handle keyboard input at the system level.

​
Service configuration

The service file is located at .config/systemd/user/kanata.service:
.config/systemd/user/kanata.service
[Unit]
Description=Kanata keyboard remapper
Documentation=https://github.com/jtroo/kanata

[Service]
Environment=PATH=/usr/local/bin:/usr/local/sbin:/usr/bin:/bin
Type=simple
ExecStart=/usr/bin/sh -c 'exec $$(which kanata) --cfg $${HOME}/.config/kanata/config.kbd'
Restart=no

[Install]
WantedBy=default.target

​
Enable and start the service

After installing the dotfiles with Stow, enable and start the Kanata service:
1

Reload systemd user daemon

systemctl --user daemon-reload
2

Enable the service

systemctl --user enable kanata.service
3

Start the service

systemctl --user start kanata.service
4

Verify the service is running

systemctl --user status kanata.service
Kanata requires permissions to read keyboard input. You may need to add your user to the input group or configure udev rules. See the Kanata documentation for platform-specific setup instructions.

​
Performance tuning

The service file includes commented-out options for increasing process priority if you encounter input lag on resource-constrained systems: 
# CPUSchedulingPolicy=rr
# CPUSchedulingPriority=99
# IOSchedulingClass=realtime
# Nice=-20
Enabling these options requires running the service as root or with elevated privileges. Only enable them if you experience noticeable input lag.

​
Troubleshooting

Check the service logs:
journalctl --user -u kanata.service -f
Common issues:
  • Kanata binary not in PATH
  • Config file syntax errors
  • Insufficient permissions to access input devices
  1. Verify the service is running: systemctl --user status kanata.service
  2. Check for config file syntax errors in the logs
  3. Ensure no other keyboard remappers are running (xcape, xmodmap, etc.)
  • Try adjusting the tap-hold timeout values in the config
  • Consider enabling the performance tuning options
  • Check system resource usage

Systemd services

Learn more about managing systemd user services

Kanata GitHub

Official Kanata documentation and examples

Build docs developers (and LLMs) love

Get started for freeTalk to us