Karabiner Edition

• 1: Install and Hyper basics
• 2: Navigation, deletion, and mouse
• 3: Windows and developer workflows
• 4: System functions and reference
• 5: Configurator
• 6: Earlier versions
  • 6.1: Mac V2
  • 6.2: Mac V1
  • 6.3: Windows

1 - Install and Hyper basics

Capslock Enhancement V3 current targets macOS and Karabiner-Elements. There is nothing else to install: the configuration is a set of complex-modification rules that Karabiner interprets, so nothing new runs in the background and nothing is compiled on your machine.

Install

brew install --cask karabiner-elements

karabiner://karabiner/assets/complex_modifications/import?url=https://raw.githubusercontent.com/Vonng/Capslock/main/mac_v3/capslock.json

Ten rules

The keyboard map is colour-coded by purpose, so a key's neighbourhood tells you roughly what it does before you look anything up. The configuration ships as ten Karabiner rules, one per family, and you enable them one by one.

Tap, hold, and Hyper

Caps Lock now has two behaviours that never collide, because one is decided on release and the other while the key is down.

✱ is not a private signal. Karabiner rewrites the held Caps Lock into all four right-side modifiers at once, ⌘+ with ⌥+ with ⌃+ with ⇧, which has two consequences worth understanding:

• Other software still sees an ordinary chord. Alfred, Moom, Magnet, Raycast and your IDE receive ⌃+ with ⌥+ with ⇧+ with ⌘ plus a key and can bind it like any other shortcut.
• Anything the rules do not claim passes straight through. ✱+ with A has no rule of its own precisely so that a window manager can own it. The same trick works for any key you want to hand to another app.

Sixteen control planes

While Hyper stays held, the four left-side modifiers act as four binary switches. Read them as four bits and you get planes 0–15:

⌘ = 1 · ⌥ = 2 · ⌃ = 4 · ⇧ = 8.

Nine planes are populated; seven are free space for rules of your own. Open the configurator to browse the same sixteen rows interactively and see what each key does on the plane you select.

The planes are not arbitrary. Across the whole configuration the same modifier keeps the same meaning, which is why the layout can be learned once rather than memorized key by key:

Compatibility

• The layout is drawn for ANSI keyboards and works the same on built-in Apple keyboards and external ones. ISO layouts work too, but the two keys that differ physically may land somewhere unexpected.
• The MouseKey family needs a numeric keypad. Everything else works on a tenkeyless board.
• Older macOS releases need an archived Karabiner-Elements build, which this guide does not cover.

Next

Continue with navigation, deletion, and mouse control.

2 - Navigation, deletion, and mouse

The pink and brown areas around the home row carry the layout's most frequent operations. The navigation and deletion families together carry 114 of the 282 mappings in V3.1, so this is the part of the layout worth learning first.

The navigator block

H J K L move left, down, up, and right, exactly as in Vim. Directly above them, U I O P extend the same idea to whole pages and lines: Page Up, Home, End, Page Down.

Those eight keys are the only ones mapped on nine different planes. Each group of planes below covers one job, and together they account for 72 of the 282 mappings in V3.1.

Moving and selecting text

The text layer follows one rule: hold ⌘ and a movement becomes a selection, because the rule emits the same arrow key with ⇧ added. Adding ⌥ on top widens the unit: a character becomes a word, a line becomes three lines, half a line becomes the whole line.

That is why ✱+ with ⌘+ with ⌥+ with I jumps to the end of the line and then selects back to its start: it is the fastest way to grab exactly one line without touching the mouse.

Switching apps, windows, tabs and desktops

⇧ moves between containers, the thing you are looking at rather than the text inside it, while ⌃ talks to the window server.

Pointer and wheel from the home row

Four more planes turn the same eight keys into a mouse, without your hands moving at all. ⇧ is the accelerator in both modes.

The middle mouse button is the one exception: it lives on ✱+ with ⌥+ with ↩ rather than on a navigator key.

Arrow-key mouse control

The physical arrow keys drive the pointer too, which is often quicker than reaching for the home-row layer. Here ⌥ slows down and ⌘ speeds up, in both pointer and wheel modes.

All five mouse buttons sit on ↩:

Semantic deletion

N M , . sit directly below the navigation keys. The pair on the left deletes backwards, the pair on the right deletes forwards, and the unit grows as you add modifiers.

Two rows break the pattern deliberately. ✱+ with ⌥+ with N and ✱+ with ⌥+ with . both send ⌘+ with ⌫, clearing everything from the cursor back to the start of the line, so the outer keys of the block are the "throw this line away" pair. And ✱+ with ⌥+ with M / ✱+ with ⌥+ with , do not delete at all: they emit ⌥+ with ⇧+ with ↓ and ⌥+ with ⇧+ with ↑, the move-line-down/up shortcut that IntelliJ, VS Code and most editors share.

