Kanata: Cross-platform multi-layer keyboard remapper with advanced customization | Hacker News Reader

Kanata: Cross-platform multi-layer keyboard remapper with advanced customization

github.com

159 pointslnyan57 comments

This is probably the joint most important piece of software on my system next to my window manager.

The elevator pitch I give for this software is "QMK for any keyboard" - you can use layers, tap dance etc. with regular keyboards that have programming symbols in sane locations with dedicated keys.

I use this with a Logitech Ergo K860, and have taken it a step further to integrate with my window manager so that layers change automatically based on the focused application[1].

[1]: https://github.com/LGUG2Z/komokana

I have the same relation with Kanata. I've grown so dependent on it that it's the first thing I have to set up on a new install.

Thanks to it, I'm using a Miryoku with Colemak-dh layout over a Razer Mechanical keyboard. I even removed the extra keys from it, which makes the keyboard a sight to see.¹

But Kanata is the real star in this show, making all the magic happen.

It's so flexible and configurable that through its blessings I've finally gone completely mouseless. I just keep my hands steady on the keyboard and my thoughts get converted to whatever action I need on screen. The humanities writer dream!

I have great respect for jtroo for creating this software. It's a perfect example of how well designed software allows to go beyond the seeming physical constraints imposed by hardware.

1. That's also why I need it so badly on a new install...

> Miryoku

O.o

How do you even go about learning a keymap like this?

Multi platform is an awesome quality for a tool like that: when you do have a customization like that, it's a huge value-loss when it can't be passed on across system boundaries.

That being said, this appears to be an active mapper that needs to be running in the background. Classic "with great power comes great responsibility". I'd rather have something less powerful that only offers the customizations that can be loaded into the native keyboard mapping engines. On Windows, I am extremely happy with a few tweaks I've built with Microsoft Keyboard Layout Creator (MSKLC). Mostly removing some of the worst pain points of my home language layout (German) that drive many of my compatriots to using an English layout (basically what nodeadkeys does on Linux, but with a few improvements like opting in to dead keys behavior with altgr+’). Would be super awesome to have a UI for setting up that kind of mapping that can output configurations for the native mapping mechanism across a range of platforms. And that only offers mappings that can be configured using the native system on all platforms supported, the intersection of capabilities.

For MacOS there's https://software.sil.org/ukelele/

For Linux, unfortunately xkb is overcomplicated and undercapable, and it's like pulling teeth to get a layout recognized as a first-class citizen by a Linux ‘desktop’.

So something like this https://github.com/divvun/kbdgen?

Not exactly - as in I did not expect half as many platforms. Awesome!

(but I can't find any mention of the AltGr modified that most languages other than English use as their central exotica pivot? That's a surprising omission)

What's the benefit of native over active?

I'd also recommend checking out https://github.com/houmain/keymapper if you're interested in context aware remaps (based on OS, application, device). It's cross-platform as well.

Keymapper was posted here ~10 days ago https://news.ycombinator.com/item?id=42871040, but the link received relatively little attention, so I assume it might have been missed by many.

Disclaimer: I'm active on the issue threads and a big fan. :)

Can it do home row mods and other advanced key remapping stuff like chords described in this project?

What's the difference between this and kanata, or is this purely a plug?

Kanata is amazing ! i'm using it right now. it can do many things like making a key a dual-function key (a letter on tap, a modifier on hold) and so much more

