Tap sends letter hold is shift using timeout

Unfortunately all the keyboard jargon makes it hard for me to know what to search or, or to understand any of the discussion when I do find something.

I want this functionality from my ergodox zsa:

I’m using (from Tap-hold for Gaming - #4 by maexxx):

ifPrimary final tapKey a
holdKey leftShift

But this does not use a timeout. Often when I am typing I haven’t released the a key by the time i’m pressing the next key. Can I make it timeout based?

Yes, see advanced secondary role options in Agent.

In a macro called $onInit, I have configured some values to tweak the primary/secondary role resolution:

set secondaryRole.defaultStrategy advanced
set secondaryRole.advanced.timeout 250
set secondaryRole.advanced.timeoutAction secondary
set secondaryRole.advanced.triggerByRelease 1
set secondaryRole.advanced.safetyMargin +5  // positive values for safetyMargin favour primary role, negative favour secondary role

With these settings, you have a timeout, and you have a slight preference towards primary resolution (your a) when there’s a slight overlap between key presses.

I believe nowadays you can also set these values directly in Agent. I have them in my $onInit for historical reasons.

Your shift function on the a key is also otherwise known as a “home row mod” (modifier on a home-row key). These are tricky to get right, because timing is critical in distinguishing a vs. shift function, especially when you are typing fast.

I’m on macOS. Where’s the advanced secondary role agent setting?

Agent version: 4.2.0

Firmware: 11.1.0

That is under typing behavior. It’s not os dependent. Be aware though between ergodox qmk and uhk own firmware there a large differences in terms of behavior so you may have surprises if you look to have consistency.