Karabiner

File Structure

mods/dotfiles/karabiner/
  polyfill.ts              # CJS require() shim
  deno.json                # Deno config, tasks, imports
  src/
    index.ts               # Entry point -- composes all rules
    cap-modifier.ts        # Caps Lock variable-based layer
    modifier-swap.ts       # Per-app Cmd/Ctrl/Fn swapping
    layers.ts              # Simlayers (a, d, l, n, s)
    window-layer.ts        # Tab dual-role for rift-cli window management
    leader-utils.ts        # exitLeader() helper
mods/dotfiles/karabiner.json  # Generated output (committed to repo)

Active Modules (Priority Order)

Rules are passed to writeToProfile() in this order. Earlier rules take precedence.

1. cap-modifier.ts -- Caps Lock Variable-Based Layer

Uses the "caps-layer" variable. Caps Lock held = layer active; Caps Lock alone = Escape.

Implementation: Raw manipulator objects with set_variable/variable_if conditions on "caps-layer".

2. modifier-swap.ts -- Per-App Cmd/Ctrl/Fn Swapping

Terminal apps (Terminal, iTerm2, Alacritty, Ghostty) are treated as "dev apps"; everything else is "standard apps".

Uses ifApp() with regex bundle ID patterns and .unless() for negation.

3. layers.ts -- Simlayers

Uses simlayer("key", "name") from karabiner.ts. Hold the trigger key and press a second key simultaneously.

a -- Delimiters/Brackets Layer:

d -- Arrows Layer: h/j/k/l = left/down/up/right arrows

l -- Operators/Symbols Layer:

n -- Numbers Layer: q=1, w=2, e=3, r=4, t=5, y=6, u=7, i=8, o=9, p=0

s -- Control Layer: h/j/k/l = Ctrl+h/j/k/l

4. window-layer.ts -- Tab Dual-Role for rift-cli Window Management

Uses two variables: "tab_window_mode_active" and "tab_q_nested_mode_active". Tab held activates primary mode; Tab+Q held activates nested mode. Tab alone = Tab.

Calls rift-cli at /etc/profiles/per-user/nick/bin/rift-cli via to$() shell commands.

Primary Mode (Tab held):

Nested Mode (Tab+Q held):

5. Inline Rule (in index.ts)

escape -> grave_accent_and_tilde (backtick/tilde key)

Support Files

polyfill.ts

import { createRequire } from "node:module";
(globalThis as any).require = createRequire(import.meta.url);

Must be imported first in index.ts (import "../polyfill.ts") before any karabiner.ts imports work.

leader-utils.ts

Exports exitLeader() which returns [toSetVar("system_leader", 0)]. Used by cap-modifier.ts to reset the leader variable when Caps is tapped alone.

karabiner.ts API Basics

import { rule, map, simlayer, writeToProfile, ifVar, toSetVar, ifApp, to$ } from "karabiner.ts";

// Create a named rule with manipulators
rule("My Rule").manipulators([
  map("a").to("b"),                                    // a -> b
  map("a").to({ key_code: "b", modifiers: ["left_control"] }), // a -> Ctrl+b
]);

// Simlayer: hold trigger + press key simultaneously
simlayer("f", "my-layer").manipulators([
  map("j").to("down_arrow"),
  map("k").to("up_arrow"),
]);

// Conditional rules using variables
rule("Conditional").manipulators([{
  type: "basic",
  from: { key_code: "h" },
  to: [{ key_code: "left_arrow" }],
  conditions: [{ type: "variable_if", name: "my_var", value: 1 }],
}]);

// Variable-based layer (dual-role key)
rule("Layer Toggle").manipulators([{
  type: "basic",
  from: { key_code: "caps_lock" },
  to: [{ set_variable: { name: "my_layer", value: 1 } }],
  to_if_alone: [{ key_code: "escape" }],
  to_after_key_up: [{ set_variable: { name: "my_layer", value: 0 } }],
}]);

// Per-app conditions
rule("App-specific", ifApp("^com\\.apple\\.Terminal")).manipulators([...]);
rule("Non-terminal", ifApp("^com\\.apple\\.Terminal").unless()).manipulators([...]);

// Shell commands
rule("Shell").manipulators([{
  type: "basic",
  from: { key_code: "f" },
  to: [to$("open -a Finder")],
}]);

// Write the profile
writeToProfile({ name: "default", dryRun: false, karabinerJsonPath }, [
  ...myRules,
  ...otherRules,
]);

How to Add New Rules

1. Create a new file in src/ with kebab-case naming (e.g., src/my-feature.ts)
2. Import polyfill is NOT needed in individual modules (only in index.ts)
3. Export a rules array:

   import { rule, map } from "karabiner.ts";
   export const myFeatureRules = [
     rule("My Feature").manipulators([
       map("some_key").to("other_key"),
     ]),
   ];
   

4. Import in src/index.ts:

   import { myFeatureRules } from "./my-feature.ts";
   

5. Add to the writeToProfile() array (position determines priority -- earlier = higher):

   writeToProfile({ name: "default", dryRun: false, karabinerJsonPath }, [
     ...capsRules,
     ...modifierSwapRules,
     ...layerRules,
     ...tabWindowManagerRules,
     ...myFeatureRules,  // <-- add here
     rule("escape -> grave_accent_and_tilde").manipulators([...]),
   ]);
   

6. Build and reload:

   deno task build && karabiner-reload.sh
   

How to Add Simlayer Keys

In layers.ts, find the target simlayer and add a new map() entry:

simlayer("a", "delimiters layer").manipulators([
  // ... existing mappings ...
  map("new_key").to("target_key"),
  // or with modifiers:
  map("new_key").to({ key_code: "target", modifiers: ["left_shift"] }),
]),

Important Notes

• Output path is mods/dotfiles/karabiner.json -- one directory UP from karabiner/. Do NOT put output inside the source directory.
• Do NOT manually edit ~/.config/karabiner/karabiner.json -- it is a symlink to the generated file.
• Always commit BOTH the TypeScript sources AND the generated karabiner.json.
• Run deno task build from the mods/dotfiles/karabiner/ directory after any change.
• Run karabiner-reload.sh or restart Karabiner-Elements (osascript -e 'quit app "Karabiner-Elements"' && sleep 1 && open -a 'Karabiner-Elements') to apply changes.
• The polyfill.ts import MUST come before any karabiner.ts imports in index.ts.
• When adding variable-based layers (like caps-modifier or window-layer), use raw manipulator objects with set_variable, variable_if, to_if_alone, and to_after_key_up for dual-role behavior.
• Simlayers (from layers.ts) use the higher-level simlayer() API which handles the variable mechanics automatically.