# Karabiner Configuration Personal [Karabiner-Elements](https://karabiner-elements.pqrs.org/) setup on macOS. A kernel-level keyboard remapper — the go-to tool for making macOS keyboards behave the way you actually want. Config file: `~/.config/karabiner/karabiner.json` > [!warning] Raw notes > These are living, personal config notes — raw, frequently out-of-date, and sometimes half-baked. They reflect my setup at some point in time, not a maintained tutorial. Verify against upstream docs before copying. Reach out if something looks broken. > [!info] What is Karabiner-Elements? > Karabiner-Elements is a macOS keyboard customization utility that operates at the driver level, intercepting keystrokes before any application sees them. It supports simple key remaps, complex modifications with conditions (e.g., "only when held, not when tapped"), and device-specific rules. Config is stored as JSON in `~/.config/karabiner/karabiner.json`. ## Key Settings | Setting | Value | Why | |---------|-------|-----| | Caps Lock | → Left Control | Home-row Control — far more ergonomic than the corner | | Keyboard type | ANSI | Matches physical keyboard layout | ## Config File The full config at `~/.config/karabiner/karabiner.json`: ```json { "profiles": [ { "name": "Default profile", "selected": true, "simple_modifications": [ { "from": { "key_code": "caps_lock" }, "to": [{ "key_code": "left_control" }] } ], "virtual_hid_keyboard": { "keyboard_type_v2": "ansi" } } ] } ``` ### Why Caps Lock → Control? Caps Lock sits dead-center on the home row — prime real estate for a key I never use as Caps Lock. Control, on the other hand, is used constantly: `Ctrl+A`, `Ctrl+E`, `Ctrl+K` in shells and readline; `Ctrl+C`/`Ctrl+Z` for signals; tmux prefix (`Ctrl+Space` isn't mapped here, but Control combos everywhere else). Remapping at the driver level means it works in every app, including the login screen. > [!tip] Simple vs Complex Modifications > The `simple_modifications` array handles unconditional 1:1 remaps. For more sophisticated rules — "act as Escape when tapped alone, Control when held with another key" (the classic dual-role binding) — Karabiner uses `complex_modifications` with `from`/`to`/`to_if_alone` conditions. This config keeps it simple: one remap, no conditions. ## Useful Commands | Action | How | |--------|-----| | Open GUI | `open -a Karabiner-Elements` | | View event log | Karabiner-EventViewer app | | Reload config | Automatic on file save | | Check driver status | Karabiner-Elements → Misc tab | ## Notes The config is deliberately minimal. Complex modification rules (e.g., home-row mods, layer switching via QMK-style hold/tap) are something to explore if a programmable keyboard is added to the setup. For now, the single Caps Lock remap covers the main ergonomic pain point. ## Links - [Karabiner-Elements docs](https://karabiner-elements.pqrs.org/docs/) - [Complex modifications reference](https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/) - [Karabiner-Elements GitHub](https://github.com/pqrs-org/Karabiner-Elements) - [Community complex modifications](https://ke-complex-modifications.pqrs.org/)