System functions and reference

This page collects the mappings and project details you look up rather than learn in sequence.

Function and system keys

F1–F12 behave as standard function keys by default; hold Hyper to send their media or system functions instead. The cyan block covers the whole top row plus the screenshot keys.

The screenshot keys follow one convention: the plain Hyper chord puts the capture on the clipboard, and adding ⌘ writes it to a file on the desktop.

The six-key navigation cluster on a full-size keyboard gives the same three system controls in smaller steps, by emitting ⇧+ with ⌥ together with the media key, macOS's own quarter-step modifier.

Symbols

The ✱ symbol is a heavy asterisk. The ordinary asterisk has ASCII code 42, the answer to life, the universe, and everything.

How a rule is written

Every mapping in the configuration has the same shape. Reading one makes the whole file legible, and makes the customization section below far less intimidating:

- description: 'control + h = ctrl + left (prev desktop)'
  type: basic
  from:
    key_code: h
    modifiers:
      mandatory: [left_control, right_command, right_control, right_shift, right_option]
  to:
    - key_code: left_arrow
      modifiers: [left_control]

The four right_* modifiers in mandatory are Hyper itself; they appear in every rule that Hyper drives. Whatever else sits beside them, left_control here, selects the control plane. to is what the application actually receives.

What changed in V3.1

V2 used only a handful of planes. V3 introduced the four-bit plane model, which is what let the layout grow to 282 mappings without becoming arbitrary. The earlier configurations are listed under Versions.

V3.1 then intentionally changed several defaults that older users will notice:

• clipboards moved to 6–0, and 1–5 are no longer slots;
• C and ⌘+ with C launch Codex and Claude;
• Spotlight and Alfred 5 replace Launchpad and Alfred 4;
• F13 and F14 provide screenshots instead of previous / next track;
• ⌘+ with D performs Define rather than opening Dictionary.

Customize the configuration

The YAML is the source of truth and the JSON is generated from it. Regenerating takes one command and yq v4:

make -C mac_v3 compile

A good first customization is claiming one of the seven free planes. Copy any rule, change the left modifier in mandatory, and you have a whole keyboard's worth of space that nothing else uses: plane 5 (✱+ with ⌘+ with ⌃) and plane 7 (✱+ with ⌘+ with ⌥+ with ⌃) are both completely empty.

Keep the YAML and the generated JSON synchronized: the import link and the Karabiner gallery both publish the JSON.

FAQ and troubleshooting

A chord does nothing at all.

Check Settings › Complex Modifications first: the ten rules are enabled individually, and a fresh import leaves nothing on. If the rule is enabled, open Karabiner-EventViewer and press the chord. It shows exactly what reaches the system, which distinguishes a missing rule from an application that swallows the shortcut.

Caps Lock sends Escape but nothing else works.

That is the signature of enabling only the first rule. CapsLock to Hyper provides tap-Escape and hold-Hyper; the other nine rules provide everything that Hyper then does.

Why can a chord trigger macOS diagnostics?

Issue #30 documents that ⌘+ with ⌥+ with ⌃+ with ⇧+ with . can trigger macOS diagnostics. Remap that system shortcut if it conflicts with your chosen plane.

Why is Linux not supported?

Desktop environments differ substantially. The author primarily uses Linux through a macOS terminal. Native support could be implemented with tools such as xmodmap; contributions are welcome.

Why does the repository contain older macOS versions?

Legacy Karabiner used XML. Karabiner-Elements replaced it for macOS Sierra and later, so the older configurations remain for historical systems. They are listed under Versions.

Is the design original?

The first AutoHotkey version dates to 2013 and the first Mac version to 2015. The current configuration is listed in the Karabiner-Elements complex-modifications gallery.

Project

Capslock Enhancement is maintained by Vonng and distributed under the Apache License 2.0. Source, releases, and issue tracking live on GitHub.