it recently got a new chording feature where you can press a whole bunch of keys at once (or just two if you'd like) and something will happen. like, you could press the letters q and n at the same time and program Kanata to send the word question or some macro like a hotkey or a series of hotkeys and strings. it's all up to you. i have a QMK board, but because Kanata has many more features and isn't limited to the memory of its chip, i use Kanata instead of QMK to architect my layout, complete with multiple layers and many QoL niceties

is there a noticeable input delay when using Kanata?

no, there is not. kanata is lightning fast

Katana is a grean tame. I remapped my n and t keys already.

I am interested in hearing how people use this level of customisation in their workflow, whether it is through this particular tool or by configuring at the keyboard firmware level. This is a new paradigm for me.

This doesn't have to be a complex workflow.

My work laptop from Dell has an idiotic "copilot" key which sends something like ctrl+shift+f23 - three separate key presses on the scancode level.

I use dkey to map this otherwise useless crap chord to Ctrl.

I only buy keyboards that allow for remapping the keys at the firmware level. Either via custom firmware or configuration file. This means the mappings are inherently cross OS platform and just work. Example, ESC key replaces the Caps Lock since ESC is used more often and rarely is Caps Lock needed.

With multi-profile keyboard mapping, I even have a gaming profile so I don't have to remap keys in the game(s).

Do the same with mice. Cross OS, my mouse can lower, raise, and mute the volume. Great in games too with improving the would audio to either listen for those to sneak up on or quickly lowering the extreme loud noise.

Only grip is that laptop keyboards need to move to the same custom firmware / configuration mapping like external for better cross OS support / user experience.

The firmware level is unfortunately unaware of the app you're running, and also can't do scripts, which adds a serious limitation on the many cool features you could do with integrated keybinding tools. Then as you noted there is laptops...

I use a combination of keyboard firmware(on one machine) and a similar tool(xremap). Mostly for:

- turning my CapsLock into escape. As a vim user I use it all the time

- when CapsLock is held it turns into a hyper key. Hyper+e to switch to Emacs window, hyper+b to browser and so on

- creating application independent maps that work on Linux and MacOS: ctrl+w is always "kill last word", super+w to kill a tab or a window

- invoking hammerspoon commands on MacOS that tile windows, bring up window switcher, etc.

Would you mind Sharing your hammerspoon Config? Are you tiling your windows similar to i3 or sway?

Sure. Should be able to extract the relevant bits tomorrow.

I tried some tiling WMs on MacOS(Amethyst?), but they never truly felt like tiling WMs on Linux. I could never reliably switch focus where I wanted it to go. This is not to disparage those projects; my config works well enough and I may not had given them a proper chance.

My tiling is manual and closer to Windows snap feature mixed with Power Toys zones.

Fwiw I'm somewhat happy combining AutoRaise for focus-follows-mouse and rectangle for tiling.

It's not as good as a dedicated tiling wm on Linux - but it's less terrible than MacOs' mouse/touchpad chauvinism.

https://github.com/sbmpost/AutoRaise

https://github.com/rxhanson/Rectangle

On Linux I often use mouse follows focus. I switch to a webbrowser and have a reasonable guess where the cursor is. IIRC that was a pain with Amethyst and my hammerspoon config. Have you set up something like this?

No, I've not found anything that gives workable mouse follow focus. But I've not looked very hard.

I am finally settled on aerospace.app which is close enough to i3 for me. Now hammerspoon for some Automation :)

Found a config that seems much cleaner than my lua mess and at a glance it has the key tiling functions[1]. Check set-window-fraction function and its callsites.

[1]: https://github.com/kbd/setup/blob/main/HOME/.hammerspoon/ini...

Thank You. Nice. Fennel lang

People choosing a non local keyboard usually require this level of adjustments for daily use of their computer.

If you want to type french with a standard US keyboard for instance, it will require at least some small layering. Typing a CJK language will require some more tweaks, in particular the dual action on keys saves a lot. If you intend to type both accented and CJK with let's say the UK international layout, you'll need every help you can get.

When using vim more heavily, having an escape key remap as the control key's single action is also a huge QOL.

Once you're in it, it opens the door for a lot of small improvements.

I just use either emacs or neovim to edit the configuration. Kanata can run on top of your xkb layout. So I use that to select one of the 3 readily-available keyboard layouts. Kanata manages 2 layers on top of that. Both layers a very sparse and mostly just pass the keystrokes transparently to xkb. Layer 1 is almost entirely pass-through, except for one tap-dance key to switch layers. It behaves more or less like a native xkb keyboard. Layer 2 adds some useful features like home-row-mods.

the main draw for me was being able to use the spacebar as a modifier, and being able to press ikjl when the spacebar is held to send the arrow keys. the ctrl and shift keys still work while the spacebar is being held which makes it great for moving the caret around and editing text, like using ctrl + right then ctrl + shift + left to select a word, but without having to move away from the home row

i also have home, end, backspace, delete, pgup, pgdn, all close enough to the homerow on that layer as well so i dont have to reach out to the corners of the keyboard

then finally on the edsf keys i have it send whether the vscode shortcuts are to move the line up or down or indent/unindent.

most of the rest of the things i have remapped are just single key things that can be done in most other remappers, sending esc when the alt key is tapped, capslock to ctrl etc

What function and timings do you use to make the space bar a modifier, but still work normally when typing? I tried a few things but couldn't figure out what to use.

tap-hold-release 200 200 spc (layer-toggle spc_layer)

That's what I am doing right now. The issue seems to be when I am sloppy with the spacebar and some unknown input processing. When this is input:

  - keydown space
  - keydown a
  - keyup a
  - keyup space

I normally get the output <space><a>, interpreted in order of keydown, but kanata outputs in order of keyup, so I get <a><space>.

im using the "kanata_gui_cmd_allowed" version on windows, but maybe if youre on linux or mac maybe it might work differently im not sure

i dont know if this would make a difference but i have "process-unmapped-keys yes" in my defcfg section

I don't use this, but as an example:

I like to use a US Intl keyboard layout for programming but as I am German I need äöüß a lot - so I've used a custom keymap for caps-aous for years (and a couple other things). Yes, you can get most OSes to somehow do this, but just doing it at firmware level would fix SO MANY PROBLEMS.

