Keyboard
Caps Lock, reborn: the remap that makes everything else reachable.
The most useful key on the keyboard was wasted on Caps Lock. This setup turns it into the two keys you press most in a terminal — Escape and Control — so the shortcuts on every other page are right under your left pinky.
One key, two jobs
Via Karabiner-Elements, Caps Lock becomes a dual-role key:
- Tap it → Esc. The single most-pressed key in Vim (it's how you leave Insert mode and get back to Normal) — now without reaching to the top-left corner.
- Hold it → Control. Press it together with another key for any Ctrl-shortcut, with your finger already on the home row.
The key earns its prime spot many times a minute, and real Caps Lock is still there when you want it — on a deliberate two-key press instead of a single accidental one.
Getting real Caps Lock back
Hold Right Shift and press Caps. That sends a genuine Caps Lock, so it toggles — the same press turns it on and turns it off. Left Shift is deliberately not bound, so ordinary capitalized typing can never trigger it by accident.
Press Right ShiftCaps. The light goes out.
This is the shortcut's main job. Once Caps Lock is remapped, the physical key can no longer send a real Caps Lock — so if the state is ever switched on by anything else, nothing on the keyboard can switch it back off, and the light stays lit. Before this binding existed the only way out was disabling the remap entirely.
Because it's a toggle, pressing it again turns Caps Lock back on. If the light doesn't respond at all, Karabiner isn't seeing the key: check that it's running and has Input Monitoring permission.
Why this is the keystone
Look back at the other pages and notice how much lives on Esc, Ctrl, and Alt:
| Neovim | Esc returns to Normal mode — the move you make constantly |
| Herdr | The prefix is Ctrla; pane nav is prefix + h/j/k/l, with direct CtrlAlth/j/k/l as a convenience |
| tmux | The prefix is Ctrla; pane nav is Alth/j/k/l |
| Shell | Line editing is all Ctrl — CtrlA/E/W/U/R |
On a Mac, the modifier names are ⌘ Command, ⌥ Option, ⌃ Control, and ⇧ Shift. Terminal documentation often says Alt for Option when the key sends an Alt/Meta sequence.
Put Esc and Ctrl under your strongest, nearest finger, and make sure Option sends real Alt. That whole vocabulary stops being a stretch.
Groundwork opens Karabiner after install/update if it is not running, but macOS still requires you to enable its background services, approve Accessibility, and allow its driver / system extension. Input Monitoring is normally unnecessary on Karabiner-Elements 16.0.0 and later; use it only for 15.9.0 or earlier, or when Karabiner itself asks. A script can't click these for you — full steps are on the Troubleshooting page.
The other keyboard tweaks
The setup also nudges a few macOS keyboard defaults so the terminal feels right:
| Key repeat | Hold a key and it repeats quickly, so j/k scrolling and holding a motion in Vim are snappy. Setup asks which speed you want — see below |
| Press-and-hold off | Holding a key repeats it instead of popping up the accent menu — essential for Vim, where you hold keys to move |
| Option as Alt | In Ghostty, the ⌥ key sends a real Alt, so shell shortcuts like AltF (forward a word), AltC (fzf folder jump), and Alth/j/k/l pane navigation work |
The key-repeat settings are read when an app launches, so they fully take hold after you log out and back in (or restart). If holding a key still shows the accent popup, that's the one to do.
How fast should key repeat be?
Holding a key is a primary motion in a terminal, not an edge case: j/k down a file, arrow keys through a long command, backspace over a wrong path. Two separate things control it — how long before repeating starts, and how fast it repeats once started. Setup asks once and you can change it later.
| Fast (default) | Starts repeating soon, repeats quickly. The recommended answer, and what the rest of these pages assume |
| Standard | Same start delay, slower repeat. Pick this if fast repeat overshoots for you |
| Aggressive | Same fast repeat, but starts sooner. Snappiest — and the one most likely to fire when you only meant to rest on a key |
Change it any time with groundwork-configure. Note that adjusting the Keyboard sliders in System Settings writes the same values, so touching them later overrides your choice.
It is a property of the machine you are typing on, never the one you are typing into. Over SSH or in a container, the repeat behavior is still your own desktop's — so Groundwork doesn't set it on headless hosts, in containers, or under WSL2 (where Windows owns the keyboard). Set it on your desktop and it follows you everywhere you connect from there.
On Linux desktops Groundwork applies it through GNOME's keyboard settings, which persist. On a non-GNOME X11 desktop it can only set the current session, and it prints the xset line to add to your own startup; other Wayland compositors set it in their own config.
Put it to use
Tap for Escape
Open nvim, press i to type, then tap Caps Lock to pop back to Normal mode. Do it a few times — this replaces the corner Esc reach you'd otherwise make hundreds of times a day.
Hold for Control
At the shell, hold Caps Lock and press R — that's CtrlR, history search. Then hold Caps and tap A / E to jump to the start / end of the line. Same finger, no stretch.
Going deeper
- Karabiner-Elements documentation — for any other remap you dream up (other dual-role keys, app-specific rules, home-row mods).
- Apple's keyboard settings — the System Settings → Keyboard panel mirrors several of these.