Numeric keypad as a mouse

If your keyboard has a keypad, Hyper turns the whole block into a mouse. The digits give eight directions around a neutral 5; the top row scrolls; the bottom and right edges are the five buttons.

The same speed modifiers apply as everywhere else: ⌥ slows the pointer to half, ⌘ doubles it, and adding ⇧ converts pointer motion into wheel motion at the matching speed.

Next

Continue with windows, applications, terminal controls, clipboards, and symbols.

3 - Windows and developer workflows

The layout dedicates several colour-coded zones to the actions that interrupt a developer's flow most often: switching windows, launching tools, sending terminal signals, parking text somewhere, and typing punctuation.

Window control

⇥ Q W A S form the azure block on the left of the keyboard. They close and cycle things, from a single tab up to the whole login session.

Two rows deserve a note.

✱+ with A is intentionally not mapped. Because Hyper is ⌃+ with ⌥+ with ⇧+ with ⌘ on the right-hand side, an unmapped key passes straight through to whatever application is listening. Bind ⌃+ with ⌥+ with ⇧+ with ⌘+ with A inside Moom, Magnet or any other window manager and it becomes your layout key. Slate is kept only as a historical example.

Sleep is not a keystroke but a shell command: ✱+ with ⇧+ with W runs pmset sleepnow and ✱+ with ⌥+ with W runs pmset displaysleepnow. Karabiner needs no extra permission for these, but they will not fire if a modal dialog is blocking input.

Application shortcuts

The yellow keys launch or focus six applications on three planes. Each rule is a plain open -a shell command, so the target is matched by application name, which is exactly what makes them safe to rewrite.

Because open -a both launches and focuses, one key does the job of a Dock icon and a ⌘+ with ⇥ hunt. If an application is already frontmost, pressing its key again does nothing: it does not toggle.

Terminal and IDE control

The green keys put the control chords a shell uses constantly under your right hand, so the left hand never has to contort into ⌃ + a letter mid-sentence.

✱+ with C and ✱+ with ⌘+ with C are open -a commands like the yellow keys, so they can be repointed at whichever assistant you use.

Five text clipboards

Number keys 6–0 become five independent text clipboards. ✱+ with ⌘ plus a number copies the current selection into that slot; ✱ plus the number pastes it back.

Two things follow from that implementation, and both are useful:

• The slots survive logout, reboot, and the system clipboard. They are ordinary files, so cat ~/.clip7 reads one from a shell and any editor can fill one without touching the keyboard at all.
• They hold plain text only. Copying an image or a file into a slot stores whatever pbpaste renders as text, not the original object.

Code-oriented shifter

The orange keys move the punctuation a programmer types all day within reach of the home row, with no ⇧ gymnastics for brackets.

The bracket keys are the payoff: [ and ] give all three pairs (round, curly and angle) from the same two positions. And because ; and ' sit side by side, : = and ! = are adjacent rolls, which is how Go and Rust assignment and comparison end up faster to type than on a bare keyboard.

Both ✱+ with / and ✱+ with \ emit ⌘+ with /, the comment shortcut nearly every editor and IDE shares.

Next

Use system functions and reference for function keys, screenshots, symbols, customization, and troubleshooting.

4 - 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.

5 - Configurator

Pick a control plane from the table or by clicking the left-side modifiers, then click any key to see the Karabiner rule behind it. Keys that launch an application can be renamed. Your edits stay in this page until you copy or download the JSON; nothing is sent anywhere.

The interactive configurator runs only on the web page: it shows all sixteen control planes, lets you rename the application shortcuts, and exports a JSON file for Karabiner-Elements. Current configuration (3.1.0): capslock.json

Import your copy

1. Choose Download config. The file is named capslock-3.1.0-custom.json.
2. Move it into ~/.config/karabiner/assets/complex_modifications/.
3. In Karabiner-Elements › Settings › Complex Modifications, remove the original Capslock rules, choose Add predefined rule, and enable the rules from your file.

The import link on Install always fetches the unmodified configuration, so use it to go back to the defaults.

6 - Earlier versions

Before V3, the Capslock layout went through three editions: an AutoHotkey script for Windows, an XML configuration for the original Karabiner on OS X, and a first set of rules for Karabiner-Elements. Their files are still in the GitHub repository. These pages record what each edition did and how it was installed.

The Mac editions wrote Hyper as ✱, and these pages keep that notation: ✱ H means hold Caps Lock and press H.

