xbxd/kanata-config
Kanata Config
My Kanata config for making laptop keyboards work the way I want. It adds tap-and-hold home-row mods, handy key layers and a few shortcuts inspired by my split keyboard.
Project details
Primary language: Shell
Last commit:
Language mix
- Shell 100%
Weekly commits
Commit counts by UTC week start for the last 52 weeks.
21 commits total; busiest week: 2026-03-15 (15 commits).
README
kanata configuration
used for re-mapping internal laptop keyboards.
keybindings
homerow mods (tap/hold)
| key | tap | hold |
|---|---|---|
a |
a | cmd |
s |
s | alt |
d |
d | shift |
f |
f | ctrl |
j |
j | ctrl |
k |
k | shift |
l |
l | alt |
; |
; | cmd |
caps |
esc | hyper |
lmet |
bspc | cmd |
positional disambiguation (timeless homerow mods). the eight letter HRMs (a/s/d/f/j/k/l/;) use tap-hold-release-keys so:
- opposite-hand press+release commits the mod-tap to hold instantly —
Ctrl+B(tmux),Cmd+C,Cmd+Vfire without racing the timer. - same-hand press forces tap — fast rolls like
asdf,kalil,salescome out as letters. - same-hand deliberate mod still works via the timer: hold A past
$hold-timeout(200ms), then press S →Cmd+S.
hand groupings live in (defvar left-hand-keys ...) / right-hand-keys and cover every alpha column in defsrc except the eight HRM positions themselves (a/s/d/f, j/k/l/;) — those are excluded so same-hand mod chords like Alt+Shift+T still work. see docs/timeless-hrm.md for the polarity gotcha and the chord-vs-roll trade-off.
caps (esc/hyper) and lmet (bspc/cmd) remain plain timing-based tap-hold — not homerow letters, no roll concern.
tap-timeout: 300ms, hold-timeout: 200ms.
bottom-row tap-dance macros (tap/hold)
mirrors QMK tap-dance + macro setup on z/x/c/v/b. hold fires once via (macro ...) so the OS doesn't auto-repeat the command on long hold.
| key | tap | hold |
|---|---|---|
z |
z | Cmd+Z (undo) |
x |
x | Cmd+X (cut) |
c |
c | Cmd+C (copy) |
v |
v | Cmd+V (paste) |
b |
b | Cmd+A (select all) |
timeout matches homerow mods (300ms tap, 200ms hold).
persist media function keys
| key | action |
|---|---|
f1 |
brightness down |
f2 |
brightness up |
f7 |
previous track |
f8 |
play/pause |
f9 |
next track |
f10 |
mute |
f11 |
volume down |
f12 |
volume up |
chords
| chord | output |
|---|---|
w + e |
- |
x + c |
_ |
q + w |
` |
tab + q |
~ |
space-hold layer (arrows)
hold space to activate the arrows layer. synced from QMK Layer 1 (Iris split keyboard).
number row — screenshot shortcuts:
| key | output |
|---|---|
| 2 | Cmd+Shift+2 |
| 3 | Cmd+Shift+3 |
mirrors SGUI(KC_2) / SGUI(KC_3) from QMK Layer 1 (macOS screenshot-style shortcuts).
qwerty row — shifted symbols:
| key | output |
|---|---|
| tab | ~ |
| q | ! |
| w | @ |
| e | # |
| r | $ |
| t | % |
| y | ^ |
| u | & |
| i | * |
| o | ( |
| p | ) |
home row — brackets, arrows, navigation:
| key | output |
|---|---|
| caps | tab |
| a | OSM(Shift+Cmd) |
| s | ( |
| d | ) |
| f | { |
| g | } |
| h | left |
| j | down |
| k | up |
| l | right |
| ; | transparent |
| ' | PgUp |
bottom row — quantum keys, brackets, symbols, math, navigation:
| key | output |
|---|---|
| lsft | Shift+Tab |
| z | LCtrl |
| x | Cmd+Shift+C |
| c | keypad dot |
| v | [ |
| b | ] |
| n | \ |
| m | | |
| , | - |
| . | + |
| / | = |
| rsft | PgDn |
setup
brew install kanata
sudo ~/.config/kanata/scripts/setup-mac-service.shthen grant Input Monitoring permission in System Settings > Privacy & Security > Input Monitoring.
service management
| action | command |
|---|---|
| check status | sudo launchctl list | grep kanata |
| start / restart | sudo launchctl kickstart -k system/xbxd.kanata |
| stop | sudo launchctl kill TERM system/xbxd.kanata |
| disable auto-start | sudo launchctl disable system/xbxd.kanata |
| enable auto-start | sudo launchctl enable system/xbxd.kanata |
| unload | sudo launchctl bootout system/xbxd.kanata |
logs are at /Library/Logs/Kanata/.
raycast integration
add ~/.config/kanata/scripts/raycast/ as a script directory in Raycast Preferences > Extensions > Script Commands.
| script | action |
|---|---|
kanata-start.sh |
start (with auto-restart) |
kanata-stop.sh |
temporarily stop (will auto-restart) |
kanata-disable.sh |
disable completely — no auto-restart |
kanata-enable.sh |
re-enable after disable |
kanata-status.sh |
show status and recent logs |
customization
tap-hold timing is set in config.kbd via the tap-timeout and hold-timeout variables. increase to reduce accidental modifier triggers, decrease for faster response.
to reload after any change:
sudo launchctl kickstart -k system/xbxd.kanatawindows setup
windows uses a parallel config config-windows.kbd (cmd-style shortcuts retranslated to ctrl, screenshot row uses Win+Shift+S). device filtering requires the Interception kernel driver — scoop's kanata package only ships the LLHOOK build which cannot scope to a single keyboard.
one-time install
both steps are automated by chezmoi scripts under .chezmoiscripts/windows/:
chezmoi apply # downloads kanata_wintercept.exe + installs Interception (UAC prompt)
# REBOOT — Interception only attaches after a restartdiscover the laptop keyboard hwid
after reboot, list Interception-visible devices:
& "$HOME\.local\bin\kanata_wintercept.exe" --listwarning: --list is misleading. it prints the device path (e.g. \\?\ACPI#LEN0071#...), but kanata's runtime matching uses the device's HardwareID property — a totally different value. paste the --list byte array and matching silently fails (is intercepted: false).
correct discovery method: stop the auto-start task, then run kanata in the foreground with debug logging:
Stop-ScheduledTask -TaskName xbxd.kanata
& "$HOME\.local\bin\kanata_wintercept.exe" -c "$HOME\.config\kanata\config-windows.kbd" -d(it'll error on parse if the placeholder is empty; that's fine -- we just need it loaded.) press a key on the laptop keyboard. it'll log something like:
[INFO] include check - res 90; device #1 is intercepted: false; hwid [65, 0, 67, 0, 80, 0, 73, 0, ...]the array after hwid is what kanata's matcher compares against -- equality on the full 1024-byte buffer (HWID_ARR_SZ in kanata's source). copy the non-zero prefix (everything up to the long run of trailing zeros) into windows-interception-keyboard-hwids (...) in dot_config/kanata/config-windows.kbd. syntax must be N,N,N -- bare commas, no spaces, no brackets, no surrounding parens. kanata's parser accepts space-separated numbers too but treats each as a separate single-byte entry, so matching never fires.
decode every other byte as ASCII to verify visually -- on ThinkPads this typically reveals a REG_MULTI_SZ containing ACPI\VEN_LEN&DEV_0071, ACPI\LEN0071, and *LEN0071 separated by \0.
then:
chezmoi apply # pushes the updated config + registers the Scheduled Task (UAC prompt)service management
| action | command |
|---|---|
| status | Get-ScheduledTask -TaskName xbxd.kanata | Get-ScheduledTaskInfo |
| start | Start-ScheduledTask -TaskName xbxd.kanata |
| stop | Stop-ScheduledTask -TaskName xbxd.kanata |
| restart | Stop-ScheduledTask xbxd.kanata; Start-ScheduledTask xbxd.kanata |
| disable | Disable-ScheduledTask -TaskName xbxd.kanata |
| enable | Enable-ScheduledTask -TaskName xbxd.kanata |
| unregister | Unregister-ScheduledTask -TaskName xbxd.kanata -Confirm:$false |
logs are appended to %LOCALAPPDATA%\Kanata\kanata.log.
powershell helpers / raycast integration
mirrors the macOS Raycast scripts. live under ~\.config\kanata\scripts\windows\ with the same @raycast.* comment-directives as the Mac side, so Raycast for Windows can index them as Script Commands.
| script | action |
|---|---|
kanata-start.ps1 |
start the task (will NOT auto-restart on this OS) |
kanata-stop.ps1 |
stop the running instance; task remains enabled |
kanata-disable.ps1 |
stop + prevent the task from triggering at next logon |
kanata-enable.ps1 |
re-enable a disabled task and start it |
kanata-status.ps1 |
show task state, process, and recent log lines |
invoke from any PowerShell:
& "$HOME\.config\kanata\scripts\windows\kanata-status.ps1"start/stop/enable/disable do NOT require an elevated shell because we own the task; the actions just call Start-ScheduledTask / Stop-ScheduledTask etc. against the user's own task store.
to expose them in Raycast: open Raycast Settings > Extensions > Script Commands > Add Script Directory and point it at %USERPROFILE%\.config\kanata\scripts\windows -- the five commands appear under the "Kanata" package, mirroring the Mac UX. alternatively bind hotkeys via PowerToys Keyboard Manager or AutoHotkey.
external keyboards
usb / bluetooth keyboards (Iris, etc.) are intentionally unaffected — only the HWID listed in windows-interception-keyboard-hwids is intercepted. all other inputs pass through to windows untouched, so qmk/vial layouts on external boards keep their native behavior.