I just tried reading the documentation and I have no idea what I’m supposed to do. I have a bunch of keyboards that won’t let me use the F keys as standard f keys (only lets me use them as multimedia keys) unless I hold the keyboards fn key. Karabiner is set to “use f keys as standard f keys” and it still doesn’t work. Anyone know how I might use kanata to use F1, F2…etc without holding the keyboards fn key?

I don’t know Kanata, but you need to find out which key codes are sent for the multimedia functions in order to remap them. This file [0] (linked from [1]) contains the key names Kanata knows, and it has entries like “VolumeUp”. You could try to remap those to the respective function key.

There are some keyboards, however, which send multimedia commands via USB “out of band” from normal key codes, and which therefore cannot be remapped that way.

[0] https://github.com/jtroo/kanata/blob/main/parser/src/keys/mo...

[1] https://jtroo.github.io/config.html#key-names

In case you are on Windows, I would recommend SharpKeys [2] for basic remappings.

[2] https://github.com/randyrants/sharpkeys

Since Karabiner is Mac only: does the system setting to use the f keys as function keys not work for these keyboards: https://support.apple.com/guide/mac-help/use-keyboard-functi...?

The level of cross-platform desktop support here is really impressive

This looks like a potential great tool but it needs a better summary of what it can do and how it works. I can't quite grasp it from the readme.

I use a mix of setxkbmap to remap the control key and AutoKey but each has its issues. Can this replace those?

On Linux, it completely captures your physical keyboard (meaning it doesn't work for other applications anymore) and creates a virtual keyboard using the uinput kernel module [1]. The configuration is for how the keys on the physical keyboard maps to the virtual keyboard.

It should be able to do whatever you suggest. But it can be a lot of configuration. I use 3 different layouts in 2 languages and that will be too much to configure manually. Instead, I just use 2 layers that are mostly just pass-through (they just pass the keystrokes to the native xkb layout). Layer1 is entirely pass-through except for a single tap-dance key to switch to layer 2. Layer2 has some additional features like home-row-mods that are not possible with plain xkb. The keyboard layouts are managed by xkb. Thus I'm able to use the features of both xkb and kanata.

[1] https://www.kernel.org/doc/html/v4.12/input/uinput.html

Short answer: remapping single keys like Control is trivial with Kanata or without. I have no problems with this.

It is likely that AHK has some features not in Kanata, so you would have to explain what you do.

I've remapped my capslock to 'tap-dance' between esc (short press) and ctrl (long press) using kanata. And, like any other people here, it's indispensable tool in my workflow right now.

Also recently, I've remapped my siblings laptop meta and rctrl key to lalt and meta respectively because the original alt key got damaged. Thanks jtroo for creating this you rocks!

Off topic.

I live in a town called Kanata west of Ottawa, Canada. I never know the meaning of the name. Thanks for explanation of "Kanata"

Anything like this with mouse support? Even better, I'm looking for something ideally like vim easy motion but by OCR the screen.

Yesterday I installed Karabiner Elements to get a jk chord mapped to escape globally. I’m a bit disappointed it’s not actually a chord, it’s a simultaneous press with a 100ms window.

Does Kanata support chords like jk to escape with a configurable timeout on when k is pressed, say 80ms or so?

This seems to rely on Karabiner for keyboard hooking, so it wouldn't be that different ? (maintainer mainly uses windows and linux, so kinda makes sense)

On macos limitations, kernel extensions are officially deprecated so I don't think we'll see a mechanism that can hook deep enough into the keyboard manager system to allow for complex chords. That's what Karabiner did as kernel ext. before switching to Elements, and the timeout workaround was introduced at that time if I remember correctly.

AFAIK https://github.com/houmain/keymapper should support this on MacOS even though it also makes use of the Karabiner virtual device lib (referring to a sibling comment). I suggest giving both a try!

Think Karabiner supports custom timeout (though not sure what you mean by the difference between a chord and a simultaneous key)

This project looks great! Does anyone know of a keyboard remapper for iOS/Android?

For Android there's at least https://github.com/keymapperorg/KeyMapper but regardless if it's popularity it didn't seem to work consistently on my device. I'd still suggest giving it a try!

Does it remap keys on the operating system, or does it flash firmware to keyboards?

As I understand, it's on the OS level

It's user-land remapping of the keyboard input. Even on Linux it's a deamon you can start/stop at any time, and if it's not running no processing is done.

Neither. It captures your regular keyboard and creates a virtual keyboard - at least on Linux.

Added later: This is what I get on my sway desktop in addition to the physical keyboard:

  Input device: kanata
    Type: Keyboard
    Identifier: 1:1:kanata
    Product ID: 1
    Vendor ID: 1
    Active Keyboard Layout: English (US)
    Libinput Send Events: enabled

And the mapping from the physical keyboard to the virtual keyboard is done by kanata running as a user service (without root privileges). You just need to give uinput access privilege to your user account.

I now use this on all of my systems. It is great for remapping laptop keyboards. I still use via/vial on my corne.

Reply on news.ycombinator.com