6.1 - Mac V2

Mac V2 was the first Capslock edition for Karabiner-Elements, the rewrite of Karabiner that macOS Sierra required. It is a set of ten complex-modification rules. A tap on Caps Lock sends Escape. Holding it turns it into Hyper (✱): Karabiner-Elements holds the four right-hand modifiers, ⌃ ⌥ ⇧ ⌘, together, so Hyper still combines with the left-hand ones and most apps accept it.

Caps Lock

Navigation

Hyper alone moves the cursor. Adding one left-hand modifier selects instead, moves the pointer, switches tabs and apps, or works with Spaces.

Mouse

Deleting

Windows and tabs

Terminal keys

Apps

The README suggested replacing these with your own favourite apps.

Function keys

V2 expected F1 to F12 to act as standard function keys and used Hyper to get the printed functions back. On a MacBook Pro with a Touch Bar, the README suggested turning on Karabiner-Elements › Function Keys › "Use all F1, F2, etc. keys as standard function keys".

Keys found on full-size keyboards:

Shifted symbols

The last four rows make != and := quick to type.

Other keys

How it was installed

These are the steps from the V2 README, kept for the record.

1. Download and install Karabiner-Elements.
2. Import the rules by opening this address in Safari:

   karabiner://karabiner/assets/complex_modifications/import?url=https://raw.githubusercontent.com/Vonng/Capslock/main/mac_v2/capslock.json

   Or copy capslock.json into ~/.config/karabiner/assets/complex_modifications/, which is what make install in the mac_v2 folder does.
3. In Karabiner-Elements, open the Complex Modifications tab, click Add Item, and enable the rules you want.
4. To change the apps or any other key, edit the imported file in ~/.config/karabiner/assets/complex_modifications/.

Files

All of V2 is in mac_v2/ in the repository.

Differences from V3

• Planes. V2 combined Hyper with one left-hand modifier at a time, which gave it only a few planes. V3 combines Hyper with any of the four left-hand modifiers, for up to 16 planes.
• Changed keys. In V3.1, F13 and F14 control screenshots instead of the previous and next track, ✱ ⌘ D runs Define instead of opening Dictionary, and Spotlight replaces Launchpad.

6.2 - Mac V1

Mac V1 was the first Capslock edition for the Mac. It needed two tools. Seil changed the key code that Caps Lock sends to 80, the code of F19. Karabiner then read V1's private.xml, which turned that key into Hyper (✱) while held and defined each group of shortcuts as a separate item to switch on in Karabiner's preferences.

Caps Lock

Navigation

Hold Hyper to move the cursor; add the left ⌘ to select as you move.

Deleting

Windows and tabs

Terminal keys

Apps

The README suggested replacing these with your own favourite apps.

Function keys

Keys found on full-size keyboards:

Shifted symbols

Mouse

Other keys

How it was installed

These are the steps from the V1 README, kept for the record.

1. Download and install Seil.
2. Download and install Karabiner.
3. In Seil, turn on Change the caps lock key and set its key code to 80.
4. In Karabiner, open the Misc & Uninstall tab and click Open private.xml. Replace that file with V1's private.xml. The setup script in the mac_v1 folder copies it to ~/Library/Application Support/Karabiner/private.xml for you.
5. Return to the Change Key tab, click Reload XML, and enable the items you want.

Files

All of V1 is in mac_v1/ in the repository.

Differences from V3

• Tools. V1 needed Seil and the original Karabiner, configured in XML. Karabiner-Elements replaced the original Karabiner for macOS Sierra and later; V2 and V3 are JSON rules for it and do not need Seil.
• Tapping Caps Lock. V1 let you choose between Escape and switching input source. V3 sends Escape on a tap.

6.3 - Windows

Capslock began on Windows in 2013, two years before the first Mac version. The script turns Caps Lock, which it calls the "useless key", into a function key like Ctrl and Alt by combining it with almost every other key on the keyboard. Caps Lock itself is kept off, and its old job moves to Caps Lock + `.

Some of its bindings differ from the Mac versions. The Mac V2 README notes this, and that the Windows version is no longer maintained.

What it did

The README summarises the script in one table. This version of it fills in the details from the script itself.

Running it

The README gives no installation steps. The repository holds the script in two forms:

• The source, CapsLock.ahk, runs with AutoHotkey. It uses AutoHotkey v1 syntax.
• A prebuilt executable, CapsLock.exe, runs without AutoHotkey.

Files

All of the Windows version is in win/ in the repository.

The SHA-256 of CapsLock.exe in the repository is e0d6a4d2de155860aed164281ed16f5871aaca95cccc6fe1d46db2b16004cb80.