Chordal Hold (aka opposite hand rule)

[clementnuss]

Is your feature request related to a problem? Please describe.

having implemented home row mods, I sometimes struggle when typing characters too quickly, such as typing a and r extremely fast which triggers a Ctrl+r in my case.

the "problem" is not new, and there are some workarounds to it (e.g. #1455), but even like that I sometimes encounter this issue.

Describe the solution you'd like.

ideally, a feature similar to chordal hold for QMK would almost completely eliminate misfires: the idea is pretty simple, a key combination should only take place when combining a home-row modifier with a letter from the other hand.

this is detailed in @getreuer blog article, and has been serving QMK pretty well.

Describe alternatives you've considered.

alternatives include tweaking permissive hold and tapping terms, but are mostly workarounds.

Additional context

No response

[GrewHair]

@clementnuss, it looks like tap-hold-except-keys achieves what you're asking for. Works pretty solidly for me.

[gerhard-h]

The advanced HRM sample https://github.com/jtroo/kanata/blob/main/cfg_samples/home-row-mod-advanced.kbd is doing something in that direction

Currently, I prefer these adaptations (make advanced HRM less restrictive), but I'm not settled, yet.

• adjust timing for each finger
• using tap-hold over tap-hold-release-keys whenever there is no actual problem with a given home row mod
• instead of full $rigthand or $lefthand only add problematic letters
• leave "typing layer" (nomods) when hitting space
• use tap-hold-release-keys over defchords to fix nasty bigramms
• skip typing-layer activation for upper case keys

 tp (switch
        (lsft rsft) XX break ;; skip typing-layer activation for upper case keys
        ()  (multi
              (layer-switch typing)
              (on-idle  35 tap-vkey to-base )
            ) break
  )

[getreuer]

Hello! (Summoned by the @getreuer callout.) I can't say I'm a Kanata user myself, but I'm a fan of the project and always point people here when looking for a software-only keyboard remapping solution.

 tp (switch
        (lsft rsft) XX break ;; skip typing-layer activation for upper case keys
        ()  (multi
              (layer-switch typing)
              (on-idle  35 tap-vkey to-base )
            ) break
  )

It's very cool what is possible with Kanata configuration! OTOH, I'd be clueless on how to come up with such a thing. What should newcomers do who want home row mods in Kanata? Is there a guide someplace with a recommended starting point recipe?

[gerhard-h]

What should newcomers do who want home row mods in Kanata?

I think the matter is not finally settled.

• SAMPLE FOLDER home-row-mod-basic is a clear the starting point (to learn the concept and the problems)

• SAMPLE FOLDER jtroo made home-row-mod-advanced wich uses a fast typing layer

• I already wrote Home row mods and automatic fast typing layer to settle the matter once and for all ... didn't pan out as my typing speed increased.

• Meanwhile, an alternate key-timing solution Skip home row mods while typing #1455 from @argenkiwi was found

Maybe one of them is perfect for you, but I run into problems with all four of these. But with my adaptations to home-row-mod-advanced I'm pretty happy.

[argenkiwi]

@getreuer I would be keen to know how these compare to their QMK equivalents in your view:

• @jtroo's advanced example using tap-hold-release-keys and Chordal Hold (i.e., bilateral combinations).
• switch + key-timing and the Tap Flow module.
• tap-hold-release and permissive hold (not completely sure about this one).

Hopefully if you can establish a connection or analogy in terms of the concepts or techniques being applied, you will have a good idea on what configuration you would personally recommend.

[gerhard-h]

My experience with QMK is: PERMISSIVE_HOLD_PER_KEY is a must, if you want to use home row shift during touch typing.
Not using PERMISSIVE_HOLD will also sluggify all shortcuts in general.

In kanata on the other side, a plain tap-hold is working much better than MOD_TAP.

In my opinion for shift, the time of release of the second key should not be that relevant anyway, because the decision to mod or not to mod should happen much earlier.

I also ditched MOD_TAP and did my own bilateral home row shift in QMK - again kanata was out of the box much better.
So I'm interested but also a bit skeptical towards all the modern QMK modules: sm_td, accordion,... and haven't found a good comparison article either.

[getreuer]

@getreuer I would be keen to know how these compare to their QMK equivalents in your view:

• @jtroo's advanced example using tap-hold-release-keys and Chordal Hold (i.e., bilateral combinations).
• switch + key-timing and the Tap Flow module.
• tap-hold-release and permissive hold (not completely sure about this one).

Hopefully if you can establish a connection or analogy in terms of the concepts or techniques being applied, you will have a good idea on what configuration you would personally recommend.

@argenkiwi thanks for that! I'd be happy to take a shot at relating these options.

What should newcomers do who want home row mods in Kanata?

I think the matter is not finally settled.

• SAMPLE FOLDER home-row-mod-basic is a clear the starting point (to learn the concept and the problems)
• SAMPLE FOLDER jtroo made home-row-mod-advanced wich uses a fast typing layer
• I already wrote Home row mods and automatic fast typing layer to settle the matter once and for all ... didn't pan out as my typing speed increased.
• Meanwhile, an alternate key-timing solution Skip home row mods while typing #1455 from @argenkiwi was found

Maybe one of them is perfect for you, but I run into problems with all four of these. But with my adaptations to home-row-mod-advanced I'm pretty happy.

@gerhard-h thank you, I appreciate the links! I'm not asking for my own use necessarily, but what to recommend to others. This outline is helpful.

It's understandable that a home row mods configuration on Kanata is not finally settled to a single solution that satisfies everyone. It's certainly not that way for QMK or ZMK. Rather, there are various ingredient options that can be combined and tuned to one's liking. That said, the configuration advice in precondition's home row mods guide and urob's timeless home row mods are frequently cited as good references.

Summary of HRMs config options

To bridge terminology between implementations, here is an attempt at a Rosetta Stone to relate the most-used tap-hold options. Caveat: The options are often only approximately equivalent across implementations in how exactly they work and what configuration options they have. The devil is in the details.

Permissive Hold: In a nested press like "A↓, B↓, B↑, A↑" in which A is a tap-hold key, A is settled as held. Permissive Hold enables one to trigger the hold function without having to wait out the tapping term. Like you said, this is essential for fast typing.

• QMK: Permissive Hold
• ZMK: the "balanced" hold-tap flavor
• Kanata: tap-hold-release (?)

"Opposite hands" rule: If, while a tap-hold key is held, another key is pressed on the same hand, the tap-hold key is immediately settled as tapped. This behavior helps substantially with avoiding mod misfires, and it also reduces the input lag inherent with tap-hold keys. The tradeoff is then you need to wait out a timeout to make same-handed chords.

• QMK: Chordal Hold (new in 2025 Q1! 🥳), or with third-party extensions by Manna Harbour’s Bilateral Combinations patch or my Achordion library.
• ZMK: positional hold-tap configuration
• Kanata: tap-hold-release-keys (?)

Global Quick Tap aka Require Prior Idle aka Automatic Fast Typing Layer: When a tap-hold key is pressed within a short time of the previous key event, it is settled as tapped. This helps particularly with fast typing, and it too reduces input lag.

• QMK does not have a core option for this yet—I'm working on that. It's possible to add with third-party extensions, like filterpaper's Contextual Mod Taps or my "Tap Flow" module.
• ZMK: require-prior-idle-ms
• Kanata: Home row mods and automatic fast typing layer #1425

Hold While Undecided, aka Eager Mods: Depending on other options, it can be slow and awkward to do things like Shift+Click with an external mouse, having to wait out a timeout to get the Shift. To get around this, the idea is to apply the mod immediately when the mod-tap is pressed. If it ends up being settled as tapped, the mod is released before sending the tap so that no damage is done.

• QMK does not have a core option for this yet, though it's been proposed. Achordion has an eager mods option to do it.
• ZMK: hold-while-undecided
• Kanata: is there an equivalent?

Caps Word: It's like Caps Lock, but turns off automatically at the end of the word. Of course, this is not in itself a tap-hold option, but it's handy in combination with home row mods for typing abbreviations and ALL_CAPS identifiers. Otherwise, with home row Shift keys, such things require awkward hand switching or finger gymnastics.

• QMK: Caps Word
• ZMK: Caps Word
• Kanata: caps-word

If anyone has corrections to this or can expand on other options or implementations, please comment!

[musjj]

Hold While Undecided

There are some attempts below, but I don't think it's currently possible to implement eager mods from the user side, at least with tap-hold-release and its variants.

The problem is that the eager mods needs to be de-activated as soon as a non-mod key is pressed while it's undecided. For example, say that your F key is a tap-hold-release for Ctrl and your O is a normal key. With the implementations below, pressing these keys together will instantly invoke Ctrl + O, defeating the purpose of tap-hold-release.

I'm not completely sure how this is handled in QMK. It does seem tricky to implement correctly.

Permissive Hold

The equivalent of permissive hold being tap-hold-release seems correct here, at least according to QMK's docs.

"Opposite hands" rule

As for Chordal Hold, an equivalent is finally implemented in #1781 and will probably be included in the next release 🥳

[argenkiwi]

Thanks @getreuer. I believe your assessment is spot on. I am unaware of an implementation of eager modifiers in Kanata, but I'd also be curious to know if there is one. Is it something you would use with home row modifiers? If so, would it work together with permissive hold?

I was also unaware of urob's timeless home row modifiers. I find I agree with that approach the most as I am not good at maintainig a consistent timing.

Hopefully I will have some time to go around the QMK learning curve in the near future so I can try Tap Flow and Chordal Hold.

[jtroo]

Hold While Undecided, aka Eager Mods:

This could theoretically be implemented by something like:

  (multi lsft (tap-hold 0 100 
     (multi (release-key lsft) s) lsft))

But as-is some environments (notably on Linux) may not like the rapidity between release-key and tap of s here; and there may be some code in Kanata that needs to be added to support delaying the mod release and the tap activation.

[getreuer]

I am unaware of an implementation of eager modifiers in Kanata, but I'd also be curious to know if there is one. Is it something you would use with home row modifiers? If so, would it work together with permissive hold?

Yes, I used HRMs with eager mods for a few years. It's one of the behaviors that Achordion implements. Whether mods are eager is orthogonal to how the tap-vs-hold decision itself is made, so you can mix and match this idea with Permissive Hold and whatever else. The idea is, at the moment the mod-tap is pressed, the mod is activated. Then, when the tap-hold key is settled...

• If the key is settled as held, then just keep holding the mod. It's a no-op since the mod is already active.
• If the key is settled as tapped, then release the mod and send the tap (in that order).

Hold While Undecided, aka Eager Mods:

This could theoretically be implemented by something like:

  (multi lsft (tap-hold 0 100 
     (multi (release-key lsft) s) lsft))

But as-is some environments (notably on Linux) may not like the rapidity between release-key and tap of s here; and there may be some code in Kanata that needs to be added to support delaying the mod release and the tap activation.

Yeah, that's a familiar issue in QMK, too. Rapid back-to-back key events don't always get handled properly. IME, inserting a delay of 10 ms between events is slow enough to fix this problem in most cases. The culprit is often the application rather than the OS. Remote Desktop software for instance is known to be particularly bad about this.

[argenkiwi]

I just wanted to share a snippet based on @jtroo's suggestion and @getreuer comment that seems to achieve eager mods using virtual keys:

(deftemplate eagervkey (char vkey)
  (switch
    ((key-timing 3 less-than 375)) $char break
    () (multi
         (on-press press-virtualkey $vkey)
         (on-release release-virtualkey $vkey)
         (tap-hold-release 200 200
           (macro (on-press release-virtualkey $vkey) 10 $char)
           ()
         )
       ) break
  )
)

(defvirtualkeys
  met lmet
)

(deflayermap (main)
  a (t! eagervkey a met)
)

The virtual key abstraction allows for using a macro to introduce a 10 millisecond delay between the cancellation of the modifier. It serves as a proof of concept, but as I type this I am coming across misfires, which may be because there is something wrong with the implementation. I attempted using tap-hold-release-timeout as well, but the modifier did not seem to eagerly trigger. The main issue it solves for me is doing control/command click which comes handy on some IDEs.

[jtroo]

Something very close to QMK's chordal hold is added in https://github.com/jtroo/kanata/releases/tag/v1.10.0-prerelease-1:
tap-hold-release-tap-keys-release