This TS package contains Karabiner.ts recipes for QMK-like layers (namely: hold-tap and mod-tap) with powerful QMK features: permissive-hold, chordal hold, and hold on key press. This package builds upon these layers to provide the first turn-key solution for home row mods that works almost like on a QMK keyboard, i.e., it’s good.
Additional features:
This section provides a step-by-step guide to installing home row mods on your mac. I wrote it, so that it can be followed even if you are not a tech person. You need to have basic familiarity with the command-line and have node and gh installed.
-
- Open a terminal and in your home directory run
npx create-karabiner-config@latest. This will create akarabiner-configdirectory.
- Open a terminal and in your home directory run
-
Plug in Greg Mods to your
karabiner-config.-
Change directory to
karabiner-config. -
Add
karabiner.ts-greg-modstopackage.json:{ "name": "karabiner-config", "description": "karabiner config in karabiner.ts", "scripts": { "build": "tsx src/index.ts", "update": "npm update karabiner.ts" }, "devDependencies": { "@types/node": "^20", "karabiner.ts": "latest", "karabiner.ts-greg-mods": "latest", "tsx": "^4", "typescript": "^5" } } -
Run
npm install.
-
-
Configure HRM by adding them to the Karabiner.ts config in
src/index.ts:import { rule, writeToProfile } from "karabiner.ts"; import { hrm } from "karabiner.ts-greg-mods"; writeToProfile("Default profile", [ rule("Home row mods").manipulators( hrm( new Map([ ["a", "l⌃"], ["s", "l⌘"], ["d", "l⇧"], ["f", "l⌥"], ["k", "r⇧"], ["l", "r⌘"], [";", "r⌃"], ]), ).build(), ), ]);
-
Install the new Karabiner.ts config in Karabiner with
npm run build.
- Clone the repository next to your Karabiner.ts project:
gh repo clone gregorias/karabiner.ts-greg-mods. - Install and build the repository with
npm installandnpm run build. - Add the repository as a dependency to your K.ts project (
package.json):"karabiner.ts-greg-mods": "file:../karabiner.ts-greg-mods",.
-
Add the dependency with
npm install karabiner.ts-greg-mods. -
Import the mods in your
karabiner.tsconfig:import { hrm } from "karabiner.ts-greg-mods";
Warning
If your hold-tap keys lose character during fast typing with rolls, increase
to_if_held_down_threshold_milliseconds (400 should be large enough).
You may be witnessing
a bug in Karabiner.
The hold-tap layer is a modified K.ts layer that mimics QMK hold-tap behavior. In addition to the default, hold-on-key-press decision mode, you can also use permissive-hold and the slow-mode (wait for the tapping term to elapse).
If you don’t activate the hold, e.g., you quickly roll over two keys during writing, this layer replays the layer and the other key. With this layer, you don’t lose your keystrokes during simple roll overs.
// A symbols layer activated with ␣.
let symbolsLayer: Rule = holdTapLayer("␣")
// Allow having ⇧ and ⇪ on for the layer key.
.optionalModifiers(["⇧", "⇪"])
// Use permissive-hold logic for actuating the following manipulators.
// I don’t want to activate the layer just when I quickly roll over with
// a ␣.
.permissiveHoldManipulators(
// …
// Some manipulators that trigger with any modifier, but transform
// to the function key on ⇧.
map("m", ["⇧"]).to("f1"),
map("m", [], "any").to("1"),
map(",", ["⇧"]).to("f2"),
map(",", [], "any").to("2"),
map(".", ["⇧"]).to("f3"),
map(".", [], "any").to("3"),
// ...
)
// I don’t roll over on these keys, so use the more aggressive strategy.
.holdOnOtherKeyPressManipulators([map("[").to("-"), map("]").to("=")])
// For any key not defined above, we’ll replay them.
// If we don’t define a key in manipulators or echo keys, they get lost.
.echoKeys(...allKeys)
// How long to wait before activating the manipulators for certain.
// Important for permissive-hold and slow manipulators.
.tappingTerm(120 /*ms*/)
.description("Symbols layer");You can define sub-layers like so:
// Trigger the sub-layer on press and hold.
.holdOnOtherKeyPressManipulators([
// Necessary: https://github.com/evan-liu/karabiner.ts/issues/171.
map("l⇧").to(toSetVar("shift-mode", 1))
.toAfterKeyUp(toSetVar("shift-mode", 0)),
map("k")
.to(toSetVar("shift-mode", 1))
.toAfterKeyUp(toSetVar("shift-mode", 0)),
// If we just rolled over the keys, replay them.
.toIfAlone("␣")
.toIfAlone("k")
])
.permissiveHoldManipulators(
...withCondition(ifVar("shift-mode"))([
// …
map("m").to("!"),
map(",").to("@"),
map(".").to("# ),
// …
]) as BasicManipulator[],
// …
map("m").to("1"),
// …The ability to replay keys doesn’t come for free. If you don’t want to lose the layer key during writing, you need to define any keys it might roll over with either as a manipulator or as an echo key. I just provide a list of all keys on my keyboard as echo keys.
Permissive-hold manipulators don’t work well with triple key roll over.
A mod-tap key is a dual-function key that acts as a normal key when tapped but
becomes a modifier when held down.
The modTap mod turns a key into a mod-tap key.
The mod-tap builder supports two main modes:
- Non-permissive:
The modifier is only activated after the
tappingTermhas elapsed. This is safer against accidental triggers during fast typing but can feel less responsive. - Permissive: The modifier is activated as soon as another key is pressed, making it feel more immediate. However, this can sometimes lead to unintended modifier activation during quick key rolls.
This recipe lets you set up bare-bones HRM with modifier chaining. It’s further described in my blog post.
const simpleHrm: BasicManipulator[] = [
...modTap().from(["a", "s"]).modifiers(toKey("l⌃", "l⌘")).build(),
...modTap().from(["s", "a"]).modifiers(toKey("l⌃", "l⌘")).build(),
...modTap().from("a").modifiers(toKey("l⌃")).build(),
...modTap().from("s").modifiers(toKey("l⌘")).build(),
];hrm is a turn-key solution for configuring home row mods that utilizes the
features of the hold-tap layer.
It provides quite snappy experience as it is responsive with permissive-hold and
chordal-hold strategies (both optional) while also not losing keys during
accidental roll overs (mostly).
const leftHandKeys = ["q" /*…*/, , "b"];
const rightHandKeys = ["y" /*…*/, , "/"];
let hrmRule: Manipulator[] = hrm(
new Map([
["a", "l⌃"],
["s", "l⌘"],
["d", "l⇧"],
["f", "l⌥"],
["j", "r⇧"],
["k", "r⇧"],
["l", "r⌘"],
[";", "r⌃"],
]),
)
.lazy(true)
.holdTapStrategy("permissive-hold")
.chordalHold(true)
// Some overrides for modded keys:
.smartManipulators(
"l⌃",
map("h").to("⌫"),
// In Chrome, L⌃ + I/O navigate history.
map("i").to("→", "l⌘").condition(ifApp("Chrome")),
map("o").to("←", "l⌘").condition(ifApp("Chrome")),
// L⌃ + N/P navigate dropdowns.
map("n").to("↓").condition(unlessKitty),
map("p").to("↑").condition(unlessKitty),
)
.smartManipulators(
"⌃",
// ⌃W deletes a word.
map("w").to("⌫", "l⌥").condition(unlessKitty),
)
.smartManipulators("l⌥", ...commaPeriodMoveChromeTabs)
// I press this combo a lot nad it’s hard to roll over it, so use a more
// responsive strategy.
.keys("l⌥", ["w", "q"], "hold-on-other-key-press")
.simultaneousThreshold(90)
.tappingTerm(110)
.build();- Same limitations as in the hold-tap layer.
- You can’t chain modifiers, e.g., you can’t press and hold l⌃ and then press and hold l⌘. You must press two modifiers simultaneously to have them available.
- Key replaying doesn’t work with modified keys. It is technically feasible, but I figured that such a capability is not worth additional rules.
let capsWordRule: Rule = capsWord()
.toggle(map("c", "Hyper").build()[0]) // ✦+C
.build();
// Also deactivate Caps WORD with ␣ in the symbols layer and other keys in
// there.
let symbolsLayer = holdTapLayer("␣")
.allowAnyModifiers()
.onAlone(disableCapsWordEvents)
.permissiveHoldManipulators(
map("s", [], ["⇪"]).to("[").to(disableCapsWordEvents),
map("x", [], ["⇪"]).to("]").to(disableCapsWordEvents),
);
// …- Caps WORD turns-on ⇪ when active. Your other manipulators should take that into account.
- How to simulate QMK home row mods in karabiner? (Karabiner#3559) — A feature request for Karabiner to enable HRM-capabilities.