Karabiner-Elements Tutorial: Remap macOS Keyboard and Build a Hyper Key

Why Karabiner-Elements?

Karabiner-Elements remaps keys at the kernel level — before any app sees them. This means you can build a Hyper key (a single key that acts as Ctrl+Shift+Opt+Cmd), remap Caps Lock to Escape, or create layers that transform your keyboard entirely.

This guide covers installation, simple remaps, and building a full Hyper key setup that supercharges your shortcuts.

• Remap any key to any other key system-wide
• Build a Hyper key for conflict-free global shortcuts
• Create complex modifications with conditional rules
• Set up device-specific remapping for multiple keyboards

Installing & Granting Permissions

Install Karabiner-Elements from karabiner-elements.pqrs.org or via Homebrew:

brew install --cask karabiner-elements

• macOS 12 or later
• Kernel extension permissions (Karabiner will prompt on first launch)
• Full disk access for Karabiner-Elements (Privacy & Security)
• System Integrity Protection can remain enabled

Simple Key Remaps

Start with simple remaps in the Simple Modifications tab. Click "Add item", select a "from" key and a "to" key.

• Map Caps Lock → Escape (the #1 most popular remap)
• Map right Cmd → Ctrl (for ergonomics)
• Map Fn → Right Option
• Map any media key to a standard key

For each key, click the dropdown and pick the key. Changes apply instantly — no restart needed.

// Simple Modifications in config:
// caps_lock → escape
{ "from": {"key_code":"caps_lock"},
"to": [{"key_code":"escape"}] }

Building a Hyper Key

The Hyper key is the killer feature. It maps Caps Lock (or any key) to act as Ctrl+Shift+Opt+Cmd simultaneously — a modifier that no app uses, so you get conflict-free global shortcuts.

In Complex Modifications, add a rule: when Caps Lock is pressed alone, send Escape; when held with another key, send Hyper.

{
"description": "Caps Lock → Hyper + Escape",
"manipulators": [{
"from": { "key_code": "caps_lock" },
"to": [{
"key_code": "left_shift",
"modifiers": ["left_control","left_option","left_command"]
}],
"to_if_alone": [{ "key_code": "escape" }],
"type": "basic"
}]
}

Now any shortcut like Hyper+J works everywhere without conflicts. Pair it with Hammerspoon or Raycast for maximum power.

• Hyper + H/J/K/L — vim-style window navigation
• Hyper + Space — launch Raycast or Spotlight
• Hyper + 1-9 — switch to specific apps
• Hyper + A — toggle always-on-top for current window

Complex Modifications & Layers

Karabiner's Complex Modifications are where the real power lives. Browse the pre-made rules at ke-complex-modifications.pqrs.org, or write your own.

• Import from the gallery: search for "Hyper key", "Vi mode", "application launcher"
• Write custom rules with conditional logic — different mappings per app, per device
• Create layers: hold a key to enter a "navigation layer" where H/J/K/L become arrows
• Set up device-specific rules for when you switch between laptop and external keyboard

Key Conflict Diagnosis

Common issues and solutions:

• Keys not remapping? Check Full Disk Access and kernel extension permissions in System Settings
• Hyper key sends escape too? The to_if_alone is expected — press alone = Escape, press with key = Hyper
• Rules not applying? Check the order — rules are evaluated top-down, first match wins
• Conflict with app shortcuts? Hyper (Ctrl+Shift+Opt+Cmd) should never conflict — no app uses all four modifiers

Keyboard Superpower

You've built a Hyper key. Here's what's next:

• Create complex modifications with layers and conditions (see [[Karabiner Complex Modifications]])
• Set up device-specific remapping for multiple keyboards (see [[Karabiner Device-Specific Remapping]])
• Pair Hyper key with Hammerspoon for window management (see [[Hammerspoon Window Management Guide]])
• Pair with BetterTouchTool for trackpad + keyboard combos (see [[BetterTouchTool Tutorial]])